# 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