ngs.Reference Maven / Gradle / Ivy
The newest version!
/*===========================================================================
*
* PUBLIC DOMAIN NOTICE
* National Center for Biotechnology Information
*
* This software/database is a "United States Government Work" under the
* terms of the United States Copyright Act. It was written as part of
* the author's official duties as a United States Government employee and
* thus cannot be copyrighted. This software/database is freely available
* to the public for use. The National Library of Medicine and the U.S.
* Government have not placed any restriction on its use or reproduction.
*
* Although all reasonable efforts have been taken to ensure the accuracy
* and reliability of the software and data, the NLM and the U.S.
* Government do not and cannot warrant the performance or results that
* may be obtained by using this software or data. The NLM and the U.S.
* Government disclaim all warranties, express or implied, including
* warranties of performance, merchantability or fitness for any particular
* purpose.
*
* Please cite the author in any work or product based on this material.
*
* ===========================================================================
*
*/
package ngs;
/**
* Represents a reference sequence
*/
public interface Reference
{
/**
* getCommonName
* @return the common name of reference, e.g. "chr1"
* @throws ErrorMsg if no common name found
*/
String getCommonName ()
throws ErrorMsg;
/**
* getCanonicalName
* @return the accessioned name of reference, e.g. "NC_000001.11"
* @throws ErrorMsg if no cannonical name found
*/
String getCanonicalName ()
throws ErrorMsg;
/**
* getIsCircular
* @return true if reference is circular
* @throws ErrorMsg if cannot detect if reference is circular
*/
boolean getIsCircular ()
throws ErrorMsg;
/**
* getLength
* @return the length of the reference sequence
* @throws ErrorMsg if length cannot be detected
*/
long getLength ()
throws ErrorMsg;
/**
* getReferenceBases
* @param offset is zero-based and non-negative
* @return sub-sequence bases for Reference
* @throws ErrorMsg if no reference-bases found at offset
*/
String getReferenceBases ( long offset )
throws ErrorMsg;
/**
* getReferenceBases
* @param offset is zero-based and non-negative
* @param length must be ≥ 0
* @return sub-sequence bases for Reference
* @throws ErrorMsg if no reference-bases found at offset or lenght invalid
*/
String getReferenceBases ( long offset, long length )
throws ErrorMsg;
/**
* getReferenceChunk
* @param offset is zero-based and non-negative
* @return 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
*/
String getReferenceChunk ( long offset )
throws ErrorMsg;
/**
* getReferenceChunk
* @param offset is zero-based and non-negative
* @param length must be > 0
* @return 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
*/
String getReferenceChunk ( long offset, long length )
throws ErrorMsg;
/*----------------------------------------------------------------------
* ALIGNMENTS
*/
/**
* Count all Alignments within the Reference
* @return 0 if there are no aligned Reads, > 0 otherwise
* @throws ErrorMsg upon an error accessing data
*/
long getAlignmentCount ()
throws ErrorMsg;
/**
* Count selected Alignments within the Reference
* @param categories is a bitfield of AlignmentCategory
* @return count of all alignments
* @see ngs.Alignment Alignment interface for definitions of AlignmentCategory
* @throws ErrorMsg if no AlignmentCount can be found
*/
long getAlignmentCount ( int categories )
throws ErrorMsg;
/**
* getAlignment
* @return an individual Alignment
* @param alignmentId the ID of the Alignment to be returned
* @throws ErrorMsg if Alignment does not exist or is not part of this Reference
*/
Alignment getAlignment ( String alignmentId )
throws ErrorMsg;
/* AlignmentCategory
* see Alignment for categories
*/
/**
* getAlignments
* @return an iterator of contained alignments
* @param categories the or'ed list of categories
* @throws ErrorMsg if no Iterator can be created
*/
AlignmentIterator getAlignments ( int categories )
throws ErrorMsg;
/**
* getAlignmentSlice
* @param start is a signed 0-based offset from the start of the Reference
* @param length is the length of the slice.
* @return an iterator across a range of Alignments
* @throws ErrorMsg if no Iterator can be created
*/
AlignmentIterator getAlignmentSlice ( long start, long length )
throws ErrorMsg;
/**
* getAlignmentSlice
* @param start is a signed 0-based offset from the start of the Reference
* @param length is the length of the slice.
* @param categories provides a means of filtering by AlignmentCategory
* @return an iterator across a range of Alignments
* @throws ErrorMsg if no Iterator can be created
*/
AlignmentIterator getAlignmentSlice ( long start, long length, int categories )
throws ErrorMsg;
/**
* getFilteredAlignmentSlice
* Behaves like "getAlignmentSlice" except that supported filters are applied to selection
* @param start is a signed 0-based offset from the start of the Reference
* @param length is the length of the slice.
* @param categories provides a means of filtering by AlignmentCategory
* @param filters is a set of filter bits defined in Alignment
* @param mappingQuality is a cutoff to be used according to bits in "filter"
* @return an iterator across a range of Alignments
* @throws ErrorMsg if no Iterator can be created
*
*/
AlignmentIterator getFilteredAlignmentSlice ( long start, long length, int categories, int filters, int mappingQuality )
throws ErrorMsg;
/*----------------------------------------------------------------------
* PILEUP
*/
/**
* getPileups
* @return an iterator of contained Pileups
* @param categories is a bitfield of AlignmentCategory
* @throws ErrorMsg if no Iterator can be created
*/
PileupIterator getPileups ( int categories )
throws ErrorMsg;
/**
* getFilteredPileups
* Filtered according to criteria in parameters
* @param categories is a bitfield of AlignmentCategory
* @param filters is a set of filter bits defined in Alignment
* @param mappingQuality is a cutoff to be used according to bits in "filter"
* @return an iterator of contained Pileups
* @throws ErrorMsg if no Iterator can be created
*/
PileupIterator getFilteredPileups ( int categories, int filters, int mappingQuality )
throws ErrorMsg;
/**
* getPileupSlice
* Creates a PileupIterator on a slice (window) of reference
* @return an iterator of contained Pileups
* @param start is the signed starting position on reference
* @param length is the unsigned number of bases in the window
* @throws ErrorMsg if no Iterator can be created
*/
PileupIterator getPileupSlice ( long start, long length )
throws ErrorMsg;
/**
* getPileupSlice
* Creates a PileupIterator on a slice (window) of reference
* @param start is the signed starting position on reference
* @param length is the unsigned number of bases in the window
* @param categories provides a means of filtering by AlignmentCategory
* @return an iterator of contained Pileups
* @throws ErrorMsg if no Iterator can be created
*/
PileupIterator getPileupSlice ( long start, long length, int categories )
throws ErrorMsg;
/**
* getFilteredPileupSlice
* Creates a PileupIterator on a slice (window) of reference
* filtered according to criteria in parameters
* @param start is the signed starting position on reference
* @param length is the unsigned number of bases in the window
* @param categories provides a means of filtering by AlignmentCategory
* @param filters is a set of filter bits defined in Alignment
* @param mappingQuality is a cutoff to be used according to bits in "filter"
* @return an iterator of contained Pileups
* @throws ErrorMsg if no Iterator can be created
*/
PileupIterator getFilteredPileupSlice ( long start, long length,
int categories, int filters, int mappingQuality )
throws ErrorMsg;
}