src/jalview/datamodel/AlignmentI.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer (Development Version 2.4.1)
   3  * Copyright (C) 2009 AM Waterhouse, J Procter, G Barton, M Clamp, S Searle
   4  *
   5  * This program is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU General Public License
   7  * as published by the Free Software Foundation; either version 2
   8  * of the License, or (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
  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
  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   public int getWidth();
  41
  42   /**
  43    * Calculates if this set of sequences is all the same length
  44    *
  45    * @return true if all sequences in alignment are the same length
  46    */
  47   public boolean isAligned();
  48
  49   /**
  50    * Gets sequences as a Vector
  51    *
  52    * @return All sequences in alignment.
  53    */
  54   public Vector getSequences();
  55
  56   /**
  57    * Gets sequences as a SequenceI[]
  58    *
  59    * @return All sequences in alignment.
  60    */
  61   public SequenceI[] getSequencesArray();
  62
  63   /**
  64    * Find a specific sequence in this alignment.
  65    *
  66    * @param i
  67    *                Index of required sequence.
  68    *
  69    * @return SequenceI at given index.
  70    */
  71   public SequenceI getSequenceAt(int i);
  72
  73   /**
  74    * Add a new sequence to this alignment.
  75    *
  76    * @param seq
  77    *                New sequence will be added at end of alignment.
  78    */
  79   public void addSequence(SequenceI seq);
  80
  81   /**
  82    * Used to set a particular index of the alignment with the given sequence.
  83    *
  84    * @param i
  85    *                Index of sequence to be updated.
  86    * @param seq
  87    *                New sequence to be inserted.
  88    */
  89   public void setSequenceAt(int i, SequenceI seq);
  90
  91   /**
  92    * Deletes a sequence from the alignment
  93    *
  94    * @param s
  95    *                Sequence to be deleted.
  96    */
  97   public void deleteSequence(SequenceI s);
  98
  99   /**
 100    * Deletes a sequence from the alignment.
 101    *
 102    * @param i
 103    *                Index of sequence to be deleted.
 104    */
 105   public void deleteSequence(int i);
 106
 107   /**
 108    * Finds sequence in alignment using sequence name as query.
 109    *
 110    * @param name
 111    *                Id of sequence to search for.
 112    *
 113    * @return Sequence matching query, if found. If not found returns null.
 114    */
 115   public SequenceI findName(String name);
 116
 117   public SequenceI[] findSequenceMatch(String name);
 118
 119   /**
 120    * Finds index of a given sequence in the alignment.
 121    *
 122    * @param s
 123    *                Sequence to look for.
 124    *
 125    * @return Index of sequence within the alignment or -1 if not found
 126    */
 127   public int findIndex(SequenceI s);
 128
 129   /**
 130    * Finds group that given sequence is part of.
 131    *
 132    * @param s
 133    *                Sequence in alignment.
 134    *
 135    * @return First group found for sequence. WARNING : Sequences may be members
 136    *         of several groups. This method is incomplete.
 137    */
 138   public SequenceGroup findGroup(SequenceI s);
 139
 140   /**
 141    * Finds all groups that a given sequence is part of.
 142    *
 143    * @param s
 144    *                Sequence in alignment.
 145    *
 146    * @return All groups containing given sequence.
 147    */
 148   public SequenceGroup[] findAllGroups(SequenceI s);
 149
 150   /**
 151    * Adds a new SequenceGroup to this alignment.
 152    *
 153    * @param sg
 154    *                New group to be added.
 155    */
 156   public void addGroup(SequenceGroup sg);
 157
 158   /**
 159    * Deletes a specific SequenceGroup
 160    *
 161    * @param g
 162    *                Group will be deleted from alignment.
 163    */
 164   public void deleteGroup(SequenceGroup g);
 165
 166   /**
 167    * Get all the groups associated with this alignment.
 168    *
 169    * @return All groups as a Vector.
 170    */
 171   public Vector getGroups();
 172
 173   /**
 174    * Deletes all groups from this alignment.
 175    */
 176   public void deleteAllGroups();
 177
 178   /**
 179    * Adds a new AlignmentAnnotation to this alignment
 180    *
 181    * @note Care should be taken to ensure that annotation is at least as wide as
 182    *       the longest sequence in the alignment for rendering purposes.
 183    */
 184   public void addAnnotation(AlignmentAnnotation aa);
 185
 186   /**
 187    * moves annotation to a specified index in alignment annotation display stack
 188    *
 189    * @param aa
 190    *                the annotation object to be moved
 191    * @param index
 192    *                the destination position
 193    */
 194   public void setAnnotationIndex(AlignmentAnnotation aa, int index);
 195
 196   /**
 197    * Deletes a specific AlignmentAnnotation from the alignment, and removes its
 198    * reference from any SequenceI object's annotation if and only if aa is
 199    * contained within the alignment's annotation vector. Otherwise, it will do
 200    * nothing.
 201    *
 202    * @param aa
 203    *                the annotation to delete
 204    * @return true if annotation was deleted from this alignment.
 205    */
 206   public boolean deleteAnnotation(AlignmentAnnotation aa);
 207
 208   /**
 209    * Get the annotation associated with this alignment
 210    *
 211    * @return array of AlignmentAnnotation objects
 212    */
 213   public AlignmentAnnotation[] getAlignmentAnnotation();
 214
 215   /**
 216    * Change the gap character used in this alignment to 'gc'
 217    *
 218    * @param gc
 219    *                the new gap character.
 220    */
 221   public void setGapCharacter(char gc);
 222
 223   /**
 224    * Get the gap character used in this alignment
 225    *
 226    * @return gap character
 227    */
 228   public char getGapCharacter();
 229
 230   /**
 231    * Test for all nucleotide alignment
 232    *
 233    * @return true if alignment is nucleotide sequence
 234    */
 235   public boolean isNucleotide();
 236
 237   /**
 238    * Set alignment to be a nucleotide sequence
 239    *
 240    */
 241   public void setNucleotide(boolean b);
 242
 243   /**
 244    * Get the associated dataset for the alignment.
 245    *
 246    * @return Alignment containing dataset sequences or null of this is a
 247    *         dataset.
 248    */
 249   public Alignment getDataset();
 250
 251   /**
 252    * Set the associated dataset for the alignment, or create one.
 253    *
 254    * @param dataset
 255    *                The dataset alignment or null to construct one.
 256    */
 257   public void setDataset(Alignment dataset);
 258
 259   /**
 260    * pads sequences with gaps (to ensure the set looks like an alignment)
 261    *
 262    * @return boolean true if alignment was modified
 263    */
 264   public boolean padGaps();
 265
 266   public HiddenSequences getHiddenSequences();
 267
 268   /**
 269    * Compact representation of alignment
 270    *
 271    * @return CigarArray
 272    */
 273   public CigarArray getCompactAlignment();
 274
 275   /**
 276    * Set an arbitrary key value pair for an alignment. Note: both key and value
 277    * objects should return a meaningful, human readable response to .toString()
 278    *
 279    * @param key
 280    * @param value
 281    */
 282   public void setProperty(Object key, Object value);
 283
 284   /**
 285    * Get a named property from the alignment.
 286    *
 287    * @param key
 288    * @return value of property
 289    */
 290   public Object getProperty(Object key);
 291
 292   /**
 293    * Get the property hashtable.
 294    *
 295    * @return hashtable of alignment properties (or null if none are defined)
 296    */
 297   public Hashtable getProperties();
 298
 299   /**
 300    * add a reference to a frame of aligned codons for this alignment
 301    *
 302    * @param codons
 303    */
 304   public void addCodonFrame(AlignedCodonFrame codons);
 305
 306   /**
 307    * remove a particular codon frame reference from this alignment
 308    *
 309    * @param codons
 310    * @return true if codon frame was removed.
 311    */
 312   public boolean removeCodonFrame(AlignedCodonFrame codons);
 313
 314   /**
 315    * get all codon frames associated with this alignment
 316    *
 317    * @return
 318    */
 319   public AlignedCodonFrame[] getCodonFrames();
 320
 321   /**
 322    * get a particular codon frame
 323    *
 324    * @param index
 325    * @return
 326    */
 327   public AlignedCodonFrame getCodonFrame(int index);
 328
 329   /**
 330    * get codon frames involving sequenceI
 331    */
 332   public AlignedCodonFrame[] getCodonFrame(SequenceI seq);
 333
 334   /**
 335    * find sequence with given name in alignment
 336    *
 337    * @param token
 338    *                name to find
 339    * @param b
 340    *                true implies that case insensitive matching will
 341    *                <em>also</em> be tried
 342    * @return matched sequence or null
 343    */
 344   public SequenceI findName(String token, boolean b);
 345
 346   /**
 347    * find next sequence with given name in alignment starting after a given
 348    * sequence
 349    *
 350    * @param startAfter
 351    *                the sequence after which the search will be started (usually
 352    *                the result of the last call to findName)
 353    * @param token
 354    *                name to find
 355    * @param b
 356    *                true implies that case insensitive matching will
 357    *                <em>also</em> be tried
 358    * @return matched sequence or null
 359    */
 360   public SequenceI findName(SequenceI startAfter, String token, boolean b);
 361
 362   /**
 363    * find first sequence in alignment which is involved in the given search result object
 364    * @param results
 365    * @return -1 or index of sequence in alignment
 366    */
 367   public int findIndex(SearchResults results);
 368
 369   /**
 370    * append sequences and annotation from another alignment object to this one.
 371    * Note: this is a straight transfer of object references, and may result in
 372    * toappend's dependent data being transformed to fit the alignment (changing gap characters, etc...).
 373    * If you are uncertain, use the copy Alignment copy constructor to create a new version
 374    * which can be appended without side effect.
 375    * @param toappend - the alignment to be appended.
 376    */
 377   public void append(AlignmentI toappend);
 378   /**
 379    * Justify the sequences to the left or right by deleting and inserting gaps before the initial residue or after the terminal residue
 380    * @param right true if alignment padded to right, false to justify to left
 381    * @return true if alignment was changed
 382    * TODO: return undo object
 383    */
 384   public boolean justify(boolean right);
 385
 386   /**
 387    * add given annotation row at given position (0 is start, -1 is end)
 388    * @param consensus
 389    * @param i
 390    */
 391   public void addAnnotation(AlignmentAnnotation consensus, int i);
 392 }