org.broadinstitute.hellbender.engine

Class LocusWalker

java.lang.Object

org.broadinstitute.hellbender.cmdline.CommandLineProgram

org.broadinstitute.hellbender.engine.GATKTool

org.broadinstitute.hellbender.engine.LocusWalker

All Implemented Interfaces:

org.broadinstitute.barclay.argparser.CommandLinePluginProvider

Direct Known Subclasses:

ASEReadCounter, CheckPileup, CollectAllelicCounts, ExampleLocusWalker, Pileup

public abstract class LocusWalker
extends GATKTool

A LocusWalker is a tool that processes reads that overlap a single position in a reference at a time from one or multiple sources of reads, with optional contextual information from a reference and/or sets of variants/Features. Reads will be: - Transformed with GATKTool.makePreReadFilterTransformer() before filtering. - Filtered with GATKTool.makeReadFilter() before post-transformers. - Transformed with GATKTool.makePostReadFilterTransformer() before processing. - Include them into the AlignmentContext before passing to apply(AlignmentContext, ReferenceContext, FeatureContext). LocusWalker authors must implement the apply() method to process each position, and may optionally implement onTraversalStart(), onTraversalSuccess() and/or closeTool().

Field Summary

Fields

Modifier and Type	Field and Description
protected int	maxDepthPerSample

Fields inherited from class org.broadinstitute.hellbender.engine.GATKTool

addOutputSAMProgramRecord, addOutputVCFCommandLine, cloudIndexPrefetchBuffer, cloudPrefetchBuffer, createOutputBamIndex, createOutputBamMD5, createOutputVariantIndex, createOutputVariantMD5, disableBamIndexCaching, intervalArgumentCollection, lenientVCFProcessing, outputSitesOnlyVCFs, progressMeter, readArguments, referenceArguments, SECONDS_BETWEEN_PROGRESS_UPDATES_NAME

Fields inherited from class org.broadinstitute.hellbender.cmdline.CommandLineProgram

GATK_CONFIG_FILE, logger, NIO_MAX_REOPENS, QUIET, specialArgumentsCollection, TMP_DIR, useJdkDeflater, useJdkInflater, VERBOSITY

Constructor Summary

Constructors

Constructor and Description
LocusWalker()

Method Summary

Modifier and Type	Method and Description
abstract void	apply(AlignmentContext alignmentContext, ReferenceContext referenceContext, FeatureContext featureContext) Process an individual AlignmentContext (with optional contextual information).
protected int	defaultMaxDepthPerSample() Returns default value for the maxDepthPerSample parameter, if none is provided on the command line.
boolean	emitEmptyLoci() Does this tool emit information for uncovered loci? Tools that do should override to return true.
java.util.List<ReadFilter>	getDefaultReadFilters() Returns the default list of CommandLineReadFilters that are used for this tool.
protected LIBSDownsamplingInfo	getDownsamplingInfo() Returns the downsampling info using maxDepthPerSample as target coverage.
java.lang.String	getProgressMeterRecordLabel()
boolean	includeDeletions() Does this tool require deletions in the AlignmentContext? Tools that don't should override to return false.
boolean	includeNs() Does this tool require Ns in the AlignmentContext? Tools that do should override to return true.
protected boolean	keepUniqueReadListInLibs() Should the LIBS keep unique reads? Tools that do should override to return true.
protected void	onShutdown() Marked final so that tool authors don't override it.
protected void	onStartup() Marked final so that tool authors don't override it.
boolean	requiresReads() LocusWalkers requires read sources
void	traverse() Implementation of locus-based traversal.
protected void	validateEmitEmptyLociParameters() The emit empty loci parameter comes with several pitfalls when used incorrectly.

Methods inherited from class org.broadinstitute.hellbender.engine.GATKTool

addFeatureInputsAfterInitialization, closeTool, createSAMWriter, createSAMWriter, createVCFWriter, doWork, getBestAvailableSequenceDictionary, getDefaultCloudIndexPrefetchBufferSize, getDefaultCloudPrefetchBufferSize, getDefaultToolVCFHeaderLines, getDefaultVariantAnnotationGroups, getDefaultVariantAnnotations, getHeaderForFeatures, getHeaderForReads, getHeaderForSAMWriter, getMasterSequenceDictionary, getPluginDescriptors, getReferenceDictionary, getSequenceDictionaryValidationArgumentCollection, getToolkitShortName, getToolName, getTransformedReadStream, hasFeatures, hasIntervals, hasReads, hasReference, makePostReadFilterTransformer, makePreReadFilterTransformer, makeReadFilter, makeVariantAnnotations, onTraversalStart, onTraversalSuccess, requiresFeatures, requiresIntervals, requiresReference, useVariantAnnotations

Methods inherited from class org.broadinstitute.hellbender.cmdline.CommandLineProgram

