src/jalview/datamodel/AlignmentI.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8.2)
   3  * Copyright (C) 2014 The Jalview Authors
   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
  10  * of the License, or (at your option) any later version.
  11  *
  12  * Jalview is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  19  * The Jalview Authors are detailed in the 'AUTHORS' file.
  20  */
  21 package jalview.datamodel;
  22
  23 import java.util.Hashtable;
  24 import java.util.List;
  25 import java.util.Map;
  26
  27 /**
  28  * Data structure to hold and manipulate a multiple sequence alignment
  29  */
  30 public interface AlignmentI extends AnnotatedCollectionI
  31 {
  32   /**
  33    * Calculates the number of sequences in an alignment
  34    *
  35    * @return Number of sequences in alignment
  36    */
  37   public int getHeight();
  38
  39   /**
  40    * Calculates the maximum width of the alignment, including gaps.
  41    *
  42    * @return Greatest sequence length within alignment.
  43    */
  44   @Override
  45   public int getWidth();
  46
  47   /**
  48    * Calculates if this set of sequences (visible and invisible) are all the
  49    * same length
  50    *
  51    * @return true if all sequences in alignment are the same length
  52    */
  53   public boolean isAligned();
  54
  55   /**
  56    * Calculates if this set of sequences is all the same length
  57    *
  58    * @param includeHidden
  59    *          optionally exclude hidden sequences from test
  60    * @return true if all (or just visible) sequences are the same length
  61    */
  62   public boolean isAligned(boolean includeHidden);
  63
  64   /**
  65    * Gets sequences as a Synchronized collection
  66    *
  67    * @return All sequences in alignment.
  68    */
  69   @Override
  70   public List<SequenceI> getSequences();
  71
  72   /**
  73    * Gets sequences as a SequenceI[]
  74    *
  75    * @return All sequences in alignment.
  76    */
  77   public SequenceI[] getSequencesArray();
  78
  79   /**
  80    * Find a specific sequence in this alignment.
  81    *
  82    * @param i
  83    *          Index of required sequence.
  84    *
  85    * @return SequenceI at given index.
  86    */
  87   public SequenceI getSequenceAt(int i);
  88
  89   /**
  90    * Add a new sequence to this alignment.
  91    *
  92    * @param seq
  93    *          New sequence will be added at end of alignment.
  94    */
  95   public void addSequence(SequenceI seq);
  96
  97   /**
  98    * Used to set a particular index of the alignment with the given sequence.
  99    *
 100    * @param i
 101    *          Index of sequence to be updated.
 102    * @param seq
 103    *          New sequence to be inserted.
 104    */
 105   public void setSequenceAt(int i, SequenceI seq);
 106
 107   /**
 108    * Deletes a sequence from the alignment
 109    *
 110    * @param s
 111    *          Sequence to be deleted.
 112    */
 113   public void deleteSequence(SequenceI s);
 114
 115   /**
 116    * Deletes a sequence from the alignment.
 117    *
 118    * @param i
 119    *          Index of sequence to be deleted.
 120    */
 121   public void deleteSequence(int i);
 122
 123   /**
 124    * Finds sequence in alignment using sequence name as query.
 125    *
 126    * @param name
 127    *          Id of sequence to search for.
 128    *
 129    * @return Sequence matching query, if found. If not found returns null.
 130    */
 131   public SequenceI findName(String name);
 132
 133   public SequenceI[] findSequenceMatch(String name);
 134
 135   /**
 136    * Finds index of a given sequence in the alignment.
 137    *
 138    * @param s
 139    *          Sequence to look for.
 140    *
 141    * @return Index of sequence within the alignment or -1 if not found
 142    */
 143   public int findIndex(SequenceI s);
 144
 145   /**
 146    * Finds group that given sequence is part of.
 147    *
 148    * @param s
 149    *          Sequence in alignment.
 150    *
 151    * @return First group found for sequence. WARNING : Sequences may be members
 152    *         of several groups. This method is incomplete.
 153    */
 154   public SequenceGroup findGroup(SequenceI s);
 155
 156   /**
 157    * Finds all groups that a given sequence is part of.
 158    *
 159    * @param s
 160    *          Sequence in alignment.
 161    *
 162    * @return All groups containing given sequence.
 163    */
 164   public SequenceGroup[] findAllGroups(SequenceI s);
 165
 166   /**
 167    * Adds a new SequenceGroup to this alignment.
 168    *
 169    * @param sg
 170    *          New group to be added.
 171    */
 172   public void addGroup(SequenceGroup sg);
 173
 174   /**
 175    * Deletes a specific SequenceGroup
 176    *
 177    * @param g
 178    *          Group will be deleted from alignment.
 179    */
 180   public void deleteGroup(SequenceGroup g);
 181
 182   /**
 183    * Get all the groups associated with this alignment.
 184    *
 185    * @return All groups as a list.
 186    */
 187   public List<SequenceGroup> getGroups();
 188
 189   /**
 190    * Deletes all groups from this alignment.
 191    */
 192   public void deleteAllGroups();
 193
 194   /**
 195    * Adds a new AlignmentAnnotation to this alignment
 196    *
 197    * @note Care should be taken to ensure that annotation is at least as wide as
 198    *       the longest sequence in the alignment for rendering purposes.
 199    */
 200   public void addAnnotation(AlignmentAnnotation aa);
 201
 202   /**
 203    * moves annotation to a specified index in alignment annotation display stack
 204    *
 205    * @param aa
 206    *          the annotation object to be moved
 207    * @param index
 208    *          the destination position
 209    */
 210   public void setAnnotationIndex(AlignmentAnnotation aa, int index);
 211
 212   /**
 213    * Deletes a specific AlignmentAnnotation from the alignment, and removes its
 214    * reference from any SequenceI or SequenceGroup object's annotation if and
 215    * only if aa is contained within the alignment's annotation vector.
 216    * Otherwise, it will do nothing.
 217    *
 218    * @param aa
 219    *          the annotation to delete
 220    * @return true if annotation was deleted from this alignment.
 221    */
 222   public boolean deleteAnnotation(AlignmentAnnotation aa);
 223
 224   /**
 225    * Deletes a specific AlignmentAnnotation from the alignment, and optionally
 226    * removes any reference from any SequenceI or SequenceGroup object's
 227    * annotation if and only if aa is contained within the alignment's annotation
 228    * vector. Otherwise, it will do nothing.
 229    *
 230    * @param aa
 231    *          the annotation to delete
 232    * @param unhook
 233    *          flag indicating if any references should be removed from
 234    *          annotation - use this if you intend to add the annotation back
 235    *          into the alignment
 236    * @return true if annotation was deleted from this alignment.
 237    */
 238   public boolean deleteAnnotation(AlignmentAnnotation aa, boolean unhook);
 239
 240   /**
 241    * Get the annotation associated with this alignment (this can be null if no
 242    * annotation has ever been created on the alignment)
 243    *
 244    * @return array of AlignmentAnnotation objects
 245    */
 246   @Override
 247   public AlignmentAnnotation[] getAlignmentAnnotation();
 248
 249   /**
 250    * Change the gap character used in this alignment to 'gc'
 251    *
 252    * @param gc
 253    *          the new gap character.
 254    */
 255   public void setGapCharacter(char gc);
 256
 257   /**
 258    * Get the gap character used in this alignment
 259    *
 260    * @return gap character
 261    */
 262   public char getGapCharacter();
 263
 264   /**
 265    * Test for all nucleotide alignment
 266    *
 267    * @return true if alignment is nucleotide sequence
 268    */
 269   public boolean isNucleotide();
 270
 271   /**
 272    * Test if alignment contains RNA structure
 273    *
 274    * @return true if RNA structure AligmnentAnnotation was added to alignment
 275    */
 276   public boolean hasRNAStructure();
 277
 278   /**
 279    * Set alignment to be a nucleotide sequence
 280    *
 281    */
 282   public void setNucleotide(boolean b);
 283
 284   /**
 285    * Get the associated dataset for the alignment.
 286    *
 287    * @return Alignment containing dataset sequences or null of this is a
 288    *         dataset.
 289    */
 290   public Alignment getDataset();
 291
 292   /**
 293    * Set the associated dataset for the alignment, or create one.
 294    *
 295    * @param dataset
 296    *          The dataset alignment or null to construct one.
 297    */
 298   public void setDataset(Alignment dataset);
 299
 300   /**
 301    * pads sequences with gaps (to ensure the set looks like an alignment)
 302    *
 303    * @return boolean true if alignment was modified
 304    */
 305   public boolean padGaps();
 306
 307   public HiddenSequences getHiddenSequences();
 308
 309   /**
 310    * Compact representation of alignment
 311    *
 312    * @return CigarArray
 313    */
 314   public CigarArray getCompactAlignment();
 315
 316   /**
 317    * Set an arbitrary key value pair for an alignment. Note: both key and value
 318    * objects should return a meaningful, human readable response to .toString()
 319    *
 320    * @param key
 321    * @param value
 322    */
 323   public void setProperty(Object key, Object value);
 324
 325   /**
 326    * Get a named property from the alignment.
 327    *
 328    * @param key
 329    * @return value of property
 330    */
 331   public Object getProperty(Object key);
 332
 333   /**
 334    * Get the property hashtable.
 335    *
 336    * @return hashtable of alignment properties (or null if none are defined)
 337    */
 338   public Hashtable getProperties();
 339
 340   /**
 341    * add a reference to a frame of aligned codons for this alignment
 342    *
 343    * @param codons
 344    */
 345   public void addCodonFrame(AlignedCodonFrame codons);
 346
 347   /**
 348    * remove a particular codon frame reference from this alignment
 349    *
 350    * @param codons
 351    * @return true if codon frame was removed.
 352    */
 353   public boolean removeCodonFrame(AlignedCodonFrame codons);
 354
 355   /**
 356    * get all codon frames associated with this alignment
 357    *
 358    * @return
 359    */
 360   public AlignedCodonFrame[] getCodonFrames();
 361
 362   /**
 363    * get a particular codon frame
 364    *
 365    * @param index
 366    * @return
 367    */
 368   public AlignedCodonFrame getCodonFrame(int index);
 369
 370   /**
 371    * get codon frames involving sequenceI
 372    */
 373   public AlignedCodonFrame[] getCodonFrame(SequenceI seq);
 374
 375   /**
 376    * find sequence with given name in alignment
 377    *
 378    * @param token
 379    *          name to find
 380    * @param b
 381    *          true implies that case insensitive matching will <em>also</em> be
 382    *          tried
 383    * @return matched sequence or null
 384    */
 385   public SequenceI findName(String token, boolean b);
 386
 387   /**
 388    * find next sequence with given name in alignment starting after a given
 389    * sequence
 390    *
 391    * @param startAfter
 392    *          the sequence after which the search will be started (usually the
 393    *          result of the last call to findName)
 394    * @param token
 395    *          name to find
 396    * @param b
 397    *          true implies that case insensitive matching will <em>also</em> be
 398    *          tried
 399    * @return matched sequence or null
 400    */
 401   public SequenceI findName(SequenceI startAfter, String token, boolean b);
 402
 403   /**
 404    * find first sequence in alignment which is involved in the given search
 405    * result object
 406    *
 407    * @param results
 408    * @return -1 or index of sequence in alignment
 409    */
 410   public int findIndex(SearchResults results);
 411
 412   /**
 413    * append sequences and annotation from another alignment object to this one.
 414    * Note: this is a straight transfer of object references, and may result in
 415    * toappend's dependent data being transformed to fit the alignment (changing
 416    * gap characters, etc...). If you are uncertain, use the copy Alignment copy
 417    * constructor to create a new version which can be appended without side
 418    * effect.
 419    *
 420    * @param toappend
 421    *          - the alignment to be appended.
 422    */
 423   public void append(AlignmentI toappend);
 424
 425   /**
 426    * Justify the sequences to the left or right by deleting and inserting gaps
 427    * before the initial residue or after the terminal residue
 428    *
 429    * @param right
 430    *          true if alignment padded to right, false to justify to left
 431    * @return true if alignment was changed TODO: return undo object
 432    */
 433   public boolean justify(boolean right);
 434
 435   /**
 436    * add given annotation row at given position (0 is start, -1 is end)
 437    *
 438    * @param consensus
 439    * @param i
 440    */
 441   public void addAnnotation(AlignmentAnnotation consensus, int i);
 442
 443   /**
 444    * search for or create a specific annotation row on the alignment
 445    *
 446    * @param name
 447    *          name for annotation (must match)
 448    * @param calcId
 449    *          calcId for the annotation (null or must match)
 450    * @param autoCalc
 451    *          - value of autocalc flag for the annotation
 452    * @param seqRef
 453    *          - null or specific sequence reference
 454    * @param groupRef
 455    *          - null or specific group reference
 456    * @param method
 457    *          - CalcId for the annotation (must match)
 458    *
 459    * @return existing annotation matching the given attributes
 460    */
 461   public AlignmentAnnotation findOrCreateAnnotation(String name,
 462           String calcId, boolean autoCalc, SequenceI seqRef,
 463           SequenceGroup groupRef);
 464
 465   /**
 466    * move the given group up or down in the alignment by the given number of
 467    * rows. Implementor assumes given group is already present on alignment - no
 468    * recalculations are triggered.
 469    *
 470    * @param sg
 471    * @param map
 472    * @param up
 473    * @param i
 474    */
 475   public void moveSelectedSequencesByOne(SequenceGroup sg,
 476           Map<SequenceI, SequenceCollectionI> map, boolean up);
 477
 478   /**
 479    * validate annotation after an edit and update any alignment state flags
 480    * accordingly
 481    *
 482    * @param alignmentAnnotation
 483    */
 484   public void validateAnnotation(AlignmentAnnotation alignmentAnnotation);
 485 }