org.broadinstitute.hellbender.utils.locusiterator

Class LocusIteratorByState

java.lang.Object

org.broadinstitute.hellbender.utils.locusiterator.LocusIteratorByState

All Implemented Interfaces:

java.util.Iterator<AlignmentContext>

public final class LocusIteratorByState
extends java.lang.Object
implements java.util.Iterator<AlignmentContext>

Iterator that traverses a SAM File, accumulating information on a per-locus basis Produces AlignmentContext objects, that contain ReadPileups of PileupElements. This class has its core job of converting an iterator of ordered GATKReads into those ReadPileups. There are a few constraints on required and ensured by LIBS: -- Requires the Iterator to returns reads in coordinate sorted order, consistent with the ordering defined by the SAM file format. That for performance reasons this constraint isn't actually enforced. The behavior of LIBS is undefined in the case where the reads are badly ordered. -- The reads in the ReadPileup are themselves in the order of appearance of the reads from the iterator. That is, the pileup is ordered in a way consistent with the SAM coordinate ordering -- Only aligned reads with at least one on-genomic cigar operator are passed on in the pileups. That is, unmapped reads or reads that are all insertions (10I) or soft clipped (10S) are not passed on. -- LIBS can perform per-sample downsampling to a coverage target if requested. -- Because of downsampling there's no guarantee that: -- A read that could be aligned to a position will actually occur in the pileup (downsampled away) -- A read that appears in a previous pileup that could align to a future position will actually occur in that pileup. That is, a read might show up at position i but be downsampled away in the pileup at j -- LIBS can optionally capture all of the reads that come off the iterator, before any leveling downsampling occurs, if requested. This allows users of LIBS to see both a ReadPileup view of the data as well as a stream of unique, sorted reads

Field Summary

Fields

Modifier and Type	Field and Description
static LIBSDownsamplingInfo	NO_DOWNSAMPLING Indicates that we shouldn't do any downsampling

Constructor Summary

Constructors

Constructor and Description
LocusIteratorByState(java.util.Iterator<GATKRead> samIterator, DownsamplingMethod downsamplingMethod, boolean keepUniqueReadListInLIBS, java.util.Collection<java.lang.String> samples, htsjdk.samtools.SAMFileHeader header, boolean includeReadsWithDeletionAtLoci) Create a new LocusIteratorByState
LocusIteratorByState(java.util.Iterator<GATKRead> samIterator, DownsamplingMethod downsamplingMethod, boolean keepUniqueReadListInLIBS, java.util.Collection<java.lang.String> samples, htsjdk.samtools.SAMFileHeader header, boolean includeReadsWithDeletionAtLoci, boolean includeReadsWithNsAtLoci) Create a new LocusIteratorByState
LocusIteratorByState(java.util.Iterator<GATKRead> samIterator, LIBSDownsamplingInfo downsamplingInfo, boolean keepUniqueReadListInLIBS, java.util.Collection<java.lang.String> samples, htsjdk.samtools.SAMFileHeader header, boolean includeReadsWithDeletionAtLoci) Create a new LocusIteratorByState
LocusIteratorByState(java.util.Iterator<GATKRead> samIterator, LIBSDownsamplingInfo downsamplingInfo, boolean keepUniqueReadListInLIBS, java.util.Collection<java.lang.String> samples, htsjdk.samtools.SAMFileHeader header, boolean includeReadsWithDeletionAtLoci, boolean includeReadsWithNsAtLoci) Create a new LocusIteratorByState

Method Summary

Modifier and Type	Method and Description
AlignmentContext	advanceToLocus(int position, boolean stopAtFirstNonEmptySiteAfterPosition) Move this LIBS until we are over position Will return null if cannot reach position (because we run out of data in the locus)
boolean	hasNext() Is there another pileup available?
AlignmentContext	next() Get the next AlignmentContext available from the reads.
java.util.List<GATKRead>	transferReadsFromAllPreviousPileups() Transfer current list of all unique reads that have ever been used in any pileup, clearing old list This list is guaranteed to only contain unique reads, even across calls to the this function.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Iterator

forEachRemaining, remove

Field Detail

NO_DOWNSAMPLING

public static final LIBSDownsamplingInfo NO_DOWNSAMPLING

Indicates that we shouldn't do any downsampling

Constructor Detail

LocusIteratorByState

public LocusIteratorByState(java.util.Iterator<GATKRead> samIterator,
                            DownsamplingMethod downsamplingMethod,
                            boolean keepUniqueReadListInLIBS,
                            java.util.Collection<java.lang.String> samples,
                            htsjdk.samtools.SAMFileHeader header,
                            boolean includeReadsWithDeletionAtLoci)

Create a new LocusIteratorByState

Parameters:

samIterator - the iterator of reads to process into pileups. Reads must be ordered according to standard coordinate-sorted BAM conventions

downsamplingMethod - information about how to downsample the reads

keepUniqueReadListInLIBS - if true, we will keep the unique reads from the samIterator and make them available via the transferReadsFromAllPreviousPileups interface

samples - a complete list of samples present in the read groups for the reads coming from samIterator. This is generally just the set of read group sample fields in the SAMFileHeader. This list of samples may contain a null element, and all reads without read groups will be mapped to this null sample

header - header from the reads

includeReadsWithDeletionAtLoci - Include reads with deletion at loci

LocusIteratorByState

