picard.cmdline

## Class CommandLineProgram

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

- Direct Known Subclasses:
    AbstractOpticalDuplicateFinderCommandLineProgram, AddCommentsToBam, AddOrReplaceReadGroups, BaitDesigner, BamIndexStats, BamToBfq, BedToIntervalList, BuildBamIndex, CalculateReadGroupChecksum, CheckFingerprint, CheckIlluminaDirectory, CheckTerminatorBlock, CleanSam, CollectHiSeqXPfFailMetrics, CollectIlluminaBasecallingMetrics, CollectIlluminaLaneMetrics, CollectIndependentReplicateMetrics, CollectJumpingLibraryMetrics, CollectMultipleMetrics, CollectOxoGMetrics, CollectRrbsMetrics, CollectTargetedMetrics, CollectVariantCallingMetrics, CollectWgsMetrics, CollectWgsMetricsFromQuerySorted, CompareMetrics, CompareSAMs, ConvertSequencingArtifactToOxoG, CreateSequenceDictionary, CrosscheckReadGroupFingerprints, DownsampleSam, ExtractIlluminaBarcodes, ExtractSequences, FastqToSam, FifoBuffer, FilterSamReads, FilterVcf, FindMendelianViolations, FixMateInformation, FixVcfHeader, GatherBamFiles, GatherVcfs, GenotypeConcordance, IlluminaBasecallsToFastq, IlluminaBasecallsToSam, IntervalListToBed, IntervalListTools, LiftOverIntervalList, LiftoverVcf, MakeSitesOnlyVcf, MarkIlluminaAdapters, MergeBamAlignment, MergeSamFiles, MergeVcfs, NonNFastaSize, NormalizeFasta, PositionBasedDownsampleSam, RenameSampleInVcf, ReorderSam, ReplaceSamHeader, RevertOriginalBaseQualitiesAndAddMateCigar, RevertSam, SamFormatConverter, SamToFastq, ScatterIntervalsByNs, SetNmMdAndUqTags, SinglePassSamProgram, SortSam, SortVcf, SplitSamByLibrary, SplitVcfs, UpdateVcfSequenceDictionary, ValidateSamFile, VcfFormatConverter, VcfToIntervalList, ViewSam

      public abstract class CommandLineProgram
      extends Object

  Abstract class to facilitate writing command-line programs. To use: 1. Extend this class with a concrete class that has data members annotated with @Option, @PositionalArguments and/or @Usage annotations. 2. If there is any custom command-line validation, override customCommandLineValidation(). When this method is called, the command line has been parsed and set into the data members of the concrete class. 3. Implement a method doWork(). This is called after successful command-line processing. The value it returns is the exit status of the program. It is assumed that the concrete class emits any appropriate error message before returning non-zero. doWork() may throw unchecked exceptions, which are caught and reported appropriately. 4. Implement the following static method in the concrete class: public static void main(String[] argv) { new MyConcreteClass().instanceMain(argv); }

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `int` | `COMPRESSION_LEVEL`
    `Boolean` | `CREATE_INDEX`
    `boolean` | `CREATE_MD5_FILE`
    `String` | `GA4GH_CLIENT_SECRETS`
    `Integer` | `MAX_RECORDS_IN_RAM`
    `Boolean` | `QUIET`
    `File` | `REFERENCE_SEQUENCE`
    `List<File>` | `TMP_DIR`
    `htsjdk.samtools.ValidationStringency` | `VALIDATION_STRINGENCY`
    `htsjdk.samtools.util.Log.LogLevel` | `VERBOSITY`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CommandLineProgram()`

  - ### Method Summary

    All Methods Instance Methods Abstract 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 abstract int` | `doWork()` Do the work after command line has been parsed.
    `String` | `getCommandLine()`
    `CommandLineParser` | `getCommandLineParser()`
    `List<htsjdk.samtools.metrics.Header>` | `getDefaultHeaders()`
    `protected <A extends htsjdk.samtools.metrics.MetricBase,B extends Comparable<?>> htsjdk.samtools.metrics.MetricsFile<A,B>` | `getMetricsFile()` Gets a MetricsFile with default headers already written into it.
    `Map<String,Object>` | `getNestedOptions()`
    `Map<String,Object>` | `getNestedOptionsForHelp()`
    `String` | `getStandardUsagePreamble()`
    `String` | `getVersion()`
    `int` | `instanceMain(String[] argv)`
    `void` | `instanceMainWithExit(String[] argv)`
    `protected boolean` | `parseArgs(String[] argv)`
    `void` | `setDefaultHeaders(List<htsjdk.samtools.metrics.Header> headers)`

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

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

