src/jalview/datamodel/SequenceI.java

   1 /*\r
   2  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8.2)\r
   3  * Copyright (C) 2014 The Jalview Authors\r
   4  * \r
   5  * This file is part of Jalview.\r
   6  * \r
   7  * Jalview is free software: you can redistribute it and/or\r
   8  * modify it under the terms of the GNU General Public License \r
   9  * as published by the Free Software Foundation, either version 3\r
  10  * of the License, or (at your option) any later version.\r
  11  *  \r
  12  * Jalview is distributed in the hope that it will be useful, but \r
  13  * WITHOUT ANY WARRANTY; without even the implied warranty \r
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR \r
  15  * PURPOSE.  See the GNU General Public License for more details.\r
  16  * \r
  17  * You should have received a copy of the GNU General Public License\r
  18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.\r
  19  * The Jalview Authors are detailed in the 'AUTHORS' file.\r
  20  */\r
  21 package jalview.datamodel;\r
  22 \r
  23 import java.util.Vector;\r
  24 \r
  25 import fr.orsay.lri.varna.models.rna.RNA;\r
  26 \r
  27 /**\r
  28  * DOCUMENT ME!\r
  29  * \r
  30  * @author $author$\r
  31  * @version $Revision$\r
  32  */\r
  33 public interface SequenceI\r
  34 {\r
  35   /**\r
  36    * Set the display name for the sequence\r
  37    * \r
  38    * @param name\r
  39    */\r
  40   public void setName(String name);\r
  41 \r
  42   /**\r
  43    * Get the display name\r
  44    */\r
  45   public String getName();\r
  46 \r
  47   /**\r
  48    * Set start position of first non-gapped symbol in sequence\r
  49    * \r
  50    * @param start\r
  51    *          new start position\r
  52    */\r
  53   public void setStart(int start);\r
  54 \r
  55   /**\r
  56    * get start position of first non-gapped residue in sequence\r
  57    * \r
  58    * @return\r
  59    */\r
  60   public int getStart();\r
  61 \r
  62   /**\r
  63    * get the displayed id of the sequence\r
  64    * \r
  65    * @return true means the id will be returned in the form\r
  66    *         DisplayName/Start-End\r
  67    */\r
  68   public String getDisplayId(boolean jvsuffix);\r
  69 \r
  70   /**\r
  71    * set end position for last residue in sequence\r
  72    * \r
  73    * @param end\r
  74    */\r
  75   public void setEnd(int end);\r
  76 \r
  77   /**\r
  78    * get end position for last residue in sequence getEnd()>getStart() unless\r
  79    * sequence only consists of gap characters\r
  80    * \r
  81    * @return\r
  82    */\r
  83   public int getEnd();\r
  84 \r
  85   /**\r
  86    * @return length of sequence including gaps\r
  87    * \r
  88    */\r
  89   public int getLength();\r
  90 \r
  91   /**\r
  92    * Replace the sequence with the given string\r
  93    * \r
  94    * @param sequence\r
  95    *          new sequence string\r
  96    */\r
  97   public void setSequence(String sequence);\r
  98 \r
  99   /**\r
 100    * @return sequence as string\r
 101    */\r
 102   public String getSequenceAsString();\r
 103 \r
 104   /**\r
 105    * get a range on the sequence as a string\r
 106    * \r
 107    * @param start\r
 108    *          position relative to start of sequence including gaps (from 0)\r
 109    * @param end\r
 110    *          position relative to start of sequence including gaps (from 0)\r
 111    * \r
 112    * @return String containing all gap and symbols in specified range\r
 113    */\r
 114   public String getSequenceAsString(int start, int end);\r
 115 \r
 116   /**\r
 117    * Get the sequence as a character array\r
 118    * \r
 119    * @return seqeunce and any gaps\r
 120    */\r
 121   public char[] getSequence();\r
 122 \r
 123   /**\r
 124    * get stretch of sequence characters in an array\r
 125    * \r
 126    * @param start\r
 127    *          absolute index into getSequence()\r
 128    * @param end\r
 129    *          exclusive index of last position in segment to be returned.\r
 130    * \r
 131    * @return char[max(0,end-start)];\r
 132    */\r
 133   public char[] getSequence(int start, int end);\r
 134 \r
 135   /**\r
 136    * create a new sequence object from start to end of this sequence\r
 137    * \r
 138    * @param start\r
 139    *          int\r
 140    * @param end\r
 141    *          int\r
 142    * @return SequenceI\r
 143    */\r
 144   public SequenceI getSubSequence(int start, int end);\r
 145 \r
 146   /**\r
 147    * DOCUMENT ME!\r
 148    * \r
 149    * @param i\r
 150    *          DOCUMENT ME!\r
 151    * \r
 152    * @return DOCUMENT ME!\r
 153    */\r
 154   public char getCharAt(int i);\r
 155 \r
 156   /**\r
 157    * DOCUMENT ME!\r
 158    * \r
 159    * @param desc\r
 160    *          DOCUMENT ME!\r
 161    */\r
 162   public void setDescription(String desc);\r
 163 \r
 164   /**\r
 165    * DOCUMENT ME!\r
 166    * \r
 167    * @return DOCUMENT ME!\r
 168    */\r
 169   public String getDescription();\r
 170 \r
 171   /**\r
 172    * Return the alignment column for a sequence position * Return the alignment\r
 173    * position for a sequence position\r
 174    * \r
 175    * @param pos\r
 176    *          lying from start to end\r
 177    * \r
 178    * @return aligned column for residue (0 if residue is upstream from\r
 179    *         alignment, -1 if residue is downstream from alignment) note.\r
 180    *         Sequence object returns sequence.getEnd() for positions upstream\r
 181    *         currently. TODO: change sequence for\r
 182    *         assert(findIndex(seq.getEnd()+1)==-1) and fix incremental bugs\r
 183    * \r
 184    */\r
 185   public int findIndex(int pos);\r
 186 \r
 187   /**\r
 188    * Returns the sequence position for an alignment position\r
 189    * \r
 190    * @param i\r
 191    *          column index in alignment (from 1)\r
 192    * \r
 193    * @return residue number for residue (left of and) nearest ith column\r
 194    */\r
 195   public int findPosition(int i);\r
 196 \r
 197   /**\r
 198    * Returns an int array where indices correspond to each residue in the\r
 199    * sequence and the element value gives its position in the alignment\r
 200    * \r
 201    * @return int[SequenceI.getEnd()-SequenceI.getStart()+1] or null if no\r
 202    *         residues in SequenceI object\r
 203    */\r
 204   public int[] gapMap();\r
 205 \r
 206   /**\r
 207    * Returns an int array where indices correspond to each position in sequence\r
 208    * char array and the element value gives the result of findPosition for that\r
 209    * index in the sequence.\r
 210    * \r
 211    * @return int[SequenceI.getLength()]\r
 212    */\r
 213   public int[] findPositionMap();\r
 214 \r
 215   /**\r
 216    * Delete a range of aligned sequence columns, creating a new dataset sequence\r
 217    * if necessary and adjusting start and end positions accordingly.\r
 218    * \r
 219    * @param i\r
 220    *          first column in range to delete\r
 221    * @param j\r
 222    *          last column in range to delete\r
 223    */\r
 224   public void deleteChars(int i, int j);\r
 225 \r
 226   /**\r
 227    * DOCUMENT ME!\r
 228    * \r
 229    * @param i\r
 230    *          DOCUMENT ME!\r
 231    * @param c\r
 232    *          DOCUMENT ME!\r
 233    */\r
 234   public void insertCharAt(int i, char c);\r
 235 \r
 236   /**\r
 237    * DOCUMENT ME!\r
 238    * \r
 239    * @param i\r
 240    *          DOCUMENT ME!\r
 241    * @param c\r
 242    *          DOCUMENT ME!\r
 243    */\r
 244   public void insertCharAt(int i, int length, char c);\r
 245 \r
 246   /**\r
 247    * DOCUMENT ME!\r
 248    * \r
 249    * @return DOCUMENT ME!\r
 250    */\r
 251   public SequenceFeature[] getSequenceFeatures();\r
 252 \r
 253   /**\r
 254    * DOCUMENT ME!\r
 255    * \r
 256    * @param v\r
 257    *          DOCUMENT ME!\r
 258    */\r
 259   public void setSequenceFeatures(SequenceFeature[] features);\r
 260 \r
 261   /**\r
 262    * DOCUMENT ME!\r
 263    * \r
 264    * @param id\r
 265    *          DOCUMENT ME!\r
 266    */\r
 267   public void setPDBId(Vector ids);\r
 268 \r
 269   /**\r
 270    * DOCUMENT ME!\r
 271    * \r
 272    * @return DOCUMENT ME!\r
 273    */\r
 274   public Vector getPDBId();\r
 275 \r
 276   /**\r
 277    * add entry to the vector of PDBIds, if it isn't in the list already\r
 278    * \r
 279    * @param entry\r
 280    */\r
 281   public void addPDBId(PDBEntry entry);\r
 282 \r
 283   /**\r
 284    * update the list of PDBEntrys to include any DBRefEntrys citing structural\r
 285    * databases\r
 286    * \r
 287    * @return true if PDBEntry list was modified\r
 288    */\r
 289   public boolean updatePDBIds();\r
 290 \r
 291   public String getVamsasId();\r
 292 \r
 293   public void setVamsasId(String id);\r
 294 \r
 295   public void setDBRef(DBRefEntry[] dbs);\r
 296 \r
 297   public DBRefEntry[] getDBRef();\r
 298 \r
 299   /**\r
 300    * add the given entry to the list of DBRefs for this sequence, or replace a\r
 301    * similar one if entry contains a map object and the existing one doesnt.\r
 302    * \r
 303    * @param entry\r
 304    */\r
 305   public void addDBRef(DBRefEntry entry);\r
 306 \r
 307   public void addSequenceFeature(SequenceFeature sf);\r
 308 \r
 309   public void deleteFeature(SequenceFeature sf);\r
 310 \r
 311   public void setDatasetSequence(SequenceI seq);\r
 312 \r
 313   public SequenceI getDatasetSequence();\r
 314 \r
 315   public AlignmentAnnotation[] getAnnotation();\r
 316 \r
 317   public void addAlignmentAnnotation(AlignmentAnnotation annotation);\r
 318 \r
 319   public void removeAlignmentAnnotation(AlignmentAnnotation annotation);\r
 320 \r
 321   /**\r
 322    * Derive a sequence (using this one's dataset or as the dataset)\r
 323    * \r
 324    * @return duplicate sequence with valid dataset sequence\r
 325    */\r
 326   public SequenceI deriveSequence();\r
 327 \r
 328   /**\r
 329    * set the array of associated AlignmentAnnotation for this sequenceI\r
 330    * \r
 331    * @param revealed\r
 332    */\r
 333   public void setAlignmentAnnotation(AlignmentAnnotation[] annotation);\r
 334 \r
 335   /**\r
 336    * Get one or more alignment annotations with a particular label.\r
 337    * \r
 338    * @param label\r
 339    *          string which each returned annotation must have as a label.\r
 340    * @return null or array of annotations.\r
 341    */\r
 342   public AlignmentAnnotation[] getAnnotation(String label);\r
 343 \r
 344   /**\r
 345    * create a new dataset sequence (if necessary) for this sequence and sets\r
 346    * this sequence to refer to it. This call will move any features or\r
 347    * references on the sequence onto the dataset. It will also make a duplicate\r
 348    * of existing annotation rows for the dataset sequence, rather than relocate\r
 349    * them in order to preserve external references (since 2.8.2).\r
 350    * \r
 351    * @return dataset sequence for this sequence\r
 352    */\r
 353   public SequenceI createDatasetSequence();\r
 354 \r
 355   /**\r
 356    * Transfer any database references or annotation from entry under a sequence\r
 357    * mapping. <br/>\r
 358    * <strong>Note: DOES NOT transfer sequence associated alignment\r
 359    * annotation </strong><br/>\r
 360    * \r
 361    * @param entry\r
 362    * @param mp\r
 363    *          null or mapping from entry's numbering to local start/end\r
 364    */\r
 365   public void transferAnnotation(SequenceI entry, Mapping mp);\r
 366 \r
 367   /**\r
 368    * @param index\r
 369    *          The sequence index in the MSA\r
 370    */\r
 371   public void setIndex(int index);\r
 372 \r
 373   /**\r
 374    * @return The index of the sequence in the alignment\r
 375    */\r
 376   public int getIndex();\r
 377 \r
 378   /**\r
 379    * @return The RNA of the sequence in the alignment\r
 380    */\r
 381 \r
 382   public RNA getRNA();\r
 383 \r
 384   /**\r
 385    * @param rna\r
 386    *          The RNA.\r
 387    */\r
 388   public void setRNA(RNA rna);\r
 389 \r
 390 }\r