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 Detail

      • getName

        java.lang.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​(java.lang.String spec)
        Parameters:
        spec - the name of a contained read group
        Returns:
        true if a call to "getReadGroup()" should succeed
      • getReadGroup

        ReadGroup getReadGroup​(java.lang.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​(java.lang.String spec)
        Parameters:
        spec - the name of a contained Reference
        Returns:
        true if a call to "getReference()" should succeed
      • getReference

        Reference getReference​(java.lang.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​(java.lang.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
      • 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​(java.lang.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