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 (this can be null if no
 219    * annotation has ever been created on the alignment)
 220    *
 221    * @return array of AlignmentAnnotation objects
 222    */
 223   public AlignmentAnnotation[] getAlignmentAnnotation();
 224
 225   /**
 226    * Change the gap character used in this alignment to 'gc'
 227    *
 228    * @param gc
 229    *          the new gap character.
 230    */
 231   public void setGapCharacter(char gc);
 232
 233   /**
 234    * Get the gap character used in this alignment
 235    *
 236    * @return gap character
 237    */
 238   public char getGapCharacter();
 239
 240   /**
 241    * Test for all nucleotide alignment
 242    *
 243    * @return true if alignment is nucleotide sequence
 244    */
 245   public boolean isNucleotide();
 246
 247   /**
 248    * Set alignment to be a nucleotide sequence
 249    *
 250    */
 251   public void setNucleotide(boolean b);
 252
 253   /**
 254    * Get the associated dataset for the alignment.
 255    *
 256    * @return Alignment containing dataset sequences or null of this is a
 257    *         dataset.
 258    */
 259   public Alignment getDataset();
 260
 261   /**
 262    * Set the associated dataset for the alignment, or create one.
 263    *
 264    * @param dataset
 265    *          The dataset alignment or null to construct one.
 266    */
 267   public void setDataset(Alignment dataset);
 268
 269   /**
 270    * pads sequences with gaps (to ensure the set looks like an alignment)
 271    *
 272    * @return boolean true if alignment was modified
 273    */
 274   public boolean padGaps();
 275
 276   public HiddenSequences getHiddenSequences();
 277
 278   /**
 279    * Compact representation of alignment
 280    *
 281    * @return CigarArray
 282    */
 283   public CigarArray getCompactAlignment();
 284
 285   /**
 286    * Set an arbitrary key value pair for an alignment. Note: both key and value
 287    * objects should return a meaningful, human readable response to .toString()
 288    *
 289    * @param key
 290    * @param value
 291    */
 292   public void setProperty(Object key, Object value);
 293
 294   /**
 295    * Get a named property from the alignment.
 296    *
 297    * @param key
 298    * @return value of property
 299    */
 300   public Object getProperty(Object key);
 301
 302   /**
 303    * Get the property hashtable.
 304    *
 305    * @return hashtable of alignment properties (or null if none are defined)
 306    */
 307   public Hashtable getProperties();
 308
 309   /**
 310    * add a reference to a frame of aligned codons for this alignment
 311    *
 312    * @param codons
 313    */
 314   public void addCodonFrame(AlignedCodonFrame codons);
 315
 316   /**
 317    * remove a particular codon frame reference from this alignment
 318    *
 319    * @param codons
 320    * @return true if codon frame was removed.
 321    */
 322   public boolean removeCodonFrame(AlignedCodonFrame codons);
 323
 324   /**
 325    * get all codon frames associated with this alignment
 326    *
 327    * @return
 328    */
 329   public AlignedCodonFrame[] getCodonFrames();
 330
 331   /**
 332    * get a particular codon frame
 333    *
 334    * @param index
 335    * @return
 336    */
 337   public AlignedCodonFrame getCodonFrame(int index);
 338
 339   /**
 340    * get codon frames involving sequenceI
 341    */
 342   public AlignedCodonFrame[] getCodonFrame(SequenceI seq);
 343
 344   /**
 345    * find sequence with given name in alignment
 346    *
 347    * @param token
 348    *          name to find
 349    * @param b
 350    *          true implies that case insensitive matching will <em>also</em> be
 351    *          tried
 352    * @return matched sequence or null
 353    */
 354   public SequenceI findName(String token, boolean b);
 355
 356   /**
 357    * find next sequence with given name in alignment starting after a given
 358    * sequence
 359    *
 360    * @param startAfter
 361    *          the sequence after which the search will be started (usually the
 362    *          result of the last call to findName)
 363    * @param token
 364    *          name to find
 365    * @param b
 366    *          true implies that case insensitive matching will <em>also</em> be
 367    *          tried
 368    * @return matched sequence or null
 369    */
 370   public SequenceI findName(SequenceI startAfter, String token, boolean b);
 371
 372   /**
 373    * find first sequence in alignment which is involved in the given search
 374    * result object
 375    *
 376    * @param results
 377    * @return -1 or index of sequence in alignment
 378    */
 379   public int findIndex(SearchResults results);
 380
 381   /**
 382    * append sequences and annotation from another alignment object to this one.
 383    * Note: this is a straight transfer of object references, and may result in
 384    * toappend's dependent data being transformed to fit the alignment (changing
 385    * gap characters, etc...). If you are uncertain, use the copy Alignment copy
 386    * constructor to create a new version which can be appended without side
 387    * effect.
 388    *
 389    * @param toappend
 390    *          - the alignment to be appended.
 391    */
 392   public void append(AlignmentI toappend);
 393
 394   /**
 395    * Justify the sequences to the left or right by deleting and inserting gaps
 396    * before the initial residue or after the terminal residue
 397    *
 398    * @param right
 399    *          true if alignment padded to right, false to justify to left
 400    * @return true if alignment was changed TODO: return undo object
 401    */
 402   public boolean justify(boolean right);
 403
 404   /**
 405    * add given annotation row at given position (0 is start, -1 is end)
 406    *
 407    * @param consensus
 408    * @param i
 409    */
 410   public void addAnnotation(AlignmentAnnotation consensus, int i);
 411 }