Please enhance documentation on the recommended use of the BWA MEM -M and -Y option

[mdkeehan]

I am planning a large alignment run on a non human species using a non alt aware reference. I would like to determine which combination of BWA MEM "-M" and "-Y" options I should be using. As far as I can tell "-M" used to be needed for the Picard compatibility as sometimes mentioned in the man page.

GATK 4 now recommends not to use "-M" for the human alt aware reference. But they are now recommending "-Y" which seems to be a new option from around (0.7.12?)

A small recommendation in the README.md would be useful.

[mdkeehan]

Thinking about it a bit more. It might be that GATK use -M for consistency for non ALT references So currently planning on going ahead without -M. Just in case we make the wrong decision here is the start of my plan B to post alignment mark with -M.

// Replicates the markMinusM option of BWA MEM.
// It turns supplementary alignments into secondary alignments.
//
int markMinusM(const int& flag){
	int res = flag;
	if(flag & 0x800 ) {// i.e. alignment is supplementary
		res = flag | 0x100; //  bitwise OR now becomes "not primary" or secondary
		res &= ~0x800; // turn off supplementary
	}
	return res;
}

It some ways science attempts to replicate how things are done but "why" things are done may not be as well documented. I am closing this off.

[jmarshall]

Please don't close your issue.

Various BWA users have been asking @lh3 what the -M option might be still useful for for quite some time — see #26, #96, and #163 for example.

It would be very helpful if Heng would explain why -M is still important. As I understand it, it was for compatibility with Picard pre v1.96, which did not understand the SUPPLEMENTARY flag. However Picard has understood this flag for almost five years now. Is there other software for which bwa mem -M remains useful?

[mdkeehan]

Ok - I'll reopen it.

Which file would be best to enhance with documentation explaining the "recommendations for use" of the more subtle options? The Readme.md or the bwa.1 man page.

[mdkeehan]

Please see pull request #198

[aallahyar]

Thanks @mdkeehan for this contribution. Indeed this part is not documented well. And I see that even after two years, it's not merged to the main branch yet.

I assume that the README.md file is where the updates are being announced now, as it is 2 years old (bwa.1 man page is 3 years old). I understand that BWA itself is not going o be updated anymore. But the manual could.

I did look around but so far I can not find an official statement from GATK4 people to confirm that indeed supplementary alignments are used as well (if they did, how exactly for example in MarkDuplicates). So I have to do an actual test for this. Please share the link that confirms this, hopefully someone else finds it useful.