2 * Jalview - A Sequence Alignment Editor and Viewer (Version 2.6)
3 * Copyright (C) 2010 J Procter, AM Waterhouse, 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
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 Vector
61 * @return All sequences in alignment.
63 public Vector getSequences();
66 * Gets sequences as a SequenceI[]
68 * @return All sequences in alignment.
70 public SequenceI[] getSequencesArray();
73 * Find a specific sequence in this alignment.
76 * Index of required sequence.
78 * @return SequenceI at given index.
80 public SequenceI getSequenceAt(int i);
83 * Add a new sequence to this alignment.
86 * New sequence will be added at end of alignment.
88 public void addSequence(SequenceI seq);
91 * Used to set a particular index of the alignment with the given sequence.
94 * Index of sequence to be updated.
96 * New sequence to be inserted.
98 public void setSequenceAt(int i, SequenceI seq);
101 * Deletes a sequence from the alignment
104 * Sequence to be deleted.
106 public void deleteSequence(SequenceI s);
109 * Deletes a sequence from the alignment.
112 * Index of sequence to be deleted.
114 public void deleteSequence(int i);
117 * Finds sequence in alignment using sequence name as query.
120 * Id of sequence to search for.
122 * @return Sequence matching query, if found. If not found returns null.
124 public SequenceI findName(String name);
126 public SequenceI[] findSequenceMatch(String name);
129 * Finds index of a given sequence in the alignment.
132 * Sequence to look for.
134 * @return Index of sequence within the alignment or -1 if not found
136 public int findIndex(SequenceI s);
139 * Finds group that given sequence is part of.
142 * Sequence in alignment.
144 * @return First group found for sequence. WARNING : Sequences may be members
145 * of several groups. This method is incomplete.
147 public SequenceGroup findGroup(SequenceI s);
150 * Finds all groups that a given sequence is part of.
153 * Sequence in alignment.
155 * @return All groups containing given sequence.
157 public SequenceGroup[] findAllGroups(SequenceI s);
160 * Adds a new SequenceGroup to this alignment.
163 * New group to be added.
165 public void addGroup(SequenceGroup sg);
168 * Deletes a specific SequenceGroup
171 * Group will be deleted from alignment.
173 public void deleteGroup(SequenceGroup g);
176 * Get all the groups associated with this alignment.
178 * @return All groups as a Vector.
180 public Vector getGroups();
183 * Deletes all groups from this alignment.
185 public void deleteAllGroups();
188 * Adds a new AlignmentAnnotation to this alignment
190 * @note Care should be taken to ensure that annotation is at least as wide as
191 * the longest sequence in the alignment for rendering purposes.
193 public void addAnnotation(AlignmentAnnotation aa);
196 * moves annotation to a specified index in alignment annotation display stack
199 * the annotation object to be moved
201 * the destination position
203 public void setAnnotationIndex(AlignmentAnnotation aa, int index);
206 * Deletes a specific AlignmentAnnotation from the alignment, and removes its
207 * reference from any SequenceI or SequenceGroup object's annotation if and only if aa is
208 * contained within the alignment's annotation vector. Otherwise, it will do
212 * the annotation to delete
213 * @return true if annotation was deleted from this alignment.
215 public boolean deleteAnnotation(AlignmentAnnotation aa);
218 * Deletes a specific AlignmentAnnotation from the alignment, and optionally removes any
219 * reference from any SequenceI or SequenceGroup object's annotation if and only if aa is
220 * contained within the alignment's annotation vector. Otherwise, it will do
224 * the annotation to delete
226 * flag indicating if any references should be removed from annotation - use this if you intend to add the annotation back into the alignment
227 * @return true if annotation was deleted from this alignment.
229 public boolean deleteAnnotation(AlignmentAnnotation aa, boolean unhook);
232 * Get the annotation associated with this alignment (this can be null if no
233 * annotation has ever been created on the alignment)
235 * @return array of AlignmentAnnotation objects
237 public AlignmentAnnotation[] getAlignmentAnnotation();
240 * Change the gap character used in this alignment to 'gc'
243 * the new gap character.
245 public void setGapCharacter(char gc);
248 * Get the gap character used in this alignment
250 * @return gap character
252 public char getGapCharacter();
255 * Test for all nucleotide alignment
257 * @return true if alignment is nucleotide sequence
259 public boolean isNucleotide();
262 * Set alignment to be a nucleotide sequence
265 public void setNucleotide(boolean b);
268 * Get the associated dataset for the alignment.
270 * @return Alignment containing dataset sequences or null of this is a
273 public Alignment getDataset();
276 * Set the associated dataset for the alignment, or create one.
279 * The dataset alignment or null to construct one.
281 public void setDataset(Alignment dataset);
284 * pads sequences with gaps (to ensure the set looks like an alignment)
286 * @return boolean true if alignment was modified
288 public boolean padGaps();
290 public HiddenSequences getHiddenSequences();
293 * Compact representation of alignment
297 public CigarArray getCompactAlignment();
300 * Set an arbitrary key value pair for an alignment. Note: both key and value
301 * objects should return a meaningful, human readable response to .toString()
306 public void setProperty(Object key, Object value);
309 * Get a named property from the alignment.
312 * @return value of property
314 public Object getProperty(Object key);
317 * Get the property hashtable.
319 * @return hashtable of alignment properties (or null if none are defined)
321 public Hashtable getProperties();
324 * add a reference to a frame of aligned codons for this alignment
328 public void addCodonFrame(AlignedCodonFrame codons);
331 * remove a particular codon frame reference from this alignment
334 * @return true if codon frame was removed.
336 public boolean removeCodonFrame(AlignedCodonFrame codons);
339 * get all codon frames associated with this alignment
343 public AlignedCodonFrame[] getCodonFrames();
346 * get a particular codon frame
351 public AlignedCodonFrame getCodonFrame(int index);
354 * get codon frames involving sequenceI
356 public AlignedCodonFrame[] getCodonFrame(SequenceI seq);
359 * find sequence with given name in alignment
364 * true implies that case insensitive matching will <em>also</em> be
366 * @return matched sequence or null
368 public SequenceI findName(String token, boolean b);
371 * find next sequence with given name in alignment starting after a given
375 * the sequence after which the search will be started (usually the
376 * result of the last call to findName)
380 * true implies that case insensitive matching will <em>also</em> be
382 * @return matched sequence or null
384 public SequenceI findName(SequenceI startAfter, String token, boolean b);
387 * find first sequence in alignment which is involved in the given search
391 * @return -1 or index of sequence in alignment
393 public int findIndex(SearchResults results);
396 * append sequences and annotation from another alignment object to this one.
397 * Note: this is a straight transfer of object references, and may result in
398 * toappend's dependent data being transformed to fit the alignment (changing
399 * gap characters, etc...). If you are uncertain, use the copy Alignment copy
400 * constructor to create a new version which can be appended without side
404 * - the alignment to be appended.
406 public void append(AlignmentI toappend);
409 * Justify the sequences to the left or right by deleting and inserting gaps
410 * before the initial residue or after the terminal residue
413 * true if alignment padded to right, false to justify to left
414 * @return true if alignment was changed TODO: return undo object
416 public boolean justify(boolean right);
419 * add given annotation row at given position (0 is start, -1 is end)
424 public void addAnnotation(AlignmentAnnotation consensus, int i);