JAL-2473 removed unused fields in JalviewDialog
[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    * Answers true if the sequence is composed of amino acid characters. Note
221    * that implementations may use heuristic methods which are not guaranteed to
222    * give the biologically 'right' answer.
223    * 
224    * @return
225    */
226   public boolean isProtein();
227
228   /**
229    * Delete a range of aligned sequence columns, creating a new dataset sequence
230    * if necessary and adjusting start and end positions accordingly.
231    * 
232    * @param i
233    *          first column in range to delete (inclusive)
234    * @param j
235    *          last column in range to delete (exclusive)
236    */
237   public void deleteChars(int i, int j);
238
239   /**
240    * DOCUMENT ME!
241    * 
242    * @param i
243    *          alignment column number
244    * @param c
245    *          character to insert
246    */
247   public void insertCharAt(int i, char c);
248
249   /**
250    * insert given character at alignment column position
251    * 
252    * @param position
253    *          alignment column number
254    * @param count
255    *          length of insert
256    * @param ch
257    *          character to insert
258    */
259   public void insertCharAt(int position, int count, char ch);
260
261   /**
262    * Gets array holding sequence features associated with this sequence. The
263    * array may be held by the sequence's dataset sequence if that is defined.
264    * 
265    * @return hard reference to array
266    */
267   public SequenceFeature[] getSequenceFeatures();
268
269   /**
270    * Replaces the array of sequence features associated with this sequence with
271    * a new array reference. If this sequence has a dataset sequence, then this
272    * method will update the dataset sequence's feature array
273    * 
274    * @param features
275    *          New array of sequence features
276    */
277   public void setSequenceFeatures(SequenceFeature[] features);
278
279   /**
280    * DOCUMENT ME!
281    * 
282    * @param id
283    *          DOCUMENT ME!
284    */
285   public void setPDBId(Vector<PDBEntry> ids);
286
287   /**
288    * Returns a list
289    * 
290    * @return DOCUMENT ME!
291    */
292   public Vector<PDBEntry> getAllPDBEntries();
293
294   /**
295    * Adds the entry to the *normalised* list of PDBIds.
296    * 
297    * If a PDBEntry is passed with the same entry.getID() string as one already
298    * in the list, or one is added that appears to be the same but has a chain ID
299    * appended, then the existing PDBEntry will be updated with the new
300    * attributes instead, unless the entries have distinct chain codes or
301    * associated structure files.
302    * 
303    * @param entry
304    * @return true if the entry was added, false if updated
305    */
306   public boolean addPDBId(PDBEntry entry);
307
308   /**
309    * update the list of PDBEntrys to include any DBRefEntrys citing structural
310    * databases
311    * 
312    * @return true if PDBEntry list was modified
313    */
314   public boolean updatePDBIds();
315
316   public String getVamsasId();
317
318   public void setVamsasId(String id);
319
320   /**
321    * set the array of Database references for the sequence.
322    * 
323    * @param dbs
324    * @deprecated - use is discouraged since side-effects may occur if DBRefEntry
325    *             set are not normalised.
326    */
327   @Deprecated
328   public void setDBRefs(DBRefEntry[] dbs);
329
330   public DBRefEntry[] getDBRefs();
331
332   /**
333    * add the given entry to the list of DBRefs for this sequence, or replace a
334    * similar one if entry contains a map object and the existing one doesnt.
335    * 
336    * @param entry
337    */
338   public void addDBRef(DBRefEntry entry);
339
340   /**
341    * Adds the given sequence feature and returns true, or returns false if it is
342    * already present on the sequence
343    * 
344    * @param sf
345    * @return
346    */
347   public boolean addSequenceFeature(SequenceFeature sf);
348
349   public void deleteFeature(SequenceFeature sf);
350
351   public void setDatasetSequence(SequenceI seq);
352
353   public SequenceI getDatasetSequence();
354
355   /**
356    * Returns a new array containing this sequence's annotations, or null.
357    */
358   public AlignmentAnnotation[] getAnnotation();
359
360   /**
361    * Returns true if this sequence has the given annotation (by object
362    * identity).
363    */
364   public boolean hasAnnotation(AlignmentAnnotation ann);
365
366   /**
367    * Add the given annotation, if not already added, and set its sequence ref to
368    * be this sequence. Does nothing if this sequence's annotations already
369    * include this annotation (by identical object reference).
370    */
371   public void addAlignmentAnnotation(AlignmentAnnotation annotation);
372
373   public void removeAlignmentAnnotation(AlignmentAnnotation annotation);
374
375   /**
376    * Derive a sequence (using this one's dataset or as the dataset)
377    * 
378    * @return duplicate sequence with valid dataset sequence
379    */
380   public SequenceI deriveSequence();
381
382   /**
383    * set the array of associated AlignmentAnnotation for this sequenceI
384    * 
385    * @param revealed
386    */
387   public void setAlignmentAnnotation(AlignmentAnnotation[] annotation);
388
389   /**
390    * Get one or more alignment annotations with a particular label.
391    * 
392    * @param label
393    *          string which each returned annotation must have as a label.
394    * @return null or array of annotations.
395    */
396   public AlignmentAnnotation[] getAnnotation(String label);
397
398   /**
399    * Returns a (possibly empty) list of any annotations that match on given
400    * calcId (source) and label (type). Null values do not match.
401    * 
402    * @param calcId
403    * @param label
404    */
405   public List<AlignmentAnnotation> getAlignmentAnnotations(String calcId,
406           String label);
407
408   /**
409    * create a new dataset sequence (if necessary) for this sequence and sets
410    * this sequence to refer to it. This call will move any features or
411    * references on the sequence onto the dataset. It will also make a duplicate
412    * of existing annotation rows for the dataset sequence, rather than relocate
413    * them in order to preserve external references (since 2.8.2).
414    * 
415    * @return dataset sequence for this sequence
416    */
417   public SequenceI createDatasetSequence();
418
419   /**
420    * Transfer any database references or annotation from entry under a sequence
421    * mapping. <br/>
422    * <strong>Note: DOES NOT transfer sequence associated alignment annotation
423    * </strong><br/>
424    * 
425    * @param entry
426    * @param mp
427    *          null or mapping from entry's numbering to local start/end
428    */
429   public void transferAnnotation(SequenceI entry, Mapping mp);
430
431   /**
432    * @param index
433    *          The sequence index in the MSA
434    */
435   public void setIndex(int index);
436
437   /**
438    * @return The index of the sequence in the alignment
439    */
440   public int getIndex();
441
442   /**
443    * @return The RNA of the sequence in the alignment
444    */
445
446   public RNA getRNA();
447
448   /**
449    * @param rna
450    *          The RNA.
451    */
452   public void setRNA(RNA rna);
453
454   /**
455    * 
456    * @return list of insertions (gap characters) in sequence
457    */
458   public List<int[]> getInsertions();
459
460   /**
461    * Given a pdbId String, return the equivalent PDBEntry if available in the
462    * given sequence
463    * 
464    * @param pdbId
465    * @return
466    */
467   public PDBEntry getPDBEntry(String pdbId);
468
469   /**
470    * Get all primary database/accessions for this sequence's data. These
471    * DBRefEntry are expected to resolve to a valid record in the associated
472    * external database, either directly or via a provided 1:1 Mapping.
473    * 
474    * @return just the primary references (if any) for this sequence, or an empty
475    *         list
476    */
477   public List<DBRefEntry> getPrimaryDBRefs();
478 }