ReferenceContext (gatk 4.1.4.1 API)

java.lang.Object
- org.broadinstitute.hellbender.engine.ReferenceContext

All Implemented Interfaces:

htsjdk.samtools.util.Locatable, java.lang.Iterable<java.lang.Byte>
```
public final class ReferenceContext
extends java.lang.Object
implements java.lang.Iterable<java.lang.Byte>, htsjdk.samtools.util.Locatable
```
Wrapper around ReferenceDataSource that presents data from a specific interval/window to a client, without improperly exposing the entire ReferenceDataSource interface. Reference data in the interval is lazily queried, so there's no overhead if the client chooses not to examine contextual information from the reference. Reference bases are returned as bytes for integration with the existing BaseUtils implementation. The reference interval can be optionally expanded by a configurable number of bases in each direction. windowLeadingBases = 3 and windowTrailingBases = 5 means 3 bases of extra reference context before the start of the interval and 5 bases of extra reference context after the end of the interval. Window boundaries can be set either at construction time or afterwards via setWindow(int, int). A ReferenceContext may have no backing data source and/or interval. In these cases, queries on it will always return empty arrays / iterators. You can determine whether there is a backing source of reference data via hasBackingDataSource(), and whether there is an interval via getInterval().

Constructor Summary

Constructors
Constructor and Description
`ReferenceContext()` Create a ReferenceContext with no backing data source.
`ReferenceContext(ReferenceContext thatContext, SimpleInterval interval)` Create a windowed ReferenceContext set up to lazily query the provided interval.
`ReferenceContext(ReferenceDataSource dataSource, SimpleInterval interval)` Create a windowless ReferenceContext set up to lazily query the bases spanning just the provided interval (with no extra bases of context)
`ReferenceContext(ReferenceDataSource dataSource, SimpleInterval interval, int windowLeadingBases, int windowTrailingBases)` Create a windowed ReferenceContext set up to lazily query the provided interval, expanded by the specified number of bases in each direction.
`ReferenceContext(ReferenceDataSource dataSource, SimpleInterval interval, SimpleInterval window)` Create a windowed ReferenceContext set up to lazily query the provided interval, expanded by the specified number of bases in each direction.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`byte`	`getBase()` Get the base at the given locus.
`byte[]`	`getBases()` Get all reference bases in this context.
`byte[]`	`getBases(int windowLeadingBases, int windowTrailingBases)` Get all reference bases in this context with the given leading / trailing bases as the window.
`byte[]`	`getBases(SimpleInterval window)` Get all reference bases in this context with the given window.
`java.lang.String`	`getContig()`
`int`	`getEnd()`
`byte[]`	`getForwardBases()` Get the bases in this context, from the beginning of the interval to the end of the window.
`SimpleInterval`	`getInterval()` Get the location on the reference represented by this context, without including any extra bases of requested context around this interval.
`java.lang.String`	`getKmerAround(int center, int numBasesOnEachSide)` Get a kmer around a position in reference without altering the internal state of the object The position must lie within the window Returns null when, at the ends of a contig, we cannot expand the window to the requested size
`int`	`getStart()`
`SimpleInterval`	`getWindow()` Get the full expanded window of bases spanned by this context, including any extra bases of requested context around the current interval.
`boolean`	`hasBackingDataSource()` Determines whether this ReferenceContext has a backing reference data source.
`java.util.Iterator<java.lang.Byte>`	`iterator()` Get an iterator over the reference bases in this context.
`int`	`numWindowLeadingBases()` Get the number of extra bases of context before the start of our interval, as configured by a call to `setWindow(int, int)` or at construction time.
`int`	`numWindowTrailingBases()` Get the number of extra bases of context after the end of our interval, as configured by a call to `setWindow(int, int)` or at construction time.
`void`	`setWindow(int windowLeadingBases, int windowTrailingBases)` Set expanded window boundaries, subject to cropping at contig boundaries Allows the client to request a specific number of extra reference bases to include before and after the bases within our interval.

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

Methods inherited from interface htsjdk.samtools.util.Locatable
contains, contigsMatch, getLengthOnReference, overlaps, withinDistanceOf

- Constructor Detail
  - ReferenceContext
```
public ReferenceContext()
```
    Create a ReferenceContext with no backing data source. This context will always return empty arrays/iterators in response to queries.
  - ReferenceContext
```
public ReferenceContext(ReferenceDataSource dataSource,
                        SimpleInterval interval)
```
    Create a windowless ReferenceContext set up to lazily query the bases spanning just the provided interval (with no extra bases of context)
    
    Parameters:
    
    dataSource - backing reference data source (may be null if there is no reference)
    
    interval - interval to query, if we are accessed by a client (may be null if our location is unknown)
  - ReferenceContext
```
public ReferenceContext(ReferenceDataSource dataSource,
                        SimpleInterval interval,
                        int windowLeadingBases,
                        int windowTrailingBases)
```
    Create a windowed ReferenceContext set up to lazily query the provided interval, expanded by the specified number of bases in each direction. Window boundaries are cropped at contig boundaries, if necessary.
    
    Parameters:
    
    dataSource - backing reference data source (may be null if there is no reference)
    
    interval - our location on the reference (may be null if our location is unknown)
    
    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.
  - ReferenceContext
```
public ReferenceContext(ReferenceContext thatContext,
                        SimpleInterval interval)
```
    Create a windowed ReferenceContext set up to lazily query the provided interval. Window is preserved from thatReferenceContext.
    
    Parameters:
    
    thatContext - An existing ReferenceContext on which to base this new one.
    
    interval - our location on the reference (may be null if our location is unknown)
  - ReferenceContext
