org.broadinstitute.hellbender.cmdline

Class CommandLineProgram

java.lang.Object

org.broadinstitute.hellbender.cmdline.CommandLineProgram

All Implemented Interfaces:

org.broadinstitute.barclay.argparser.CommandLinePluginProvider

Direct Known Subclasses:

AnalyzeCovariates, BwaMemIndexImageCreator, CalculateContamination, CallCopyRatioSegments, CNNVariantTrain, CNNVariantWriteTensors, CompareIntervalLists, ConvertHeaderlessHadoopBamShardToBam, CreateHadoopBamSplittingIndex, DenoiseReadCounts, DetermineGermlineContigPloidy, FilterIntervals, FuncotatorDataSourceDownloader, GatherBQSRReports, GatherPileupSummaries, GatherTranches, GatherVcfsCloud, GATKTool, GermlineCNVCaller, IndexFeatureFile, LearnReadOrientationModel, MergeMutectStats, ModelSegments, PathSeqBuildKmers, PathSeqBuildReferenceTaxonomy, PicardCommandLineProgram, PicardCommandLineProgramExecutor, PlotDenoisedCopyRatios, PlotModeledSegments, PrintBGZFBlockInformation, SparkCommandLineProgram

public abstract class CommandLineProgram
extends java.lang.Object
implements org.broadinstitute.barclay.argparser.CommandLinePluginProvider

Abstract class to facilitate writing command-line programs. To use: 1. Extend this class with a concrete class that has data members annotated with @Argument, @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 doWork() method may return null or a result object (they are not interpreted by the toolkit and passed onto the caller). doWork() may throw unchecked exceptions, which are NOT caught and passed onto the VM.

Field Summary

Fields

Modifier and Type	Field and Description
java.lang.String	GATK_CONFIG_FILE
protected org.apache.logging.log4j.Logger	logger
int	NIO_MAX_REOPENS
java.lang.String	NIO_PROJECT_FOR_REQUESTER_PAYS
java.lang.Boolean	QUIET
org.broadinstitute.barclay.argparser.SpecialArgumentsCollection	specialArgumentsCollection
GATKPathSpecifier	tmpDir
boolean	useJdkDeflater
boolean	useJdkInflater
htsjdk.samtools.util.Log.LogLevel	VERBOSITY

Constructor Summary

Constructors

Constructor and Description
CommandLineProgram()

Method Summary

Modifier and Type	Method and Description
protected java.lang.String[]	customCommandLineValidation() Put any custom command-line validation in an override of this method.
protected abstract java.lang.Object	doWork() Do the work after command line has been parsed.
java.lang.String	getCommandLine()
org.broadinstitute.barclay.argparser.CommandLineParser	getCommandLineParser()
java.util.List<htsjdk.samtools.metrics.Header>	getDefaultHeaders() Returns the (live) list of default metrics headers used by this tool.
protected <A extends htsjdk.samtools.metrics.MetricBase,B extends java.lang.Comparable<?>> htsjdk.samtools.metrics.MetricsFile<A,B>	getMetricsFile() Gets a MetricsFile with default headers already written into it.
java.util.List<? extends org.broadinstitute.barclay.argparser.CommandLinePluginDescriptor<?>>	getPluginDescriptors() Return the list of GATKCommandLinePluginDescriptors to be used for this CLP.
protected java.lang.String	getSupportInformation()
protected java.lang.String	getToolkitName()
protected java.lang.String	getToolkitShortName()
protected java.lang.String	getToolStatusWarning(boolean useTerminalColor) If this tool is either Experimental or Beta, return a warning message advising against use in production envirogetnment.
java.lang.String	getUsage()
java.lang.String	getVersion()
java.lang.Object	instanceMain(java.lang.String[] argv)
java.lang.Object	instanceMainPostParseArgs()
boolean	isBetaFeature()
boolean	isExperimentalFeature()
protected void	onShutdown() Perform cleanup after doWork() is finished.
protected void	onStartup() Perform initialization/setup after command-line argument parsing but before doWork() is invoked.
protected boolean	parseArgs(java.lang.String[] argv) Parse arguments and initialize any values annotated with Argument
protected void	printLibraryVersions() Output versions of important dependencies to the logger.
protected void	printSettings() Output a curated set of important settings to the logger.
protected void	printStartupMessage(java.time.ZonedDateTime startDateTime) Prints a user-friendly message on startup with some information about who we are and the runtime environment.
java.lang.Object	runTool() Template method that runs the startup hook, doWork and then the shutdown hook.
void	setDefaultHeaders(java.util.List<htsjdk.samtools.metrics.Header> headers) Replaces the set of default metrics headers by the given argument.
protected void	warnOnToolStatus() If a tool is either Experimental or Beta, log a warning against use in production a environment.

Methods inherited from class java.lang.Object

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

Field Detail

logger

protected final org.apache.logging.log4j.Logger logger

tmpDir

@Argument(fullName="tmp-dir",
          common=true,
          optional=true,
          doc="Temp directory to use.")
public GATKPathSpecifier tmpDir

specialArgumentsCollection

@ArgumentCollection(doc="Special Arguments that have meaning to the argument parsing system.  It is unlikely these will ever need to be accessed by the command line program")
public org.broadinstitute.barclay.argparser.SpecialArgumentsCollection specialArgumentsCollection

VERBOSITY

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

QUIET

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

useJdkDeflater

@Argument(fullName="use-jdk-deflater",
          shortName="jdk-deflater",
          doc="Whether to use the JdkDeflater (as opposed to IntelDeflater)",
          common=true)
public boolean useJdkDeflater

useJdkInflater

