org.broadinstitute.hellbender.engine

Class ReadsDataSource

java.lang.Object

org.broadinstitute.hellbender.engine.ReadsDataSource

All Implemented Interfaces:

java.lang.AutoCloseable, java.lang.Iterable<GATKRead>, GATKDataSource<GATKRead>

public final class ReadsDataSource
extends java.lang.Object
implements GATKDataSource<GATKRead>, java.lang.AutoCloseable

Manages traversals and queries over sources of reads (for now, SAM/BAM/CRAM files only). Two basic operations are available: -Iteration over all reads, optionally restricted to reads that overlap a set of intervals -Targeted queries by one interval at a time

Field Summary

Fields

Modifier and Type	Field and Description
protected static org.apache.logging.log4j.Logger	logger

Constructor Summary

Constructors

Constructor and Description
ReadsDataSource(java.util.List<java.nio.file.Path> samFiles) Initialize this data source with multiple SAM/BAM files and validation stringency SILENT.
ReadsDataSource(java.util.List<java.nio.file.Path> samPaths, java.util.List<java.nio.file.Path> samIndices) Initialize this data source with multiple SAM/BAM/CRAM files, and explicit indices for those files.
ReadsDataSource(java.util.List<java.nio.file.Path> samPaths, java.util.List<java.nio.file.Path> samIndices, htsjdk.samtools.SamReaderFactory customSamReaderFactory) Initialize this data source with multiple SAM/BAM/CRAM files, explicit indices for those files, and a custom SamReaderFactory.
ReadsDataSource(java.util.List<java.nio.file.Path> samPaths, java.util.List<java.nio.file.Path> samIndices, htsjdk.samtools.SamReaderFactory customSamReaderFactory, java.util.function.Function<java.nio.channels.SeekableByteChannel,java.nio.channels.SeekableByteChannel> cloudWrapper, java.util.function.Function<java.nio.channels.SeekableByteChannel,java.nio.channels.SeekableByteChannel> cloudIndexWrapper) Initialize this data source with multiple SAM/BAM/CRAM files, explicit indices for those files, and a custom SamReaderFactory.
ReadsDataSource(java.util.List<java.nio.file.Path> samPaths, java.util.List<java.nio.file.Path> samIndices, htsjdk.samtools.SamReaderFactory customSamReaderFactory, int cloudPrefetchBuffer, int cloudIndexPrefetchBuffer) Initialize this data source with multiple SAM/BAM/CRAM files, explicit indices for those files, and a custom SamReaderFactory.
ReadsDataSource(java.util.List<java.nio.file.Path> samPaths, htsjdk.samtools.SamReaderFactory customSamReaderFactory) Initialize this data source with multiple SAM/BAM files and a custom SamReaderFactory
ReadsDataSource(java.nio.file.Path samFile) Initialize this data source with a single SAM/BAM file and validation stringency SILENT.
ReadsDataSource(java.nio.file.Path samPath, htsjdk.samtools.SamReaderFactory customSamReaderFactory) Initialize this data source with a single SAM/BAM file and a custom SamReaderFactory

Method Summary

Modifier and Type	Method and Description
void	close() Shut down this data source permanently, closing all iterations and readers.
htsjdk.samtools.SAMFileHeader	getHeader() Returns the SAM header for this data source.
htsjdk.samtools.SAMSequenceDictionary	getSequenceDictionary() Get the sequence dictionary for this ReadsDataSource
boolean	indicesAvailable() Are indices available for all files?
java.util.Iterator<GATKRead>	iterator() Iterate over all reads in this data source.
java.util.Iterator<GATKRead>	query(SimpleInterval interval) Query reads over a specific interval.
java.util.Iterator<GATKRead>	queryUnmapped()
void	setTraversalBounds(java.util.List<SimpleInterval> intervals) Restricts a traversal of this data source via iterator() to only return reads which overlap the given intervals.
void	setTraversalBounds(java.util.List<SimpleInterval> intervals, boolean traverseUnmapped) Restricts a traversal of this data source via iterator() to only return reads that overlap the given intervals, and to unmapped reads if specified.
void	setTraversalBounds(TraversalParameters traversalParameters) Restricts a traversal of this data source via iterator() to only return reads that overlap the given intervals, and to unmapped reads if specified.
boolean	traversalIsBounded()

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

