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