org.broadinstitute.hellbender.engine

Class FeatureContext

java.lang.Object

org.broadinstitute.hellbender.engine.FeatureContext

@DoNotSubclass
public class FeatureContext
extends java.lang.Object

Wrapper around FeatureManager that presents Feature data from a particular interval to a client tool without improperly exposing engine internals. The client passes in one or more FeatureInputs that were declared as tool arguments, and gets back a List of all Features from those FeatureInputs overlapping the interval spanned by this FeatureContext. Features returned may optionally be additionally constrained to start at a particular position. Features are returned strongly-typed based on the type parameter of each FeatureInput requested, so a query on a FeatureInput will return VariantContext objects (no casting required by tool authors). Feature sources are lazily queried, so there's no overhead if the client chooses not to examine the FeatureContext it's passed. A FeatureContext may have no backing data source and/or interval. In these cases, queries on it will always return empty Lists. You can determine whether there is a backing source of Features via hasBackingDataSource(), and whether there is an interval via getInterval() Note: This class is NOT intended to be extended outside of the testing harness.

Constructor Summary

Constructors

Constructor and Description
FeatureContext() Creates an empty FeatureContext with no backing data source.
FeatureContext(FeatureContext featureContext, SimpleInterval interval) Creates a new FeatureContext given a FeatureContext and a query interval.
FeatureContext(FeatureManager featureManager, SimpleInterval interval) Creates a new FeatureContext given a FeatureManager and a query interval.

Method Summary

Modifier and Type	Method and Description
static FeatureContext	createFeatureContextForTesting(java.util.Map<FeatureInput<? extends htsjdk.tribble.Feature>,java.lang.Class<? extends htsjdk.tribble.Feature>> featureInputsWithType, java.lang.String dummyToolInstanceName, SimpleInterval interval, int featureQueryLookahead, int cloudPrefetchBuffer, int cloudIndexPrefetchBuffer, java.nio.file.Path reference) Convenience method to create a new instance for test methods.
<T extends htsjdk.tribble.Feature> java.lang.Object	getHeader(FeatureInput<T> featureDescriptor) Gets the header associated with the provided FeatureInput
SimpleInterval	getInterval() Gets our query interval (the interval that all Features returned by this FeatureContext overlap).
<T extends htsjdk.tribble.Feature> java.util.List<T>	getValues(java.util.Collection<FeatureInput<T>> featureDescriptors) Gets all Features from the sources represented by the provided FeatureInput arguments that overlap this FeatureContext's query interval.
<T extends htsjdk.tribble.Feature> java.util.List<T>	getValues(java.util.Collection<FeatureInput<T>> featureDescriptors, int featureStart) Gets all Features from the sources represented by the provided FeatureInput arguments that overlap this FeatureContext's query interval, AND that start at the specified start position.
<T extends htsjdk.tribble.Feature> java.util.List<T>	getValues(FeatureInput<T> featureDescriptor) Gets all Features from the source represented by the provided FeatureInput argument that overlap this FeatureContext's query interval.
<T extends htsjdk.tribble.Feature> java.util.List<T>	getValues(FeatureInput<T> featureDescriptor, int featureStart) Gets all Features from the source represented by the provided FeatureInput argument that overlap this FeatureContext's query interval AND that start at the specified start position.
<T extends htsjdk.tribble.Feature> java.util.List<T>	getValues(FeatureInput<T> featureDescriptor, int windowLeadingBases, int windowTrailingBases) Gets all Features from the source represented by the provided FeatureInput argument that overlap this FeatureContext's query interval as expanded by the specified number of leading/trailing bases.
<T extends htsjdk.tribble.Feature> java.util.List<T>	getValues(FeatureInput<T> featureDescriptor, htsjdk.samtools.util.Locatable queryInterval) Gets all Features from the source represented by the provided FeatureInput argument that overlap the given interval.
boolean	hasBackingDataSource() Determines whether this FeatureContext has a backing source of Features.

Methods inherited from class java.lang.Object

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

Constructor Detail

FeatureContext

public FeatureContext()

Creates an empty FeatureContext with no backing data source. All queries on this context will return an empty List.

FeatureContext

public FeatureContext(FeatureManager featureManager,
                      SimpleInterval interval)

