LevelingDownsampler (gatk 4.1.7.0 API)

java.lang.Object
- org.broadinstitute.hellbender.utils.downsampling.Downsampler<T>
- - org.broadinstitute.hellbender.utils.downsampling.LevelingDownsampler<T,E>

Type Parameters:

T - the List type representing the stacks to be leveled

E - the type of the elements of each List

All Implemented Interfaces:

PushPullTransformer<T>
```
public final class LevelingDownsampler<T extends java.util.List<E>,E>
extends Downsampler<T>
```
Leveling Downsampler: Given a set of Lists of arbitrary items and a target size, removes items from the Lists in an even fashion until the total size of all Lists is <= the target size. Leveling does not occur until all Lists have been submitted and signalEndOfInput() is called. The Lists should be LinkedLists for maximum efficiency during item removal, however other kinds of Lists are also accepted (albeit at a slight performance penalty). Since this downsampler extends the Downsampler interface rather than the ReadsDownsampler interface, the Lists need not contain reads.

Constructor Summary

Constructors
Constructor and Description
`LevelingDownsampler(long targetSize)` Construct a LevelingDownsampler Uses the default minElementsPerStack of 1
`LevelingDownsampler(long targetSize, int minElementsPerStack)` Construct a LevelingDownsampler

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`clearItems()` Empty the downsampler of all finalized/pending items
`java.util.List<T>`	`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?
`T`	`peekFinalized()` Peek at the first finalized item stored in this downsampler (or null if there are no finalized items)
`T`	`peekPending()` Peek at the first pending item stored in this downsampler (or null if there are no pending items)
`void`	`signalEndOfInput()` Used to tell the downsampler that no more items will be submitted to it, and that it should finalize any pending items.
`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(java.util.Collection<T> items)` Submit a collection of items to the downsampler for consideration.
`void`	`submit(T item)` Submit one item to the downsampler for consideration.

Methods inherited from class org.broadinstitute.hellbender.utils.downsampling.Downsampler
getNumberOfDiscardedItems, incrementNumberOfDiscardedItems, resetStats

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - LevelingDownsampler
```
public LevelingDownsampler(long targetSize)
```
    Construct a LevelingDownsampler Uses the default minElementsPerStack of 1
    
    Parameters:
    
    targetSize - the sum of the sizes of all individual Lists this downsampler is fed may not exceed this value -- if it does, items are removed from Lists evenly until the total size is <= this value
  - LevelingDownsampler
```
public LevelingDownsampler(long targetSize,
                           int minElementsPerStack)
```
    Construct a LevelingDownsampler
    
    Parameters:
    
    targetSize - the sum of the sizes of all individual Lists this downsampler is fed may not exceed this value -- if it does, items are removed from Lists evenly until the total size is <= this value
    
    minElementsPerStack - no stack will be reduced below this size during downsampling. That is, if a stack has only 3 elements and minElementsPerStack is 3, no matter what we'll not reduce this stack below 3.
- Method Detail
  - submit
```
public void submit(T item)
```
    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 interface PushPullTransformer<T extends java.util.List<E>>
    
    Specified by:
    
    submit in class Downsampler<T extends java.util.List<E>>
    
    Parameters:
    
    item - the individual item to submit to the downsampler for consideration
  - submit
```
public void submit(java.util.Collection<T> items)
```
    Description copied from class: Downsampler
    
    Submit a collection of items to the downsampler for consideration. Should be equivalent to calling submit() on each individual item in the collection.
    
    Specified by:
    
    submit in interface PushPullTransformer<T extends java.util.List<E>>
    
    Overrides:
    
    submit in class Downsampler<T extends java.util.List<E>>
    
    Parameters:
    
    items - the collection of items 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 interface PushPullTransformer<T extends java.util.List<E>>
    
    Specified by:
    
    hasFinalizedItems in class Downsampler<T extends java.util.List<E>>
    
    Returns:
    
    true if this downsampler has > 0 finalized items, otherwise false
  - consumeFinalizedItems
```
public java.util.List<T> 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 interface PushPullTransformer<T extends java.util.List<E>>
    
    Specified by:
    
    consumeFinalizedItems in class Downsampler<T extends java.util.List<E>>
    
    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<T extends java.util.List<E>>
    
    Returns:
    
    true if this downsampler has > 0 pending items, otherwise false
  - peekFinalized
```
public T 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<T extends java.util.List<E>>
    
    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 T 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<T extends java.util.List<E>>
    
    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<T extends java.util.List<E>>
    
    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 interface PushPullTransformer<T extends java.util.List<E>>
    
    Specified by:
    
    signalEndOfInput in class Downsampler<T extends java.util.List<E>>
  - clearItems
```
public void clearItems()
```
    Description copied from class: Downsampler
    
    Empty the downsampler of all finalized/pending items
    
    Specified by:
    
    clearItems in class Downsampler<T extends java.util.List<E>>

Class LevelingDownsampler<T extends java.util.List<E>,E>

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

Constructor Detail

LevelingDownsampler

LevelingDownsampler

Method Detail

submit

submit

hasFinalizedItems

consumeFinalizedItems

hasPendingItems

peekFinalized

peekPending

size

signalEndOfInput

clearItems