src/jalview/datamodel/AlignmentI.java

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