JAL-1632 add score model params to PCAModel and PCA constructors
[jalview.git] / src / jalview / datamodel / AlignmentI.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 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 License for more details.
16  * 
17  * You should have received a copy of the GNU General 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.Hashtable;
24 import java.util.List;
25 import java.util.Map;
26 import java.util.Set;
27
28 /**
29  * Data structure to hold and manipulate a multiple sequence alignment
30  */
31 public interface AlignmentI extends AnnotatedCollectionI
32 {
33   /**
34    * Calculates the number of sequences in an alignment
35    * 
36    * @return Number of sequences in alignment
37    */
38   int getHeight();
39
40   /**
41    * 
42    * Calculates the maximum width of the alignment, including gaps.
43    * 
44    * @return Greatest sequence length within alignment, or -1 if no sequences
45    *         present
46    */
47   @Override
48   int getWidth();
49
50   /**
51    * Calculates if this set of sequences (visible and invisible) are all the
52    * same length
53    * 
54    * @return true if all sequences in alignment are the same length
55    */
56   boolean isAligned();
57
58   /**
59    * Calculates if this set of sequences is all the same length
60    * 
61    * @param includeHidden
62    *          optionally exclude hidden sequences from test
63    * @return true if all (or just visible) sequences are the same length
64    */
65   boolean isAligned(boolean includeHidden);
66
67   /**
68    * Gets sequences as a Synchronized collection
69    * 
70    * @return All sequences in alignment.
71    */
72   @Override
73   List<SequenceI> getSequences();
74
75   /**
76    * Gets sequences as a SequenceI[]
77    * 
78    * @return All sequences in alignment.
79    */
80   SequenceI[] getSequencesArray();
81
82   /**
83    * Find a specific sequence in this alignment.
84    * 
85    * @param i
86    *          Index of required sequence.
87    * 
88    * @return SequenceI at given index.
89    */
90   SequenceI getSequenceAt(int i);
91
92   /**
93    * Returns a map of lists of sequences keyed by sequence name.
94    * 
95    * @return
96    */
97   Map<String, List<SequenceI>> getSequencesByName();
98
99   /**
100    * Add a new sequence to this alignment.
101    * 
102    * @param seq
103    *          New sequence will be added at end of alignment.
104    */
105   void addSequence(SequenceI seq);
106
107   /**
108    * Used to set a particular index of the alignment with the given sequence.
109    * 
110    * @param i
111    *          Index of sequence to be updated. if i>length, sequence will be
112    *          added to end, with no intervening positions.
113    * @param seq
114    *          New sequence to be inserted. The existing sequence at position i
115    *          will be replaced.
116    * @return existing sequence (or null if i>current length)
117    */
118   SequenceI replaceSequenceAt(int i, SequenceI seq);
119
120   /**
121    * Deletes a sequence from the alignment
122    * 
123    * @param s
124    *          Sequence to be deleted.
125    */
126   void deleteSequence(SequenceI s);
127
128   /**
129    * Deletes a sequence from the alignment.
130    * 
131    * @param i
132    *          Index of sequence to be deleted.
133    */
134   void deleteSequence(int i);
135
136   /**
137    * Finds sequence in alignment using sequence name as query.
138    * 
139    * @param name
140    *          Id of sequence to search for.
141    * 
142    * @return Sequence matching query, if found. If not found returns null.
143    */
144   SequenceI findName(String name);
145
146   SequenceI[] findSequenceMatch(String name);
147
148   /**
149    * Finds index of a given sequence in the alignment.
150    * 
151    * @param s
152    *          Sequence to look for.
153    * 
154    * @return Index of sequence within the alignment or -1 if not found
155    */
156   int findIndex(SequenceI s);
157
158   /**
159    * Returns the first group (in the order in which groups were added) that
160    * includes the given sequence instance and aligned position (base 0), or null
161    * if none found
162    * 
163    * @param seq
164    *          - must be contained in the alignment (not a dataset sequence)
165    * @param position
166    * 
167    * @return
168    */
169   SequenceGroup findGroup(SequenceI seq, int position);
170
171   /**
172    * Finds all groups that a given sequence is part of.
173    * 
174    * @param s
175    *          Sequence in alignment.
176    * 
177    * @return All groups containing given sequence.
178    */
179   SequenceGroup[] findAllGroups(SequenceI s);
180
181   /**
182    * Adds a new SequenceGroup to this alignment.
183    * 
184    * @param sg
185    *          New group to be added.
186    */
187   void addGroup(SequenceGroup sg);
188
189   /**
190    * Deletes a specific SequenceGroup
191    * 
192    * @param g
193    *          Group will be deleted from alignment.
194    */
195   void deleteGroup(SequenceGroup g);
196
197   /**
198    * Get all the groups associated with this alignment.
199    * 
200    * @return All groups as a list.
201    */
202   List<SequenceGroup> getGroups();
203
204   /**
205    * Deletes all groups from this alignment.
206    */
207   void deleteAllGroups();
208
209   /**
210    * Adds a new AlignmentAnnotation to this alignment
211    * 
212    * @note Care should be taken to ensure that annotation is at least as wide as
213    *       the longest sequence in the alignment for rendering purposes.
214    */
215   void addAnnotation(AlignmentAnnotation aa);
216
217   /**
218    * moves annotation to a specified index in alignment annotation display stack
219    * 
220    * @param aa
221    *          the annotation object to be moved
222    * @param index
223    *          the destination position
224    */
225   void setAnnotationIndex(AlignmentAnnotation aa, int index);
226
227   /**
228    * Delete all annotations, including auto-calculated if the flag is set true.
229    * Returns true if at least one annotation was deleted, else false.
230    * 
231    * @param includingAutoCalculated
232    * @return
233    */
234   boolean deleteAllAnnotations(boolean includingAutoCalculated);
235
236   /**
237    * Deletes a specific AlignmentAnnotation from the alignment, and removes its
238    * reference from any SequenceI or SequenceGroup object's annotation if and
239    * only if aa is contained within the alignment's annotation vector.
240    * Otherwise, it will do nothing.
241    * 
242    * @param aa
243    *          the annotation to delete
244    * @return true if annotation was deleted from this alignment.
245    */
246   boolean deleteAnnotation(AlignmentAnnotation aa);
247
248   /**
249    * Deletes a specific AlignmentAnnotation from the alignment, and optionally
250    * removes any reference from any SequenceI or SequenceGroup object's
251    * annotation if and only if aa is contained within the alignment's annotation
252    * vector. Otherwise, it will do nothing.
253    * 
254    * @param aa
255    *          the annotation to delete
256    * @param unhook
257    *          flag indicating if any references should be removed from
258    *          annotation - use this if you intend to add the annotation back
259    *          into the alignment
260    * @return true if annotation was deleted from this alignment.
261    */
262   boolean deleteAnnotation(AlignmentAnnotation aa, boolean unhook);
263
264   /**
265    * Get the annotation associated with this alignment (this can be null if no
266    * annotation has ever been created on the alignment)
267    * 
268    * @return array of AlignmentAnnotation objects
269    */
270   @Override
271   AlignmentAnnotation[] getAlignmentAnnotation();
272
273   /**
274    * Change the gap character used in this alignment to 'gc'
275    * 
276    * @param gc
277    *          the new gap character.
278    */
279   void setGapCharacter(char gc);
280
281   /**
282    * Get the gap character used in this alignment
283    * 
284    * @return gap character
285    */
286   char getGapCharacter();
287
288   /**
289    * Test if alignment contains RNA structure
290    * 
291    * @return true if RNA structure AligmnentAnnotation was added to alignment
292    */
293   boolean hasRNAStructure();
294
295   /**
296    * Get the associated dataset for the alignment.
297    * 
298    * @return Alignment containing dataset sequences or null of this is a
299    *         dataset.
300    */
301   AlignmentI getDataset();
302
303   /**
304    * Set the associated dataset for the alignment, or create one.
305    * 
306    * @param dataset
307    *          The dataset alignment or null to construct one.
308    */
309   void setDataset(AlignmentI dataset);
310
311   /**
312    * pads sequences with gaps (to ensure the set looks like an alignment)
313    * 
314    * @return boolean true if alignment was modified
315    */
316   boolean padGaps();
317
318   HiddenSequences getHiddenSequences();
319
320   /**
321    * Compact representation of alignment
322    * 
323    * @return CigarArray
324    */
325   CigarArray getCompactAlignment();
326
327   /**
328    * Set an arbitrary key value pair for an alignment. Note: both key and value
329    * objects should return a meaningful, human readable response to .toString()
330    * 
331    * @param key
332    * @param value
333    */
334   void setProperty(Object key, Object value);
335
336   /**
337    * Get a named property from the alignment.
338    * 
339    * @param key
340    * @return value of property
341    */
342   Object getProperty(Object key);
343
344   /**
345    * Get the property hashtable.
346    * 
347    * @return hashtable of alignment properties (or null if none are defined)
348    */
349   Hashtable getProperties();
350
351   /**
352    * add a reference to a frame of aligned codons for this alignment
353    * 
354    * @param codons
355    */
356   void addCodonFrame(AlignedCodonFrame codons);
357
358   /**
359    * remove a particular codon frame reference from this alignment
360    * 
361    * @param codons
362    * @return true if codon frame was removed.
363    */
364   boolean removeCodonFrame(AlignedCodonFrame codons);
365
366   /**
367    * get all codon frames associated with this alignment
368    * 
369    * @return
370    */
371   List<AlignedCodonFrame> getCodonFrames();
372
373   /**
374    * Set the codon frame mappings (replacing any existing list).
375    */
376   void setCodonFrames(List<AlignedCodonFrame> acfs);
377
378   /**
379    * get codon frames involving sequenceI
380    */
381   List<AlignedCodonFrame> getCodonFrame(SequenceI seq);
382
383   /**
384    * find sequence with given name in alignment
385    * 
386    * @param token
387    *          name to find
388    * @param b
389    *          true implies that case insensitive matching will <em>also</em> be
390    *          tried
391    * @return matched sequence or null
392    */
393   SequenceI findName(String token, boolean b);
394
395   /**
396    * find next sequence with given name in alignment starting after a given
397    * sequence
398    * 
399    * @param startAfter
400    *          the sequence after which the search will be started (usually the
401    *          result of the last call to findName)
402    * @param token
403    *          name to find
404    * @param b
405    *          true implies that case insensitive matching will <em>also</em> be
406    *          tried
407    * @return matched sequence or null
408    */
409   SequenceI findName(SequenceI startAfter, String token, boolean b);
410
411   /**
412    * find first sequence in alignment which is involved in the given search
413    * result object
414    * 
415    * @param results
416    * @return -1 or index of sequence in alignment
417    */
418   int findIndex(SearchResultsI results);
419
420   /**
421    * append sequences and annotation from another alignment object to this one.
422    * Note: this is a straight transfer of object references, and may result in
423    * toappend's dependent data being transformed to fit the alignment (changing
424    * gap characters, etc...). If you are uncertain, use the copy Alignment copy
425    * constructor to create a new version which can be appended without side
426    * effect.
427    * 
428    * @param toappend
429    *          - the alignment to be appended.
430    */
431   void append(AlignmentI toappend);
432
433   /**
434    * Justify the sequences to the left or right by deleting and inserting gaps
435    * before the initial residue or after the terminal residue
436    * 
437    * @param right
438    *          true if alignment padded to right, false to justify to left
439    * @return true if alignment was changed TODO: return undo object
440    */
441   boolean justify(boolean right);
442
443   /**
444    * add given annotation row at given position (0 is start, -1 is end)
445    * 
446    * @param consensus
447    * @param i
448    */
449   void addAnnotation(AlignmentAnnotation consensus, int i);
450
451   /**
452    * search for or create a specific annotation row on the alignment
453    * 
454    * @param name
455    *          name for annotation (must match)
456    * @param calcId
457    *          calcId for the annotation (null or must match)
458    * @param autoCalc
459    *          - value of autocalc flag for the annotation
460    * @param seqRef
461    *          - null or specific sequence reference
462    * @param groupRef
463    *          - null or specific group reference
464    * @param method
465    *          - CalcId for the annotation (must match)
466    * 
467    * @return existing annotation matching the given attributes
468    */
469   AlignmentAnnotation findOrCreateAnnotation(String name, String calcId,
470           boolean autoCalc, SequenceI seqRef, SequenceGroup groupRef);
471
472   /**
473    * move the given group up or down in the alignment by the given number of
474    * rows. Implementor assumes given group is already present on alignment - no
475    * recalculations are triggered.
476    * 
477    * @param sg
478    * @param map
479    * @param up
480    * @param i
481    */
482   void moveSelectedSequencesByOne(SequenceGroup sg,
483           Map<SequenceI, SequenceCollectionI> map, boolean up);
484
485   /**
486    * validate annotation after an edit and update any alignment state flags
487    * accordingly
488    * 
489    * @param alignmentAnnotation
490    */
491   void validateAnnotation(AlignmentAnnotation alignmentAnnotation);
492
493   /**
494    * Align this alignment the same as the given one. If both of the same type
495    * (nucleotide/protein) then align both identically. If this is nucleotide and
496    * the other is protein, make 3 gaps for each gap in the protein sequences. If
497    * this is protein and the other is nucleotide, insert a gap for each 3 gaps
498    * (or part thereof) between nucleotide bases. Returns the number of mapped
499    * sequences that were realigned .
500    * 
501    * @param al
502    * @return
503    */
504   int alignAs(AlignmentI al);
505
506   /**
507    * Returns the set of distinct sequence names in the alignment.
508    * 
509    * @return
510    */
511   Set<String> getSequenceNames();
512
513   /**
514    * Checks if the alignment has at least one sequence with one non-gaped
515    * residue
516    * 
517    * @return
518    */
519   public boolean hasValidSequence();
520
521   /**
522    * Update any mappings to 'virtual' sequences to compatible real ones, if
523    * present in the added sequences. Returns a count of mappings updated.
524    * 
525    * @param seqs
526    * @return
527    */
528   int realiseMappings(List<SequenceI> seqs);
529
530   /**
531    * Returns the first AlignedCodonFrame that has a mapping between the given
532    * dataset sequences
533    * 
534    * @param mapFrom
535    * @param mapTo
536    * @return
537    */
538   AlignedCodonFrame getMapping(SequenceI mapFrom, SequenceI mapTo);
539
540   /**
541    * Calculate the visible start and end index of an alignment. The result is
542    * returned an int array where: int[0] = startIndex, and int[1] = endIndex.
543    * 
544    * @param hiddenCols
545    * @return
546    */
547   public int[] getVisibleStartAndEndIndex(List<int[]> hiddenCols);
548 }