src/jalview/datamodel/AlignmentI.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.7)
   3  * Copyright (C) 2011 J Procter, AM Waterhouse, J Engelhardt, LM Lui, 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 extends AnnotatedCollectionI
  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 Synchronized collection
  60    *
  61    * @return All sequences in alignment.
  62    */
  63   @Override
  64   public List<SequenceI> getSequences();
  65
  66   /**
  67    * Gets sequences as a SequenceI[]
  68    *
  69    * @return All sequences in alignment.
  70    */
  71   public SequenceI[] getSequencesArray();
  72
  73   /**
  74    * Find a specific sequence in this alignment.
  75    *
  76    * @param i
  77    *          Index of required sequence.
  78    *
  79    * @return SequenceI at given index.
  80    */
  81   public SequenceI getSequenceAt(int i);
  82
  83   /**
  84    * Add a new sequence to this alignment.
  85    *
  86    * @param seq
  87    *          New sequence will be added at end of alignment.
  88    */
  89   public void addSequence(SequenceI seq);
  90
  91   /**
  92    * Used to set a particular index of the alignment with the given sequence.
  93    *
  94    * @param i
  95    *          Index of sequence to be updated.
  96    * @param seq
  97    *          New sequence to be inserted.
  98    */
  99   public void setSequenceAt(int i, SequenceI seq);
 100
 101   /**
 102    * Deletes a sequence from the alignment
 103    *
 104    * @param s
 105    *          Sequence to be deleted.
 106    */
 107   public void deleteSequence(SequenceI s);
 108
 109   /**
 110    * Deletes a sequence from the alignment.
 111    *
 112    * @param i
 113    *          Index of sequence to be deleted.
 114    */
 115   public void deleteSequence(int i);
 116
 117   /**
 118    * Finds sequence in alignment using sequence name as query.
 119    *
 120    * @param name
 121    *          Id of sequence to search for.
 122    *
 123    * @return Sequence matching query, if found. If not found returns null.
 124    */
 125   public SequenceI findName(String name);
 126
 127   public SequenceI[] findSequenceMatch(String name);
 128
 129   /**
 130    * Finds index of a given sequence in the alignment.
 131    *
 132    * @param s
 133    *          Sequence to look for.
 134    *
 135    * @return Index of sequence within the alignment or -1 if not found
 136    */
 137   public int findIndex(SequenceI s);
 138
 139   /**
 140    * Finds group that given sequence is part of.
 141    *
 142    * @param s
 143    *          Sequence in alignment.
 144    *
 145    * @return First group found for sequence. WARNING : Sequences may be members
 146    *         of several groups. This method is incomplete.
 147    */
 148   public SequenceGroup findGroup(SequenceI s);
 149
 150   /**
 151    * Finds all groups that a given sequence is part of.
 152    *
 153    * @param s
 154    *          Sequence in alignment.
 155    *
 156    * @return All groups containing given sequence.
 157    */
 158   public SequenceGroup[] findAllGroups(SequenceI s);
 159
 160   /**
 161    * Adds a new SequenceGroup to this alignment.
 162    *
 163    * @param sg
 164    *          New group to be added.
 165    */
 166   public void addGroup(SequenceGroup sg);
 167
 168   /**
 169    * Deletes a specific SequenceGroup
 170    *
 171    * @param g
 172    *          Group will be deleted from alignment.
 173    */
 174   public void deleteGroup(SequenceGroup g);
 175
 176   /**
 177    * Get all the groups associated with this alignment.
 178    *
 179    * @return All groups as a list.
 180    */
 181   public List<SequenceGroup> getGroups();
 182
 183   /**
 184    * Deletes all groups from this alignment.
 185    */
 186   public void deleteAllGroups();
 187
 188   /**
 189    * Adds a new AlignmentAnnotation to this alignment
 190    *
 191    * @note Care should be taken to ensure that annotation is at least as wide as
 192    *       the longest sequence in the alignment for rendering purposes.
 193    */
 194   public void addAnnotation(AlignmentAnnotation aa);
 195
 196   /**
 197    * moves annotation to a specified index in alignment annotation display stack
 198    *
 199    * @param aa
 200    *          the annotation object to be moved
 201    * @param index
 202    *          the destination position
 203    */
 204   public void setAnnotationIndex(AlignmentAnnotation aa, int index);
 205
 206   /**
 207    * Deletes a specific AlignmentAnnotation from the alignment, and removes its
 208    * reference from any SequenceI or SequenceGroup object's annotation if and
 209    * only if aa is contained within the alignment's annotation vector.
 210    * Otherwise, it will do nothing.
 211    *
 212    * @param aa
 213    *          the annotation to delete
 214    * @return true if annotation was deleted from this alignment.
 215    */
 216   public boolean deleteAnnotation(AlignmentAnnotation aa);
 217
 218   /**
 219    * Deletes a specific AlignmentAnnotation from the alignment, and optionally
 220    * removes any reference from any SequenceI or SequenceGroup object's
 221    * annotation if and only if aa is contained within the alignment's annotation
 222    * vector. Otherwise, it will do nothing.
 223    *
 224    * @param aa
 225    *          the annotation to delete
 226    * @param unhook
 227    *          flag indicating if any references should be removed from
 228    *          annotation - use this if you intend to add the annotation back
 229    *          into the alignment
 230    * @return true if annotation was deleted from this alignment.
 231    */
 232   public boolean deleteAnnotation(AlignmentAnnotation aa, boolean unhook);
 233
 234   /**
 235    * Get the annotation associated with this alignment (this can be null if no
 236    * annotation has ever been created on the alignment)
 237    *
 238    * @return array of AlignmentAnnotation objects
 239    */
 240   public AlignmentAnnotation[] getAlignmentAnnotation();
 241
 242   /**
 243    * Change the gap character used in this alignment to 'gc'
 244    *
 245    * @param gc
 246    *          the new gap character.
 247    */
 248   public void setGapCharacter(char gc);
 249
 250   /**
 251    * Get the gap character used in this alignment
 252    *
 253    * @return gap character
 254    */
 255   public char getGapCharacter();
 256
 257   /**
 258    * Test for all nucleotide alignment
 259    *
 260    * @return true if alignment is nucleotide sequence
 261    */
 262   public boolean isNucleotide();
 263
 264   /**
 265    * Test if alignment contains RNA structure
 266    *
 267    * @return true if RNA structure AligmnentAnnotation was added to alignment
 268    */
 269   public boolean hasRNAStructure();
 270
 271   /**
 272    * Set alignment to be a nucleotide sequence
 273    *
 274    */
 275   public void setNucleotide(boolean b);
 276
 277   /**
 278    * Get the associated dataset for the alignment.
 279    *
 280    * @return Alignment containing dataset sequences or null of this is a
 281    *         dataset.
 282    */
 283   public Alignment getDataset();
 284
 285   /**
 286    * Set the associated dataset for the alignment, or create one.
 287    *
 288    * @param dataset
 289    *          The dataset alignment or null to construct one.
 290    */
 291   public void setDataset(Alignment dataset);
 292
 293   /**
 294    * pads sequences with gaps (to ensure the set looks like an alignment)
 295    *
 296    * @return boolean true if alignment was modified
 297    */
 298   public boolean padGaps();
 299
 300   public HiddenSequences getHiddenSequences();
 301
 302   /**
 303    * Compact representation of alignment
 304    *
 305    * @return CigarArray
 306    */
 307   public CigarArray getCompactAlignment();
 308
 309   /**
 310    * Set an arbitrary key value pair for an alignment. Note: both key and value
 311    * objects should return a meaningful, human readable response to .toString()
 312    *
 313    * @param key
 314    * @param value
 315    */
 316   public void setProperty(Object key, Object value);
 317
 318   /**
 319    * Get a named property from the alignment.
 320    *
 321    * @param key
 322    * @return value of property
 323    */
 324   public Object getProperty(Object key);
 325
 326   /**
 327    * Get the property hashtable.
 328    *
 329    * @return hashtable of alignment properties (or null if none are defined)
 330    */
 331   public Hashtable getProperties();
 332
 333   /**
 334    * add a reference to a frame of aligned codons for this alignment
 335    *
 336    * @param codons
 337    */
 338   public void addCodonFrame(AlignedCodonFrame codons);
 339
 340   /**
 341    * remove a particular codon frame reference from this alignment
 342    *
 343    * @param codons
 344    * @return true if codon frame was removed.
 345    */
 346   public boolean removeCodonFrame(AlignedCodonFrame codons);
 347
 348   /**
 349    * get all codon frames associated with this alignment
 350    *
 351    * @return
 352    */
 353   public AlignedCodonFrame[] getCodonFrames();
 354
 355   /**
 356    * get a particular codon frame
 357    *
 358    * @param index
 359    * @return
 360    */
 361   public AlignedCodonFrame getCodonFrame(int index);
 362
 363   /**
 364    * get codon frames involving sequenceI
 365    */
 366   public AlignedCodonFrame[] getCodonFrame(SequenceI seq);
 367
 368   /**
 369    * find sequence with given name in alignment
 370    *
 371    * @param token
 372    *          name to find
 373    * @param b
 374    *          true implies that case insensitive matching will <em>also</em> be
 375    *          tried
 376    * @return matched sequence or null
 377    */
 378   public SequenceI findName(String token, boolean b);
 379
 380   /**
 381    * find next sequence with given name in alignment starting after a given
 382    * sequence
 383    *
 384    * @param startAfter
 385    *          the sequence after which the search will be started (usually the
 386    *          result of the last call to findName)
 387    * @param token
 388    *          name to find
 389    * @param b
 390    *          true implies that case insensitive matching will <em>also</em> be
 391    *          tried
 392    * @return matched sequence or null
 393    */
 394   public SequenceI findName(SequenceI startAfter, String token, boolean b);
 395
 396   /**
 397    * find first sequence in alignment which is involved in the given search
 398    * result object
 399    *
 400    * @param results
 401    * @return -1 or index of sequence in alignment
 402    */
 403   public int findIndex(SearchResults results);
 404
 405   /**
 406    * append sequences and annotation from another alignment object to this one.
 407    * Note: this is a straight transfer of object references, and may result in
 408    * toappend's dependent data being transformed to fit the alignment (changing
 409    * gap characters, etc...). If you are uncertain, use the copy Alignment copy
 410    * constructor to create a new version which can be appended without side
 411    * effect.
 412    *
 413    * @param toappend
 414    *          - the alignment to be appended.
 415    */
 416   public void append(AlignmentI toappend);
 417
 418   /**
 419    * Justify the sequences to the left or right by deleting and inserting gaps
 420    * before the initial residue or after the terminal residue
 421    *
 422    * @param right
 423    *          true if alignment padded to right, false to justify to left
 424    * @return true if alignment was changed TODO: return undo object
 425    */
 426   public boolean justify(boolean right);
 427
 428   /**
 429    * add given annotation row at given position (0 is start, -1 is end)
 430    *
 431    * @param consensus
 432    * @param i
 433    */
 434   public void addAnnotation(AlignmentAnnotation consensus, int i);
 435
 436   /**
 437    * search for or create a specific annotation row on the alignment
 438    *
 439    * @param method - CalcId for the annotation (must match)
 440    * @param autoCalc - value of autocalc flag for the annotation
 441    * @param seqRef - null or specific sequence reference
 442    * @param groupRef - null or specific group reference
 443    * @return existing annotation matching the given attributes
 444    */
 445   public AlignmentAnnotation findOrCreateAnnotation(String name, boolean autoCalc,
 446           SequenceI seqRef, SequenceGroup groupRef);
 447 }