JAL-972 workaround for working out source URL for pre DAS 1.6 sources.
[jalview.git] / src / jalview / datamodel / SequenceI.java
1 /*
2  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.7)
3  * Copyright (C) 2011 J Procter, AM Waterhouse, J Engelhardt, LM Lui, G Barton, M Clamp, S Searle
4  * 
5  * This file is part of Jalview.
6  * 
7  * Jalview is free software: you can redistribute it and/or
8  * modify it under the terms of the GNU General Public License 
9  * as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
10  * 
11  * Jalview is distributed in the hope that it will be useful, but 
12  * WITHOUT ANY WARRANTY; without even the implied warranty 
13  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
14  * PURPOSE.  See the GNU General Public License for more details.
15  * 
16  * You should have received a copy of the GNU General Public License along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
17  */
18 package jalview.datamodel;
19
20 import java.util.*;
21
22 /**
23  * DOCUMENT ME!
24  * 
25  * @author $author$
26  * @version $Revision$
27  */
28 public interface SequenceI
29 {
30   /**
31    * Set the display name for the sequence
32    * 
33    * @param name
34    */
35   public void setName(String name);
36
37   /**
38    * Get the display name
39    */
40   public String getName();
41
42   /**
43    * Set start position of first non-gapped symbol in sequence
44    * 
45    * @param start
46    *          new start position
47    */
48   public void setStart(int start);
49
50   /**
51    * get start position of first non-gapped residue in sequence
52    * 
53    * @return
54    */
55   public int getStart();
56
57   /**
58    * get the displayed id of the sequence
59    * 
60    * @return true means the id will be returned in the form
61    *         DisplayName/Start-End
62    */
63   public String getDisplayId(boolean jvsuffix);
64
65   /**
66    * set end position for last residue in sequence
67    * 
68    * @param end
69    */
70   public void setEnd(int end);
71
72   /**
73    * get end position for last residue in sequence getEnd()>getStart() unless
74    * sequence only consists of gap characters
75    * 
76    * @return
77    */
78   public int getEnd();
79
80   /**
81    * @return length of sequence including gaps
82    * 
83    */
84   public int getLength();
85
86   /**
87    * Replace the sequence with the given string
88    * 
89    * @param sequence
90    *          new sequence string
91    */
92   public void setSequence(String sequence);
93
94   /**
95    * @return sequence as string
96    */
97   public String getSequenceAsString();
98
99   /**
100    * get a range on the seuqence as a string
101    * 
102    * @param start
103    *          DOCUMENT ME!
104    * @param end
105    *          DOCUMENT ME!
106    * 
107    * @return DOCUMENT ME!
108    */
109   public String getSequenceAsString(int start, int end);
110
111   /**
112    * DOCUMENT ME!
113    * 
114    * @return DOCUMENT ME!
115    */
116   public char[] getSequence();
117
118   /**
119    * get stretch of sequence characters in an array
120    * 
121    * @param start
122    *          absolute index into getSequence()
123    * @param end
124    *          exclusive index of last position in segment to be returned.
125    * 
126    * @return char[max(0,end-start)];
127    */
128   public char[] getSequence(int start, int end);
129
130   /**
131    * create a new sequence object from start to end of this sequence
132    * 
133    * @param start
134    *          int
135    * @param end
136    *          int
137    * @return SequenceI
138    */
139   public SequenceI getSubSequence(int start, int end);
140
141   /**
142    * DOCUMENT ME!
143    * 
144    * @param i
145    *          DOCUMENT ME!
146    * 
147    * @return DOCUMENT ME!
148    */
149   public char getCharAt(int i);
150
151   /**
152    * DOCUMENT ME!
153    * 
154    * @param desc
155    *          DOCUMENT ME!
156    */
157   public void setDescription(String desc);
158
159   /**
160    * DOCUMENT ME!
161    * 
162    * @return DOCUMENT ME!
163    */
164   public String getDescription();
165
166   /**
167    * DOCUMENT ME!
168    * 
169    * @param pos
170    *          DOCUMENT ME!
171    * 
172    * @return DOCUMENT ME!
173    */
174   public int findIndex(int pos);
175
176   /**
177    * Returns the sequence position for an alignment position
178    * 
179    * @param i
180    *          column index in alignment (from 1)
181    * 
182    * @return residue number for residue (left of and) nearest ith column
183    */
184   public int findPosition(int i);
185
186   /**
187    * Returns an int array where indices correspond to each residue in the
188    * sequence and the element value gives its position in the alignment
189    * 
190    * @return int[SequenceI.getEnd()-SequenceI.getStart()+1] or null if no
191    *         residues in SequenceI object
192    */
193   public int[] gapMap();
194
195   /**
196    * Returns an int array where indices correspond to each position in sequence
197    * char array and the element value gives the result of findPosition for that
198    * index in the sequence.
199    * 
200    * @return int[SequenceI.getLength()]
201    */
202   public int[] findPositionMap();
203
204   /**
205    * Delete a range of aligned sequence columns, creating a new dataset sequence
206    * if necessary and adjusting start and end positions accordingly.
207    * 
208    * @param i
209    *          first column in range to delete
210    * @param j
211    *          last column in range to delete
212    */
213   public void deleteChars(int i, int j);
214
215   /**
216    * DOCUMENT ME!
217    * 
218    * @param i
219    *          DOCUMENT ME!
220    * @param c
221    *          DOCUMENT ME!
222    */
223   public void insertCharAt(int i, char c);
224
225   /**
226    * DOCUMENT ME!
227    * 
228    * @param i
229    *          DOCUMENT ME!
230    * @param c
231    *          DOCUMENT ME!
232    */
233   public void insertCharAt(int i, int length, char c);
234
235   /**
236    * DOCUMENT ME!
237    * 
238    * @return DOCUMENT ME!
239    */
240   public SequenceFeature[] getSequenceFeatures();
241
242   /**
243    * DOCUMENT ME!
244    * 
245    * @param v
246    *          DOCUMENT ME!
247    */
248   public void setSequenceFeatures(SequenceFeature[] features);
249
250   /**
251    * DOCUMENT ME!
252    * 
253    * @param id
254    *          DOCUMENT ME!
255    */
256   public void setPDBId(Vector ids);
257
258   /**
259    * DOCUMENT ME!
260    * 
261    * @return DOCUMENT ME!
262    */
263   public Vector getPDBId();
264
265   /**
266    * add entry to the vector of PDBIds, if it isn't in the list already
267    * 
268    * @param entry
269    */
270   public void addPDBId(PDBEntry entry);
271
272   /**
273    * update the list of PDBEntrys to include any DBRefEntrys citing structural
274    * databases
275    * 
276    * @return true if PDBEntry list was modified
277    */
278   public boolean updatePDBIds();
279
280   public String getVamsasId();
281
282   public void setVamsasId(String id);
283
284   public void setDBRef(DBRefEntry[] dbs);
285
286   public DBRefEntry[] getDBRef();
287
288   /**
289    * add the given entry to the list of DBRefs for this sequence, or replace a
290    * similar one if entry contains a map object and the existing one doesnt.
291    * 
292    * @param entry
293    */
294   public void addDBRef(DBRefEntry entry);
295
296   public void addSequenceFeature(SequenceFeature sf);
297
298   public void deleteFeature(SequenceFeature sf);
299
300   public void setDatasetSequence(SequenceI seq);
301
302   public SequenceI getDatasetSequence();
303
304   public AlignmentAnnotation[] getAnnotation();
305
306   public void addAlignmentAnnotation(AlignmentAnnotation annotation);
307
308   public void removeAlignmentAnnotation(AlignmentAnnotation annotation);
309
310   /**
311    * Derive a sequence (using this one's dataset or as the dataset)
312    * 
313    * @return duplicate sequence with valid dataset sequence
314    */
315   public SequenceI deriveSequence();
316
317   /**
318    * set the array of associated AlignmentAnnotation for this sequenceI
319    * 
320    * @param revealed
321    */
322   public void setAlignmentAnnotation(AlignmentAnnotation[] annotation);
323
324   /**
325    * Get one or more alignment annotations with a particular label.
326    * 
327    * @param label
328    *          string which each returned annotation must have as a label.
329    * @return null or array of annotations.
330    */
331   public AlignmentAnnotation[] getAnnotation(String label);
332
333   /**
334    * create a new dataset sequence (if necessary) for this sequence and sets
335    * this sequence to refer to it. This call will move any features or
336    * references on the sequence onto the dataset.
337    * 
338    * @return dataset sequence for this sequence
339    */
340   public SequenceI createDatasetSequence();
341
342   /**
343    * Transfer any database references or annotation from entry under a sequence
344    * mapping.
345    * 
346    * @param entry
347    * @param mp
348    *          null or mapping from entry's numbering to local start/end
349    */
350   public void transferAnnotation(SequenceI entry, Mapping mp);
351
352 }