Package picard.sam

## Class MergeSamFiles

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

-     @DocumentedFeature
      public class MergeSamFiles
      extends CommandLineProgram

  This tool is used for combining SAM and/or BAM files from different runs or read groups into a single file, similar to the \"merge\" function of Samtools (http://www.htslib.org/doc/samtools.html).
  Note that to prevent errors in downstream processing, it is critical to identify/label read groups appropriately. If different samples contain identical read group IDs, this tool will avoid collisions by modifying the read group IDs to be unique. For more information about read groups, see the GATK Dictionary entry.

  #### Usage example:

       java -jar picard.jar MergeSamFiles \\

            I=input_1.bam \\

            I=input_2.bam \\

            O=output_merged_files.bam

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `boolean` | `ASSUME_SORTED` |
    `List<String>` | `COMMENT` |
    `List<File>` | `INPUT` |
    `File` | `INTERVALS` |
    `boolean` | `MERGE_SEQUENCE_DICTIONARIES` |
    `File` | `OUTPUT` |
    `htsjdk.samtools.SAMFileHeader.SortOrder` | `SORT_ORDER` |
    `boolean` | `USE_THREADING` |

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

      `COMPRESSION_LEVEL, CREATE_INDEX, CREATE_MD5_FILE, GA4GH_CLIENT_SECRETS, MAX_RECORDS_IN_RAM, QUIET, REFERENCE_SEQUENCE, referenceSequence, specialArgumentsCollection, TMP_DIR, USE_JDK_DEFLATER, USE_JDK_INFLATER, VALIDATION_STRINGENCY, VERBOSITY`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `MergeSamFiles()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected String[]` | `customCommandLineValidation()` | Put any custom command-line validation in an override of this method.
    `protected int` | `doWork()` | Combines multiple SAM/BAM files into one.
    `static void` | `main​(String[] argv)` | Required main method implementation.

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

      `getCommandLine, getCommandLineParser, getDefaultHeaders, getFaqLink, getMetricsFile, getStandardUsagePreamble, getStandardUsagePreamble, getVersion, hasWebDocumentation, instanceMain, instanceMainWithExit, makeReferenceArgumentCollection, parseArgs, requiresReference, setDefaultHeaders, useLegacyParser`

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

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

- - ### Field Detail

    - #### INPUT

          @Argument(shortName="I",
                    doc="SAM or BAM input file",
                    minElements=1)
          public List<File> INPUT

    - #### OUTPUT

          @Argument(shortName="O",
                    doc="SAM or BAM file to write merged result to")
          public File OUTPUT

    - #### SORT_ORDER

          @Argument(shortName="SO",
                    doc="Sort order of output file",
                    optional=true)
          public htsjdk.samtools.SAMFileHeader.SortOrder SORT_ORDER

    - #### ASSUME_SORTED

          @Argument(doc="If true, assume that the input files are in the same sort order as the requested output sort order, even if their headers say otherwise.",
                    shortName="AS")
          public boolean ASSUME_SORTED

    - #### MERGE_SEQUENCE_DICTIONARIES

          @Argument(shortName="MSD",
                    doc="Merge the sequence dictionaries",
                    optional=true)
          public boolean MERGE_SEQUENCE_DICTIONARIES

    - #### USE_THREADING

          @Argument(doc="Option to create a background thread to encode, compress and write to disk the output file. The threaded version uses about 20% more CPU and decreases runtime by ~20% when writing out a compressed BAM file.")
          public boolean USE_THREADING

    - #### COMMENT

          @Argument(doc="Comment(s) to include in the merged output file\'s header.",
                    optional=true,
                    shortName="CO")
          public List<String> COMMENT

    - #### INTERVALS

          @Argument(shortName="RGN",
                    doc="An interval list file that contains the locations of the positions to merge. Assume bam are sorted and indexed. The resulting file will contain alignments that may overlap with genomic regions outside the requested region. Unmapped reads are discarded.",
                    optional=true)
          public File INTERVALS

  - ### Constructor Detail

    - #### MergeSamFiles

          public MergeSamFiles()

  - ### Method Detail

    - #### main

          public static void main​(String[] argv)

      Required main method implementation.

    - #### doWork

          protected int doWork()

      Combines multiple SAM/BAM files into one.
      Specified by:
        `doWork` in class `CommandLineProgram`
      Returns:
        program exit status.

    - #### customCommandLineValidation

          protected String[] customCommandLineValidation()

      Description copied from class: `CommandLineProgram`
      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 message to be written to the appropriate place.