org.broadinstitute.hellbender.utils.downsampling

Class FractionalDownsampler

java.lang.Object

org.broadinstitute.hellbender.utils.downsampling.Downsampler<GATKRead>

org.broadinstitute.hellbender.utils.downsampling.ReadsDownsampler

org.broadinstitute.hellbender.utils.downsampling.FractionalDownsampler

public final class FractionalDownsampler
extends ReadsDownsampler

Fractional Downsampler: selects a specified fraction of the reads for inclusion. Since the selection is done randomly, the actual fraction of reads retained may be slightly more or less than the requested fraction, depending on the total number of reads submitted.

Constructor Summary

Constructors

Constructor and Description
FractionalDownsampler(double fraction) Construct a FractionalDownsampler

Method Summary

Modifier and Type	Method and Description
void	clearItems() Empty the downsampler of all finalized/pending items
java.util.List<GATKRead>	consumeFinalizedItems() Return (and *remove*) all items that have survived downsampling and are waiting to be retrieved.
boolean	hasFinalizedItems() Are there items that have survived the downsampling process waiting to be retrieved?
boolean	hasPendingItems() Are there items stored in this downsampler that it doesn't yet know whether they will ultimately survive the downsampling process?
GATKRead	peekFinalized() Peek at the first finalized item stored in this downsampler (or null if there are no finalized items)
GATKRead	peekPending() Peek at the first pending item stored in this downsampler (or null if there are no pending items)
boolean	requiresCoordinateSortOrder() Does this downsampler require that reads be fed to it in coordinate order?
void	signalEndOfInput() Used to tell the downsampler that no more items will be submitted to it, and that it should finalize any pending items.
void	signalNoMoreReadsBefore(GATKRead read) Tell this downsampler that no more reads located before the provided read (according to the sort order of the read stream) will be fed to it.
int	size() Get the current number of items in this downsampler This should be the best estimate of the total number of elements that will come out of the downsampler were consumeFinalizedItems() to be called immediately after this call.
void	submit(GATKRead newRead) Submit one item to the downsampler for consideration.

Methods inherited from class org.broadinstitute.hellbender.utils.downsampling.Downsampler

getNumberOfDiscardedItems, incrementNumberOfDiscardedItems, resetStats, submit

Methods inherited from class java.lang.Object

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

Constructor Detail

FractionalDownsampler

public FractionalDownsampler(double fraction)

Construct a FractionalDownsampler

Parameters:

fraction - Fraction of reads to preserve, between 0.0 (inclusive) and 1.0 (inclusive). Actual number of reads preserved may differ randomly.

Method Detail

submit

public void submit(GATKRead newRead)

Description copied from class: Downsampler

Submit one item to the downsampler for consideration. Some downsamplers will be able to determine immediately whether the item survives the downsampling process, while others will need to see more items before making that determination.

Specified by:

submit in class Downsampler<GATKRead>

Parameters:

newRead - the individual item to submit to the downsampler for consideration

hasFinalizedItems

public boolean hasFinalizedItems()

Description copied from class: Downsampler

Are there items that have survived the downsampling process waiting to be retrieved?

Specified by:

hasFinalizedItems in class Downsampler<GATKRead>

Returns:

true if this downsampler has > 0 finalized items, otherwise false

consumeFinalizedItems

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

Description copied from class: Downsampler

Return (and *remove*) all items that have survived downsampling and are waiting to be retrieved.

Specified by:

consumeFinalizedItems in class Downsampler<GATKRead>

Returns:

a list of all finalized items this downsampler contains, or an empty list if there are none

hasPendingItems

public boolean hasPendingItems()

Description copied from class: Downsampler

Are there items stored in this downsampler that it doesn't yet know whether they will ultimately survive the downsampling process?

Specified by:

hasPendingItems in class Downsampler<GATKRead>

Returns:

true if this downsampler has > 0 pending items, otherwise false

peekFinalized

public GATKRead peekFinalized()

Description copied from class: Downsampler

Peek at the first finalized item stored in this downsampler (or null if there are no finalized items)

Specified by:

peekFinalized in class Downsampler<GATKRead>

Returns:

the first finalized item in this downsampler (the item is not removed from the downsampler by this call), or null if there are none

peekPending

public GATKRead peekPending()

Description copied from class: Downsampler

Peek at the first pending item stored in this downsampler (or null if there are no pending items)

Specified by:

peekPending in class Downsampler<GATKRead>

Returns:

the first pending item stored in this downsampler (the item is not removed from the downsampler by this call), or null if there are none

size

public int size()

Description copied from class: Downsampler

Get the current number of items in this downsampler This should be the best estimate of the total number of elements that will come out of the downsampler were consumeFinalizedItems() to be called immediately after this call. In other words it should be number of finalized items + estimate of number of pending items that will ultimately be included as well.

Specified by:

size in class Downsampler<GATKRead>

Returns:

a positive integer

signalEndOfInput

public void signalEndOfInput()

Description copied from class: Downsampler

Used to tell the downsampler that no more items will be submitted to it, and that it should finalize any pending items.

Specified by:

signalEndOfInput in class Downsampler<GATKRead>

clearItems

public void clearItems()

Description copied from class: Downsampler

Empty the downsampler of all finalized/pending items

Specified by:

clearItems in class Downsampler<GATKRead>

requiresCoordinateSortOrder

public boolean requiresCoordinateSortOrder()

Description copied from class: ReadsDownsampler

Does this downsampler require that reads be fed to it in coordinate order?

Specified by:

requiresCoordinateSortOrder in class ReadsDownsampler

Returns:

true if reads must be submitted to this downsampler in coordinate order, otherwise false

signalNoMoreReadsBefore

public void signalNoMoreReadsBefore(GATKRead read)

Description copied from class: ReadsDownsampler

Tell this downsampler that no more reads located before the provided read (according to the sort order of the read stream) will be fed to it. Allows position-aware downsamplers to finalize pending reads earlier than they would otherwise be able to, particularly when doing per-sample downsampling and reads for certain samples are sparser than average.

Specified by:

signalNoMoreReadsBefore in class ReadsDownsampler

Parameters:

read - the downsampler will assume that no reads located before this read will ever be submitted to it in the future