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