logger

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

Constructor Detail

ReadsDataSource

public ReadsDataSource(java.nio.file.Path samFile)

Initialize this data source with a single SAM/BAM file and validation stringency SILENT.

Parameters:

samFile - SAM/BAM file, not null.

ReadsDataSource

public ReadsDataSource(java.util.List<java.nio.file.Path> samFiles)

Initialize this data source with multiple SAM/BAM files and validation stringency SILENT.

Parameters:

samFiles - SAM/BAM files, not null.

ReadsDataSource

public ReadsDataSource(java.nio.file.Path samPath,
                       htsjdk.samtools.SamReaderFactory customSamReaderFactory)

Initialize this data source with a single SAM/BAM file and a custom SamReaderFactory

Parameters:

samPath - path to SAM/BAM file, not null.

customSamReaderFactory - SamReaderFactory to use, if null a default factory with no reference and validation stringency SILENT is used.

ReadsDataSource

public ReadsDataSource(java.util.List<java.nio.file.Path> samPaths,
                       htsjdk.samtools.SamReaderFactory customSamReaderFactory)

Initialize this data source with multiple SAM/BAM files and a custom SamReaderFactory

Parameters:

samPaths - path to SAM/BAM file, not null.

customSamReaderFactory - SamReaderFactory to use, if null a default factory with no reference and validation stringency SILENT is used.

ReadsDataSource

public ReadsDataSource(java.util.List<java.nio.file.Path> samPaths,
                       java.util.List<java.nio.file.Path> samIndices)

Initialize this data source with multiple SAM/BAM/CRAM files, and explicit indices for those files.

Parameters:

samPaths - paths to SAM/BAM/CRAM files, not null

samIndices - indices for all of the SAM/BAM/CRAM files, in the same order as samPaths. May be null, in which case index paths are inferred automatically.

ReadsDataSource

public ReadsDataSource(java.util.List<java.nio.file.Path> samPaths,
                       java.util.List<java.nio.file.Path> samIndices,
                       htsjdk.samtools.SamReaderFactory customSamReaderFactory)

Initialize this data source with multiple SAM/BAM/CRAM files, explicit indices for those files, and a custom SamReaderFactory.

Parameters:

samPaths - paths to SAM/BAM/CRAM files, not null

samIndices - indices for all of the SAM/BAM/CRAM files, in the same order as samPaths. May be null, in which case index paths are inferred automatically.

customSamReaderFactory - SamReaderFactory to use, if null a default factory with no reference and validation stringency SILENT is used.

ReadsDataSource

public ReadsDataSource(java.util.List<java.nio.file.Path> samPaths,
                       java.util.List<java.nio.file.Path> samIndices,
                       htsjdk.samtools.SamReaderFactory customSamReaderFactory,
                       int cloudPrefetchBuffer,
                       int cloudIndexPrefetchBuffer)

Initialize this data source with multiple SAM/BAM/CRAM files, explicit indices for those files, and a custom SamReaderFactory.

Parameters:

samPaths - paths to SAM/BAM/CRAM files, not null

samIndices - indices for all of the SAM/BAM/CRAM files, in the same order as samPaths. May be null, in which case index paths are inferred automatically.

customSamReaderFactory - SamReaderFactory to use, if null a default factory with no reference and validation stringency SILENT is used.

cloudPrefetchBuffer - MB size of caching/prefetching wrapper for the data, if on Google Cloud (0 to disable).

cloudIndexPrefetchBuffer - MB size of caching/prefetching wrapper for the index, if on Google Cloud (0 to disable).

ReadsDataSource

public ReadsDataSource(java.util.List<java.nio.file.Path> samPaths,
                       java.util.List<java.nio.file.Path> samIndices,
                       htsjdk.samtools.SamReaderFactory customSamReaderFactory,
                       java.util.function.Function<java.nio.channels.SeekableByteChannel,java.nio.channels.SeekableByteChannel> cloudWrapper,
                       java.util.function.Function<java.nio.channels.SeekableByteChannel,java.nio.channels.SeekableByteChannel> cloudIndexWrapper)

Initialize this data source with multiple SAM/BAM/CRAM files, explicit indices for those files, and a custom SamReaderFactory.

