# Class CRAMReferenceRegion

java.lang.Object
htsjdk.samtools.cram.build.CRAMReferenceRegion

public class CRAMReferenceRegion extends Object
Holds a region/fragment of a reference contig. Maintains a CRAMReferenceSource for retrieving additional regions. This is a mutable object that is used to traverse along a reference contig via serial calls to either `fetchReferenceBases(int)` or `fetchReferenceBasesByRegion(int, int, int)`. It caches the bases from the previous request, along with metadata about the (0-based) start offset, and length of the cached bases. NOTE: this class is not thread-safe/safe for concurrent access across threads.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final int`
`UNINITIALIZED_LENGTH`
`static final int`
`UNINITIALIZED_START`

## Constructor Summary

Constructors
Constructor
Description
`CRAMReferenceRegion(CRAMReferenceSource cramReferenceSource, SAMSequenceDictionary sequenceDictionary)`

## Method Summary

Modifier and Type
Method
Description
`void`
`fetchReferenceBases(int referenceIndex)`
Return the reference bases for an entire contig given a reference contig index.
`void`
`fetchReferenceBasesByRegion(int referenceIndex, int zeroBasedStart, int requestedFragmentLength)`
Get the reference bases for a region of a reference contig.
`void`
`fetchReferenceBasesByRegion(AlignmentContext alignmentContext)`
Fetch the bases to span an `AlignmentContext`.
`byte[]`
`getCurrentReferenceBases()`
`int`
`getFullContigLength()`
`int`
`getReferenceIndex()`
`int`
`getRegionLength()`
`int`
`getRegionStart()`
`void`
`setEmbeddedReferenceBases(byte[] embeddedReferenceBases, int embeddedReferenceIndex, int zeroBasedStart)`
Set this `CRAMReferenceRegion` to use an embedded reference.

### Methods inherited from class Object

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

## Field Details

### UNINITIALIZED_START

public static final int UNINITIALIZED_START

See Also:
  - Constant Field Values

### UNINITIALIZED_LENGTH

public static final int UNINITIALIZED_LENGTH

See Also:
  - Constant Field Values

## Constructor Details

### CRAMReferenceRegion

public CRAMReferenceRegion(CRAMReferenceSource cramReferenceSource, SAMSequenceDictionary sequenceDictionary)

Parameters:
  `cramReferenceSource` - `CRAMReferenceSource` to use to obtain reference bases
  `sequenceDictionary` - `SAMSequenceDictionary` to use to resolve reference contig names to reference index

## Method Details

### getCurrentReferenceBases

public byte[] getCurrentReferenceBases()

Returns:
  the currently cached reference bases (may return null)

### getReferenceIndex

public int getReferenceIndex()

Returns:
  the current reference index or `ReferenceContext.UNINITIALIZED_REFERENCE_ID` if no index has been established

### getRegionStart

public int getRegionStart()

Returns:
  the 0-based start position of the range of the current reference sequence region. `UNINITIALIZED_START` if no region has been established

### getRegionLength

public int getRegionLength()

Returns:
  the length of the current reference sequence region. `UNINITIALIZED_LENGTH` if no region has been established

### fetchReferenceBases

public void fetchReferenceBases(int referenceIndex)
Return the reference bases for an entire contig given a reference contig index. Note: Serial calls to this method on behalf of non-coordinate sorted inputs can result in thrashing and poor performance due to repeated calls to the underlying CRAMReferenceSource, especially when the CRAMReferenceSource is fetching bases from a remote reference.

Parameters:
  `referenceIndex` - the reference index for which bases should be retrieved.
Throws:
  `IllegalArgumentException` - if the requested index is not present in the sequence dictionary or if the sequence's bases cannot be retrieved from the CRAMReferenceSource

### fetchReferenceBasesByRegion

public void fetchReferenceBasesByRegion(int referenceIndex, int zeroBasedStart, int requestedFragmentLength)
Get the reference bases for a region of a reference contig. If the current region does not match the requested region, the `referenceSource` will be called to retrieve the bases. The caller cannot assume that the entire region requested is always fetched (if the requested range matches the alignment span for CRAM record or slice contains a CRAM records that is mapped beyond the end of the reference contig, fewer bases than were requested may be fetched.

Parameters:
  `referenceIndex` - reference index for which to retrieve bases
  `zeroBasedStart` - zero based start of the first base to be retrieved
  `requestedFragmentLength` - length of the fragment to be retrieved
Throws:
  `IllegalArgumentException` - if the requested sequence cannot be located in the sequence dictionary, or if the requested sequence cannot be provided by the underlying referenceSource

### fetchReferenceBasesByRegion

public void fetchReferenceBasesByRegion(AlignmentContext alignmentContext)
Fetch the bases to span an `AlignmentContext`.

Parameters:
  `alignmentContext` - the alignment context for which to fetch bases. must be an AlignmentContext for a single reference `ReferenceContextType.SINGLE_REFERENCE_TYPE` slice (see `ReferenceContext.isMappedSingleRef()`)

### setEmbeddedReferenceBases

public void setEmbeddedReferenceBases(byte[] embeddedReferenceBases, int embeddedReferenceIndex, int zeroBasedStart)
Set this `CRAMReferenceRegion` to use an embedded reference.

Parameters:
  `embeddedReferenceBases` - the embedded reference bases to be used
  `embeddedReferenceIndex` - the reference ID used in the slice containing the embedded reference
  `zeroBasedStart` - the zero based reference start of the first base in the embedded reference bases

### getFullContigLength

public int getFullContigLength()

Returns:
  the length of the entire reference contig maintained by this region. note that this is not the same as the length of the current bases maintained by this region (this can happen if the region contains a fragment, or an embedded reference fragment), or -1 if no current region is established