org.broadinstitute.hellbender.engine

Class ReadWalker

java.lang.Object

org.broadinstitute.hellbender.cmdline.CommandLineProgram

org.broadinstitute.hellbender.engine.GATKTool

org.broadinstitute.hellbender.engine.WalkerBase

org.broadinstitute.hellbender.engine.ReadWalker

All Implemented Interfaces:

org.broadinstitute.barclay.argparser.CommandLinePluginProvider

Direct Known Subclasses:

AddOriginalAlignmentTags, ApplyBQSR, BaseRecalibrator, ClipReads, CollectReadCounts, CountBases, CountReads, DuplicateSetWalker, ExamplePostTraversalPythonExecutor, ExampleReadWalkerWithReference, ExampleReadWalkerWithVariants, ExampleStreamingPythonExecutor, FixMisencodedBaseQualityReads, FlagStat, GeneExpressionEvaluation, LeftAlignIndels, MultiplePassReadWalker, PairedEndAndSplitReadEvidenceCollection, PrintReads, ReadAnonymizer, RevertBaseQualityScores, SplitReads, StructuralVariantDiscoverer, UnmarkDuplicates

public abstract class ReadWalker
extends WalkerBase

A ReadWalker is a tool that processes a single read at a time from one or multiple sources of reads, with optional contextual information from a reference and/or sets of variants/Features. If multiple sources of reads are specified, they are merged together into a single sorted stream of reads. Reads will be: - Transformed with GATKTool.makePreReadFilterTransformer() before filtering. - Filtered with GATKTool.makeReadFilter() before post-transformers. - Transformed with GATKTool.makePostReadFilterTransformer() before processing. - Passed to apply(GATKRead, ReferenceContext, FeatureContext) for processing. ReadWalker authors must implement the apply() method to process each read, and may optionally implement onTraversalStart() and/or onTraversalSuccess(). See the PrintReadsWithReference walker for an example.

Field Summary

Fields

Modifier and Type	Field and Description
static int	FEATURE_CACHE_LOOKAHEAD This number controls the size of the cache for our FeatureInputs (specifically, the number of additional bases worth of overlapping records to cache when querying feature sources).

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

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

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

GATK_CONFIG_FILE, logger, NIO_MAX_REOPENS, NIO_PROJECT_FOR_REQUESTER_PAYS, QUIET, specialArgumentsCollection, tmpDir, useJdkDeflater, useJdkInflater, VERBOSITY

Constructor Summary

Constructors

Constructor and Description
ReadWalker()

Method Summary

Modifier and Type	Method and Description
abstract void	apply(GATKRead read, ReferenceContext referenceContext, FeatureContext featureContext) Process an individual read (with optional contextual information).
java.util.List<ReadFilter>	getDefaultReadFilters() Returns the default list of CommandLineReadFilters that are used for this tool.
java.lang.String	getProgressMeterRecordLabel()
protected void	onShutdown() Shutdown data sources.
protected void	onStartup() Initialize data sources for traversal.
boolean	requiresReads() Does this tool require reads? Traversals types and/or tools that do should override to return true.
void	resetReadsDataSource() Reset the reads data source so the caller can iterate through the reads again.
void	traverse() A complete traversal from start to finish.

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

directlyAccessEngineFeatureManager, directlyAccessEngineReadsDataSource, directlyAccessEngineReferenceDataSource

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

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

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

customCommandLineValidation, getCommandLine, getCommandLineParser, getDefaultHeaders, getMetricsFile, getSupportInformation, getToolkitName, getToolkitShortName, 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

FEATURE_CACHE_LOOKAHEAD

public static final int FEATURE_CACHE_LOOKAHEAD

This number controls the size of the cache for our FeatureInputs (specifically, the number of additional bases worth of overlapping records to cache when querying feature sources).

See Also:

Constant Field Values

Constructor Detail

ReadWalker

public ReadWalker()

Method Detail

requiresReads

public boolean requiresReads()

Description copied from class: GATKTool

Does this tool require reads? Traversals types and/or tools that do should override to return true.

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")

onStartup

protected final void onStartup()

Initialize data sources for traversal. 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()

A complete traversal from start to finish. Tool authors who wish to "roll their own" traversal from scratch can extend this class directly and implement this method. Walker authors should instead extend a Walker class and implement the Walker-appropriate apply() method, since the Walker base classes implement the various kinds of traversals for you. Implementation of read-based traversal. The default implementation creates filters using GATKTool.makeReadFilter() and transformers using GATKTool.makePreReadFilterTransformer() GATKTool.makePostReadFilterTransformer() and then iterates over all reads, applies the pre-filter transformer, the filter, then the post-filter transformer and hands the resulting reads to the apply(org.broadinstitute.hellbender.utils.read.GATKRead, org.broadinstitute.hellbender.engine.ReferenceContext, org.broadinstitute.hellbender.engine.FeatureContext) function of the walker (along with additional contextual information, if present, such as reference bases). NOTE: You should only override traverse() if you are writing a new walker base class in the engine package that extends this class. It is not meant to be overridden by tools outside of the engine package.

Specified by:

traverse in class GATKTool

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

resetReadsDataSource

public void resetReadsDataSource()

Reset the reads data source so the caller can iterate through the reads again.

apply

public abstract void apply(GATKRead read,
                           ReferenceContext referenceContext,
                           FeatureContext featureContext)

Process an individual read (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. TODO: Determine whether and to what degree the GATK engine should provide a reduce operation TODO: to complement this operation. At a minimum, we should make apply() return a value to TODO: discourage statefulness in walkers, but how this value should be handled is TBD.

Parameters:

read - current read

referenceContext - Reference bases spanning the current read. 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 read's interval by invoking ReferenceContext.setWindow(int, int) on this object before calling ReferenceContext.getBases()

featureContext - Features spanning the current read. 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()

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

Overrides:

onShutdown in class GATKTool