src/jalview/datamodel/AlignmentI.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer
   3  * Copyright (C) 2007 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 /** 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 is all the same length
  43    *
  44    * @return true if all sequences in alignment are the same length
  45    */
  46   public boolean isAligned();
  47
  48   /**
  49    * Gets sequences as a Vector
  50    *
  51    * @return All sequences in alignment.
  52    */
  53   public Vector getSequences();
  54
  55   /**
  56    * Gets sequences as a SequenceI[]
  57    *
  58    * @return All sequences in alignment.
  59    */
  60   public SequenceI[] getSequencesArray();
  61
  62   /**
  63    * Find a specific sequence in this alignment.
  64    *
  65    * @param i Index of required sequence.
  66    *
  67    * @return SequenceI at given index.
  68    */
  69   public SequenceI getSequenceAt(int i);
  70
  71   /**
  72    * Add a new sequence to this alignment.
  73    *
  74    * @param seq New sequence will be added at end of alignment.
  75    */
  76   public void addSequence(SequenceI seq);
  77
  78   /**
  79    * Used to set a particular index of the alignment with the given sequence.
  80    *
  81    * @param i Index of sequence to be updated.
  82    * @param seq New sequence to be inserted.
  83    */
  84   public void setSequenceAt(int i, SequenceI seq);
  85
  86   /**
  87    * Deletes a sequence from the alignment
  88    *
  89    * @param s Sequence to be deleted.
  90    */
  91   public void deleteSequence(SequenceI s);
  92
  93   /**
  94    * Deletes a sequence from the alignment.
  95    *
  96    * @param i Index of sequence to be deleted.
  97    */
  98   public void deleteSequence(int i);
  99
 100   /**
 101    * Finds sequence in alignment using sequence name as query.
 102    *
 103    * @param name Id of sequence to search for.
 104    *
 105    * @return Sequence matching query, if found. If not found returns null.
 106    */
 107   public SequenceI findName(String name);
 108
 109   public SequenceI[] findSequenceMatch(String name);
 110
 111   /**
 112    * Finds index of a given sequence in the alignment.
 113    *
 114    * @param s Sequence to look for.
 115    *
 116    * @return Index of sequence within the alignment.
 117    */
 118   public int findIndex(SequenceI s);
 119
 120   /**
 121    * Finds group that given sequence is part of.
 122    *
 123    * @param s Sequence in alignment.
 124    *
 125    * @return First group found for sequence. WARNING :
 126    * Sequences may be members of several groups. This method is incomplete.
 127    */
 128   public SequenceGroup findGroup(SequenceI s);
 129
 130   /**
 131    * Finds all groups that a given sequence is part of.
 132    *
 133    * @param s Sequence in alignment.
 134    *
 135    * @return All groups containing given sequence.
 136    */
 137   public SequenceGroup[] findAllGroups(SequenceI s);
 138
 139   /**
 140    * Adds a new SequenceGroup to this alignment.
 141    *
 142    * @param sg New group to be added.
 143    */
 144   public void addGroup(SequenceGroup sg);
 145
 146   /**
 147    * Deletes a specific SequenceGroup
 148    *
 149    * @param g Group will be deleted from alignment.
 150    */
 151   public void deleteGroup(SequenceGroup g);
 152
 153   /**
 154    * Get all the groups associated with this alignment.
 155    *
 156    * @return All groups as a Vector.
 157    */
 158   public Vector getGroups();
 159
 160
 161   /**
 162    * Deletes all groups from this alignment.
 163    */
 164   public void deleteAllGroups();
 165
 166   /**
 167    * Adds a new AlignmentAnnotation to this alignment
 168    * @note Care should be taken to ensure that annotation is at
 169    * least as wide as the longest sequence in the alignment
 170    * for rendering purposes.
 171    */
 172   public void addAnnotation(AlignmentAnnotation aa);
 173   /**
 174    * moves annotation to a specified index in alignment annotation display stack
 175    * @param aa the annotation object to be moved
 176    * @param index the destination position
 177    */
 178   public void setAnnotationIndex(AlignmentAnnotation aa, int index);
 179
 180   /**
 181    * Deletes a specific AlignmentAnnotation from the alignment,
 182    * and removes its reference from any SequenceI object's annotation
 183    * if and only if aa is contained within the alignment's annotation
 184    * vector. Otherwise, it will do nothing.
 185    *
 186    * @param aa the annotation to delete
 187    * @return true if annotation was deleted from this alignment.
 188    */
 189   public boolean deleteAnnotation(AlignmentAnnotation aa);
 190
 191   /**
 192    * Get the annotation associated with this alignment
 193    *
 194    * @return array of AlignmentAnnotation objects
 195    */
 196   public AlignmentAnnotation[] getAlignmentAnnotation();
 197
 198   /**
 199    * Change the gap character used in this alignment to 'gc'
 200    *
 201    * @param gc the new gap character.
 202    */
 203   public void setGapCharacter(char gc);
 204
 205   /**
 206    * Get the gap character used in this alignment
 207    *
 208    * @return gap character
 209    */
 210   public char getGapCharacter();
 211
 212   /**
 213    * Test for all nucleotide alignment
 214    *
 215    * @return true if alignment is nucleotide sequence
 216    */
 217   public boolean isNucleotide();
 218
 219   /**
 220    * Set alignment to be a nucleotide sequence
 221    *
 222    */
 223   public void setNucleotide(boolean b);
 224
 225   /**
 226    * Get the associated dataset for the alignment.
 227    * @return Alignment containing dataset sequences or null of this is a dataset.
 228    */
 229   public Alignment getDataset();
 230
 231   /**
 232    * Set the associated dataset for the alignment, or create one.
 233    * @param dataset The dataset alignment or null to construct one.
 234    */
 235   public void setDataset(Alignment dataset);
 236
 237   /**
 238    * pads sequences with gaps (to ensure the set looks like an alignment)
 239    * @return boolean true if alignment was modified
 240    */
 241   public boolean padGaps();
 242
 243   public HiddenSequences getHiddenSequences();
 244
 245   /**
 246    * Compact representation of alignment
 247    * @return CigarArray
 248    */
 249   public CigarArray getCompactAlignment();
 250
 251   /**
 252    * Set an arbitrary key value pair for an alignment.
 253    * Note: both key and value objects should return a
 254    * meaningful, human readable response to .toString()
 255    * @param key
 256    * @param value
 257    */
 258   public void setProperty(Object key, Object value);
 259   /**
 260    * Get a named property from the alignment.
 261    * @param key
 262    * @return value of property
 263    */
 264   public Object getProperty(Object key);
 265   /**
 266    * Get the property hashtable.
 267    * @return hashtable of alignment properties (or null if none are defined)
 268    */
 269   public Hashtable getProperties();
 270
 271   /**
 272    * add a reference to a frame of aligned codons for this alignment
 273    * @param codons
 274    */
 275   public void addCodonFrame(AlignedCodonFrame codons);
 276   /**
 277    * remove a particular codon frame reference from this alignment
 278    * @param codons
 279    * @return true if codon frame was removed.
 280    */
 281   public boolean removeCodonFrame(AlignedCodonFrame codons);
 282   /**
 283    * get all codon frames associated with this alignment
 284    * @return
 285    */
 286   public AlignedCodonFrame[] getCodonFrames();
 287   /**
 288    * get a particular codon frame
 289    * @param index
 290    * @return
 291    */
 292   public AlignedCodonFrame getCodonFrame(int index);
 293   /**
 294    * get codon frames involving sequenceI
 295    */
 296   public AlignedCodonFrame[] getCodonFrame(SequenceI seq);
 297   /**
 298    * find sequence with given name in alignment
 299    * @param token name to find
 300    * @param b true implies that case insensitive matching will <em>also</em> be tried
 301    * @return matched sequence or null
 302    */
 303   public SequenceI findName(String token, boolean b);
 304
 305 }