Creates a new FeatureContext given a FeatureManager and a query interval. These may be null if no sources of Features are available and/or we don't have a known location on the reference, in which case all queries on this context will return an empty List.

Parameters:

featureManager - FeatureManager containing backing data sources for all discovered Feature arguments. Null if there are no sources of Features.

interval - Interval to constrain queries on this FeatureContext. Null if we have no known location.

FeatureContext

public FeatureContext(FeatureContext featureContext,
                      SimpleInterval interval)

Creates a new FeatureContext given a FeatureContext and a query interval. This will reference the FeatureManager from the original and use the supplied interval.

Method Detail

hasBackingDataSource

public boolean hasBackingDataSource()

Determines whether this FeatureContext has a backing source of Features. A FeatureContext with no backing data source will always return an empty List in response to a query.

Returns:

true if this FeatureContext has a backing source of Features, otherwise false

getInterval

public SimpleInterval getInterval()

Gets our query interval (the interval that all Features returned by this FeatureContext overlap). Null if this context has no interval.

Returns:

query interval for this FeatureContext (may be null)

getHeader

public <T extends htsjdk.tribble.Feature> java.lang.Object getHeader(FeatureInput<T> featureDescriptor)

Gets the header associated with the provided FeatureInput

Type Parameters:

T - type of Feature in our FeatureInput

Parameters:

featureDescriptor - FeatureInput whose header we want to retrieve

Returns:

header for the provided FeatureInput (null if we have no backing data sources)

getValues

public <T extends htsjdk.tribble.Feature> java.util.List<T> getValues(FeatureInput<T> featureDescriptor)

Gets all Features from the source represented by the provided FeatureInput argument that overlap this FeatureContext's query interval. Will return an empty List if this FeatureContext has no backing source of Features and/or interval. Returned Features are not guaranteed to be in any particular order.

Type Parameters:

T - type of Feature in the data source backing the provided FeatureInput

Parameters:

featureDescriptor - FeatureInput argument for which to fetch Features

Returns:

All Features in the data source backing the provided FeatureInput that overlap this FeatureContext's query interval. Empty List if there is no backing data source and/or interval.

getValues

public <T extends htsjdk.tribble.Feature> java.util.List<T> getValues(FeatureInput<T> featureDescriptor,
                                                                      int windowLeadingBases,
                                                                      int windowTrailingBases)

Gets all Features from the source represented by the provided FeatureInput argument that overlap this FeatureContext's query interval as expanded by the specified number of leading/trailing bases. Returns an empty List if this FeatureContext has no backing source of Features and/or interval. Returned Features are not guaranteed to be in any particular order. Note: if windowLeadingBases > 0 and query lookahead caching is enabled for the underlying FeatureDataSource, there will be a cache miss on every call, since the current caching scheme prefetches Features after the current query interval but not before it (on the assumption that the common access pattern involves gradually increasing query intervals).

Type Parameters:

T - type of Feature in the data source backing the provided FeatureInput

Parameters:

featureDescriptor - FeatureInput argument for which to fetch Features

windowLeadingBases - Number of extra reference bases to include before the start of our interval. Must be >= 0.

windowTrailingBases - Number of extra reference bases to include after the end of our interval. Must be >= 0.

Returns:

All Features in the data source backing the provided FeatureInput that overlap this FeatureContext's query interval as expanded by the specified number of leading/trailing bases. Empty List if there is no backing data source and/or interval.

getValues

public <T extends htsjdk.tribble.Feature> java.util.List<T> getValues(FeatureInput<T> featureDescriptor,
                                                                      htsjdk.samtools.util.Locatable queryInterval)

Gets all Features from the source represented by the provided FeatureInput argument that overlap the given interval. Returns an empty List if this FeatureContext has no backing source of Features and/or interval. Returned Features are not guaranteed to be in any particular order. Note: if query lookahead caching is enabled for the underlying FeatureDataSource, there will be a cache miss on almost every call, since the current caching scheme prefetches Features after the current query interval but not before it (on the assumption that the common access pattern involves gradually increasing query intervals).

Type Parameters:

T - type of Feature in the data source backing the provided FeatureInput

Parameters:

featureDescriptor - FeatureInput argument for which to fetch Features

Returns:

All Features in the data source backing the provided FeatureInput that overlap this FeatureContext's query interval as expanded by the specified number of leading/trailing bases. Empty List if there is no backing data source and/or interval.