Parameters:

samPaths - paths to SAM/BAM/CRAM files, not null

samIndices - indices for all of the SAM/BAM/CRAM files, in the same order as samPaths. May be null, in which case index paths are inferred automatically.

customSamReaderFactory - SamReaderFactory to use, if null a default factory with no reference and validation stringency SILENT is used.

cloudWrapper - caching/prefetching wrapper for the data, if on Google Cloud.

cloudIndexWrapper - caching/prefetching wrapper for the index, if on Google Cloud.

Method Detail

indicesAvailable

public boolean indicesAvailable()

Are indices available for all files?

setTraversalBounds

public void setTraversalBounds(java.util.List<SimpleInterval> intervals)

Restricts a traversal of this data source via iterator() to only return reads which overlap the given intervals. Calls to query(org.broadinstitute.hellbender.utils.SimpleInterval) are not affected by setting these intervals.

Parameters:

intervals - Our next full traversal will return only reads overlapping these intervals

setTraversalBounds

public void setTraversalBounds(TraversalParameters traversalParameters)

Restricts a traversal of this data source via iterator() to only return reads that overlap the given intervals, and to unmapped reads if specified. Calls to query(org.broadinstitute.hellbender.utils.SimpleInterval) are not affected by this method.

Parameters:

traversalParameters - set of traversal parameters to control which reads get returned by the next call to iterator()

setTraversalBounds

public void setTraversalBounds(java.util.List<SimpleInterval> intervals,
                               boolean traverseUnmapped)

Restricts a traversal of this data source via iterator() to only return reads that overlap the given intervals, and to unmapped reads if specified. Calls to query(org.broadinstitute.hellbender.utils.SimpleInterval) are not affected by this method.

Parameters:

intervals - Our next full traversal will return reads overlapping these intervals

traverseUnmapped - Our next full traversal will return unmapped reads (this affects only unmapped reads that have no position -- unmapped reads that have the position of their mapped mates will be included if the interval overlapping that position is included).

traversalIsBounded

public boolean traversalIsBounded()

Returns:

True if traversals initiated via iterator() will be restricted to reads that overlap intervals as configured via setTraversalBounds(java.util.List<org.broadinstitute.hellbender.utils.SimpleInterval>), otherwise false

iterator

public java.util.Iterator<GATKRead> iterator()

Iterate over all reads in this data source. If intervals were provided via setTraversalBounds(java.util.List<org.broadinstitute.hellbender.utils.SimpleInterval>), iteration is limited to reads that overlap that set of intervals.

Specified by:

iterator in interface java.lang.Iterable<GATKRead>

Returns:

An iterator over the reads in this data source, limited to reads that overlap the intervals supplied via setTraversalBounds(java.util.List<org.broadinstitute.hellbender.utils.SimpleInterval>) (if intervals were provided)

query

public java.util.Iterator<GATKRead> query(SimpleInterval interval)

Query reads over a specific interval. This operation is not affected by prior calls to setTraversalBounds(java.util.List<org.broadinstitute.hellbender.utils.SimpleInterval>)

Specified by:

query in interface GATKDataSource<GATKRead>

Parameters:

interval - The interval over which to query

Returns:

Iterator over reads overlapping the query interval

queryUnmapped

public java.util.Iterator<GATKRead> queryUnmapped()

Returns:

An iterator over just the unmapped reads with no assigned position. This operation is not affected by prior calls to setTraversalBounds(java.util.List<org.broadinstitute.hellbender.utils.SimpleInterval>). The underlying file must be indexed.

getHeader

public htsjdk.samtools.SAMFileHeader getHeader()

Returns the SAM header for this data source. Will be a merged header if there are multiple readers. If there is only a single reader, returns its header directly.

Returns:

SAM header for this data source

close

public void close()

Shut down this data source permanently, closing all iterations and readers.

Specified by:

close in interface java.lang.AutoCloseable

getSequenceDictionary

public htsjdk.samtools.SAMSequenceDictionary getSequenceDictionary()

Get the sequence dictionary for this ReadsDataSource

Returns:

SAMSequenceDictionary from the SAMReader backing this if there is only 1 input file, otherwise the merged SAMSequenceDictionary from the merged header