src/jalview/datamodel/AlignmentI.java

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