# Interface Reference

All Known Subinterfaces:
  `ReferenceIterator`

public interface Reference
Represents a reference sequence

## Method Summary

Modifier and Type
Method
Description
`Alignment`
`getAlignment(String alignmentId)`
getAlignment
`long`
`getAlignmentCount()`
Count all Alignments within the Reference
`long`
`getAlignmentCount(int categories)`
Count selected Alignments within the Reference
`AlignmentIterator`
`getAlignments(int categories)`
getAlignments
`AlignmentIterator`
`getAlignmentSlice(long start, long length)`
getAlignmentSlice
`AlignmentIterator`
`getAlignmentSlice(long start, long length, int categories)`
getAlignmentSlice
`String`
`getCanonicalName()`
getCanonicalName
`String`
`getCommonName()`
getCommonName
`AlignmentIterator`
`getFilteredAlignmentSlice(long start, long length, int categories, int filters, int mappingQuality)`
getFilteredAlignmentSlice Behaves like "getAlignmentSlice" except that supported filters are applied to selection
`PileupIterator`
`getFilteredPileups(int categories, int filters, int mappingQuality)`
getFilteredPileups Filtered according to criteria in parameters
`PileupIterator`
`getFilteredPileupSlice(long start, long length, int categories, int filters, int mappingQuality)`
getFilteredPileupSlice Creates a PileupIterator on a slice (window) of reference filtered according to criteria in parameters
`boolean`
`getIsCircular()`
getIsCircular
`boolean`
`getIsLocal()`
getIsLocal
`long`
`getLength()`
getLength
`PileupIterator`
`getPileups(int categories)`
getPileups
`PileupIterator`
`getPileupSlice(long start, long length)`
getPileupSlice Creates a PileupIterator on a slice (window) of reference
`PileupIterator`
`getPileupSlice(long start, long length, int categories)`
getPileupSlice Creates a PileupIterator on a slice (window) of reference
`String`
`getReferenceBases(long offset)`
getReferenceBases
`String`
`getReferenceBases(long offset, long length)`
getReferenceBases
`String`
`getReferenceChunk(long offset)`
getReferenceChunk
`String`
`getReferenceChunk(long offset, long length)`
getReferenceChunk

## Method Details

### getCommonName

String getCommonName() throws ErrorMsg
getCommonName

Returns:
  the common name of reference, e.g. "chr1"
Throws:
  `ErrorMsg` - if no common name found

### getCanonicalName

String getCanonicalName() throws ErrorMsg
getCanonicalName

Returns:
  the accessioned name of reference, e.g. "NC_000001.11"
Throws:
  `ErrorMsg` - if no cannonical name found

### getIsCircular

boolean getIsCircular() throws ErrorMsg
getIsCircular

Returns:
  true if reference is circular
Throws:
  `ErrorMsg` - if cannot detect if reference is circular

### getIsLocal

boolean getIsLocal() throws ErrorMsg
getIsLocal

Returns:
  true if Reference is stored locally within the ReadCollection. Unique Reference sequences are stored locally, while Publicly available Reference sequences are stored externally. An exception to this rule is when a public Reference is small, in which case the sequence will be available both locally and externally
Throws:
  `ErrorMsg` - if cannot detect if reference is local

### getLength

long getLength() throws ErrorMsg
getLength

Returns:
  the length of the reference sequence
Throws:
  `ErrorMsg` - if length cannot be detected

### getReferenceBases

String getReferenceBases(long offset) throws ErrorMsg
getReferenceBases

Parameters:
  `offset` - is zero-based and non-negative
Returns:
  sub-sequence bases for Reference
Throws:
  `ErrorMsg` - if no reference-bases found at offset

### getReferenceBases

String getReferenceBases(long offset, long length) throws ErrorMsg
getReferenceBases

Parameters:
  `offset` - is zero-based and non-negative
  `length` - must be ≥ 0
Returns:
  sub-sequence bases for Reference
Throws:
  `ErrorMsg` - if no reference-bases found at offset or lenght invalid

### getReferenceChunk

String getReferenceChunk(long offset) throws ErrorMsg
getReferenceChunk

Parameters:
  `offset` - is zero-based and non-negative
Returns:
  largest contiguous chunk available of sub-sequence bases for Reference

  NB - actual returned sequence may be shorter than requested. to obtain all bases available in chunk, use a negative "size" value

Throws:
  `ErrorMsg` - if no ReferenceChunk found

### getReferenceChunk

String getReferenceChunk(long offset, long length) throws ErrorMsg
getReferenceChunk

Parameters:
  `offset` - is zero-based and non-negative
  `length` - must be > 0
Returns:
  largest contiguous chunk available of sub-sequence bases for Reference

  NB - actual returned sequence may be shorter than requested. to obtain all bases available in chunk, use a negative "size" value

Throws:
  `ErrorMsg` - if no ReferenceChunk found

### getAlignmentCount

