2 * Jalview - A Sequence Alignment Editor and Viewer (Version 2.7)
3 * Copyright (C) 2011 J Procter, AM Waterhouse, J Engelhardt, LM Lui, G Barton, M Clamp, S Searle
5 * This file is part of Jalview.
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 of the License, or (at your option) any later version.
11 * Jalview is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty
13 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
14 * PURPOSE. See the GNU General Public License for more details.
16 * You should have received a copy of the GNU General Public License along with Jalview. If not, see <http://www.gnu.org/licenses/>.
18 package jalview.datamodel;
23 * Data structure to hold and manipulate a multiple sequence alignment
25 public interface AlignmentI extends AnnotatedCollectionI
28 * Calculates the number of sequences in an alignment
30 * @return Number of sequences in alignment
32 public int getHeight();
35 * Calculates the maximum width of the alignment, including gaps.
37 * @return Greatest sequence length within alignment.
39 public int getWidth();
42 * Calculates if this set of sequences (visible and invisible) are all the
45 * @return true if all sequences in alignment are the same length
47 public boolean isAligned();
50 * Calculates if this set of sequences is all the same length
52 * @param includeHidden
53 * optionally exclude hidden sequences from test
54 * @return true if all (or just visible) sequences are the same length
56 public boolean isAligned(boolean includeHidden);
59 * Gets sequences as a Synchronized collection
61 * @return All sequences in alignment.
64 public List<SequenceI> getSequences();
67 * Gets sequences as a SequenceI[]
69 * @return All sequences in alignment.
71 public SequenceI[] getSequencesArray();
74 * Find a specific sequence in this alignment.
77 * Index of required sequence.
79 * @return SequenceI at given index.
81 public SequenceI getSequenceAt(int i);
84 * Add a new sequence to this alignment.
87 * New sequence will be added at end of alignment.
89 public void addSequence(SequenceI seq);
92 * Used to set a particular index of the alignment with the given sequence.
95 * Index of sequence to be updated.
97 * New sequence to be inserted.
99 public void setSequenceAt(int i, SequenceI seq);
102 * Deletes a sequence from the alignment
105 * Sequence to be deleted.
107 public void deleteSequence(SequenceI s);
110 * Deletes a sequence from the alignment.
113 * Index of sequence to be deleted.
115 public void deleteSequence(int i);
118 * Finds sequence in alignment using sequence name as query.
121 * Id of sequence to search for.
123 * @return Sequence matching query, if found. If not found returns null.
125 public SequenceI findName(String name);
127 public SequenceI[] findSequenceMatch(String name);
130 * Finds index of a given sequence in the alignment.
133 * Sequence to look for.
135 * @return Index of sequence within the alignment or -1 if not found
137 public int findIndex(SequenceI s);
140 * Finds group that given sequence is part of.
143 * Sequence in alignment.
145 * @return First group found for sequence. WARNING : Sequences may be members
146 * of several groups. This method is incomplete.
148 public SequenceGroup findGroup(SequenceI s);
151 * Finds all groups that a given sequence is part of.
154 * Sequence in alignment.
156 * @return All groups containing given sequence.
158 public SequenceGroup[] findAllGroups(SequenceI s);
161 * Adds a new SequenceGroup to this alignment.
164 * New group to be added.
166 public void addGroup(SequenceGroup sg);
169 * Deletes a specific SequenceGroup
172 * Group will be deleted from alignment.
174 public void deleteGroup(SequenceGroup g);
177 * Get all the groups associated with this alignment.
179 * @return All groups as a list.
181 public List<SequenceGroup> getGroups();
184 * Deletes all groups from this alignment.
186 public void deleteAllGroups();
189 * Adds a new AlignmentAnnotation to this alignment
191 * @note Care should be taken to ensure that annotation is at least as wide as
192 * the longest sequence in the alignment for rendering purposes.
194 public void addAnnotation(AlignmentAnnotation aa);
197 * moves annotation to a specified index in alignment annotation display stack
200 * the annotation object to be moved
202 * the destination position
204 public void setAnnotationIndex(AlignmentAnnotation aa, int index);
207 * Deletes a specific AlignmentAnnotation from the alignment, and removes its
208 * reference from any SequenceI or SequenceGroup object's annotation if and
209 * only if aa is contained within the alignment's annotation vector.
210 * Otherwise, it will do nothing.
213 * the annotation to delete
214 * @return true if annotation was deleted from this alignment.
216 public boolean deleteAnnotation(AlignmentAnnotation aa);
219 * Deletes a specific AlignmentAnnotation from the alignment, and optionally
220 * removes any reference from any SequenceI or SequenceGroup object's
221 * annotation if and only if aa is contained within the alignment's annotation
222 * vector. Otherwise, it will do nothing.
225 * the annotation to delete
227 * flag indicating if any references should be removed from
228 * annotation - use this if you intend to add the annotation back
230 * @return true if annotation was deleted from this alignment.
232 public boolean deleteAnnotation(AlignmentAnnotation aa, boolean unhook);
235 * Get the annotation associated with this alignment (this can be null if no
236 * annotation has ever been created on the alignment)
238 * @return array of AlignmentAnnotation objects
240 public AlignmentAnnotation[] getAlignmentAnnotation();
243 * Change the gap character used in this alignment to 'gc'
246 * the new gap character.
248 public void setGapCharacter(char gc);
251 * Get the gap character used in this alignment
253 * @return gap character
255 public char getGapCharacter();
258 * Test for all nucleotide alignment
260 * @return true if alignment is nucleotide sequence
262 public boolean isNucleotide();
265 * Test if alignment contains RNA structure
267 * @return true if RNA structure AligmnentAnnotation was added to alignment
269 public boolean hasRNAStructure();
272 * Set alignment to be a nucleotide sequence
275 public void setNucleotide(boolean b);
278 * Get the associated dataset for the alignment.
280 * @return Alignment containing dataset sequences or null of this is a
283 public Alignment getDataset();
286 * Set the associated dataset for the alignment, or create one.
289 * The dataset alignment or null to construct one.
291 public void setDataset(Alignment dataset);
294 * pads sequences with gaps (to ensure the set looks like an alignment)
296 * @return boolean true if alignment was modified
298 public boolean padGaps();
300 public HiddenSequences getHiddenSequences();
303 * Compact representation of alignment
307 public CigarArray getCompactAlignment();
310 * Set an arbitrary key value pair for an alignment. Note: both key and value
311 * objects should return a meaningful, human readable response to .toString()
316 public void setProperty(Object key, Object value);
319 * Get a named property from the alignment.
322 * @return value of property
324 public Object getProperty(Object key);
327 * Get the property hashtable.
329 * @return hashtable of alignment properties (or null if none are defined)
331 public Hashtable getProperties();
334 * add a reference to a frame of aligned codons for this alignment
338 public void addCodonFrame(AlignedCodonFrame codons);
341 * remove a particular codon frame reference from this alignment
344 * @return true if codon frame was removed.
346 public boolean removeCodonFrame(AlignedCodonFrame codons);
349 * get all codon frames associated with this alignment
353 public AlignedCodonFrame[] getCodonFrames();
356 * get a particular codon frame
361 public AlignedCodonFrame getCodonFrame(int index);
364 * get codon frames involving sequenceI
366 public AlignedCodonFrame[] getCodonFrame(SequenceI seq);
369 * find sequence with given name in alignment
374 * true implies that case insensitive matching will <em>also</em> be
376 * @return matched sequence or null
378 public SequenceI findName(String token, boolean b);
381 * find next sequence with given name in alignment starting after a given
385 * the sequence after which the search will be started (usually the
386 * result of the last call to findName)
390 * true implies that case insensitive matching will <em>also</em> be
392 * @return matched sequence or null
394 public SequenceI findName(SequenceI startAfter, String token, boolean b);
397 * find first sequence in alignment which is involved in the given search
401 * @return -1 or index of sequence in alignment
403 public int findIndex(SearchResults results);
406 * append sequences and annotation from another alignment object to this one.
407 * Note: this is a straight transfer of object references, and may result in
408 * toappend's dependent data being transformed to fit the alignment (changing
409 * gap characters, etc...). If you are uncertain, use the copy Alignment copy
410 * constructor to create a new version which can be appended without side
414 * - the alignment to be appended.
416 public void append(AlignmentI toappend);
419 * Justify the sequences to the left or right by deleting and inserting gaps
420 * before the initial residue or after the terminal residue
423 * true if alignment padded to right, false to justify to left
424 * @return true if alignment was changed TODO: return undo object
426 public boolean justify(boolean right);
429 * add given annotation row at given position (0 is start, -1 is end)
434 public void addAnnotation(AlignmentAnnotation consensus, int i);
437 * search for or create a specific annotation row on the alignment
439 * @param method - CalcId for the annotation (must match)
440 * @param autoCalc - value of autocalc flag for the annotation
441 * @param seqRef - null or specific sequence reference
442 * @param groupRef - null or specific group reference
443 * @return existing annotation matching the given attributes
445 public AlignmentAnnotation findOrCreateAnnotation(String name, boolean autoCalc,
446 SequenceI seqRef, SequenceGroup groupRef);
449 * move the given group up or down in the alignment by the given number of rows.
450 * Implementor assumes given group is already present on alignment - no recalculations are triggered.
456 public void moveSelectedSequencesByOne(SequenceGroup sg,
457 Map<SequenceI, SequenceCollectionI> map, boolean up);