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 > 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, > 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