# Class SamPairUtil

java.lang.Object
htsjdk.samtools.SamPairUtil

public class SamPairUtil extends Object
Utility methods for pairs of SAMRecords

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static enum`
`SamPairUtil.PairOrientation`
The possible orientations of paired reads.
`static class`
`SamPairUtil.SetMateInfoIterator`
A class to iterate through SAMRecords and set mate information on the given records, and optionally set the mate cigar tag (true by default).

## Constructor Summary

Constructors
Constructor
Description
`SamPairUtil()`

## Method Summary

Modifier and Type
Method
Description
`static void`
`assertMate(SAMRecord firstOfPair, SAMRecord secondOfPair)`
`static int`
`computeInsertSize(SAMRecord firstEnd, SAMRecord secondEnd)`
Compute SAMRecord insert size
`static SamPairUtil.PairOrientation`
`getPairOrientation(SAMRecord record)`
Computes the pair orientation of the given SAMRecord.
`static boolean`
`isProperPair(SAMRecord firstEnd, SAMRecord secondEnd, List<SamPairUtil.PairOrientation> expectedOrientations)`
`static SAMRecord`
`obtainAssertedMate(Iterator<SAMRecord> samRecordIterator, SAMRecord firstOfPair)`
Obtain the secondOfPair mate belonging to the firstOfPair SAMRecord (assumed to be in the next element of the specified samRecordIterator)
`static void`
`setMateInfo(SAMRecord rec1, SAMRecord rec2)`
Write the mate info for two SAMRecords.
`static void`
`setMateInfo(SAMRecord rec1, SAMRecord rec2, boolean setMateCigar)`
Write the mate info for two SAMRecords
`static void`
`setMateInfo(SAMRecord rec1, SAMRecord rec2, SAMFileHeader header)`
Deprecated.
use `setMateInfo(SAMRecord, SAMRecord)` instead
`static void`
`setMateInfo(SAMRecord rec1, SAMRecord rec2, SAMFileHeader header, boolean setMateCigar)`
Deprecated.
use `setMateInfo(SAMRecord, SAMRecord, boolean)` instead
`static void`
`setMateInformationOnSupplementalAlignment(SAMRecord supplemental, SAMRecord matePrimary)`
Sets mate pair information appropriately on a supplemental SAMRecord (e.g.
`static void`
`setMateInformationOnSupplementalAlignment(SAMRecord supplemental, SAMRecord matePrimary, boolean setMateCigar)`
Sets mate pair information appropriately on a supplemental SAMRecord (e.g.
`static void`
`setProperPairAndMateInfo(SAMRecord rec1, SAMRecord rec2, SAMFileHeader header, List<SamPairUtil.PairOrientation> expectedOrientations)`
Deprecated.
use `setProperPairAndMateInfo(SAMRecord, SAMRecord, List)` instead
`static void`
`setProperPairAndMateInfo(SAMRecord rec1, SAMRecord rec2, SAMFileHeader header, List<SamPairUtil.PairOrientation> expectedOrientations, boolean addMateCigar)`
Deprecated.
use `setProperPairAndMateInfo(SAMRecord, SAMRecord, List, boolean)`
`static void`
`setProperPairAndMateInfo(SAMRecord rec1, SAMRecord rec2, List<SamPairUtil.PairOrientation> expectedOrientations)`
This method will clear any mate cigar already present.
`static void`
`setProperPairAndMateInfo(SAMRecord rec1, SAMRecord rec2, List<SamPairUtil.PairOrientation> expectedOrientations, boolean addMateCigar)`
`static void`
`setProperPairFlags(SAMRecord rec1, SAMRecord rec2, List<SamPairUtil.PairOrientation> expectedOrientations)`

### Methods inherited from class Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### SamPairUtil

public SamPairUtil()

## Method Details

### getPairOrientation

public static SamPairUtil.PairOrientation getPairOrientation(SAMRecord record)
Computes the pair orientation of the given SAMRecord.

Parameters:
  `record` - the record for which the pair orientation is requested
Returns:
  PairOrientation of the given SAMRecord.
Throws:
  `IllegalArgumentException` - If the record is not a paired read, or one or both reads are unmapped, or if the two records are not mapped to the same reference. NOTA BENE: This is NOT the orientation byte as used in Picard's MarkDuplicates. For that please look in ReadEnds (in Picard). When the record is on the forward strand, the mate's 5' position is computed from the mate CIGAR (MC) tag if present, and otherwise falls back to `CoordMath.getEnd(getAlignmentStart(), getInferredInsertSize())`. The fallback is exact for TLEN values written under htsjdk's 5'-to-5' convention (see `computeInsertSize(SAMRecord, SAMRecord)`) but can still produce asymmetric results on dovetail pairs when TLEN was written under SAM v1 §1.4's leftmost-to-rightmost convention. Callers that need symmetric orientation on such pairs should ensure the MC tag is set on at least the forward-strand record.

### isProperPair

public static boolean isProperPair(SAMRecord firstEnd, SAMRecord secondEnd, List<SamPairUtil.PairOrientation> expectedOrientations)

### assertMate

public static void assertMate(SAMRecord firstOfPair, SAMRecord secondOfPair)

### obtainAssertedMate

public static SAMRecord obtainAssertedMate(Iterator<SAMRecord> samRecordIterator, SAMRecord firstOfPair)
Obtain the secondOfPair mate belonging to the firstOfPair SAMRecord (assumed to be in the next element of the specified samRecordIterator)

Parameters:
  `samRecordIterator` - the iterator assumed to contain the secondOfPair SAMRecord in the next element in the iteration
  `firstOfPair` - the firstOfPair SAMRecord
Returns:
  the secondOfPair SAMRecord
Throws:
  `SAMException` - when the secondOfPair mate cannot be obtained due to assertion failures

### computeInsertSize

public static int computeInsertSize(SAMRecord firstEnd, SAMRecord secondEnd)
Compute SAMRecord insert size

Parameters:
  `firstEnd` -
  `secondEnd` -
Returns:
  note that when storing insert size on the secondEnd, the return value must be negated.

### setMateInfo

public static void setMateInfo(SAMRecord rec1, SAMRecord rec2)
Write the mate info for two SAMRecords. This will always clear/remove any mate cigar tag that is present.

Parameters:
  `rec1` - the first SAM record
  `rec2` - the second SAM record

### setMateInfo

public static void setMateInfo(SAMRecord rec1, SAMRecord rec2, boolean setMateCigar)
Write the mate info for two SAMRecords

Parameters:
  `rec1` - the first SAM record. Must have a non-null SAMFileHeader.
  `rec2` - the second SAM record. Must have a non-null SAMFileHeader.
  `setMateCigar` - true if we are to update/create the Mate CIGAR (MC) optional tag, false if we are to clear any mate cigar tag that is present.

### setMateInfo

@Deprecated public static void setMateInfo(SAMRecord rec1, SAMRecord rec2, SAMFileHeader header, boolean setMateCigar)
Deprecated.
use `setMateInfo(SAMRecord, SAMRecord, boolean)` instead
Write the mate info for two SAMRecords

Parameters:
  `rec1` - the first SAM record
  `rec2` - the second SAM record
  `header` - the SAM file header
  `setMateCigar` - true if we are to update/create the Mate CIGAR (MC) optional tag, false if we are to clear any mate cigar tag that is present.

### setMateInfo

@Deprecated public static void setMateInfo(SAMRecord rec1, SAMRecord rec2, SAMFileHeader header)
Deprecated.
use `setMateInfo(SAMRecord, SAMRecord)` instead
Write the mate info for two SAMRecords. This will always clear/remove any mate cigar tag that is present.

Parameters:
  `rec1` - the first SAM record
  `rec2` - the second SAM record
  `header` - the SAM file header

### setMateInformationOnSupplementalAlignment

public static void setMateInformationOnSupplementalAlignment(SAMRecord supplemental, SAMRecord matePrimary, boolean setMateCigar)
Sets mate pair information appropriately on a supplemental SAMRecord (e.g. from a split alignment) using the primary alignment of the read's mate.

Parameters:
  `supplemental` - a supplemental alignment for the mate pair of the primary supplied
  `matePrimary` - the primary alignment of the the mate pair of the supplemental
  `setMateCigar` - true if we are to update/create the Mate CIGAR (MC) optional tag, false if we are to clear any mate cigar tag that is present.

### setMateInformationOnSupplementalAlignment

public static void setMateInformationOnSupplementalAlignment(SAMRecord supplemental, SAMRecord matePrimary)
Sets mate pair information appropriately on a supplemental SAMRecord (e.g. from a split alignment) using the primary alignment of the read's mate.

Parameters:
  `supplemental` - a supplemental alignment for the mate pair of the primary supplied
  `matePrimary` - the primary alignment of the the mate pair of the supplemental

### setProperPairAndMateInfo

@Deprecated public static void setProperPairAndMateInfo(SAMRecord rec1, SAMRecord rec2, SAMFileHeader header, List<SamPairUtil.PairOrientation> expectedOrientations)
Deprecated.
use `setProperPairAndMateInfo(SAMRecord, SAMRecord, List)` instead
This method will clear any mate cigar already present.

### setProperPairAndMateInfo

@Deprecated public static void setProperPairAndMateInfo(SAMRecord rec1, SAMRecord rec2, SAMFileHeader header, List<SamPairUtil.PairOrientation> expectedOrientations, boolean addMateCigar)
Deprecated.
use `setProperPairAndMateInfo(SAMRecord, SAMRecord, List, boolean)`

Parameters:
  `addMateCigar` - true if we are to update/create the Mate CIGAR (MC) optional tag, false if we are to clear any mate cigar tag that is present.

### setProperPairAndMateInfo

public static void setProperPairAndMateInfo(SAMRecord rec1, SAMRecord rec2, List<SamPairUtil.PairOrientation> expectedOrientations)
This method will clear any mate cigar already present.

### setProperPairAndMateInfo

public static void setProperPairAndMateInfo(SAMRecord rec1, SAMRecord rec2, List<SamPairUtil.PairOrientation> expectedOrientations, boolean addMateCigar)

Parameters:
  `addMateCigar` - true if we are to update/create the Mate CIGAR (MC) optional tag, false if we are to clear any mate cigar tag that is present.

### setProperPairFlags

public static void setProperPairFlags(SAMRecord rec1, SAMRecord rec2, List<SamPairUtil.PairOrientation> expectedOrientations)