customCommandLineValidation, getCommandLine, getCommandLineParser, getDefaultHeaders, getMetricsFile, getSupportInformation, getToolkitName, getToolStatusWarning, getUsage, getVersion, instanceMain, instanceMainPostParseArgs, isBetaFeature, isExperimentalFeature, parseArgs, printLibraryVersions, printSettings, printStartupMessage, runTool, setDefaultHeaders, warnOnToolStatus

Methods inherited from class java.lang.Object

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

Field Detail

maxDepthPerSample

@Argument(fullName="maxDepthPerSample",
          shortName="maxDepthPerSample",
          doc="Maximum number of reads to retain per sample per locus. Reads above this threshold will be downsampled. Set to 0 to disable.",
          optional=true)
protected int maxDepthPerSample

Constructor Detail

LocusWalker

public LocusWalker()

Method Detail

keepUniqueReadListInLibs

protected boolean keepUniqueReadListInLibs()

Should the LIBS keep unique reads? Tools that do should override to return true.

requiresReads

public boolean requiresReads()

LocusWalkers requires read sources

Overrides:

requiresReads in class GATKTool

Returns:

true if this tool requires reads, otherwise false

getProgressMeterRecordLabel

public java.lang.String getProgressMeterRecordLabel()

Overrides:

getProgressMeterRecordLabel in class GATKTool

Returns:

String label to use for records in progress meter output. Defaults to ProgressMeter.DEFAULT_RECORD_LABEL, but tools may override to provide a more appropriate label (like "reads" or "regions")

includeDeletions

public boolean includeDeletions()

Does this tool require deletions in the AlignmentContext? Tools that don't should override to return false.

Returns:

true if this tool requires deletions, false otherwise

includeNs

public boolean includeNs()

Does this tool require Ns in the AlignmentContext? Tools that do should override to return true.

Returns:

true if this tool requires Ns, false otherwise

emitEmptyLoci

public boolean emitEmptyLoci()

Does this tool emit information for uncovered loci? Tools that do should override to return true. NOTE: Typically, this should only be used when intervals are specified. NOTE: If MappedReadFilter is removed, then emitting empty loci will fail. NOTE: If there is no available sequence dictionary and this is set to true, there should be a failure. Please consider requiring reads and/or references for all tools that wish to set this to true.

Returns:

true if this tool requires uncovered loci information to be emitted, false otherwise

defaultMaxDepthPerSample

protected int defaultMaxDepthPerSample()

Returns default value for the maxDepthPerSample parameter, if none is provided on the command line. Default implementation returns 0 (no downsampling by default).

getDefaultReadFilters

public java.util.List<ReadFilter> getDefaultReadFilters()

Returns the default list of CommandLineReadFilters that are used for this tool. The filters returned by this method are subject to selective enabling/disabling by the user via the command line. The default implementation uses the WellformedReadFilter and ReadFilterLibrary.MappedReadFilter filter with all default options. Subclasses can override to provide alternative filters. Note: this method is called before command line parsing begins, and thus before a SAMFileHeader is available through {link #getHeaderForReads}.

Overrides:

getDefaultReadFilters in class GATKTool

Returns:

List of individual filters to be applied for this tool.

getDownsamplingInfo

protected final LIBSDownsamplingInfo getDownsamplingInfo()

Returns the downsampling info using maxDepthPerSample as target coverage.

onStartup

protected final void onStartup()

Marked final so that tool authors don't override it. Tool authors should override onTraversalStart() instead.

Overrides:

onStartup in class GATKTool

traverse

public void traverse()

Implementation of locus-based traversal. Subclasses can override to provide their own behavior but default implementation should be suitable for most uses. The default implementation iterates over all positions in the reference covered by reads (filtered and transformed) for all samples in the read groups, using the downsampling method provided by getDownsamplingInfo() and including deletions only if includeDeletions() returns true.

Specified by:

traverse in class GATKTool

apply

public abstract void apply(AlignmentContext alignmentContext,
                           ReferenceContext referenceContext,
                           FeatureContext featureContext)

Process an individual AlignmentContext (with optional contextual information). Must be implemented by tool authors. In general, tool authors should simply stream their output from apply(), and maintain as little internal state as possible.

Parameters:

alignmentContext - current alignment context

referenceContext - Reference bases spanning the current locus. Will be an empty, but non-null, context object if there is no backing source of reference data (in which case all queries on it will return an empty array/iterator). Can request extra bases of context around the current locus by invoking ReferenceContext.setWindow(int, int) on this object before calling ReferenceContext.getBases()

featureContext - Features spanning the current locus. Will be an empty, but non-null, context object if there is no backing source of Feature data (in which case all queries on it will return an empty List).

onShutdown

protected final void onShutdown()

Marked final so that tool authors don't override it. Tool authors should override onTraversalSuccess() instead.

Overrides:

onShutdown in class GATKTool

validateEmitEmptyLociParameters

protected void validateEmitEmptyLociParameters()

The emit empty loci parameter comes with several pitfalls when used incorrectly. Here we check and either give warnings or errors.