1 /*===========================================================================
2 *
3 *                            PUBLIC DOMAIN NOTICE
4 *               National Center for Biotechnology Information
5 *
6 *  This software/database is a "United States Government Work" under the
7 *  terms of the United States Copyright Act.  It was written as part of
8 *  the author's official duties as a United States Government employee and
9 *  thus cannot be copyrighted.  This software/database is freely available
10 *  to the public for use. The National Library of Medicine and the U.S.
11 *  Government have not placed any restriction on its use or reproduction.
12 *
13 *  Although all reasonable efforts have been taken to ensure the accuracy
14 *  and reliability of the software and data, the NLM and the U.S.
15 *  Government do not and cannot warrant the performance or results that
16 *  may be obtained by using this software or data. The NLM and the U.S.
17 *  Government disclaim all warranties, express or implied, including
18 *  warranties of performance, merchantability or fitness for any particular
19 *  purpose.
20 *
21 *  Please cite the author in any work or product based on this material.
22 *
23 * ===========================================================================
24 *
25 */
26 
27 package ngs;
28 
29 
30 /**
31  * Represents a reference sequence
32  */
33 public interface Reference
34 {
35 
36     /**
37      * getCommonName
38      * @return the common name of reference, e.g. "chr1"
39 	 * @throws ErrorMsg if no common name found
40      */
getCommonName()41     String getCommonName ()
42         throws ErrorMsg;
43 
44     /**
45      * getCanonicalName
46      * @return the accessioned name of reference, e.g. "NC_000001.11"
47 	 * @throws ErrorMsg if no cannonical name found
48      */
getCanonicalName()49     String getCanonicalName ()
50         throws ErrorMsg;
51 
52 
53     /**
54      * getIsCircular
55      * @return true if reference is circular
56 	 * @throws ErrorMsg if cannot detect if reference is circular
57      */
getIsCircular()58     boolean getIsCircular ()
59         throws ErrorMsg;
60 
61 
62     /**
63      * getIsLocal
64      * @return true if Reference is stored locally within the ReadCollection.
65      *          Unique Reference sequences are stored locally, while  Publicly available Reference sequences are stored externally.
66      *          An exception to this rule is when a public Reference is small,  in which case the sequence will be available both locally and externally
67 	 * @throws ErrorMsg if cannot detect if reference is local
68      */
getIsLocal()69     boolean getIsLocal ()
70         throws ErrorMsg;
71 
72 
73     /**
74      * getLength
75      * @return the length of the reference sequence
76 	 * @throws ErrorMsg if length cannot be detected
77      */
getLength()78     long getLength ()
79         throws ErrorMsg;
80 
81 
82     /**
83      * getReferenceBases
84      * @param offset is zero-based and non-negative
85      * @return sub-sequence bases for Reference
86 	 * @throws ErrorMsg if no reference-bases found at offset
87      */
getReferenceBases( long offset )88     String getReferenceBases ( long offset )
89         throws ErrorMsg;
90 
91     /**
92      * getReferenceBases
93      * @param offset is zero-based and non-negative
94      * @param length must be ≥ 0
95      * @return sub-sequence bases for Reference
96 	 * @throws ErrorMsg if no reference-bases found at offset or lenght invalid
97      */
getReferenceBases( long offset, long length )98     String getReferenceBases ( long offset, long length )
99         throws ErrorMsg;
100 
101     /**
102      * getReferenceChunk
103      * @param offset is zero-based and non-negative
104      * @return largest contiguous chunk available of sub-sequence bases for Reference
105      * <p>
106      *  NB - actual returned sequence may be shorter
107      *  than requested. to obtain all bases available
108      *  in chunk, use a negative "size" value
109      * </p>
110 	 * @throws ErrorMsg if no ReferenceChunk found
111      */
getReferenceChunk( long offset )112     String getReferenceChunk ( long offset )
113         throws ErrorMsg;
114 
115     /**
116      * getReferenceChunk
117      * @param offset is zero-based and non-negative
118      * @param length must be &gt; 0
119      * @return largest contiguous chunk available of sub-sequence bases for Reference
120      * <p>
121      *  NB - actual returned sequence may be shorter
122      *  than requested. to obtain all bases available
123      *  in chunk, use a negative "size" value
124      * </p>
125 	 * @throws ErrorMsg if no ReferenceChunk found
126      */
getReferenceChunk( long offset, long length )127     String getReferenceChunk ( long offset, long length )
128         throws ErrorMsg;
129 
130     /*----------------------------------------------------------------------
131      * ALIGNMENTS
132      */
133 
134     /**
135      * Count all Alignments within the Reference
136      * @return 0 if there are no aligned Reads, &gt; 0 otherwise
137      * @throws ErrorMsg upon an error accessing data
138      */
getAlignmentCount()139     long getAlignmentCount ()
140         throws ErrorMsg;
141 /**
142      * Count selected Alignments within the Reference
143      * @param categories is a bitfield of AlignmentCategory
144      * @return count of all alignments
145      * @see ngs.Alignment Alignment interface for definitions of AlignmentCategory
146 	 * @throws ErrorMsg if no AlignmentCount can be found
147      */
getAlignmentCount( int categories )148     long getAlignmentCount ( int categories )
149         throws ErrorMsg;
150 
151     /**
152      * getAlignment
153      * @return an individual Alignment
154 	 * @param alignmentId the ID of the Alignment to be returned
155      * @throws ErrorMsg if Alignment does not exist or is not part of this Reference
156      */
getAlignment( String alignmentId )157     Alignment getAlignment ( String alignmentId )
158         throws ErrorMsg;
159 
160     /* AlignmentCategory
161      * see Alignment for categories
162      */
163 
164     /**
165      * getAlignments
166      * @return an iterator of contained alignments
167 	 * @param categories the or'ed list of categories
168      * @throws ErrorMsg if no Iterator can be created
169      */
getAlignments( int categories )170     AlignmentIterator getAlignments ( int categories )
171         throws ErrorMsg;
172 
173     /**
174      * getAlignmentSlice
175      * @param start is a signed 0-based offset from the start of the Reference
176      * @param length is the length of the slice.
177      * @return an iterator across a range of Alignments
178      * @throws ErrorMsg if no Iterator can be created
179      */
getAlignmentSlice( long start, long length )180     AlignmentIterator getAlignmentSlice ( long start, long length )
181         throws ErrorMsg;
182 
183     /**
184      * getAlignmentSlice
185      * @param start is a signed 0-based offset from the start of the Reference
186      * @param length is the length of the slice.
187      * @param categories provides a means of filtering by AlignmentCategory
188      * @return an iterator across a range of Alignments
189      * @throws ErrorMsg if no Iterator can be created
190      */
getAlignmentSlice( long start, long length, int categories )191     AlignmentIterator getAlignmentSlice ( long start, long length, int categories )
192         throws ErrorMsg;
193 
194     /**
195      * getFilteredAlignmentSlice
196      * Behaves like "getAlignmentSlice" except that supported filters are applied to selection
197      * @param start is a signed 0-based offset from the start of the Reference
198      * @param length is the length of the slice.
199      * @param categories provides a means of filtering by AlignmentCategory
200      * @param filters is a set of filter bits defined in Alignment
201      * @param mappingQuality is a cutoff to be used according to bits in "filter"
202      * @return an iterator across a range of Alignments
203      * @throws ErrorMsg if no Iterator can be created
204      *
205      */
getFilteredAlignmentSlice( long start, long length, int categories, int filters, int mappingQuality )206     AlignmentIterator getFilteredAlignmentSlice ( long start, long length, int categories, int filters, int mappingQuality )
207         throws ErrorMsg;
208 
209 
210     /*----------------------------------------------------------------------
211      * PILEUP
212      */
213 
214     /**
215      * getPileups
216      * @return an iterator of contained Pileups
217      * @param categories is a bitfield of AlignmentCategory
218      * @throws ErrorMsg if no Iterator can be created
219      */
getPileups( int categories )220     PileupIterator getPileups ( int categories )
221         throws ErrorMsg;
222 
223     /**
224      * getFilteredPileups
225      * Filtered according to criteria in parameters
226      * @param categories is a bitfield of AlignmentCategory
227      * @param filters is a set of filter bits defined in Alignment
228      * @param mappingQuality is a cutoff to be used according to bits in "filter"
229      * @return an iterator of contained Pileups
230      * @throws ErrorMsg if no Iterator can be created
231      */
getFilteredPileups( int categories, int filters, int mappingQuality )232     PileupIterator getFilteredPileups ( int categories, int filters, int mappingQuality )
233         throws ErrorMsg;
234 
235     /**
236      * getPileupSlice
237      * Creates a PileupIterator on a slice (window) of reference
238      * @return an iterator of contained Pileups
239      * @param start is the signed starting position on reference
240      * @param length is the unsigned number of bases in the window
241      * @throws ErrorMsg if no Iterator can be created
242      */
getPileupSlice( long start, long length )243     PileupIterator getPileupSlice ( long start, long length )
244         throws ErrorMsg;
245 
246     /**
247      * getPileupSlice
248      * Creates a PileupIterator on a slice (window) of reference
249      * @param start is the signed starting position on reference
250      * @param length is the unsigned number of bases in the window
251      * @param categories provides a means of filtering by AlignmentCategory
252      * @return an iterator of contained Pileups
253      * @throws ErrorMsg if no Iterator can be created
254      */
getPileupSlice( long start, long length, int categories )255     PileupIterator getPileupSlice ( long start, long length, int categories )
256         throws ErrorMsg;
257 
258     /**
259      * getFilteredPileupSlice
260      * Creates a PileupIterator on a slice (window) of reference
261      * filtered according to criteria in parameters
262      * @param start is the signed starting position on reference
263      * @param length is the unsigned number of bases in the window
264      * @param categories provides a means of filtering by AlignmentCategory
265      * @param filters is a set of filter bits defined in Alignment
266      * @param mappingQuality is a cutoff to be used according to bits in "filter"
267      * @return an iterator of contained Pileups
268      * @throws ErrorMsg if no Iterator can be created
269      */
getFilteredPileupSlice( long start, long length, int categories, int filters, int mappingQuality )270     PileupIterator getFilteredPileupSlice ( long start, long length,
271             int categories, int filters, int mappingQuality )
272         throws ErrorMsg;
273 }
274