@Argument(fullName="use-jdk-inflater",
          shortName="jdk-inflater",
          doc="Whether to use the JdkInflater (as opposed to IntelInflater)",
          common=true)
public boolean useJdkInflater

NIO_MAX_REOPENS

@Argument(fullName="gcs-max-retries",
          shortName="gcs-retries",
          doc="If the GCS bucket channel errors out, how many times it will attempt to re-initiate the connection",
          optional=true)
public int NIO_MAX_REOPENS

NIO_PROJECT_FOR_REQUESTER_PAYS

@Argument(fullName="gcs-project-for-requester-pays",
          doc="Project to bill when accessing \"requester pays\" buckets. If unset, these buckets cannot be accessed.",
          optional=true)
public java.lang.String NIO_PROJECT_FOR_REQUESTER_PAYS

GATK_CONFIG_FILE

@Argument(fullName="gatk-config-file",
          doc="A configuration file to use with the GATK.",
          common=true,
          optional=true)
public java.lang.String GATK_CONFIG_FILE

Constructor Detail

CommandLineProgram

public CommandLineProgram()

Method Detail

onStartup

protected void onStartup()

Perform initialization/setup after command-line argument parsing but before doWork() is invoked. Default implementation does nothing. Subclasses can override to perform initialization.

doWork

protected abstract java.lang.Object doWork()

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

Returns:

the return value or null is there is none.

onShutdown

protected void onShutdown()

Perform cleanup after doWork() is finished. Always executes even if an exception is thrown during the run. Default implementation does nothing. Subclasses can override to perform cleanup.

runTool

public final java.lang.Object runTool()

Template method that runs the startup hook, doWork and then the shutdown hook.

instanceMainPostParseArgs

public java.lang.Object instanceMainPostParseArgs()

instanceMain

public java.lang.Object instanceMain(java.lang.String[] argv)

customCommandLineValidation

protected java.lang.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 arguments 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.

Throws:

org.broadinstitute.barclay.argparser.CommandLineException - if command line is invalid and handling as exception is preferred.

parseArgs

protected final boolean parseArgs(java.lang.String[] argv)

Parse arguments and initialize any values annotated with Argument

Returns:

true if program should be executed, false if an information only argument like SpecialArgumentsCollection.HELP_FULLNAME was specified

Throws:

org.broadinstitute.barclay.argparser.CommandLineException - if command line validation fails

getPluginDescriptors

public java.util.List<? extends org.broadinstitute.barclay.argparser.CommandLinePluginDescriptor<?>> getPluginDescriptors()

Return the list of GATKCommandLinePluginDescriptors to be used for this CLP. Default implementation returns null. Subclasses can override this to return a custom list.

Specified by:

getPluginDescriptors in interface org.broadinstitute.barclay.argparser.CommandLinePluginProvider

getMetricsFile

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

Gets a MetricsFile with default headers already written into it.

printStartupMessage

protected void printStartupMessage(java.time.ZonedDateTime startDateTime)

Prints a user-friendly message on startup with some information about who we are and the runtime environment. May be overridden by subclasses to provide a custom implementation if desired.

Parameters:

startDateTime - Startup date/time

getToolStatusWarning

protected java.lang.String getToolStatusWarning(boolean useTerminalColor)

If this tool is either Experimental or Beta, return a warning message advising against use in production envirogetnment.

Parameters:

useTerminalColor - true if the message should include highlighting terminal colorization

Returns:

a warning message if the tool is Beta or Experimental, otherwise null

warnOnToolStatus

protected void warnOnToolStatus()

If a tool is either Experimental or Beta, log a warning against use in production a environment.

isBetaFeature

public boolean isBetaFeature()

Returns:

true if this tool has BetaFeature status.

isExperimentalFeature

public boolean isExperimentalFeature()

Returns:

true if this tool has ExperimentalFeature status.

getToolkitName

protected java.lang.String getToolkitName()

Returns:

The name of this toolkit. The default implementation uses "Implementation-Title" from the jar manifest, or (if that's not available) the package name. May be overridden by subclasses to provide a custom implementation if desired.

getToolkitShortName

protected java.lang.String getToolkitShortName()

Returns:

An abbreviated name of the toolkit for this tool. Looks for "Tool-Short-Name" in the manifest by default. Uses DEFAULT_TOOLKIT_SHORT_NAME if the manifest is unavailable. Subclasses may override to do something different.

getVersion

public java.lang.String getVersion()

Returns:

the version of this tool. It is the version stored in the manifest of the jarfile by default, or "Unavailable" if that's not available. May be overridden by subclasses to provide a custom implementation if desired.

getSupportInformation

protected java.lang.String getSupportInformation()

Returns:

A String containing information about how to get support for this toolkit. May be overridden by subclasses to provide a custom implementation if desired.

printLibraryVersions

protected void printLibraryVersions()

Output versions of important dependencies to the logger. May be overridden by subclasses to provide a custom implementation if desired.

printSettings

protected void printSettings()

Output a curated set of important settings to the logger. May be overridden by subclasses to specify a different set of settings to output.

getCommandLine

public final java.lang.String getCommandLine()

Returns:

the commandline used to run this program, will be null if arguments have not yet been parsed

getUsage

public final java.lang.String getUsage()

Returns:

get usage and help information for this command line program if it is available

setDefaultHeaders

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

Replaces the set of default metrics headers by the given argument. The given list is copied.

getDefaultHeaders

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

Returns the (live) list of default metrics headers used by this tool.

getCommandLineParser

public final org.broadinstitute.barclay.argparser.CommandLineParser getCommandLineParser()

Returns:

this programs CommandLineParser. If one is not initialized yet this will initialize it.