# Class SamAlignmentMerger

java.lang.Object
picard.sam.AbstractAlignmentMerger
picard.sam.SamAlignmentMerger

public class SamAlignmentMerger extends AbstractAlignmentMerger
Class that takes in a set of alignment information in SAM format and merges it with the set of all reads for which alignment was attempted, stored in an unmapped SAM file. This class overrides mergeAlignment in AbstractAlignmentNMerger and proceeds on the assumption that the underlying alignment records are aleady in query-name sorted order (true for bwa). If they are not, the mergeAlignment method catches the IllegalStateException, forces a sort of the underlying alignment records, and tries again.

## Nested Class Summary

### Nested classes/interfaces inherited from class AbstractAlignmentMerger

`AbstractAlignmentMerger.UnmappingReadStrategy`

## Field Summary

### Fields inherited from class AbstractAlignmentMerger

`inputIsRegularFile, MAX_RECORDS_IN_RAM, referenceFasta`

## Constructor Summary

Constructors
Constructor
Description
`SamAlignmentMerger(File unmappedBamFile, File targetBamFile, File referenceFasta, htsjdk.samtools.SAMProgramRecord programRecord, boolean clipAdapters, boolean bisulfiteSequence, boolean alignedReadsOnly, List<File> alignedSamFile, int maxGaps, List<String> attributesToRetain, List<String> attributesToRemove, Integer read1BasesTrimmed, Integer read2BasesTrimmed, List<File> read1AlignedSamFile, List<File> read2AlignedSamFile, List<htsjdk.samtools.SamPairUtil.PairOrientation> expectedOrientations, htsjdk.samtools.SAMFileHeader.SortOrder sortOrder, PrimaryAlignmentSelectionStrategy primaryAlignmentSelectionStrategy, boolean addMateCigar, boolean unmapContaminantReads, int minUnclippedBases)`
Constructor with a default value for unmappingReadStrategy
`SamAlignmentMerger(File unmappedBamFile, File targetBamFile, File referenceFasta, htsjdk.samtools.SAMProgramRecord programRecord, boolean clipAdapters, boolean bisulfiteSequence, boolean alignedReadsOnly, List<File> alignedSamFile, int maxGaps, List<String> attributesToRetain, List<String> attributesToRemove, Integer read1BasesTrimmed, Integer read2BasesTrimmed, List<File> read1AlignedSamFile, List<File> read2AlignedSamFile, List<htsjdk.samtools.SamPairUtil.PairOrientation> expectedOrientations, htsjdk.samtools.SAMFileHeader.SortOrder sortOrder, PrimaryAlignmentSelectionStrategy primaryAlignmentSelectionStrategy, boolean addMateCigar, boolean unmapContaminantReads, int minUnclippedBases, AbstractAlignmentMerger.UnmappingReadStrategy unmappingReadStrategy, List<String> requiredMatchingDictionaryTags)`
Constructor

## Method Summary

Modifier and Type
Method
Description
`protected htsjdk.samtools.SAMSequenceDictionary`
`getDictionaryForMergedBam()`
`boolean`
`getForceSort()`
`protected htsjdk.samtools.util.CloseableIterator<htsjdk.samtools.SAMRecord>`
`getQuerynameSortedAlignedRecords()`
Reads the aligned SAM records into a SortingCollection and returns an iterator over that collection
`protected boolean`
`ignoreAlignment(htsjdk.samtools.SAMRecord sam)`
For now, we ignore only those alignments that have more than `maxGaps` insertions or deletions.
`protected boolean`
`isContaminant(picard.sam.HitsForInsert hits)`
Criteria for contaminant reads: 1.
`void`
`mergeAlignment(File referenceFasta)`
Merges the alignment from the map file with the non-aligned records from the source BAM file.

### Methods inherited from class AbstractAlignmentMerger

`clipForOverlappingReads, close, createNewCigarsIfMapsOffEndOfReference, encodeMappingInformation, fixNmMdAndUq, fixUq, getAttributesToReverse, getAttributesToReverseComplement, getHeader, getProgramRecord, isClipOverlappingReads, isKeepAlignerProperPairFlags, isReservedTag, resetRefSeqFileWalker, setAddPGTagToReads, setAttributesToReverse, setAttributesToReverseComplement, setClipOverlappingReads, setHardClipOverlappingReads, setIncludeSecondaryAlignments, setKeepAlignerProperPairFlags, setMaxRecordsInRam, setProgramRecord, setValuesFromAlignment, updateCigarForTrimmedOrClippedBases`

### Methods inherited from class Object

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

## Constructor Details

### SamAlignmentMerger

public SamAlignmentMerger(File unmappedBamFile, File targetBamFile, File referenceFasta, htsjdk.samtools.SAMProgramRecord programRecord, boolean clipAdapters, boolean bisulfiteSequence, boolean alignedReadsOnly, List<File> alignedSamFile, int maxGaps, List<String> attributesToRetain, List<String> attributesToRemove, Integer read1BasesTrimmed, Integer read2BasesTrimmed, List<File> read1AlignedSamFile, List<File> read2AlignedSamFile, List<htsjdk.samtools.SamPairUtil.PairOrientation> expectedOrientations, htsjdk.samtools.SAMFileHeader.SortOrder sortOrder, PrimaryAlignmentSelectionStrategy primaryAlignmentSelectionStrategy, boolean addMateCigar, boolean unmapContaminantReads, int minUnclippedBases)
Constructor with a default value for unmappingReadStrategy

