2 * Jalview - A Sequence Alignment Editor and Viewer (Version 2.5)
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 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 * Get the annotation associated with this alignment
219 * (this can be null if no annotation has ever been created on the alignment)
220 * @return array of AlignmentAnnotation objects
222 public AlignmentAnnotation[] getAlignmentAnnotation();
225 * Change the gap character used in this alignment to 'gc'
228 * the new gap character.
230 public void setGapCharacter(char gc);
233 * Get the gap character used in this alignment
235 * @return gap character
237 public char getGapCharacter();
240 * Test for all nucleotide alignment
242 * @return true if alignment is nucleotide sequence
244 public boolean isNucleotide();
247 * Set alignment to be a nucleotide sequence
250 public void setNucleotide(boolean b);
253 * Get the associated dataset for the alignment.
255 * @return Alignment containing dataset sequences or null of this is a
258 public Alignment getDataset();
261 * Set the associated dataset for the alignment, or create one.
264 * The dataset alignment or null to construct one.
266 public void setDataset(Alignment dataset);
269 * pads sequences with gaps (to ensure the set looks like an alignment)
271 * @return boolean true if alignment was modified
273 public boolean padGaps();
275 public HiddenSequences getHiddenSequences();
278 * Compact representation of alignment
282 public CigarArray getCompactAlignment();
285 * Set an arbitrary key value pair for an alignment. Note: both key and value
286 * objects should return a meaningful, human readable response to .toString()
291 public void setProperty(Object key, Object value);
294 * Get a named property from the alignment.
297 * @return value of property
299 public Object getProperty(Object key);
302 * Get the property hashtable.
304 * @return hashtable of alignment properties (or null if none are defined)
306 public Hashtable getProperties();
309 * add a reference to a frame of aligned codons for this alignment
313 public void addCodonFrame(AlignedCodonFrame codons);
316 * remove a particular codon frame reference from this alignment
319 * @return true if codon frame was removed.
321 public boolean removeCodonFrame(AlignedCodonFrame codons);
324 * get all codon frames associated with this alignment
328 public AlignedCodonFrame[] getCodonFrames();
331 * get a particular codon frame
336 public AlignedCodonFrame getCodonFrame(int index);
339 * get codon frames involving sequenceI
341 public AlignedCodonFrame[] getCodonFrame(SequenceI seq);
344 * find sequence with given name in alignment
349 * true implies that case insensitive matching will <em>also</em> be
351 * @return matched sequence or null
353 public SequenceI findName(String token, boolean b);
356 * find next sequence with given name in alignment starting after a given
360 * the sequence after which the search will be started (usually the
361 * result of the last call to findName)
365 * true implies that case insensitive matching will <em>also</em> be
367 * @return matched sequence or null
369 public SequenceI findName(SequenceI startAfter, String token, boolean b);
372 * find first sequence in alignment which is involved in the given search
376 * @return -1 or index of sequence in alignment
378 public int findIndex(SearchResults results);
381 * append sequences and annotation from another alignment object to this one.
382 * Note: this is a straight transfer of object references, and may result in
383 * toappend's dependent data being transformed to fit the alignment (changing
384 * gap characters, etc...). If you are uncertain, use the copy Alignment copy
385 * constructor to create a new version which can be appended without side
389 * - the alignment to be appended.
391 public void append(AlignmentI toappend);
394 * Justify the sequences to the left or right by deleting and inserting gaps
395 * before the initial residue or after the terminal residue
398 * true if alignment padded to right, false to justify to left
399 * @return true if alignment was changed TODO: return undo object
401 public boolean justify(boolean right);
404 * add given annotation row at given position (0 is start, -1 is end)
409 public void addAnnotation(AlignmentAnnotation consensus, int i);