JAL-1632 add score model params to PCAModel and PCA constructors
[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   public void addSequenceFeature(SequenceFeature sf);
341
342   public void deleteFeature(SequenceFeature sf);
343
344   public void setDatasetSequence(SequenceI seq);
345
346   public SequenceI getDatasetSequence();
347
348   /**
349    * Returns a new array containing this sequence's annotations, or null.
350    */
351   public AlignmentAnnotation[] getAnnotation();
352
353   /**
354    * Returns true if this sequence has the given annotation (by object
355    * identity).
356    */
357   public boolean hasAnnotation(AlignmentAnnotation ann);
358
359   /**
360    * Add the given annotation, if not already added, and set its sequence ref to
361    * be this sequence. Does nothing if this sequence's annotations already
362    * include this annotation (by identical object reference).
363    */
364   public void addAlignmentAnnotation(AlignmentAnnotation annotation);
365
366   public void removeAlignmentAnnotation(AlignmentAnnotation annotation);
367
368   /**
369    * Derive a sequence (using this one's dataset or as the dataset)
370    * 
371    * @return duplicate sequence with valid dataset sequence
372    */
373   public SequenceI deriveSequence();
374
375   /**
376    * set the array of associated AlignmentAnnotation for this sequenceI
377    * 
378    * @param revealed
379    */
380   public void setAlignmentAnnotation(AlignmentAnnotation[] annotation);
381
382   /**
383    * Get one or more alignment annotations with a particular label.
384    * 
385    * @param label
386    *          string which each returned annotation must have as a label.
387    * @return null or array of annotations.
388    */
389   public AlignmentAnnotation[] getAnnotation(String label);
390
391   /**
392    * Returns a (possibly empty) list of any annotations that match on given
393    * calcId (source) and label (type). Null values do not match.
394    * 
395    * @param calcId
396    * @param label
397    */
398   public List<AlignmentAnnotation> getAlignmentAnnotations(String calcId,
399           String label);
400
401   /**
402    * create a new dataset sequence (if necessary) for this sequence and sets
403    * this sequence to refer to it. This call will move any features or
404    * references on the sequence onto the dataset. It will also make a duplicate
405    * of existing annotation rows for the dataset sequence, rather than relocate
406    * them in order to preserve external references (since 2.8.2).
407    * 
408    * @return dataset sequence for this sequence
409    */
410   public SequenceI createDatasetSequence();
411
412   /**
413    * Transfer any database references or annotation from entry under a sequence
414    * mapping. <br/>
415    * <strong>Note: DOES NOT transfer sequence associated alignment annotation
416    * </strong><br/>
417    * 
418    * @param entry
419    * @param mp
420    *          null or mapping from entry's numbering to local start/end
421    */
422   public void transferAnnotation(SequenceI entry, Mapping mp);
423
424   /**
425    * @param index
426    *          The sequence index in the MSA
427    */
428   public void setIndex(int index);
429
430   /**
431    * @return The index of the sequence in the alignment
432    */
433   public int getIndex();
434
435   /**
436    * @return The RNA of the sequence in the alignment
437    */
438
439   public RNA getRNA();
440
441   /**
442    * @param rna
443    *          The RNA.
444    */
445   public void setRNA(RNA rna);
446
447   /**
448    * 
449    * @return list of insertions (gap characters) in sequence
450    */
451   public List<int[]> getInsertions();
452
453   /**
454    * Given a pdbId String, return the equivalent PDBEntry if available in the
455    * given sequence
456    * 
457    * @param pdbId
458    * @return
459    */
460   public PDBEntry getPDBEntry(String pdbId);
461
462   /**
463    * Get all primary database/accessions for this sequence's data. These
464    * DBRefEntry are expected to resolve to a valid record in the associated
465    * external database, either directly or via a provided 1:1 Mapping.
466    * 
467    * @return just the primary references (if any) for this sequence, or an empty
468    *         list
469    */
470   public List<DBRefEntry> getPrimaryDBRefs();
471 }