Merge alignment data from a SAM or BAM with data in an unmapped BAM file. This tool produces a new SAM or BAM file that includes all aligned and unaligned reads and also carries forward additional read attributes from the unmapped BAM (attributes that are otherwise lost in the process of alignment). The purpose of this tool is to use information from the unmapped BAM to fix up aligner output. The resulting file will be valid for use by other Picard tools. For simple BAM file merges, use MergeSamFiles. Note that MergeBamAlignment expects to find a sequence dictionary in the same directory as REFERENCE_SEQUENCE and expects it to have the same base name as the reference FASTA except with the extension ".dict". If the output sort order is not coordinate, then reads that are clipped due to adapters or overlapping will not contain the NM, MD, or UQ tags.
java -jar picard.jar MergeBamAlignment ALIGNED=aligned.bam UNMAPPED=unmapped.bam O=merge_alignments.bam R=reference_sequence.fasta
UNMAPPED_BAM (File) Original SAM or BAM file of unmapped reads, which must be in queryname order. Required.
ALIGNED_BAM (File) SAM or BAM file(s) with alignment data. Default value: null. This option may be specified 0 or more times. Cannot be used in conjuction with option(s) READ1_ALIGNED_BAM (R1_ALIGNED) READ2_ALIGNED_BAM (R2_ALIGNED)
READ1_ALIGNED_BAM (File) SAM or BAM file(s) with alignment data from the first read of a pair. Default value: null. This option may be specified 0 or more times. Cannot be used in conjuction with option(s) ALIGNED_BAM (ALIGNED)
READ2_ALIGNED_BAM (File) SAM or BAM file(s) with alignment data from the second read of a pair. Default value: null. This option may be specified 0 or more times. Cannot be used in conjuction with option(s) ALIGNED_BAM (ALIGNED)
OUTPUT (File) Merged SAM or BAM file to write to. Required.
REFERENCE_SEQUENCE (File) Path to the fasta file for the reference sequence. Required.
PROGRAM_RECORD_ID (String) The program group ID of the aligner (if not supplied by the aligned file). Default value: null.
PROGRAM_GROUP_VERSION (String) The version of the program group (if not supplied by the aligned file). Default value: null.
PROGRAM_GROUP_COMMAND_LINE (String) The command line of the program group (if not supplied by the aligned file). Default value: null.
PROGRAM_GROUP_NAME (String) The name of the program group (if not supplied by the aligned file). Default value: null.
PAIRED_RUN (Boolean) This argument is ignored and will be removed. Default value: true. This option can be set to 'null' to clear the default value. Possible values: {true, false}
JUMP_SIZE (Integer) The expected jump size (required if this is a jumping library). Deprecated. Use EXPECTED_ORIENTATIONS instead Default value: null. Cannot be used in conjuction with option(s) EXPECTED_ORIENTATIONS (ORIENTATIONS)
CLIP_ADAPTERS (Boolean) Whether to clip adapters where identified. Default value: true. This option can be set to 'null' to clear the default value. Possible values: {true, false}
IS_BISULFITE_SEQUENCE (Boolean) Whether the lane is bisulfite sequence (used when calculating the NM tag). Default value: false. This option can be set to 'null' to clear the default value. Possible values: {true, false}
ALIGNED_READS_ONLY (Boolean) Whether to output only aligned reads. Default value: false. This option can be set to 'null' to clear the default value. Possible values: {true, false}
MAX_INSERTIONS_OR_DELETIONS (Integer) The maximum number of insertions or deletions permitted for an alignment to be included. Alignments with more than this many insertions or deletions will be ignored. Set to -1 to allow any number of insertions or deletions. Default value: 1. This option can be set to 'null' to clear the default value.
ATTRIBUTES_TO_RETAIN (String) Reserved alignment attributes (tags starting with X, Y, or Z) that should be brought over from the alignment data when merging. Default value: null. This option may be specified 0 or more times.
ATTRIBUTES_TO_REMOVE (String) Attributes from the alignment record that should be removed when merging. This overrides ATTRIBUTES_TO_RETAIN if they share common tags. Default value: null. This option may be specified 0 or more times.
ATTRIBUTES_TO_REVERSE (String) Attributes on negative strand reads that need to be reversed. Default value: [OQ, U2]. This option can be set to 'null' to clear the default value. This option may be specified 0 or more times. This option can be set to 'null' to clear the default list.
ATTRIBUTES_TO_REVERSE_COMPLEMENT (String) Attributes on negative strand reads that need to be reverse complemented. Default value: [E2, SQ]. This option can be set to 'null' to clear the default value. This option may be specified 0 or more times. This option can be set to 'null' to clear the default list.
READ1_TRIM (Integer) The number of bases trimmed from the beginning of read 1 prior to alignment Default value: 0. This option can be set to 'null' to clear the default value.
READ2_TRIM (Integer) The number of bases trimmed from the beginning of read 2 prior to alignment Default value: 0. This option can be set to 'null' to clear the default value.
EXPECTED_ORIENTATIONS (PairOrientation) The expected orientation of proper read pairs. Replaces JUMP_SIZE Default value: null. Possible values: {FR, RF, TANDEM} This option may be specified 0 or more times. Cannot be used in conjuction with option(s) JUMP_SIZE (JUMP)
ALIGNER_PROPER_PAIR_FLAGS (Boolean) Use the aligner's idea of what a proper pair is rather than computing in this program. Default value: false. This option can be set to 'null' to clear the default value. Possible values: {true, false}
SORT_ORDER (SortOrder) The order in which the merged reads should be output. Default value: coordinate. This option can be set to 'null' to clear the default value. Possible values: {unsorted, queryname, coordinate, duplicate}
PRIMARY_ALIGNMENT_STRATEGY (PrimaryAlignmentStrategy) Strategy for selecting primary alignment when the aligner has provided more than one alignment for a pair or fragment, and none are marked as primary, more than one is marked as primary, or the primary alignment is filtered out for some reason. BestMapq expects that multiple alignments will be correlated with HI tag, and prefers the pair of alignments with the largest MAPQ, in the absence of a primary selected by the aligner. EarliestFragment prefers the alignment which maps the earliest base in the read. Note that EarliestFragment may not be used for paired reads. BestEndMapq is appropriate for cases in which the aligner is not pair-aware, and does not output the HI tag. It simply picks the alignment for each end with the highest MAPQ, and makes those alignments primary, regardless of whether the two alignments make sense together.MostDistant is also for a non-pair-aware aligner, and picks the alignment pair with the largest insert size. If all alignments would be chimeric, it picks the alignments for each end with the best MAPQ. For all algorithms, ties are resolved arbitrarily. Default value: BestMapq. This option can be set to 'null' to clear the default value. Possible values: {BestMapq, EarliestFragment, BestEndMapq, MostDistant}
CLIP_OVERLAPPING_READS (Boolean) For paired reads, soft clip the 3' end of each read if necessary so that it does not extend past the 5' end of its mate. Default value: true. This option can be set to 'null' to clear the default value. Possible values: {true, false}
INCLUDE_SECONDARY_ALIGNMENTS (Boolean) If false, do not write secondary alignments to output. Default value: true. This option can be set to 'null' to clear the default value. Possible values: {true, false}
ADD_MATE_CIGAR (Boolean) Adds the mate CIGAR tag (MC) if true, does not if false. Default value: true. This option can be set to 'null' to clear the default value. Possible values: {true, false}
UNMAP_CONTAMINANT_READS (Boolean) Detect reads originating from foreign organisms (e.g. bacterial DNA in a non-bacterial sample),and unmap + label those reads accordingly. Default value: false. This option can be set to 'null' to clear the default value. Possible values: {true, false}
MIN_UNCLIPPED_BASES (Integer) If UNMAP_CONTAMINANT_READS is set, require this many unclipped bases or else the read will be marked as contaminant. Default value: 32. This option can be set to 'null' to clear the default value.
MATCHING_DICTIONARY_TAGS (String) List of Sequence Records tags that must be equal (if present) in the reference dictionary and in the aligned file. Mismatching tags will cause an error if in this list, and a warning otherwise. Default value: [M5, LN]. This option can be set to 'null' to clear the default value. This option may be specified 0 or more times. This option can be set to 'null' to clear the default list.
UNMAPPED_READ_STRATEGY (UnmappingReadStrategy) How to deal with alignment information in reads that are being unmapped (e.g. due to cross-species contamination.) Currently ignored unless UNMAP_CONTAMINANT_READS = true Default value: DO_NOT_CHANGE. This option can be set to 'null' to clear the default value. Possible values: {COPY_TO_TAG, DO_NOT_CHANGE, MOVE_TO_TAG}