Fixing API incomplete functionality for read side detection

[agalitsyna]

What was wrong?

• Detection of the read side was not functional with some aligners after API refactoring 9d99660

Technical description of the issue:

• Detection of the read side was moved from push_pysam to group_alignments_by_side, which relied on sam.is_read1 attribute of pysam entry. It simply does not always work as intended in pysam, and detection of the read side shall be done by sam.flag instead, like was done in

  pairtools/pairtools/lib/parse.py

  Lines 220 to 227 in 6303de6

  	def push_pysam(sam_entry, sams1, sams2):
  	"""Parse pysam AlignedSegment (sam) into pairtools sams entry"""
  	flag = sam_entry.flag
  	if (flag & 0x40) != 0:
  	sams1.append(sam_entry) # left read, or first read in a pair
  	else:
  	sams2.append(sam_entry) # right read, or mate pair
  	return

• Inappropriate detection of the read side probably resulted in sometimes reporting the read side, potentially depending on the aligner. It did not work for single-end reads reported in issue single-end mode is broken in v1.1.0 #247.

Solution:

• group_alignments_by_side was refactored and fully merged with the old push_pysam function.

I did not design any specific test, as existing tests cover parse and parse2 read side detection; they just cannot cover all possible aligners that can report read side differently.

[agalitsyna]

Another issue with readID transformation pointed out by #247 (comment) : readID transformation was applied to the readID only upon reading the first alignment.
Now this functionality was moved to read_alignment_block completely.

[agalitsyna]

Fixed --expand not working together with --single-end.
Issue was inherited from earlier versions, highlighter by #247 (comment)

[golobor]

looks good to me, good to merge!

[golobor]

btw, why do we use "outer" as the default? Wouldn't junction make more sense?

[agalitsyna]

Ah, "outer" makes the output interpretation similar to traditional Hi-C (as if there pairs were sequences by paired-end seq)!

[agalitsyna]

I'll merge it for now (current version keeps the default that we have had already; I've just expanded the docs). Feel free to update anytime if you think it's critical, though!