Package ngs

# 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