src/jalview/datamodel/AlignmentI.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer (Development Version 2.4.1)
   3  * Copyright (C) 2009 AM Waterhouse, J Procter, G Barton, M Clamp, S Searle
   4  *
   5  * This program is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU General Public License
   7  * as published by the Free Software Foundation; either version 2
   8  * of the License, or (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
  18  */
  19 package jalview.datamodel;
  20
  21 import java.util.*;
  22
  23 /**
  24  * Data structure to hold and manipulate a multiple sequence alignment
  25  */
  26 public interface AlignmentI
  27 {
  28   /**
  29    * Calculates the number of sequences in an alignment
  30    *
  31    * @return Number of sequences in alignment
  32    */
  33   public int getHeight();
  34
  35   /**
  36    * Calculates the maximum width of the alignment, including gaps.
  37    *
  38    * @return Greatest sequence length within alignment.
  39    */
  40   public int getWidth();
  41
  42   /**
  43    * Calculates if this set of sequences (visible and invisible) are all the same length
  44    *
  45    * @return true if all sequences in alignment are the same length
  46    */
  47   public boolean isAligned();
  48   /**
  49    * Calculates if this set of sequences is all the same length
  50    * @param includeHidden  optionally exclude hidden sequences from test
  51    * @return true if all (or just visible) sequences are the same length
  52    */
  53   public boolean isAligned(boolean includeHidden);
  54   /**
  55    * Gets sequences as a Vector
  56    *
  57    * @return All sequences in alignment.
  58    */
  59   public Vector getSequences();
  60
  61   /**
  62    * Gets sequences as a SequenceI[]
  63    *
  64    * @return All sequences in alignment.
  65    */
  66   public SequenceI[] getSequencesArray();
  67
  68   /**
  69    * Find a specific sequence in this alignment.
  70    *
  71    * @param i
  72    *                Index of required sequence.
  73    *
  74    * @return SequenceI at given index.
  75    */
  76   public SequenceI getSequenceAt(int i);
  77
  78   /**
  79    * Add a new sequence to this alignment.
  80    *
  81    * @param seq
  82    *                New sequence will be added at end of alignment.
  83    */
  84   public void addSequence(SequenceI seq);
  85
  86   /**
  87    * Used to set a particular index of the alignment with the given sequence.
  88    *
  89    * @param i
  90    *                Index of sequence to be updated.
  91    * @param seq
  92    *                New sequence to be inserted.
  93    */
  94   public void setSequenceAt(int i, SequenceI seq);
  95
  96   /**
  97    * Deletes a sequence from the alignment
  98    *
  99    * @param s
 100    *                Sequence to be deleted.
 101    */
 102   public void deleteSequence(SequenceI s);
 103
 104   /**
 105    * Deletes a sequence from the alignment.
 106    *
 107    * @param i
 108    *                Index of sequence to be deleted.
 109    */
 110   public void deleteSequence(int i);
 111
 112   /**
 113    * Finds sequence in alignment using sequence name as query.
 114    *
 115    * @param name
 116    *                Id of sequence to search for.
 117    *
 118    * @return Sequence matching query, if found. If not found returns null.
 119    */
 120   public SequenceI findName(String name);
 121
 122   public SequenceI[] findSequenceMatch(String name);
 123
 124   /**
 125    * Finds index of a given sequence in the alignment.
 126    *
 127    * @param s
 128    *                Sequence to look for.
 129    *
 130    * @return Index of sequence within the alignment or -1 if not found
 131    */
 132   public int findIndex(SequenceI s);
 133
 134   /**
 135    * Finds group that given sequence is part of.
 136    *
 137    * @param s
 138    *                Sequence in alignment.
 139    *
 140    * @return First group found for sequence. WARNING : Sequences may be members
 141    *         of several groups. This method is incomplete.
 142    */
 143   public SequenceGroup findGroup(SequenceI s);
 144
 145   /**
 146    * Finds all groups that a given sequence is part of.
 147    *
 148    * @param s
 149    *                Sequence in alignment.
 150    *
 151    * @return All groups containing given sequence.
 152    */
 153   public SequenceGroup[] findAllGroups(SequenceI s);
 154
 155   /**
 156    * Adds a new SequenceGroup to this alignment.
 157    *
 158    * @param sg
 159    *                New group to be added.
 160    */
 161   public void addGroup(SequenceGroup sg);
 162
 163   /**
 164    * Deletes a specific SequenceGroup
 165    *
 166    * @param g
 167    *                Group will be deleted from alignment.
 168    */
 169   public void deleteGroup(SequenceGroup g);
 170
 171   /**
 172    * Get all the groups associated with this alignment.
 173    *
 174    * @return All groups as a Vector.
 175    */
 176   public Vector getGroups();
 177
 178   /**
 179    * Deletes all groups from this alignment.
 180    */
 181   public void deleteAllGroups();
 182
 183   /**
 184    * Adds a new AlignmentAnnotation to this alignment
 185    *
 186    * @note Care should be taken to ensure that annotation is at least as wide as
 187    *       the longest sequence in the alignment for rendering purposes.
 188    */
 189   public void addAnnotation(AlignmentAnnotation aa);
 190
 191   /**
 192    * moves annotation to a specified index in alignment annotation display stack
 193    *
 194    * @param aa
 195    *                the annotation object to be moved
 196    * @param index
 197    *                the destination position
 198    */
 199   public void setAnnotationIndex(AlignmentAnnotation aa, int index);
 200
 201   /**
 202    * Deletes a specific AlignmentAnnotation from the alignment, and removes its
 203    * reference from any SequenceI object's annotation if and only if aa is
 204    * contained within the alignment's annotation vector. Otherwise, it will do
 205    * nothing.
 206    *
 207    * @param aa
 208    *                the annotation to delete
 209    * @return true if annotation was deleted from this alignment.
 210    */
 211   public boolean deleteAnnotation(AlignmentAnnotation aa);
 212
 213   /**
 214    * Get the annotation associated with this alignment
 215    *
 216    * @return array of AlignmentAnnotation objects
 217    */
 218   public AlignmentAnnotation[] getAlignmentAnnotation();
 219
 220   /**
 221    * Change the gap character used in this alignment to 'gc'
 222    *
 223    * @param gc
 224    *                the new gap character.
 225    */
 226   public void setGapCharacter(char gc);
 227
 228   /**
 229    * Get the gap character used in this alignment
 230    *
 231    * @return gap character
 232    */
 233   public char getGapCharacter();
 234
 235   /**
 236    * Test for all nucleotide alignment
 237    *
 238    * @return true if alignment is nucleotide sequence
 239    */
 240   public boolean isNucleotide();
 241
 242   /**
 243    * Set alignment to be a nucleotide sequence
 244    *
 245    */
 246   public void setNucleotide(boolean b);
 247
 248   /**
 249    * Get the associated dataset for the alignment.
 250    *
 251    * @return Alignment containing dataset sequences or null of this is a
 252    *         dataset.
 253    */
 254   public Alignment getDataset();
 255
 256   /**
 257    * Set the associated dataset for the alignment, or create one.
 258    *
 259    * @param dataset
 260    *                The dataset alignment or null to construct one.
 261    */
 262   public void setDataset(Alignment dataset);
 263
 264   /**
 265    * pads sequences with gaps (to ensure the set looks like an alignment)
 266    *
 267    * @return boolean true if alignment was modified
 268    */
 269   public boolean padGaps();
 270
 271   public HiddenSequences getHiddenSequences();
 272
 273   /**
 274    * Compact representation of alignment
 275    *
 276    * @return CigarArray
 277    */
 278   public CigarArray getCompactAlignment();
 279
 280   /**
 281    * Set an arbitrary key value pair for an alignment. Note: both key and value
 282    * objects should return a meaningful, human readable response to .toString()
 283    *
 284    * @param key
 285    * @param value
 286    */
 287   public void setProperty(Object key, Object value);
 288
 289   /**
 290    * Get a named property from the alignment.
 291    *
 292    * @param key
 293    * @return value of property
 294    */
 295   public Object getProperty(Object key);
 296
 297   /**
 298    * Get the property hashtable.
 299    *
 300    * @return hashtable of alignment properties (or null if none are defined)
 301    */
 302   public Hashtable getProperties();
 303
 304   /**
 305    * add a reference to a frame of aligned codons for this alignment
 306    *
 307    * @param codons
 308    */
 309   public void addCodonFrame(AlignedCodonFrame codons);
 310
 311   /**
 312    * remove a particular codon frame reference from this alignment
 313    *
 314    * @param codons
 315    * @return true if codon frame was removed.
 316    */
 317   public boolean removeCodonFrame(AlignedCodonFrame codons);
 318
 319   /**
 320    * get all codon frames associated with this alignment
 321    *
 322    * @return
 323    */
 324   public AlignedCodonFrame[] getCodonFrames();
 325
 326   /**
 327    * get a particular codon frame
 328    *
 329    * @param index
 330    * @return
 331    */
 332   public AlignedCodonFrame getCodonFrame(int index);
 333
 334   /**
 335    * get codon frames involving sequenceI
 336    */
 337   public AlignedCodonFrame[] getCodonFrame(SequenceI seq);
 338
 339   /**
 340    * find sequence with given name in alignment
 341    *
 342    * @param token
 343    *                name to find
 344    * @param b
 345    *                true implies that case insensitive matching will
 346    *                <em>also</em> be tried
 347    * @return matched sequence or null
 348    */
 349   public SequenceI findName(String token, boolean b);
 350
 351   /**
 352    * find next sequence with given name in alignment starting after a given
 353    * sequence
 354    *
 355    * @param startAfter
 356    *                the sequence after which the search will be started (usually
 357    *                the result of the last call to findName)
 358    * @param token
 359    *                name to find
 360    * @param b
 361    *                true implies that case insensitive matching will
 362    *                <em>also</em> be tried
 363    * @return matched sequence or null
 364    */
 365   public SequenceI findName(SequenceI startAfter, String token, boolean b);
 366
 367   /**
 368    * find first sequence in alignment which is involved in the given search result object
 369    * @param results
 370    * @return -1 or index of sequence in alignment
 371    */
 372   public int findIndex(SearchResults results);
 373
 374   /**
 375    * append sequences and annotation from another alignment object to this one.
 376    * Note: this is a straight transfer of object references, and may result in
 377    * toappend's dependent data being transformed to fit the alignment (changing gap characters, etc...).
 378    * If you are uncertain, use the copy Alignment copy constructor to create a new version
 379    * which can be appended without side effect.
 380    * @param toappend - the alignment to be appended.
 381    */
 382   public void append(AlignmentI toappend);
 383   /**
 384    * Justify the sequences to the left or right by deleting and inserting gaps before the initial residue or after the terminal residue
 385    * @param right true if alignment padded to right, false to justify to left
 386    * @return true if alignment was changed
 387    * TODO: return undo object
 388    */
 389   public boolean justify(boolean right);
 390
 391   /**
 392    * add given annotation row at given position (0 is start, -1 is end)
 393    * @param consensus
 394    * @param i
 395    */
 396   public void addAnnotation(AlignmentAnnotation consensus, int i);
 397 }