- - ### Field Detail

    - #### TMP_DIR

          @Option(common=true,
                  optional=true)
          public List<File> TMP_DIR

    - #### VERBOSITY

          @Option(doc="Control verbosity of logging.",
                  common=true)
          public htsjdk.samtools.util.Log.LogLevel VERBOSITY

    - #### QUIET

          @Option(doc="Whether to suppress job-summary info on System.err.",
                  common=true)
          public Boolean QUIET

    - #### VALIDATION_STRINGENCY

          @Option(doc="Validation stringency for all SAM files read by this program.  Setting stringency to SILENT can improve performance when processing a BAM file in which variable-length data (read, qualities, tags) do not otherwise need to be decoded.",
                  common=true)
          public htsjdk.samtools.ValidationStringency VALIDATION_STRINGENCY

    - #### COMPRESSION_LEVEL

          @Option(doc="Compression level for all compressed files created (e.g. BAM and GELI).",
                  common=true)
          public int COMPRESSION_LEVEL

    - #### MAX_RECORDS_IN_RAM

          @Option(doc="When writing SAM files that need to be sorted, this will specify the number of records stored in RAM before spilling to disk. Increasing this number reduces the number of file handles needed to sort a SAM file, and increases the amount of RAM needed.",
                  optional=true,
                  common=true)
          public Integer MAX_RECORDS_IN_RAM

    - #### CREATE_INDEX

          @Option(doc="Whether to create a BAM index when writing a coordinate-sorted BAM file.",
                  common=true)
          public Boolean CREATE_INDEX

    - #### CREATE_MD5_FILE

          @Option(doc="Whether to create an MD5 digest for any BAM or FASTQ files created.  ",
                  common=true)
          public boolean CREATE_MD5_FILE

    - #### REFERENCE_SEQUENCE

          @Option(shortName="R",
                  doc="Reference sequence file.",
                  common=true,
                  optional=true,
                  overridable=true)
          public File REFERENCE_SEQUENCE

    - #### GA4GH_CLIENT_SECRETS

          @Option(doc="Google Genomics API client_secrets.json file path.",
                  common=true)
          public String GA4GH_CLIENT_SECRETS

  - ### Constructor Detail

    - #### CommandLineProgram

          public CommandLineProgram()

  - ### Method Detail

    - #### doWork

          protected abstract int doWork()

      Do the work after command line has been parsed. RuntimeException may be thrown by this method, and are reported appropriately.
      Returns:
        program exit status.

    - #### instanceMainWithExit

          public void instanceMainWithExit(String[] argv)

    - #### instanceMain

          public int instanceMain(String[] argv)

    - #### 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.
      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.

    - #### parseArgs

          protected boolean parseArgs(String[] argv)

      Returns:
        true if command line is valid

    - #### getMetricsFile

          protected <A extends htsjdk.samtools.metrics.MetricBase,B extends Comparable<?>> htsjdk.samtools.metrics.MetricsFile<A,B> getMetricsFile()

      Gets a MetricsFile with default headers already written into it.

    - #### getStandardUsagePreamble

          public String getStandardUsagePreamble()

    - #### getCommandLineParser

          public CommandLineParser getCommandLineParser()

    - #### getVersion

          public String getVersion()

      Returns:
        Version stored in the manifest of the jarfile.

    - #### getCommandLine

          public String getCommandLine()

    - #### setDefaultHeaders

          public void setDefaultHeaders(List<htsjdk.samtools.metrics.Header> headers)

    - #### getDefaultHeaders

          public List<htsjdk.samtools.metrics.Header> getDefaultHeaders()

    - #### getNestedOptions

          public Map<String,Object> getNestedOptions()

      Returns:
        Map of nested options, where the key is the prefix to be used when specifying Options inside of a nested options object, and the value is the nested options object itself. Default implementation is to return a map of all the fields annotated with @NestedOptions, with key being the field name.

    - #### getNestedOptionsForHelp

          public Map<String,Object> getNestedOptionsForHelp()

      Returns:
        Map of nested options, where the key is the prefix to be used when specifying Options inside of a nested options object, and the value is the nested options object itself, for the purpose of generating help. Default implementation is to return the same map as getNestedOptions().