```
public ReferenceContext(ReferenceDataSource dataSource,
                        SimpleInterval interval,
                        SimpleInterval window)
```
    Create a windowed ReferenceContext set up to lazily query the provided interval, expanded by the specified number of bases in each direction. Window boundaries are cropped at contig boundaries, if necessary.
    
    Parameters:
    
    dataSource - backing reference data source (may be null if there is no reference)
    
    interval - our location on the reference (may be null if our location is unknown)
    
    window - the expanded location on the reference. May be null if our location is unknown or there is no expanded window (ie., the interval == window case). Must be null if interval is null. Must contain interval if both are non-null.
- Method Detail
  - getContig
```
public java.lang.String getContig()
```
    Specified by:
    
    getContig in interface htsjdk.samtools.util.Locatable
  - getStart
```
public int getStart()
```
    Specified by:
    
    getStart in interface htsjdk.samtools.util.Locatable
  - getEnd
```
public int getEnd()
```
    Specified by:
    
    getEnd in interface htsjdk.samtools.util.Locatable
  - hasBackingDataSource
```
public boolean hasBackingDataSource()
```
    Determines whether this ReferenceContext has a backing reference data source. A ReferenceContext with no backing data source will always return an empty bases array from getBases() and an empty iterator from iterator()
    
    Returns:
    
    true if this ReferenceContext has a backing reference data source, otherwise false
  - iterator
```
public java.util.Iterator<java.lang.Byte> iterator()
```
    Get an iterator over the reference bases in this context. Will return an empty iterator if this context has no backing data source and/or interval. Call setWindow(int, int) before calling this method if you want to configure the amount of extra reference context to include around the current interval
    
    Specified by:
    
    iterator in interface java.lang.Iterable<java.lang.Byte>
    
    Returns:
    
    iterator over the reference bases in this context
  - getBases
```
public byte[] getBases()
```
    Get all reference bases in this context. The results are cached in this object for future queries. Will always return an empty array if there is no backing data source and/or interval to query. Call setWindow(int, int) before calling this method if you want to configure the amount of extra reference context to include around the current interval
    
    Returns:
    
    reference bases in this context, as a byte array
  - getBases
```
public byte[] getBases(SimpleInterval window)
```
    Get all reference bases in this context with the given window. Does not cache results or modify this ReferenceContext at all. Will always return an empty array if there is no backing data source and/or interval to query.
    
    Returns:
    
    reference bases in this context, as a byte array
  - getBases
```
public byte[] getBases(int windowLeadingBases,
                       int windowTrailingBases)
```
    Get all reference bases in this context with the given leading / trailing bases as the window. Uses the current window as a basis for the position. Does not cache results or modify this ReferenceContext at all. Will always return an empty array if there is no backing data source and/or interval to query.
    
    Returns:
    
    reference bases in this context, as a byte array
  - getForwardBases
```
public byte[] getForwardBases()
```
    Get the bases in this context, from the beginning of the interval to the end of the window.
  - getInterval
```
public SimpleInterval getInterval()
```
    Get the location on the reference represented by this context, without including any extra bases of requested context around this interval.
    
    Returns:
    
    location on the reference represented by this context as a SimpleInterval (may be null if we have no known location)
  - getWindow
```
public SimpleInterval getWindow()
```
    Get the full expanded window of bases spanned by this context, including any extra bases of requested context around the current interval. Note that the true window size may be smaller than originally requested due to cropping at contig boundaries.
    
    Returns:
    
    full expanded window of bases spanned by this context as a SimpleInterval (will be null if this context has no interval)
  - setWindow
```
public void setWindow(int windowLeadingBases,
                      int windowTrailingBases)
```
    Set expanded window boundaries, subject to cropping at contig boundaries Allows the client to request a specific number of extra reference bases to include before and after the bases within our interval. These extra bases will be returned by calls to getBases() and iterator() in addition to the bases spanning our actual interval. Note that the true window size may be smaller than requested due to cropping at contig boundaries. Call @numWindowLeadingBases and @numWindowTrailingBases to get the actual window dimensions.
    
    Parameters:
    
    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.
  - numWindowLeadingBases
```
public int numWindowLeadingBases()
```
    Get the number of extra bases of context before the start of our interval, as configured by a call to setWindow(int, int) or at construction time. Actual number of bases may be less than originally requested if the interval is near a contig boundary.
    
    Returns:
    
    number of extra bases of context before the start of our interval
  - numWindowTrailingBases
```
public int numWindowTrailingBases()
```
    Get the number of extra bases of context after the end of our interval, as configured by a call to setWindow(int, int) or at construction time. Actual number of bases may be less than originally requested if the interval is near a contig boundary.
    
    Returns:
    
    number of extra bases of context after the end of our interval
  - getBase
```
public byte getBase()
```
    Get the base at the given locus.
    
    Returns:
    
    The base at the given locus from the reference.
  - getKmerAround
```
public java.lang.String getKmerAround(int center,
                                      int numBasesOnEachSide)
```
    Get a kmer around a position in reference without altering the internal state of the object The position must lie within the window Returns null when, at the ends of a contig, we cannot expand the window to the requested size

Class ReferenceContext

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Methods inherited from interface htsjdk.samtools.util.Locatable

Constructor Detail

ReferenceContext

ReferenceContext

ReferenceContext

ReferenceContext

ReferenceContext

Method Detail

getContig

getStart

getEnd

hasBackingDataSource

iterator

getBases

getBases

getBases

getForwardBases

getInterval

getWindow

setWindow

numWindowLeadingBases

numWindowTrailingBases

getBase

getKmerAround