javadoc and transferAnnotation method

[jalview.git] / src / jalview / datamodel / SequenceI.java

diff --git a/src/jalview/datamodel/SequenceI.java b/src/jalview/datamodel/SequenceI.java
index 44e74e2..da49a31 100755 (executable)
--- a/src/jalview/datamodel/SequenceI.java
+++ b/src/jalview/datamodel/SequenceI.java
@@ -29,78 +29,70 @@ import java.util.*;
 public interface SequenceI
 {
   /**
-   * DOCUMENT ME!
+   * Set the display name for the sequence
    *
-   * @param name DOCUMENT ME!
+   * @param name 
    */
   public void setName(String name);
 
   /**
-   * DOCUMENT ME!
-   *
-   * @return DOCUMENT ME!
+   * Get the display name
    */
   public String getName();
 
   /**
-   * DOCUMENT ME!
+   * Set start position of first non-gapped symbol in sequence
    *
-   * @param start DOCUMENT ME!
+   * @param start new start position
    */
   public void setStart(int start);
 
   /**
-   * DOCUMENT ME!
-   *
-   * @return DOCUMENT ME!
+   * get start position of first non-gapped residue in sequence
+   * @return 
    */
   public int getStart();
 
   /**
-   * DOCUMENT ME!
-   *
-   * @return DOCUMENT ME!
+   * get the displayed id of the sequence
+   * @return true means the id will be returned in the form DisplayName/Start-End
    */
   public String getDisplayId(boolean jvsuffix);
 
   /**
-   * DOCUMENT ME!
-   *
-   * @param end DOCUMENT ME!
+   * set end position for last residue in sequence
+   * @param end 
    */
   public void setEnd(int end);
 
   /**
-   * DOCUMENT ME!
+   * get end position for last residue in sequence
+   * getEnd()>getStart() unless sequence only consists of gap characters
    *
-   * @return DOCUMENT ME!
+   * @return 
    */
   public int getEnd();
 
   /**
-   * DOCUMENT ME!
-   *
-   * @return DOCUMENT ME!
+   * @return length of sequence including gaps
+
    */
   public int getLength();
 
   /**
-   * DOCUMENT ME!
+   * Replace the sequence with the given string
    *
-   * @param sequence DOCUMENT ME!
+   * @param sequence new sequence string
    */
   public void setSequence(String sequence);
 
   /**
-   * DOCUMENT ME!
-   *
-   * @return DOCUMENT ME!
+   * @return sequence as string
    */
   public String getSequenceAsString();
 
   /**
-   * DOCUMENT ME!
-   *
+   * get a range on the seuqence as a string
    * @param start DOCUMENT ME!
    * @param end DOCUMENT ME!
    *
@@ -116,12 +108,12 @@ public interface SequenceI
   public char[] getSequence();
 
   /**
-   * DOCUMENT ME!
+   * get stretch of sequence characters in an array
    *
-   * @param start DOCUMENT ME!
-   * @param end DOCUMENT ME!
+   * @param start absolute index into getSequence()
+   * @param end exclusive index of last position in segment to be returned.
    *
-   * @return DOCUMENT ME!
+   * @return char[max(0,end-start)];
    */
   public char[] getSequence(int start, int end);
 
@@ -182,10 +174,11 @@ public interface SequenceI
   public int[] gapMap();
 
   /**
-   * DOCUMENT ME!
+   * Delete a range of aligned sequence columns, creating a new dataset sequence if necessary
+   * and adjusting start and end positions accordingly.
    *
-   * @param i DOCUMENT ME!
-   * @param j DOCUMENT ME!
+   * @param i first column in range to delete
+   * @param j last column in range to delete
    */
   public void deleteChars(int i, int j);
 
@@ -233,7 +226,16 @@ public interface SequenceI
    */
   public Vector getPDBId();
 
+  /**
+   * add entry to the vector of PDBIds, if it isn't in the list already
+   * @param entry
+   */
   public void addPDBId(PDBEntry entry);
+  /**
+   * update the list of PDBEntrys to include any DBRefEntrys citing structural databases 
+   * @return true if PDBEntry list was modified
+   */
+  public boolean updatePDBIds();
 
   public String getVamsasId();
 
@@ -243,6 +245,12 @@ public interface SequenceI
 
   public DBRefEntry[] getDBRef();
 
+  /**
+   * add the given entry to the list of DBRefs for this sequence, 
+   * or replace a similar one if entry contains a map object 
+   * and the existing one doesnt. 
+   * @param entry
+   */
   public void addDBRef(DBRefEntry entry);
 
   public void addSequenceFeature(SequenceFeature sf);
@@ -257,6 +265,8 @@ public interface SequenceI
 
   public void addAlignmentAnnotation(AlignmentAnnotation annotation);
 
+  public void removeAlignmentAnnotation(AlignmentAnnotation annotation);
+
   /**
    * Derive a sequence (using this one's dataset or as the dataset)
    * @return duplicate sequence with valid dataset sequence
@@ -267,5 +277,26 @@ public interface SequenceI
    * @param revealed
    */
   public void setAlignmentAnnotation(AlignmentAnnotation[] annotation);
+  /**
+   * Get one or more alignment annotations with a particular label.  
+   * @param label string which each returned annotation must have as a label.
+   * @return null or array of annotations.
+   */
+  public AlignmentAnnotation[] getAnnotation(String label);
+  /**
+   * create a new dataset sequence (if necessary) 
+   * for this sequence and sets this sequence to refer to it.
+   * This call will move any features or references on the sequence onto the dataset.
+   * @return dataset sequence for this sequence
+   */
+  public SequenceI createDatasetSequence();
+  
+  /**
+   * Transfer any database references or annotation from entry
+   * under a sequence mapping.
+   * @param entry
+   * @param mp null or mapping from entry's numbering to local start/end
+   */
+  public void transferAnnotation(SequenceI entry, Mapping mp);
 
 }