X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=src%2Fjalview%2Fdatamodel%2FSequenceI.java;h=38be37f1f72af433fc3605e8f80ce7c0d12d1996;hb=88694463a2aea303694231603b61970f72a5a259;hp=46669ae037829c70f142e37799cd8c3a9e3e9db2;hpb=393316810f2e54f069863145fb35102c6e889d50;p=jalview.git diff --git a/src/jalview/datamodel/SequenceI.java b/src/jalview/datamodel/SequenceI.java index 46669ae..38be37f 100755 --- a/src/jalview/datamodel/SequenceI.java +++ b/src/jalview/datamodel/SequenceI.java @@ -1,6 +1,6 @@ /* - * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8.2) - * Copyright (C) 2014 The Jalview Authors + * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$) + * Copyright (C) $$Year-Rel$$ The Jalview Authors * * This file is part of Jalview. * @@ -20,18 +20,22 @@ */ package jalview.datamodel; +import jalview.datamodel.features.SequenceFeaturesI; + +import java.util.BitSet; import java.util.List; import java.util.Vector; import fr.orsay.lri.varna.models.rna.RNA; /** - * DOCUMENT ME! + * Methods for manipulating a sequence, its metadata and related annotation in + * an alignment or dataset. * * @author $author$ * @version $Revision$ */ -public interface SequenceI +public interface SequenceI extends ASequenceI { /** * Set the display name for the sequence @@ -134,12 +138,13 @@ public interface SequenceI public char[] getSequence(int start, int end); /** - * create a new sequence object from start to end of this sequence + * create a new sequence object with a subsequence of this one but sharing the + * same dataset sequence * * @param start - * int index for start position + * int index for start position (base 0, inclusive) * @param end - * int index for end position + * int index for end position (base 0, exclusive) * * @return SequenceI * @note implementations may use getSequence to get the sequence data @@ -147,12 +152,12 @@ public interface SequenceI public SequenceI getSubSequence(int start, int end); /** - * DOCUMENT ME! + * get the i'th character in this sequence's local reference frame (ie from + * 0-number of characters lying from start-end) * * @param i - * DOCUMENT ME! - * - * @return DOCUMENT ME! + * index + * @return character or ' ' */ public char getCharAt(int i); @@ -172,8 +177,7 @@ public interface SequenceI public String getDescription(); /** - * Return the alignment column for a sequence position * Return the alignment - * position for a sequence position + * Return the alignment column (from 1..) for a sequence position * * @param pos * lying from start to end @@ -188,16 +192,41 @@ public interface SequenceI public int findIndex(int pos); /** - * Returns the sequence position for an alignment position + * Returns the sequence position for an alignment position. * * @param i * column index in alignment (from 0.. + * Example: + * >Seq/8-13 + * ABC--DE-F + * findPositions(1, 4) returns Range(9, 9) // B only + * findPositions(3, 4) returns null // all gaps + * findPositions(2, 6) returns Range(10, 12) // CDE + * findPositions(3, 7) returns Range(11,12) // DE + * + * + * @param fromCol + * first aligned column position (base 0, inclusive) + * @param toCol + * last aligned column position (base 0, inclusive) + * + * @return + */ + public Range findPositions(int fromCol, int toCol); + + /** * Returns an int array where indices correspond to each residue in the * sequence and the element value gives its position in the alignment * @@ -216,13 +245,22 @@ public interface SequenceI public int[] findPositionMap(); /** + * Answers true if the sequence is composed of amino acid characters. Note + * that implementations may use heuristic methods which are not guaranteed to + * give the biologically 'right' answer. + * + * @return + */ + public boolean isProtein(); + + /** * Delete a range of aligned sequence columns, creating a new dataset sequence * if necessary and adjusting start and end positions accordingly. * * @param i - * first column in range to delete + * first column in range to delete (inclusive) * @param j - * last column in range to delete + * last column in range to delete (exclusive) */ public void deleteChars(int i, int j); @@ -230,36 +268,47 @@ public interface SequenceI * DOCUMENT ME! * * @param i - * DOCUMENT ME! + * alignment column number * @param c - * DOCUMENT ME! + * character to insert */ public void insertCharAt(int i, char c); /** - * DOCUMENT ME! + * insert given character at alignment column position * - * @param i - * DOCUMENT ME! - * @param c - * DOCUMENT ME! + * @param position + * alignment column number + * @param count + * length of insert + * @param ch + * character to insert */ - public void insertCharAt(int i, int length, char c); + public void insertCharAt(int position, int count, char ch); /** - * DOCUMENT ME! + * Answers a list of all sequence features associated with this sequence. The + * list may be held by the sequence's dataset sequence if that is defined. * - * @return DOCUMENT ME! + * @return hard reference to array */ - public SequenceFeature[] getSequenceFeatures(); + public List getSequenceFeatures(); /** - * DOCUMENT ME! + * Answers the object holding features for the sequence * - * @param v - * DOCUMENT ME! + * @return + */ + SequenceFeaturesI getFeatures(); + + /** + * Replaces the sequence features associated with this sequence with the given + * features. If this sequence has a dataset sequence, then this method will + * update the dataset sequence's features instead. + * + * @param features */ - public void setSequenceFeatures(SequenceFeature[] features); + public void setSequenceFeatures(List features); /** * DOCUMENT ME! @@ -267,21 +316,28 @@ public interface SequenceI * @param id * DOCUMENT ME! */ - public void setPDBId(Vector ids); + public void setPDBId(Vector ids); /** - * DOCUMENT ME! + * Returns a list * * @return DOCUMENT ME! */ - public Vector getPDBId(); + public Vector getAllPDBEntries(); /** - * add entry to the vector of PDBIds, if it isn't in the list already + * Adds the entry to the *normalised* list of PDBIds. + * + * If a PDBEntry is passed with the same entry.getID() string as one already + * in the list, or one is added that appears to be the same but has a chain ID + * appended, then the existing PDBEntry will be updated with the new + * attributes instead, unless the entries have distinct chain codes or + * associated structure files. * * @param entry + * @return true if the entry was added, false if updated */ - public void addPDBId(PDBEntry entry); + public boolean addPDBId(PDBEntry entry); /** * update the list of PDBEntrys to include any DBRefEntrys citing structural @@ -295,9 +351,17 @@ public interface SequenceI public void setVamsasId(String id); - public void setDBRef(DBRefEntry[] dbs); + /** + * set the array of Database references for the sequence. + * + * @param dbs + * @deprecated - use is discouraged since side-effects may occur if DBRefEntry + * set are not normalised. + */ + @Deprecated + public void setDBRefs(DBRefEntry[] dbs); - public DBRefEntry[] getDBRef(); + public DBRefEntry[] getDBRefs(); /** * add the given entry to the list of DBRefs for this sequence, or replace a @@ -307,7 +371,14 @@ public interface SequenceI */ public void addDBRef(DBRefEntry entry); - public void addSequenceFeature(SequenceFeature sf); + /** + * Adds the given sequence feature and returns true, or returns false if it is + * already present on the sequence, or if the feature type is null. + * + * @param sf + * @return + */ + public boolean addSequenceFeature(SequenceFeature sf); public void deleteFeature(SequenceFeature sf); @@ -382,8 +453,8 @@ public interface SequenceI /** * Transfer any database references or annotation from entry under a sequence * mapping.
- * Note: DOES NOT transfer sequence associated alignment - * annotation
+ * Note: DOES NOT transfer sequence associated alignment annotation + *
* * @param entry * @param mp @@ -414,4 +485,54 @@ public interface SequenceI */ public void setRNA(RNA rna); + /** + * + * @return list of insertions (gap characters) in sequence + */ + public List getInsertions(); + + /** + * Given a pdbId String, return the equivalent PDBEntry if available in the + * given sequence + * + * @param pdbId + * @return + */ + public PDBEntry getPDBEntry(String pdbId); + + /** + * Get all primary database/accessions for this sequence's data. These + * DBRefEntry are expected to resolve to a valid record in the associated + * external database, either directly or via a provided 1:1 Mapping. + * + * @return just the primary references (if any) for this sequence, or an empty + * list + */ + public List getPrimaryDBRefs(); + + /** + * Returns a (possibly empty) list of sequence features that overlap the range + * from-to (inclusive), optionally restricted to one or more specified feature + * types + * + * @param from + * @param to + * @param types + * @return + */ + List findFeatures(int from, int to, String... types); + + /** + * Method to call to indicate that the sequence (characters or alignment/gaps) + * has been modified. Provided to allow any cursors on residue/column + * positions to be invalidated. + */ + void sequenceChanged(); + + /** + * + * @return BitSet corresponding to index [0,length) where Comparison.isGap() + * returns true. + */ + BitSet getInsertionsAsBits(); }