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 /**
32  *  Represents an alignment between a Fragment and Reference sub-sequence
33  *  provides a path to Read and mate Alignment
34  */
35 public interface Alignment
36     extends Fragment
37 {
38 
39     /**
40      * Retrieve an identifying String that can be used for later access.
41      * The id will be unique within ReadCollection.
42      * @return alignment id
43      * @throws ErrorMsg if the property cannot be retrieved
44      */
getAlignmentId()45     String getAlignmentId ()
46         throws ErrorMsg;
47 
48 
49     /*------------------------------------------------------------------
50      * Reference
51      */
52 
53     /**
54      * getReferenceSpec
55      * @return the name of the reference
56      * @throws ErrorMsg if the property cannot be retrieved
57      */
getReferenceSpec()58     String getReferenceSpec ()
59         throws ErrorMsg;
60 
61     /**
62      * getMappingQuality
63      * @return mapping quality
64      * @throws ErrorMsg if the property cannot be retrieved
65      */
getMappingQuality()66     int getMappingQuality ()
67         throws ErrorMsg;
68 
69     /**
70      * getReferenceBases
71      * @return reference bases
72      * @throws ErrorMsg if the property cannot be retrieved
73      */
getReferenceBases()74     String getReferenceBases ()
75         throws ErrorMsg;
76 
77 
78     /*------------------------------------------------------------------
79      * Fragment
80      */
81 
82     /**
83      *  getReadGroup
84      * @return the name of the read-group
85      * @throws ErrorMsg if the property cannot be retrieved
86      */
getReadGroup()87     String getReadGroup ()
88         throws ErrorMsg;
89 
90     /**
91      * getReadId
92      * @return the unique name of the read
93      * @throws ErrorMsg if the property cannot be retrieved
94      */
getReadId()95     String getReadId ()
96         throws ErrorMsg;
97 
98     /**
99      * getClippedFragmentBases
100      * @return clipped fragment bases
101      * @throws ErrorMsg if the property cannot be retrieved
102      */
getClippedFragmentBases()103     String getClippedFragmentBases ()
104         throws ErrorMsg;
105 
106     /**
107      * getClippedFragmentQualities
108      * @return clipped fragment phred quality values using ASCII offset of 33
109      * @throws ErrorMsg if the property cannot be retrieved
110      */
getClippedFragmentQualities()111     String getClippedFragmentQualities ()
112         throws ErrorMsg;
113 
114     /**
115      * getAlignedFragmentBases
116      * @return fragment bases in their aligned orientation
117      * @throws ErrorMsg if the property cannot be retrieved
118      */
getAlignedFragmentBases()119     String getAlignedFragmentBases ()
120         throws ErrorMsg;
121 
122     /*------------------------------------------------------------------
123      * details of this alignment
124      */
125 
126     /* AlignmentFilter
127      *  values should be or'd together to produce filter bits
128      */
129     static int passFailed = 1;         // reads rejected due to platform/vendor quality criteria
130     static int passDuplicates = 2;     // either a PCR or optical duplicate
131     static int minMapQuality = 4;      // pass alignments with mappingQuality >= param
132     static int maxMapQuality = 8;      // pass alignments with mappingQuality <= param
133     static int noWraparound = 16;      // do not include leading wrapped around alignments to circular references
134     static int startWithinSlice = 32;  // change slice intersection criteria so that start pos is within slice
135 
136     /* AlignmentCategory
137      */
138     static int primaryAlignment   = 1;
139     static int secondaryAlignment = 2;
140     static int all                = primaryAlignment | secondaryAlignment;
141 
142     /**
143      * Alignments are categorized as primary or secondary (alternate).
144      * @return either Alignment.primaryAlignment or Alignment.secondaryAlignment
145      * @throws ErrorMsg if the property cannot be retrieved
146      */
getAlignmentCategory()147     int getAlignmentCategory ()
148         throws ErrorMsg;
149 
150     /**
151      * Retrieve the Alignment's starting position on the Reference
152      * @return unsigned 0-based offset from start of Reference
153      * @throws ErrorMsg if the property cannot be retrieved
154      */
getAlignmentPosition()155     long getAlignmentPosition ()
156         throws ErrorMsg;
157 
158     /**
159      * Retrieve the projected length of an Alignment projected upon Reference.
160      * @return unsigned length of projection
161      * @throws ErrorMsg if the property cannot be retrieved
162      */
getAlignmentLength()163     long getAlignmentLength ()
164         throws ErrorMsg;
165 
166     /**
167      * Test if orientation is reversed with respect to the Reference sequence.
168      * @return true if reversed
169      * @throws ErrorMsg if the property cannot be retrieved
170      */
getIsReversedOrientation()171     boolean getIsReversedOrientation ()
172         throws ErrorMsg;
173 
174     /* ClipEdge
175      */
176     static int clipLeft  = 0;
177     static int clipRight = 1;
178 
179     /**
180      * getSoftClip
181      * @return the position of the clipping
182      * @param edge which edge
183      * @throws ErrorMsg if the property cannot be retrieved
184      */
getSoftClip( int edge )185     int getSoftClip ( int edge )
186         throws ErrorMsg;
187 
188     /**
189      * getTemplateLength
190      * @return the lenght of the template
191      * @throws ErrorMsg if the property cannot be retrieved
192      */
getTemplateLength()193     long getTemplateLength ()
194         throws ErrorMsg;
195 
196     /**
197      * getShortCigar
198      * @param clipped selects if clipping has to be applied
199      * @return a text string describing alignment details
200      * @throws ErrorMsg if the property cannot be retrieved
201      */
getShortCigar( boolean clipped )202     String getShortCigar ( boolean clipped )
203         throws ErrorMsg;
204 
205     /**
206      * getLongCigar
207      * @param clipped selects if clipping has to be applied
208      * @return a text string describing alignment details
209      * @throws ErrorMsg if the property cannot be retrieved
210      */
getLongCigar( boolean clipped )211     String getLongCigar ( boolean clipped )
212         throws ErrorMsg;
213 
214     /**
215      * getRNAOrientation
216      * @return '+' if positive strand is transcribed
217      * @return '-' if negative strand is transcribed
218      * @return '?' if unknown
219      * @throws ErrorMsg if the property cannot be retrieved
220      */
getRNAOrientation()221     char getRNAOrientation ()
222         throws ErrorMsg;
223 
224 
225     /*------------------------------------------------------------------
226      * details of mate alignment
227      */
228 
229     /**
230      * hasMate
231      * @return if the alignment has a mate
232      */
hasMate()233     boolean hasMate ();
234 
235     /**
236      * getMateAlignmentId
237      * @return unique ID of th alignment
238      * @throws ErrorMsg if the property cannot be retrieved
239      */
getMateAlignmentId()240     String getMateAlignmentId ()
241         throws ErrorMsg;
242 
243     /**
244      * getMateAlignment
245      * @return the mate as alignment
246      * @throws ErrorMsg if the property cannot be retrieved
247      */
getMateAlignment()248     Alignment getMateAlignment ()
249         throws ErrorMsg;
250 
251     /**
252      * getMateReferenceSpec
253      * @return the name of the reference the mate is aligned at
254      * @throws ErrorMsg if the property cannot be retrieved
255      */
getMateReferenceSpec()256     String getMateReferenceSpec ()
257         throws ErrorMsg;
258 
259     /**
260      * getMateIsReversedOrientation
261      * @return the orientation of the mate
262      * @throws ErrorMsg if the property cannot be retrieved
263      */
getMateIsReversedOrientation()264     boolean getMateIsReversedOrientation ()
265         throws ErrorMsg;
266 }
267