src/jalview/datamodel/AlignmentI.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   3  * Copyright (C) $$Year-Rel$$ 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.Collection;
  24 import java.util.Hashtable;
  25 import java.util.List;
  26 import java.util.Map;
  27 import java.util.Set;
  28
  29 /**
  30  * Data structure to hold and manipulate a multiple sequence alignment
  31  */
  32 public interface AlignmentI extends AnnotatedCollectionI
  33 {
  34   /**
  35    * Calculates the number of sequences in an alignment, excluding hidden
  36    * sequences
  37    *
  38    * @return Number of sequences in alignment
  39    */
  40   int getHeight();
  41
  42   /**
  43    * Calculates the number of sequences in an alignment, including hidden
  44    * sequences
  45    *
  46    * @return Number of sequences in alignment
  47    */
  48   int getAbsoluteHeight();
  49
  50   /**
  51    *
  52    * Answers the width of the alignment, including gaps, that is, the length of
  53    * the longest sequence, or -1 if there are no sequences. Avoid calling this
  54    * method repeatedly where possible, as it has to perform a calculation. Note
  55    * that this width includes any hidden columns.
  56    *
  57    * @return
  58    * @see AlignmentI#getVisibleWidth()
  59    */
  60   @Override
  61   int getWidth();
  62
  63   /**
  64    *
  65    * Answers the visible width of the alignment, including gaps, that is, the
  66    * length of the longest sequence, excluding any hidden columns. Answers -1 if
  67    * there are no sequences. Avoid calling this method repeatedly where
  68    * possible, as it has to perform a calculation.
  69    *
  70    * @return
  71    */
  72   int getVisibleWidth();
  73
  74   /**
  75    * Calculates if this set of sequences (visible and invisible) are all the
  76    * same length
  77    *
  78    * @return true if all sequences in alignment are the same length
  79    */
  80   boolean isAligned();
  81
  82   /**
  83    * Calculates if this set of sequences is all the same length
  84    *
  85    * @param includeHidden
  86    *          optionally exclude hidden sequences from test
  87    * @return true if all (or just visible) sequences are the same length
  88    */
  89   boolean isAligned(boolean includeHidden);
  90
  91   /**
  92    * Answers if the sequence at alignmentIndex is hidden
  93    *
  94    * @param alignmentIndex
  95    *          the index to check
  96    * @return true if the sequence is hidden
  97    */
  98   boolean isHidden(int alignmentIndex);
  99
 100   /**
 101    * Gets sequences as a Synchronized collection
 102    *
 103    * @return All sequences in alignment.
 104    */
 105   @Override
 106   List<SequenceI> getSequences();
 107
 108   /**
 109    * Gets sequences as a SequenceI[]
 110    *
 111    * @return All sequences in alignment.
 112    */
 113   SequenceI[] getSequencesArray();
 114
 115   /**
 116    * Find a specific sequence in this alignment.
 117    *
 118    * @param i
 119    *          Index of required sequence.
 120    *
 121    * @return SequenceI at given index.
 122    */
 123   SequenceI getSequenceAt(int i);
 124
 125   /**
 126    * Find a specific sequence in this alignment.
 127    *
 128    * @param i
 129    *          Index of required sequence in full alignment, i.e. if all columns
 130    *          were visible
 131    *
 132    * @return SequenceI at given index.
 133    */
 134   SequenceI getSequenceAtAbsoluteIndex(int i);
 135
 136   /**
 137    * Returns a map of lists of sequences keyed by sequence name.
 138    *
 139    * @return
 140    */
 141   Map<String, List<SequenceI>> getSequencesByName();
 142
 143   /**
 144    * Add a new sequence to this alignment.
 145    *
 146    * @param seq
 147    *          New sequence will be added at end of alignment.
 148    */
 149   void addSequence(SequenceI seq);
 150
 151   /**
 152    * Used to set a particular index of the alignment with the given sequence.
 153    *
 154    * @param i
 155    *          Index of sequence to be updated. if i>length, sequence will be
 156    *          added to end, with no intervening positions.
 157    * @param seq
 158    *          New sequence to be inserted. The existing sequence at position i
 159    *          will be replaced.
 160    * @return existing sequence (or null if i>current length)
 161    */
 162   SequenceI replaceSequenceAt(int i, SequenceI seq);
 163
 164   /**
 165    * Deletes a sequence from the alignment. Updates hidden sequences to account
 166    * for the removed sequence. Do NOT use this method to delete sequences which
 167    * are just hidden.
 168    *
 169    * @param s
 170    *          Sequence to be deleted.
 171    */
 172   void deleteSequence(SequenceI s);
 173
 174   /**
 175    * Deletes a sequence from the alignment. Updates hidden sequences to account
 176    * for the removed sequence. Do NOT use this method to delete sequences which
 177    * are just hidden.
 178    *
 179    * @param i
 180    *          Index of sequence to be deleted.
 181    */
 182   void deleteSequence(int i);
 183
 184   /**
 185    * Deletes a sequence in the alignment which has been hidden.
 186    *
 187    * @param i
 188    *          Index of sequence to be deleted
 189    */
 190   void deleteHiddenSequence(int i);
 191
 192   /**
 193    * Finds sequence in alignment using sequence name as query.
 194    *
 195    * @param name
 196    *          Id of sequence to search for.
 197    *
 198    * @return Sequence matching query, if found. If not found returns null.
 199    */
 200   SequenceI findName(String name);
 201
 202   SequenceI[] findSequenceMatch(String name);
 203
 204   /**
 205    * Finds index of a given sequence in the alignment.
 206    *
 207    * @param s
 208    *          Sequence to look for.
 209    *
 210    * @return Index of sequence within the alignment or -1 if not found
 211    */
 212   int findIndex(SequenceI s);
 213
 214   /**
 215    * Returns the first group (in the order in which groups were added) that
 216    * includes the given sequence instance and aligned position (base 0), or null
 217    * if none found
 218    *
 219    * @param seq
 220    *          - must be contained in the alignment (not a dataset sequence)
 221    * @param position
 222    *
 223    * @return
 224    */
 225   SequenceGroup findGroup(SequenceI seq, int position);
 226
 227   /**
 228    * Finds all groups that a given sequence is part of.
 229    *
 230    * @param s
 231    *          Sequence in alignment.
 232    *
 233    * @return All groups containing given sequence.
 234    */
 235   SequenceGroup[] findAllGroups(SequenceI s);
 236
 237   /**
 238    * Adds a new SequenceGroup to this alignment.
 239    *
 240    * @param sg
 241    *          New group to be added.
 242    */
 243   void addGroup(SequenceGroup sg);
 244
 245   /**
 246    * Deletes a specific SequenceGroup
 247    *
 248    * @param g
 249    *          Group will be deleted from alignment.
 250    */
 251   void deleteGroup(SequenceGroup g);
 252
 253   /**
 254    * Get all the groups associated with this alignment.
 255    *
 256    * @return All groups as a list.
 257    */
 258   List<SequenceGroup> getGroups();
 259
 260   /**
 261    * Deletes all groups from this alignment.
 262    */
 263   void deleteAllGroups();
 264
 265   /**
 266    * Adds a new AlignmentAnnotation to this alignment
 267    *
 268    * @note Care should be taken to ensure that annotation is at least as wide as
 269    *       the longest sequence in the alignment for rendering purposes.
 270    */
 271   void addAnnotation(AlignmentAnnotation aa);
 272
 273   /**
 274    * moves annotation to a specified index in alignment annotation display stack
 275    *
 276    * @param aa
 277    *          the annotation object to be moved
 278    * @param index
 279    *          the destination position
 280    */
 281   void setAnnotationIndex(AlignmentAnnotation aa, int index);
 282
 283   /**
 284    * Delete all annotations, including auto-calculated if the flag is set true.
 285    * Returns true if at least one annotation was deleted, else false.
 286    *
 287    * @param includingAutoCalculated
 288    * @return
 289    */
 290   boolean deleteAllAnnotations(boolean includingAutoCalculated);
 291
 292   /**
 293    * Deletes a specific AlignmentAnnotation from the alignment, and removes its
 294    * reference from any SequenceI or SequenceGroup object's annotation if and
 295    * only if aa is contained within the alignment's annotation vector.
 296    * Otherwise, it will do nothing.
 297    *
 298    * @param aa
 299    *          the annotation to delete
 300    * @return true if annotation was deleted from this alignment.
 301    */
 302   boolean deleteAnnotation(AlignmentAnnotation aa);
 303
 304   /**
 305    * Deletes a specific AlignmentAnnotation from the alignment, and optionally
 306    * removes any reference from any SequenceI or SequenceGroup object's
 307    * annotation if and only if aa is contained within the alignment's annotation
 308    * vector. Otherwise, it will do nothing.
 309    *
 310    * @param aa
 311    *          the annotation to delete
 312    * @param unhook
 313    *          flag indicating if any references should be removed from
 314    *          annotation - use this if you intend to add the annotation back
 315    *          into the alignment
 316    * @return true if annotation was deleted from this alignment.
 317    */
 318   boolean deleteAnnotation(AlignmentAnnotation aa, boolean unhook);
 319
 320   /**
 321    * Get the annotation associated with this alignment (this can be null if no
 322    * annotation has ever been created on the alignment)
 323    *
 324    * @return array of AlignmentAnnotation objects
 325    */
 326   @Override
 327   AlignmentAnnotation[] getAlignmentAnnotation();
 328
 329   /**
 330    * Change the gap character used in this alignment to 'gc'
 331    *
 332    * @param gc
 333    *          the new gap character.
 334    */
 335   void setGapCharacter(char gc);
 336
 337   /**
 338    * Get the gap character used in this alignment
 339    *
 340    * @return gap character
 341    */
 342   char getGapCharacter();
 343
 344   /**
 345    * Test if alignment contains RNA structure
 346    *
 347    * @return true if RNA structure AligmnentAnnotation was added to alignment
 348    */
 349   boolean hasRNAStructure();
 350
 351   /**
 352    * Get the associated dataset for the alignment.
 353    *
 354    * @return Alignment containing dataset sequences or null of this is a
 355    *         dataset.
 356    */
 357   AlignmentI getDataset();
 358
 359   /**
 360    * Set the associated dataset for the alignment, or create one.
 361    *
 362    * @param dataset
 363    *          The dataset alignment or null to construct one.
 364    */
 365   void setDataset(AlignmentI dataset);
 366
 367   /**
 368    * pads sequences with gaps (to ensure the set looks like an alignment)
 369    *
 370    * @return boolean true if alignment was modified
 371    */
 372   boolean padGaps();
 373
 374   HiddenSequences getHiddenSequences();
 375
 376   HiddenColumns getHiddenColumns();
 377
 378   /**
 379    * Compact representation of alignment
 380    *
 381    * @return CigarArray
 382    */
 383   CigarArray getCompactAlignment();
 384
 385   /**
 386    * Set an arbitrary key value pair for an alignment. Note: both key and value
 387    * objects should return a meaningful, human readable response to .toString()
 388    *
 389    * @param key
 390    * @param value
 391    */
 392   void setProperty(Object key, Object value);
 393
 394   /**
 395    * Get a named property from the alignment.
 396    *
 397    * @param key
 398    * @return value of property
 399    */
 400   Object getProperty(Object key);
 401
 402   /**
 403    * Get the property hashtable.
 404    *
 405    * @return hashtable of alignment properties (or null if none are defined)
 406    */
 407   Hashtable getProperties();
 408
 409   /**
 410    * add a reference to a frame of aligned codons for this alignment
 411    *
 412    * @param codons
 413    */
 414   void addCodonFrame(AlignedCodonFrame codons);
 415
 416   /**
 417    * remove a particular codon frame reference from this alignment
 418    *
 419    * @param codons
 420    * @return true if codon frame was removed.
 421    */
 422   boolean removeCodonFrame(AlignedCodonFrame codons);
 423
 424   /**
 425    * get all codon frames associated with this alignment
 426    *
 427    * @return
 428    */
 429   List<AlignedCodonFrame> getCodonFrames();
 430
 431   /**
 432    * Set the codon frame mappings (replacing any existing list).
 433    */
 434   void setCodonFrames(List<AlignedCodonFrame> acfs);
 435
 436   /**
 437    * get codon frames involving sequenceI
 438    */
 439   List<AlignedCodonFrame> getCodonFrame(SequenceI seq);
 440
 441   /**
 442    * find sequence with given name in alignment
 443    *
 444    * @param token
 445    *          name to find
 446    * @param b
 447    *          true implies that case insensitive matching will <em>also</em> be
 448    *          tried
 449    * @return matched sequence or null
 450    */
 451   SequenceI findName(String token, boolean b);
 452
 453   /**
 454    * find next sequence with given name in alignment starting after a given
 455    * sequence
 456    *
 457    * @param startAfter
 458    *          the sequence after which the search will be started (usually the
 459    *          result of the last call to findName)
 460    * @param token
 461    *          name to find
 462    * @param b
 463    *          true implies that case insensitive matching will <em>also</em> be
 464    *          tried
 465    * @return matched sequence or null
 466    */
 467   SequenceI findName(SequenceI startAfter, String token, boolean b);
 468
 469   /**
 470    * find first sequence in alignment which is involved in the given search
 471    * result object
 472    *
 473    * @param results
 474    * @return -1 or index of sequence in alignment
 475    */
 476   int findIndex(SearchResultsI results);
 477
 478   /**
 479    * append sequences and annotation from another alignment object to this one.
 480    * Note: this is a straight transfer of object references, and may result in
 481    * toappend's dependent data being transformed to fit the alignment (changing
 482    * gap characters, etc...). If you are uncertain, use the copy Alignment copy
 483    * constructor to create a new version which can be appended without side
 484    * effect.
 485    *
 486    * @param toappend
 487    *          - the alignment to be appended.
 488    */
 489   void append(AlignmentI toappend);
 490
 491   /**
 492    * Justify the sequences to the left or right by deleting and inserting gaps
 493    * before the initial residue or after the terminal residue
 494    *
 495    * @param right
 496    *          true if alignment padded to right, false to justify to left
 497    * @return true if alignment was changed TODO: return undo object
 498    */
 499   boolean justify(boolean right);
 500
 501   /**
 502    * add given annotation row at given position (0 is start, -1 is end)
 503    *
 504    * @param consensus
 505    * @param i
 506    */
 507   void addAnnotation(AlignmentAnnotation consensus, int i);
 508
 509   /**
 510    * search for or create a specific annotation row on the alignment
 511    *
 512    * @param name
 513    *          name for annotation (must match)
 514    * @param calcId
 515    *          calcId for the annotation (null or must match)
 516    * @param autoCalc
 517    *          - value of autocalc flag for the annotation
 518    * @param seqRef
 519    *          - null or specific sequence reference
 520    * @param groupRef
 521    *          - null or specific group reference
 522    * @param method
 523    *          - CalcId for the annotation (must match)
 524    *
 525    * @return existing annotation matching the given attributes
 526    */
 527   AlignmentAnnotation findOrCreateAnnotation(String name, String calcId,
 528           boolean autoCalc, SequenceI seqRef, SequenceGroup groupRef);
 529
 530   /**
 531    * move the given group up or down in the alignment by the given number of
 532    * rows. Implementor assumes given group is already present on alignment - no
 533    * recalculations are triggered.
 534    *
 535    * @param sg
 536    * @param map
 537    * @param up
 538    * @param i
 539    */
 540   void moveSelectedSequencesByOne(SequenceGroup sg,
 541           Map<SequenceI, SequenceCollectionI> map, boolean up);
 542
 543   /**
 544    * validate annotation after an edit and update any alignment state flags
 545    * accordingly
 546    *
 547    * @param alignmentAnnotation
 548    */
 549   void validateAnnotation(AlignmentAnnotation alignmentAnnotation);
 550
 551   /**
 552    * Align this alignment the same as the given one. If both of the same type
 553    * (nucleotide/protein) then align both identically. If this is nucleotide and
 554    * the other is protein, make 3 gaps for each gap in the protein sequences. If
 555    * this is protein and the other is nucleotide, insert a gap for each 3 gaps
 556    * (or part thereof) between nucleotide bases. Returns the number of mapped
 557    * sequences that were realigned .
 558    *
 559    * @param al
 560    * @return
 561    */
 562   int alignAs(AlignmentI al);
 563
 564   /**
 565    * Returns the set of distinct sequence names in the alignment.
 566    *
 567    * @return
 568    */
 569   Set<String> getSequenceNames();
 570
 571   /**
 572    * Checks if the alignment has at least one sequence with one non-gaped
 573    * residue
 574    *
 575    * @return
 576    */
 577   public boolean hasValidSequence();
 578
 579   /**
 580    * Update any mappings to 'virtual' sequences to compatible real ones, if
 581    * present in the added sequences. Returns a count of mappings updated.
 582    *
 583    * @param seqs
 584    * @return
 585    */
 586   int realiseMappings(List<SequenceI> seqs);
 587
 588   /**
 589    * Returns the first AlignedCodonFrame that has a mapping between the given
 590    * dataset sequences
 591    *
 592    * @param mapFrom
 593    * @param mapTo
 594    * @return
 595    */
 596   AlignedCodonFrame getMapping(SequenceI mapFrom, SequenceI mapTo);
 597
 598   /**
 599    * Set the hidden columns collection on the alignment. Answers true if the
 600    * hidden column selection changed, else false.
 601    *
 602    * @param cols
 603    * @return
 604    */
 605   public boolean setHiddenColumns(HiddenColumns cols);
 606
 607   /**
 608    * Set the first sequence as representative and hide its insertions. Typically
 609    * used when loading JPred files.
 610    */
 611   public void setupJPredAlignment();
 612
 613   /**
 614    * Add gaps into the sequences aligned to profileseq under the given
 615    * AlignmentView
 616    *
 617    * @param profileseq
 618    *          sequence in al which sequences are aligned to
 619    * @param input
 620    *          alignment view where sequence corresponding to profileseq is first
 621    *          entry
 622    * @return new HiddenColumns for new alignment view, with insertions into
 623    *         profileseq marked as hidden.
 624    */
 625   public HiddenColumns propagateInsertions(SequenceI profileseq,
 626           AlignmentView input);
 627
 628   /**
 629    * resolve a contact list instance (if any) associated with the annotation row
 630    * and column position
 631    *
 632    * @param _aa
 633    * @param column
 634    * @return
 635    */
 636   ContactListI getContactListFor(AlignmentAnnotation _aa, int column);
 637
 638   AlignmentAnnotation addContactList(ContactMatrixI cm);
 639
 640   Collection<ContactMatrixI> getContactMaps();
 641 }