picard.sam

## Class MergeBamAlignment

- java.lang.Object
- - picard.cmdline.CommandLineProgram
  - - picard.sam.MergeBamAlignment

-     public class MergeBamAlignment
      extends CommandLineProgram

  A command-line tool to merge BAM/SAM alignment info from a third-party aligner with the data in an unmapped BAM file, producing a third BAM file that has alignment data and all the additional data from the unmapped BAM

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `Boolean` | `ADD_MATE_CIGAR`
    `List<File>` | `ALIGNED_BAM`
    `boolean` | `ALIGNED_READS_ONLY`
    `boolean` | `ALIGNER_PROPER_PAIR_FLAGS`
    `List<String>` | `ATTRIBUTES_TO_REMOVE`
    `List<String>` | `ATTRIBUTES_TO_RETAIN`
    `boolean` | `CLIP_ADAPTERS`
    `boolean` | `CLIP_OVERLAPPING_READS`
    `List<htsjdk.samtools.SamPairUtil.PairOrientation>` | `EXPECTED_ORIENTATIONS`
    `boolean` | `INCLUDE_SECONDARY_ALIGNMENTS`
    `boolean` | `IS_BISULFITE_SEQUENCE`
    `Integer` | `JUMP_SIZE`
    `int` | `MAX_INSERTIONS_OR_DELETIONS`
    `int` | `MIN_UNCLIPPED_BASES`
    `File` | `OUTPUT`
    `Boolean` | `PAIRED_RUN` Deprecated.
    `picard.sam.MergeBamAlignment.PrimaryAlignmentStrategy` | `PRIMARY_ALIGNMENT_STRATEGY`
    `String` | `PROGRAM_GROUP_COMMAND_LINE`
    `String` | `PROGRAM_GROUP_NAME`
    `String` | `PROGRAM_GROUP_VERSION`
    `String` | `PROGRAM_RECORD_ID`
    `List<File>` | `READ1_ALIGNED_BAM`
    `int` | `READ1_TRIM`
    `List<File>` | `READ2_ALIGNED_BAM`
    `int` | `READ2_TRIM`
    `File` | `REFERENCE_SEQUENCE`
    `htsjdk.samtools.SAMFileHeader.SortOrder` | `SORT_ORDER`
    `boolean` | `UNMAP_CONTAMINANT_READS`
    `File` | `UNMAPPED_BAM`

    - ### Fields inherited from class picard.cmdline.CommandLineProgram

      `COMPRESSION_LEVEL, CREATE_INDEX, CREATE_MD5_FILE, GA4GH_CLIENT_SECRETS, MAX_RECORDS_IN_RAM, QUIET, TMP_DIR, VALIDATION_STRINGENCY, VERBOSITY`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MergeBamAlignment()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected String[]` | `customCommandLineValidation()` Put any custom command-line validation in an override of this method.
    `protected int` | `doWork()` Do the work after command line has been parsed.
    `static void` | `main(String[] argv)` Required main method implementation.

    - ### Methods inherited from class picard.cmdline.CommandLineProgram

      `getCommandLine, getCommandLineParser, getDefaultHeaders, getMetricsFile, getNestedOptions, getNestedOptionsForHelp, getStandardUsagePreamble, getVersion, instanceMain, instanceMainWithExit, parseArgs, setDefaultHeaders`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### UNMAPPED_BAM

          @Option(shortName="UNMAPPED",
                  doc="Original SAM or BAM file of unmapped reads, which must be in queryname order.")
          public File UNMAPPED_BAM

    - #### ALIGNED_BAM

          @Option(shortName="ALIGNED",
                  doc="SAM or BAM file(s) with alignment data.",
                  mutex={"READ1_ALIGNED_BAM","READ2_ALIGNED_BAM"},
                  optional=true)
          public List<File> ALIGNED_BAM

    - #### READ1_ALIGNED_BAM

          @Option(shortName="R1_ALIGNED",
                  doc="SAM or BAM file(s) with alignment data from the first read of a pair.",
                  mutex="ALIGNED_BAM",
                  optional=true)
          public List<File> READ1_ALIGNED_BAM

    - #### READ2_ALIGNED_BAM

          @Option(shortName="R2_ALIGNED",
                  doc="SAM or BAM file(s) with alignment data from the second read of a pair.",
                  mutex="ALIGNED_BAM",
                  optional=true)
          public List<File> READ2_ALIGNED_BAM

    - #### OUTPUT

          @Option(shortName="O",
                  doc="Merged SAM or BAM file to write to.")
          public File OUTPUT

    - #### REFERENCE_SEQUENCE

          @Option(shortName="R",
                  doc="Path to the fasta file for the reference sequence.")
          public File REFERENCE_SEQUENCE

    - #### PROGRAM_RECORD_ID

          @Option(shortName="PG",
                  doc="The program group ID of the aligner (if not supplied by the aligned file).",
                  optional=true)
          public String PROGRAM_RECORD_ID

    - #### PROGRAM_GROUP_VERSION

          @Option(shortName="PG_VERSION",
                  doc="The version of the program group (if not supplied by the aligned file).",
                  optional=true)
          public String PROGRAM_GROUP_VERSION

    - #### PROGRAM_GROUP_COMMAND_LINE

          @Option(shortName="PG_COMMAND",
                  doc="The command line of the program group (if not supplied by the aligned file).",
                  optional=true)
          public String PROGRAM_GROUP_COMMAND_LINE

    - #### PROGRAM_GROUP_NAME

          @Option(shortName="PG_NAME",
                  doc="The name of the program group (if not supplied by the aligned file).",
                  optional=true)
          public String PROGRAM_GROUP_NAME

    - #### PAIRED_RUN

          @Deprecated
           @Option(doc="This argument is ignored and will be removed.",
                  shortName="PE",
                  optional=true)
          public Boolean PAIRED_RUN

      Deprecated.

    - #### JUMP_SIZE

          @Option(doc="The expected jump size (required if this is a jumping library). Deprecated. Use EXPECTED_ORIENTATIONS instead",
                  shortName="JUMP",
                  mutex="EXPECTED_ORIENTATIONS",
                  optional=true)
          public Integer JUMP_SIZE

    - #### CLIP_ADAPTERS

          @Option(doc="Whether to clip adapters where identified.")
          public boolean CLIP_ADAPTERS

    - #### IS_BISULFITE_SEQUENCE

          @Option(doc="Whether the lane is bisulfite sequence (used when caculating the NM tag).")
          public boolean IS_BISULFITE_SEQUENCE

    - #### ALIGNED_READS_ONLY

          @Option(doc="Whether to output only aligned reads.  ")
          public boolean ALIGNED_READS_ONLY

    - #### MAX_INSERTIONS_OR_DELETIONS

          @Option(doc="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.",
                  shortName="MAX_GAPS")
          public int MAX_INSERTIONS_OR_DELETIONS

    - #### ATTRIBUTES_TO_RETAIN

          @Option(doc="Reserved alignment attributes (tags starting with X, Y, or Z) that should be brought over from the alignment data when merging.")
          public List<String> ATTRIBUTES_TO_RETAIN

    - #### ATTRIBUTES_TO_REMOVE

          @Option(doc="Attributes from the alignment record that should be removed when merging.  This overrides ATTRIBUTES_TO_RETAIN if they share common tags.")
          public List<String> ATTRIBUTES_TO_REMOVE

    - #### READ1_TRIM

          @Option(shortName="R1_TRIM",
                  doc="The number of bases trimmed from the beginning of read 1 prior to alignment")
          public int READ1_TRIM

    - #### READ2_TRIM

          @Option(shortName="R2_TRIM",
                  doc="The number of bases trimmed from the beginning of read 2 prior to alignment")
          public int READ2_TRIM

    - #### EXPECTED_ORIENTATIONS

          @Option(shortName="ORIENTATIONS",
                  doc="The expected orientation of proper read pairs. Replaces JUMP_SIZE",
                  mutex="JUMP_SIZE",
                  optional=true)
          public List<htsjdk.samtools.SamPairUtil.PairOrientation> EXPECTED_ORIENTATIONS

    - #### ALIGNER_PROPER_PAIR_FLAGS

          @Option(doc="Use the aligner\'s idea of what a proper pair is rather than computing in this program.")
          public boolean ALIGNER_PROPER_PAIR_FLAGS

    - #### SORT_ORDER

          @Option(shortName="SO",
                  doc="The order in which the merged reads should be output.")
          public htsjdk.samtools.SAMFileHeader.SortOrder SORT_ORDER

    - #### PRIMARY_ALIGNMENT_STRATEGY

          @Option(doc="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.")
          public picard.sam.MergeBamAlignment.PrimaryAlignmentStrategy PRIMARY_ALIGNMENT_STRATEGY

    - #### CLIP_OVERLAPPING_READS

          @Option(doc="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.")
          public boolean CLIP_OVERLAPPING_READS

    - #### INCLUDE_SECONDARY_ALIGNMENTS

          @Option(doc="If false, do not write secondary alignments to output.")
          public boolean INCLUDE_SECONDARY_ALIGNMENTS

    - #### ADD_MATE_CIGAR

          @Option(shortName="MC",
                  optional=true,
                  doc="Adds the mate CIGAR tag (MC) if true, does not if false.")
          public Boolean ADD_MATE_CIGAR

    - #### UNMAP_CONTAMINANT_READS

          @Option(shortName="UNMAP_CONTAM",
                  optional=true,
                  doc="Detect reads originating from foreign organisms (e.g. bacterial DNA in a non-bacterial sample),and unmap + label those reads accordingly.")
          public boolean UNMAP_CONTAMINANT_READS

    - #### MIN_UNCLIPPED_BASES

          @Option(doc="If UNMAP_CONTAMINANT_READS is set, require this many unclipped bases or else the read will be marked as contaminant.")
          public int MIN_UNCLIPPED_BASES

  - ### Constructor Detail

    - #### MergeBamAlignment

          public MergeBamAlignment()

  - ### Method Detail

    - #### main

          public static void main(String[] argv)

      Required main method implementation.

    - #### doWork

          protected int doWork()

      Description copied from class: `CommandLineProgram`
      Do the work after command line has been parsed. RuntimeException may be thrown by this method, and are reported appropriately.
      Specified by:
        `doWork` in class `CommandLineProgram`
      Returns:
        program exit status.

    - #### customCommandLineValidation

          protected String[] customCommandLineValidation()

      Put any custom command-line validation in an override of this method. clp is initialized at this point and can be used to print usage and access argv. Any options set by command-line parser can be validated.
      Overrides:
        `customCommandLineValidation` in class `CommandLineProgram`
      Returns:
        null if command line is valid. If command line is invalid, returns an array of error messages to be written to the appropriate place.