f1cba43be02b5f2ba384f014f612d996a88b4f67
[jalview.git] / src / jalview / datamodel / SequenceI.java
1 /*
2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
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
10  * of the License, or (at your option) any later version.
11  *  
12  * Jalview is distributed in the hope that it will be useful, but 
13  * WITHOUT ANY WARRANTY; without even the implied warranty 
14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
15  * PURPOSE.  See the GNU General Public License for more details.
16  * 
17  * You should have received a copy of the GNU General Public License
18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
19  * The Jalview Authors are detailed in the 'AUTHORS' file.
20  */
21 package jalview.datamodel;
22
23 import jalview.api.DBRefEntryI;
24
25 import java.util.List;
26 import java.util.Vector;
27
28 import fr.orsay.lri.varna.models.rna.RNA;
29
30 /**
31  * Methods for manipulating a sequence, its metadata and related annotation in
32  * an alignment or dataset.
33  * 
34  * @author $author$
35  * @version $Revision$
36  */
37 public interface SequenceI extends ASequenceI
38 {
39   /**
40    * Set the display name for the sequence
41    * 
42    * @param name
43    */
44   public void setName(String name);
45
46   /**
47    * Get the display name
48    */
49   public String getName();
50
51   /**
52    * Set start position of first non-gapped symbol in sequence
53    * 
54    * @param start
55    *          new start position
56    */
57   public void setStart(int start);
58
59   /**
60    * get start position of first non-gapped residue in sequence
61    * 
62    * @return
63    */
64   public int getStart();
65
66   /**
67    * get the displayed id of the sequence
68    * 
69    * @return true means the id will be returned in the form
70    *         DisplayName/Start-End
71    */
72   public String getDisplayId(boolean jvsuffix);
73
74   /**
75    * set end position for last residue in sequence
76    * 
77    * @param end
78    */
79   public void setEnd(int end);
80
81   /**
82    * get end position for last residue in sequence getEnd()>getStart() unless
83    * sequence only consists of gap characters
84    * 
85    * @return
86    */
87   public int getEnd();
88
89   /**
90    * @return length of sequence including gaps
91    * 
92    */
93   public int getLength();
94
95   /**
96    * Replace the sequence with the given string
97    * 
98    * @param sequence
99    *          new sequence string
100    */
101   public void setSequence(String sequence);
102
103   /**
104    * @return sequence as string
105    */
106   public String getSequenceAsString();
107
108   /**
109    * get a range on the sequence as a string
110    * 
111    * @param start
112    *          position relative to start of sequence including gaps (from 0)
113    * @param end
114    *          position relative to start of sequence including gaps (from 0)
115    * 
116    * @return String containing all gap and symbols in specified range
117    */
118   public String getSequenceAsString(int start, int end);
119
120   /**
121    * Get the sequence as a character array
122    * 
123    * @return seqeunce and any gaps
124    */
125   public char[] getSequence();
126
127   /**
128    * get stretch of sequence characters in an array
129    * 
130    * @param start
131    *          absolute index into getSequence()
132    * @param end
133    *          exclusive index of last position in segment to be returned.
134    * 
135    * @return char[max(0,end-start)];
136    */
137   public char[] getSequence(int start, int end);
138
139   /**
140    * create a new sequence object with a subsequence of this one but sharing the
141    * same dataset sequence
142    * 
143    * @param start
144    *          int index for start position (base 0, inclusive)
145    * @param end
146    *          int index for end position (base 0, exclusive)
147    * 
148    * @return SequenceI
149    * @note implementations may use getSequence to get the sequence data
150    */
151   public SequenceI getSubSequence(int start, int end);
152
153   /**
154    * get the i'th character in this sequence's local reference frame (ie from
155    * 0-number of characters lying from start-end)
156    * 
157    * @param i
158    *          index
159    * @return character or ' '
160    */
161   public char getCharAt(int i);
162
163   /**
164    * DOCUMENT ME!
165    * 
166    * @param desc
167    *          DOCUMENT ME!
168    */
169   public void setDescription(String desc);
170
171   /**
172    * DOCUMENT ME!
173    * 
174    * @return DOCUMENT ME!
175    */
176   public String getDescription();
177
178   /**
179    * Return the alignment column for a sequence position
180    * 
181    * @param pos
182    *          lying from start to end
183    * 
184    * @return aligned column for residue (0 if residue is upstream from
185    *         alignment, -1 if residue is downstream from alignment) note.
186    *         Sequence object returns sequence.getEnd() for positions upstream
187    *         currently. TODO: change sequence for
188    *         assert(findIndex(seq.getEnd()+1)==-1) and fix incremental bugs
189    * 
190    */
191   public int findIndex(int pos);
192
193   /**
194    * Returns the sequence position for an alignment position
195    * 
196    * @param i
197    *          column index in alignment (from 0..<length)
198    * 
199    * @return residue number for residue (left of and) nearest ith column
200    */
201   public int findPosition(int i);
202
203   /**
204    * Returns an int array where indices correspond to each residue in the
205    * sequence and the element value gives its position in the alignment
206    * 
207    * @return int[SequenceI.getEnd()-SequenceI.getStart()+1] or null if no
208    *         residues in SequenceI object
209    */
210   public int[] gapMap();
211
212   /**
213    * Returns an int array where indices correspond to each position in sequence
214    * char array and the element value gives the result of findPosition for that
215    * index in the sequence.
216    * 
217    * @return int[SequenceI.getLength()]
218    */
219   public int[] findPositionMap();
220
221   /**
222    * Delete a range of aligned sequence columns, creating a new dataset sequence
223    * if necessary and adjusting start and end positions accordingly.
224    * 
225    * @param i
226    *          first column in range to delete (inclusive)
227    * @param j
228    *          last column in range to delete (exclusive)
229    */
230   public void deleteChars(int i, int j);
231
232   /**
233    * DOCUMENT ME!
234    * 
235    * @param i
236    *          DOCUMENT ME!
237    * @param c
238    *          DOCUMENT ME!
239    */
240   public void insertCharAt(int i, char c);
241
242   /**
243    * DOCUMENT ME!
244    * 
245    * @param position
246    *          DOCUMENT ME!
247    * @param ch
248    *          DOCUMENT ME!
249    */
250   public void insertCharAt(int position, int count, char ch);
251
252   /**
253    * DOCUMENT ME!
254    * 
255    * @return DOCUMENT ME!
256    */
257   public SequenceFeature[] getSequenceFeatures();
258
259   /**
260    * DOCUMENT ME!
261    * 
262    * @param v
263    *          DOCUMENT ME!
264    */
265   public void setSequenceFeatures(SequenceFeature[] features);
266
267   /**
268    * DOCUMENT ME!
269    * 
270    * @param id
271    *          DOCUMENT ME!
272    */
273   public void setPDBId(Vector<PDBEntry> ids);
274
275   /**
276    * Returns a list
277    * 
278    * @return DOCUMENT ME!
279    */
280   public Vector<PDBEntry> getAllPDBEntries();
281
282   /**
283    * add entry to the vector of PDBIds, if it isn't in the list already
284    * 
285    * @param entry
286    */
287   public void addPDBId(PDBEntry entry);
288
289   /**
290    * update the list of PDBEntrys to include any DBRefEntrys citing structural
291    * databases
292    * 
293    * @return true if PDBEntry list was modified
294    */
295   public boolean updatePDBIds();
296
297   public String getVamsasId();
298
299   public void setVamsasId(String id);
300
301   public void setDBRefs(DBRefEntry[] dbs);
302
303   public DBRefEntry[] getDBRefs();
304
305   /**
306    * add the given entry to the list of DBRefs for this sequence, or replace a
307    * similar one if entry contains a map object and the existing one doesnt.
308    * 
309    * @param entry
310    */
311   public void addDBRef(DBRefEntry entry);
312
313   public void addSequenceFeature(SequenceFeature sf);
314
315   public void deleteFeature(SequenceFeature sf);
316
317   public void setDatasetSequence(SequenceI seq);
318
319   public SequenceI getDatasetSequence();
320
321   /**
322    * Returns a new array containing this sequence's annotations, or null.
323    */
324   public AlignmentAnnotation[] getAnnotation();
325
326   /**
327    * Returns true if this sequence has the given annotation (by object
328    * identity).
329    */
330   public boolean hasAnnotation(AlignmentAnnotation ann);
331
332   /**
333    * Add the given annotation, if not already added, and set its sequence ref to
334    * be this sequence. Does nothing if this sequence's annotations already
335    * include this annotation (by identical object reference).
336    */
337   public void addAlignmentAnnotation(AlignmentAnnotation annotation);
338
339   public void removeAlignmentAnnotation(AlignmentAnnotation annotation);
340
341   /**
342    * Derive a sequence (using this one's dataset or as the dataset)
343    * 
344    * @return duplicate sequence with valid dataset sequence
345    */
346   public SequenceI deriveSequence();
347
348   /**
349    * set the array of associated AlignmentAnnotation for this sequenceI
350    * 
351    * @param revealed
352    */
353   public void setAlignmentAnnotation(AlignmentAnnotation[] annotation);
354
355   /**
356    * Get one or more alignment annotations with a particular label.
357    * 
358    * @param label
359    *          string which each returned annotation must have as a label.
360    * @return null or array of annotations.
361    */
362   public AlignmentAnnotation[] getAnnotation(String label);
363
364   /**
365    * Returns a (possibly empty) list of any annotations that match on given
366    * calcId (source) and label (type). Null values do not match.
367    * 
368    * @param calcId
369    * @param label
370    */
371   public List<AlignmentAnnotation> getAlignmentAnnotations(String calcId,
372           String label);
373
374   /**
375    * create a new dataset sequence (if necessary) for this sequence and sets
376    * this sequence to refer to it. This call will move any features or
377    * references on the sequence onto the dataset. It will also make a duplicate
378    * of existing annotation rows for the dataset sequence, rather than relocate
379    * them in order to preserve external references (since 2.8.2).
380    * 
381    * @return dataset sequence for this sequence
382    */
383   public SequenceI createDatasetSequence();
384
385   /**
386    * Transfer any database references or annotation from entry under a sequence
387    * mapping. <br/>
388    * <strong>Note: DOES NOT transfer sequence associated alignment annotation
389    * </strong><br/>
390    * 
391    * @param entry
392    * @param mp
393    *          null or mapping from entry's numbering to local start/end
394    */
395   public void transferAnnotation(SequenceI entry, Mapping mp);
396
397   /**
398    * @param index
399    *          The sequence index in the MSA
400    */
401   public void setIndex(int index);
402
403   /**
404    * @return The index of the sequence in the alignment
405    */
406   public int getIndex();
407
408   /**
409    * @return The RNA of the sequence in the alignment
410    */
411
412   public RNA getRNA();
413
414   /**
415    * @param rna
416    *          The RNA.
417    */
418   public void setRNA(RNA rna);
419
420   /**
421    * 
422    * @return list of insertions (gap characters) in sequence
423    */
424   public List<int[]> getInsertions();
425
426   /**
427    * Given a pdbId String, return the equivalent PDBEntry if available in the
428    * given sequence
429    * 
430    * @param pdbId
431    * @return
432    */
433   public PDBEntry getPDBEntry(String pdbId);
434
435   public void setSourceDBRef(DBRefEntryI dbRef);
436
437   public DBRefEntryI getSourceDBRef();
438 }