getValues

public <T extends htsjdk.tribble.Feature> java.util.List<T> getValues(FeatureInput<T> featureDescriptor,
                                                                      int featureStart)

Gets all Features from the source represented by the provided FeatureInput argument that overlap this FeatureContext's query interval AND that start at the specified start position. Will return an empty List if this FeatureContext has no backing source of Features and/or interval. Returned Features are not guaranteed to be in any particular order.

Type Parameters:

T - type of Feature in the data source backing the provided FeatureInput

Parameters:

featureDescriptor - FeatureInput argument for which to fetch Features

featureStart - All returned Features must start at this position, in addition to overlapping this FeatureContext's query interval

Returns:

All Features in the data source backing the provided FeatureInput that overlap this FeatureContext's query interval AND that start at the specified start position. Empty List if there is no backing data source and/or interval.

getValues

public <T extends htsjdk.tribble.Feature> java.util.List<T> getValues(java.util.Collection<FeatureInput<T>> featureDescriptors)

Gets all Features from the sources represented by the provided FeatureInput arguments that overlap this FeatureContext's query interval. Will return an empty List if this FeatureContext has no backing source of Features and/or interval. Returned Features are not guaranteed to be in any particular order, or to be globally unique across all sources of Features.

Type Parameters:

T - type of Feature in the data sources backing the provided FeatureInputs

Parameters:

featureDescriptors - FeatureInput arguments for which to fetch Features

Returns:

All Features in the data sources backing the provided FeatureInputs that overlap this FeatureContext's query interval. Empty List if there is no backing data source and/or interval.

getValues

public <T extends htsjdk.tribble.Feature> java.util.List<T> getValues(java.util.Collection<FeatureInput<T>> featureDescriptors,
                                                                      int featureStart)

Gets all Features from the sources represented by the provided FeatureInput arguments that overlap this FeatureContext's query interval, AND that start at the specified start position. Will return an empty List if this FeatureContext has no backing source of Features and/or interval. Returned Features are not guaranteed to be in any particular order, or to be globally unique across all sources of Features.

Type Parameters:

T - type of Feature in the data sources backing the provided FeatureInputs

Parameters:

featureDescriptors - FeatureInput arguments for which to fetch Features

featureStart - All returned Features must start at this position, in addition to overlapping this FeatureContext's query interval

Returns:

All Features in the data sources backing the provided FeatureInputs that overlap this FeatureContext's query interval, AND that start at the specified start position. Empty List if there is no backing data source and/or interval.

createFeatureContextForTesting

public static FeatureContext createFeatureContextForTesting(java.util.Map<FeatureInput<? extends htsjdk.tribble.Feature>,java.lang.Class<? extends htsjdk.tribble.Feature>> featureInputsWithType,
                                                            java.lang.String dummyToolInstanceName,
                                                            SimpleInterval interval,
                                                            int featureQueryLookahead,
                                                            int cloudPrefetchBuffer,
                                                            int cloudIndexPrefetchBuffer,
                                                            java.nio.file.Path reference)

Convenience method to create a new instance for test methods. This method should be used for testing only.

Parameters:

featureInputsWithType - Map of a FeatureInput to the output type that must extend Feature. Never null, but empty list is acceptable.

dummyToolInstanceName - A name to use for the "tool". Any string will work here. Never null.

interval - genomic interval for the result. Typically, this would be the interval of the variant. Never null.

featureQueryLookahead - When querying FeatureDataSources, cache this many extra bases of context beyond the end of query intervals in anticipation of future queries. Must be >= 0. If uncertain, use zero.

cloudPrefetchBuffer - See FeatureManager.FeatureManager(CommandLineProgram, int, int, int, org.broadinstitute.hellbender.tools.genomicsdb.GenomicsDBOptions) If uncertain, use zero.

cloudIndexPrefetchBuffer - See FeatureManager.FeatureManager(CommandLineProgram, int, int, int, org.broadinstitute.hellbender.tools.genomicsdb.GenomicsDBOptions) If uncertain, use zero.

reference - See FeatureManager.FeatureManager(CommandLineProgram, int, int, int, org.broadinstitute.hellbender.tools.genomicsdb.GenomicsDBOptions) If uncertain, use null.