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