Package ngs

# Interface ReadCollection

public interface ReadCollection

Represents an NGS-capable object with a collection of Reads, References and Alignments.

Each of the basic content types may be accessed by id as either a standalone object, or more commonly through an Iterator over a selected collection of objects.

Reads are grouped by ReadGroup. When not specifically assigned, Reads will be placed into the default ReadGroup.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Alignment`
  `getAlignment(String alignmentId)`
  Access a single Alignment by id.
  `long`
  `getAlignmentCount()`
  Count all Alignments within the ReadCollection
  `long`
  `getAlignmentCount(int categories)`
  Count selected Alignments within the ReadCollection
  `AlignmentIterator`
  `getAlignmentRange(long first, long count)`
  getAlignmentRange
  `AlignmentIterator`
  `getAlignmentRange(long first, long count, int categories)`
  getAlignmentRange
  `AlignmentIterator`
  `getAlignments(int categories)`
  Select Alignments by AlignmentCategory.
  `String`
  `getName()`
  Access the simple name of the ReadCollection.
  `Read`
  `getRead(String readId)`
  getRead
  `long`
  `getReadCount()`
  getReadCount
  `long`
  `getReadCount(int categories)`
  getReadCount
  `ReadGroup`
  `getReadGroup(String spec)`
  Access a single ReadGroup by name.
  `ReadGroupIterator`
  `getReadGroups()`
  Access all non-empty ReadGroups.
  `ReadIterator`
  `getReadRange(long first, long count)`
  getReadRange
  `ReadIterator`
  `getReadRange(long first, long count, int categories)`
  getReadRange
  `ReadIterator`
  `getReads(int categories)`
  getReads
  `Reference`
  `getReference(String spec)`
  Access a single Reference by name spec.
  `ReferenceIterator`
  `getReferences()`
  Access all References having aligned Reads.
  `boolean`
  `hasReadGroup(String spec)`
  `boolean`
  `hasReference(String spec)`

- ## Method Details

  - ### getName

    String getName() throws ErrorMsg

    Access the simple name of the ReadCollection. This name is generally extracted from the "spec" used to create the object, but may also be mapped to a canonical name if one may be determined and differs from that given in the spec.

    if the name is extracted from "spec" and contains well-known file extensions that do not form part of a canonical name (e.g. ".sra"), they will be removed.

    Returns:
      the simple name of the ReadCollection
    Throws:
      `ErrorMsg` - if the name cannot be retrieved
    See Also:
      - `NGS class for "spec" definition`

  - ### getReadGroups

    ReadGroupIterator getReadGroups() throws ErrorMsg
    Access all non-empty ReadGroups. Iterator will contain at least one ReadGroup unless the ReadCollection itself is empty.
    Returns:
      an unordered Iterator of ReadGroups
    Throws:
      `ErrorMsg` - only upon an error accessing data

  - ### hasReadGroup

    boolean hasReadGroup(String spec)
    Parameters:
      `spec` - the name of a contained read group
    Returns:
      true if a call to "getReadGroup()" should succeed

  - ### getReadGroup

    ReadGroup getReadGroup(String spec) throws ErrorMsg
    Access a single ReadGroup by name.
    Parameters:
      `spec` - the name of a contained read group
    Returns:
      an instance of the designated ReadGroup
    Throws:
      `ErrorMsg` - if specified ReadGroup is not found
      `ErrorMsg` - upon an error accessing data

  - ### getReferences

    ReferenceIterator getReferences() throws ErrorMsg
    Access all References having aligned Reads. Iterator will contain at least one ReadGroup unless no Reads are aligned.
    Returns:
      an unordered Iterator of References
    Throws:
      `ErrorMsg` - upon an error accessing data

  - ### hasReference

    boolean hasReference(String spec)
    Parameters:
      `spec` - the name of a contained Reference
    Returns:
      true if a call to "getReference()" should succeed

  - ### getReference

    Reference getReference(String spec) throws ErrorMsg
    Access a single Reference by name spec.
    Parameters:
      `spec` - a common or canonical name of a contained reference
    Returns:
      an instance of the designated Reference
    Throws:
      `ErrorMsg` - if the Reference is not found
      `ErrorMsg` - upon an error accessing data

  - ### getAlignment

    Alignment getAlignment(String alignmentId) throws ErrorMsg
    Access a single Alignment by id. The object id is unique within any given ReadCollection, and may designate an Alignment of any category. Note Excessive usage may create pressure on JVM and System memory.
    Parameters:
      `alignmentId` - the ID of the alignment to return
    Returns:
      an individual Alignment instance
    Throws:
      `ErrorMsg` - if Alignment is not found
      `ErrorMsg` - upon an error accessing data

  - ### getAlignments

    AlignmentIterator getAlignments(int categories) throws ErrorMsg
    Select Alignments by AlignmentCategory.
    Parameters:
      `categories` - is a bitfield of AlignmentCategory
    Returns:
      an iterator of all Alignments from specified categories
    Throws:
      `ErrorMsg` - upon an error accessing data

  - ### getAlignmentCount

    long getAlignmentCount() throws ErrorMsg
    Count all Alignments within the ReadCollection
    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 ReadCollection
    Parameters:
      `categories` - is a bitfield of AlignmentCategory
    Returns:
      count of all alignments
    Throws:
      `ErrorMsg` - upon an error accessing data
    See Also:
      - `Alignment interface for definitions of AlignmentCategory`

  - ### getAlignmentRange

    AlignmentIterator getAlignmentRange(long first, long count) throws ErrorMsg
    getAlignmentRange
    Parameters:
      `first` - is an unsigned ordinal into set
      `count` - the number of alignments
    Returns:
      an iterator across a range of Alignments
    Throws:
      `ErrorMsg` - upon an error accessing data

  - ### getAlignmentRange

    AlignmentIterator getAlignmentRange(long first, long count, int categories) throws ErrorMsg
    getAlignmentRange
    Parameters:
      `first` - is an unsigned ordinal into set
      `count` - number of alignments
      `categories` - provides a means of filtering by AlignmentCategory
    Returns:
      an iterator across a range of Alignments
    Throws:
      `ErrorMsg` - upon an error accessing data

  - ### getRead

    Read getRead(String readId) throws ErrorMsg
    getRead
    Parameters:
      `readId` - the ID of the Read to return
    Returns:
      an individual Read
    Throws:
      `ErrorMsg` - if Read does not exist

  - ### getReads

    ReadIterator getReads(int categories) throws ErrorMsg
    getReads
    Parameters:
      `categories` - provides a means of filtering by ReadCategory
    Returns:
      an iterator of all contained machine Reads
    Throws:
      `ErrorMsg` - upon an error accessing data

  - ### getReadCount

    long getReadCount() throws ErrorMsg
    getReadCount
    Returns:
      the number of reads in the collection
    Throws:
      `ErrorMsg` - upon an error accessing data

  - ### getReadCount

    long getReadCount(int categories) throws ErrorMsg
    getReadCount
    Parameters:
      `categories` - provides an optional means of filtering by ReadCategory
    Returns:
      the number of reads in the collection
    Throws:
      `ErrorMsg` - upon an error accessing data

  - ### getReadRange

    ReadIterator getReadRange(long first, long count) throws ErrorMsg
    getReadRange
    Parameters:
      `first` - is an unsigned ordinal into set
      `count` - the number of reads
    Returns:
      an iterator across a range of Reads
    Throws:
      `ErrorMsg` - upon an error accessing data

  - ### getReadRange

    ReadIterator getReadRange(long first, long count, int categories) throws ErrorMsg
    getReadRange
    Parameters:
      `first` - is an unsigned ordinal into set
      `count` - the number of reads
      `categories` - provides an optional means of filtering by ReadCategory
    Returns:
      an iterator across a range of Reads
    Throws:
      `ErrorMsg` - upon an error accessing data