long getAlignmentCount() throws ErrorMsg
Count all Alignments within the Reference

Returns:
  0 if there are no aligned Reads, > 0 otherwise
Throws:
  `ErrorMsg` - upon an error accessing data

### getAlignmentCount

long getAlignmentCount(int categories) throws ErrorMsg
Count selected Alignments within the Reference

Parameters:
  `categories` - is a bitfield of AlignmentCategory
Returns:
  count of all alignments
Throws:
  `ErrorMsg` - if no AlignmentCount can be found
See Also:
  - Alignment interface for definitions of AlignmentCategory

### getAlignment

Alignment getAlignment(String alignmentId) throws ErrorMsg
getAlignment

Parameters:
  `alignmentId` - the ID of the Alignment to be returned
Returns:
  an individual Alignment
Throws:
  `ErrorMsg` - if Alignment does not exist or is not part of this Reference

### getAlignments

AlignmentIterator getAlignments(int categories) throws ErrorMsg
getAlignments

Parameters:
  `categories` - the or'ed list of categories
Returns:
  an iterator of contained alignments
Throws:
  `ErrorMsg` - if no Iterator can be created

### getAlignmentSlice

AlignmentIterator getAlignmentSlice(long start, long length) throws ErrorMsg
getAlignmentSlice

Parameters:
  `start` - is a signed 0-based offset from the start of the Reference
  `length` - is the length of the slice.
Returns:
  an iterator across a range of Alignments
Throws:
  `ErrorMsg` - if no Iterator can be created

### getAlignmentSlice

AlignmentIterator getAlignmentSlice(long start, long length, int categories) throws ErrorMsg
getAlignmentSlice

Parameters:
  `start` - is a signed 0-based offset from the start of the Reference
  `length` - is the length of the slice.
  `categories` - provides a means of filtering by AlignmentCategory
Returns:
  an iterator across a range of Alignments
Throws:
  `ErrorMsg` - if no Iterator can be created

### getFilteredAlignmentSlice

AlignmentIterator getFilteredAlignmentSlice(long start, long length, int categories, int filters, int mappingQuality) throws ErrorMsg
getFilteredAlignmentSlice Behaves like "getAlignmentSlice" except that supported filters are applied to selection

Parameters:
  `start` - is a signed 0-based offset from the start of the Reference
  `length` - is the length of the slice.
  `categories` - provides a means of filtering by AlignmentCategory
  `filters` - is a set of filter bits defined in Alignment
  `mappingQuality` - is a cutoff to be used according to bits in "filter"
Returns:
  an iterator across a range of Alignments
Throws:
  `ErrorMsg` - if no Iterator can be created

### getPileups

PileupIterator getPileups(int categories) throws ErrorMsg
getPileups

Parameters:
  `categories` - is a bitfield of AlignmentCategory
Returns:
  an iterator of contained Pileups
Throws:
  `ErrorMsg` - if no Iterator can be created

### getFilteredPileups

PileupIterator getFilteredPileups(int categories, int filters, int mappingQuality) throws ErrorMsg
getFilteredPileups Filtered according to criteria in parameters

Parameters:
  `categories` - is a bitfield of AlignmentCategory
  `filters` - is a set of filter bits defined in Alignment
  `mappingQuality` - is a cutoff to be used according to bits in "filter"
Returns:
  an iterator of contained Pileups
Throws:
  `ErrorMsg` - if no Iterator can be created

### getPileupSlice

PileupIterator getPileupSlice(long start, long length) throws ErrorMsg
getPileupSlice Creates a PileupIterator on a slice (window) of reference

Parameters:
  `start` - is the signed starting position on reference
  `length` - is the unsigned number of bases in the window
Returns:
  an iterator of contained Pileups
Throws:
  `ErrorMsg` - if no Iterator can be created

### getPileupSlice

PileupIterator getPileupSlice(long start, long length, int categories) throws ErrorMsg
getPileupSlice Creates a PileupIterator on a slice (window) of reference

Parameters:
  `start` - is the signed starting position on reference
  `length` - is the unsigned number of bases in the window
  `categories` - provides a means of filtering by AlignmentCategory
Returns:
  an iterator of contained Pileups
Throws:
  `ErrorMsg` - if no Iterator can be created

### getFilteredPileupSlice

PileupIterator getFilteredPileupSlice(long start, long length, int categories, int filters, int mappingQuality) throws ErrorMsg
getFilteredPileupSlice Creates a PileupIterator on a slice (window) of reference filtered according to criteria in parameters

Parameters:
  `start` - is the signed starting position on reference
  `length` - is the unsigned number of bases in the window
  `categories` - provides a means of filtering by AlignmentCategory
  `filters` - is a set of filter bits defined in Alignment
  `mappingQuality` - is a cutoff to be used according to bits in "filter"
Returns:
  an iterator of contained Pileups
Throws:
  `ErrorMsg` - if no Iterator can be created