### SamAlignmentMerger

public SamAlignmentMerger(File unmappedBamFile, File targetBamFile, File referenceFasta, htsjdk.samtools.SAMProgramRecord programRecord, boolean clipAdapters, boolean bisulfiteSequence, boolean alignedReadsOnly, List<File> alignedSamFile, int maxGaps, List<String> attributesToRetain, List<String> attributesToRemove, Integer read1BasesTrimmed, Integer read2BasesTrimmed, List<File> read1AlignedSamFile, List<File> read2AlignedSamFile, List<htsjdk.samtools.SamPairUtil.PairOrientation> expectedOrientations, htsjdk.samtools.SAMFileHeader.SortOrder sortOrder, PrimaryAlignmentSelectionStrategy primaryAlignmentSelectionStrategy, boolean addMateCigar, boolean unmapContaminantReads, int minUnclippedBases, AbstractAlignmentMerger.UnmappingReadStrategy unmappingReadStrategy, List<String> requiredMatchingDictionaryTags)
Constructor

Parameters:
  `unmappedBamFile` - The BAM file that was used as the input to the aligner, which will include info on all the reads that did not map. Required.
  `targetBamFile` - The file to which to write the merged SAM records. Required.
  `referenceFasta` - The reference sequence for the map files. Required.
  `programRecord` - Program record for taget file SAMRecords created.
  `clipAdapters` - Whether adapters marked in unmapped BAM file should be marked as soft clipped in the merged bam. Required.
  `bisulfiteSequence` - Whether the reads are bisulfite sequence (used when calculating the NM and UQ tags). Required.
  `alignedReadsOnly` - Whether to output only those reads that have alignment data
  `alignedSamFile` - The SAM file(s) with alignment information. Optional. If this is not provided, then read1AlignedSamFile and read2AlignedSamFile must be.
  `maxGaps` - The maximum number of insertions or deletions permitted in an alignment. Alignments with more than this many gaps will be ignored. -1 means to allow any number of gaps.
  `attributesToRetain` - attributes from the alignment record that should be retained when merging, overridden by attributesToRemove if they share common tags.
  `attributesToRemove` - attributes from the alignment record that should be removed when merging. This overrides attributesToRetain if they share common tags.
  `read1BasesTrimmed` - The number of bases trimmed from start of read 1 prior to alignment. Optional.
  `read2BasesTrimmed` - The number of bases trimmed from start of read 2 prior to alignment. Optional.
  `read1AlignedSamFile` - The alignment records for read1. Used when the two ends of a read are aligned separately. This is optional, but must be specified if alignedSamFile is not.
  `read2AlignedSamFile` - The alignment records for read1. Used when the two ends of a read are aligned separately. This is optional, but must be specified if alignedSamFile is not.
  `expectedOrientations` - A List of SamPairUtil.PairOrientations that are expected for aligned pairs. Used to determine the properPair flag.
  `sortOrder` - The order in which the merged records should be output. If null, output will be coordinate-sorted
  `primaryAlignmentSelectionStrategy` - How to handle multiple alignments for a fragment or read pair, in which none are primary, or more than one is marked primary
  `addMateCigar` - True if we are to add or maintain the mate CIGAR (MC) tag, false if we are to remove or not include.
  `unmapContaminantReads` - If true, identify reads having the signature of cross-species contamination (i.e. mostly clipped bases), and mark them as unmapped.
  `minUnclippedBases` - If unmapContaminantReads is set, require this many unclipped bases or else the read will be marked as contaminant.
  `unmappingReadStrategy` - An enum describing how to deal with reads whose mapping information are being removed (currently this happens due to cross-species contamination). Ignored unless unmapContaminantReads is true.
  `requiredMatchingDictionaryTags` - A list of SAMSequenceRecord tags that must be equal (if present) in the aligned bam and the reference dictionary. Program will issue a warning about other tags, if present in both files and are different.

## Method Details

### mergeAlignment

public void mergeAlignment(File referenceFasta)
Merges the alignment from the map file with the non-aligned records from the source BAM file. Overrides mergeAlignment in AbstractAlignmentMerger. Tries first to proceed on the assumption that the alignment records are pre-sorted. If not, catches the exception, forces a sort, and tries again.

Overrides:
  `mergeAlignment` in class `AbstractAlignmentMerger`

### getDictionaryForMergedBam

protected htsjdk.samtools.SAMSequenceDictionary getDictionaryForMergedBam()

Specified by:
  `getDictionaryForMergedBam` in class `AbstractAlignmentMerger`

### getQuerynameSortedAlignedRecords

protected htsjdk.samtools.util.CloseableIterator<htsjdk.samtools.SAMRecord> getQuerynameSortedAlignedRecords()
Reads the aligned SAM records into a SortingCollection and returns an iterator over that collection

Specified by:
  `getQuerynameSortedAlignedRecords` in class `AbstractAlignmentMerger`

### ignoreAlignment

protected boolean ignoreAlignment(htsjdk.samtools.SAMRecord sam)
For now, we ignore only those alignments that have more than `maxGaps` insertions or deletions.

Overrides:
  `ignoreAlignment` in class `AbstractAlignmentMerger`

### isContaminant

protected boolean isContaminant(picard.sam.HitsForInsert hits)
Criteria for contaminant reads: 1. primary alignment has fewer than minUnclippedBases unclipped bases 2. primary alignment has both ends clipped

Overrides:
  `isContaminant` in class `AbstractAlignmentMerger`

### getForceSort

public boolean getForceSort()