public LocusIteratorByState(java.util.Iterator<GATKRead> samIterator,
                            DownsamplingMethod downsamplingMethod,
                            boolean keepUniqueReadListInLIBS,
                            java.util.Collection<java.lang.String> samples,
                            htsjdk.samtools.SAMFileHeader header,
                            boolean includeReadsWithDeletionAtLoci,
                            boolean includeReadsWithNsAtLoci)

Create a new LocusIteratorByState

Parameters:

samIterator - the iterator of reads to process into pileups. Reads must be ordered according to standard coordinate-sorted BAM conventions

downsamplingMethod - information about how to downsample the reads

keepUniqueReadListInLIBS - if true, we will keep the unique reads from the samIterator and make them available via the transferReadsFromAllPreviousPileups interface

samples - a complete list of samples present in the read groups for the reads coming from samIterator. This is generally just the set of read group sample fields in the SAMFileHeader. This list of samples may contain a null element, and all reads without read groups will be mapped to this null sample

header - header from the reads

includeReadsWithDeletionAtLoci - Include reads with deletion at loci

includeReadsWithNsAtLoci - Include reads with Ns at loci (usually it is not needed)

LocusIteratorByState

public LocusIteratorByState(java.util.Iterator<GATKRead> samIterator,
                            LIBSDownsamplingInfo downsamplingInfo,
                            boolean keepUniqueReadListInLIBS,
                            java.util.Collection<java.lang.String> samples,
                            htsjdk.samtools.SAMFileHeader header,
                            boolean includeReadsWithDeletionAtLoci)

Create a new LocusIteratorByState

Parameters:

samIterator - the iterator of reads to process into pileups. Reads must be ordered according to standard coordinate-sorted BAM conventions

downsamplingInfo - meta-information about how to downsample the reads

keepUniqueReadListInLIBS - if true, we will keep the unique reads from the samIterator and make them available via the transferReadsFromAllPreviousPileups interface

samples - a complete list of samples present in the read groups for the reads coming from samIterator. This is generally just the set of read group sample fields in the SAMFileHeader. This list of samples may contain a null element, and all reads without read groups will be mapped to this null sample

header - header from the reads

includeReadsWithDeletionAtLoci - Include reads with deletion at loci

LocusIteratorByState

public LocusIteratorByState(java.util.Iterator<GATKRead> samIterator,
                            LIBSDownsamplingInfo downsamplingInfo,
                            boolean keepUniqueReadListInLIBS,
                            java.util.Collection<java.lang.String> samples,
                            htsjdk.samtools.SAMFileHeader header,
                            boolean includeReadsWithDeletionAtLoci,
                            boolean includeReadsWithNsAtLoci)

Create a new LocusIteratorByState

Parameters:

samIterator - the iterator of reads to process into pileups. Reads must be ordered according to standard coordinate-sorted BAM conventions

downsamplingInfo - meta-information about how to downsample the reads

keepUniqueReadListInLIBS - if true, we will keep the unique reads from the samIterator and make them available via the transferReadsFromAllPreviousPileups interface

samples - a complete list of samples present in the read groups for the reads coming from samIterator. This is generally just the set of read group sample fields in the SAMFileHeader. This list of samples may contain a null element, and all reads without read groups will be mapped to this null sample

header - header from the reads

includeReadsWithDeletionAtLoci - Include reads with deletion at loci

includeReadsWithNsAtLoci - Include reads with Ns at loci (usually it is not needed)

Method Detail

hasNext

public boolean hasNext()

Is there another pileup available?

Specified by:

hasNext in interface java.util.Iterator<AlignmentContext>

next

public AlignmentContext next()

Get the next AlignmentContext available from the reads.

Specified by:

next in interface java.util.Iterator<AlignmentContext>

Returns:

a non-null AlignmentContext of the pileup after to the next genomic position covered by at least one read.

advanceToLocus

public AlignmentContext advanceToLocus(int position,
                                       boolean stopAtFirstNonEmptySiteAfterPosition)

Move this LIBS until we are over position Will return null if cannot reach position (because we run out of data in the locus)

Parameters:

position - the start position of the AlignmentContext we want back

stopAtFirstNonEmptySiteAfterPosition - if true, we will stop as soon as we find a context with data with position >= position, otherwise we will return a null value and consume the data for the next position. This means that without specifying this value the LIBS will be in an indeterminate state after calling this function, and should be reconstructed from scratch for subsequent use

Returns:

a AlignmentContext at position, or null if this isn't possible

transferReadsFromAllPreviousPileups

public java.util.List<GATKRead> transferReadsFromAllPreviousPileups()

Transfer current list of all unique reads that have ever been used in any pileup, clearing old list This list is guaranteed to only contain unique reads, even across calls to the this function. It is literally the unique set of reads ever seen. The list occurs in the same order as they are encountered in the underlying iterator. Takes the maintained list of submitted reads, and transfers it to the caller of this function. The old list of set to a new, cleanly allocated list so the caller officially owns the list returned by this call. This is the only way to clear the tracking of submitted reads, if enabled. The purpose of this function is allow users of LIBS to keep track of all of the reads pulled off the underlying GATKRead iterator and that appeared at any point in the list of SAMRecordAlignmentState for any reads. This function is intended to allow users to efficiently reconstruct the unique set of reads used across all pileups. This is necessary for LIBS to handle because attempting to do so from the pileups coming out of LIBS is extremely expensive. This functionality is only available if LIBS was created with the argument to track the reads

Returns:

the current list

Throws:

java.lang.UnsupportedOperationException - if called when keepingSubmittedReads is false