X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=src%2Fjalview%2Fdatamodel%2FSequenceI.java;h=d5114e0aa9ab56e183285670118eec7a234f05ab;hb=HEAD;hp=5c779402b1f1b43267c274a1af1fa4d8f2aca142;hpb=c920b3c897f5d20d839a3fc84c2bfa097970b5d1;p=jalview.git diff --git a/src/jalview/datamodel/SequenceI.java b/src/jalview/datamodel/SequenceI.java index 5c77940..d5114e0 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,17 +20,25 @@ */ package jalview.datamodel; +import java.util.BitSet; +import java.util.Iterator; +import java.util.List; import java.util.Vector; import fr.orsay.lri.varna.models.rna.RNA; +import jalview.datamodel.Sequence.DBModList; +import jalview.datamodel.features.SequenceFeaturesI; +import jalview.util.MapList; +import jalview.ws.params.InvalidArgumentException; /** - * 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, ContactMapHolderI { /** * Set the display name for the sequence @@ -105,18 +113,20 @@ public interface SequenceI * get a range on the sequence as a string * * @param start - * position relative to start of sequence including gaps (from 0) + * (inclusive) position relative to start of sequence including gaps + * (from 0) * @param end - * position relative to start of sequence including gaps (from 0) + * (exclusive) position relative to start of sequence including gaps + * (from 0) * * @return String containing all gap and symbols in specified range */ public String getSequenceAsString(int start, int end); /** - * Get the sequence as a character array + * Answers a copy of the sequence as a character array * - * @return seqeunce and any gaps + * @return */ public char[] getSequence(); @@ -133,23 +143,26 @@ 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 + * int index for start position (base 0, inclusive) * @param end - * int + * int index for end position (base 0, exclusive) + * * @return SequenceI + * @note implementations may use getSequence to get the sequence data */ 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); @@ -169,8 +182,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 @@ -185,16 +197,31 @@ public interface SequenceI public int findIndex(int pos); /** - * Returns the sequence position for an alignment position + * Returns the sequence position for an alignment (column) position. If at a + * gap, returns the position of the next residue to the right. If beyond the + * end of the sequence, returns 1 more than the last residue position. * * @param i - * column index in alignment (from 1) + * column index in alignment (from 0.. getSequenceFeatures(); /** - * DOCUMENT ME! + * Answers the object holding features for the sequence * - * @param v - * DOCUMENT ME! + * @return */ - public void setSequenceFeatures(SequenceFeature[] features); + 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(List features); /** * DOCUMENT ME! @@ -264,21 +318,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 @@ -292,9 +353,21 @@ public interface SequenceI public void setVamsasId(String id); - public void setDBRef(DBRefEntry[] dbs); + /** + * set the array of Database references for the sequence. + * + * BH 2019.02.04 changes param to DBModlist + * + * @param dbs + * @deprecated - use is discouraged since side-effects may occur if DBRefEntry + * set are not normalised. + * @throws InvalidArgumentException + * if the is not one created by Sequence itself + */ + @Deprecated + public void setDBRefs(DBModList dbs); - public DBRefEntry[] getDBRef(); + public DBModList getDBRefs(); /** * add the given entry to the list of DBRefs for this sequence, or replace a @@ -304,7 +377,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); @@ -312,8 +392,22 @@ public interface SequenceI public SequenceI getDatasetSequence(); + /** + * Returns a new array containing this sequence's annotations, or null. + */ public AlignmentAnnotation[] getAnnotation(); + /** + * Returns true if this sequence has the given annotation (by object + * identity). + */ + public boolean hasAnnotation(AlignmentAnnotation ann); + + /** + * Add the given annotation, if not already added, and set its sequence ref to + * be this sequence. Does nothing if this sequence's annotations already + * include this annotation (by identical object reference). + */ public void addAlignmentAnnotation(AlignmentAnnotation annotation); public void removeAlignmentAnnotation(AlignmentAnnotation annotation); @@ -321,7 +415,8 @@ public interface SequenceI /** * Derive a sequence (using this one's dataset or as the dataset) * - * @return duplicate sequence with valid dataset sequence + * @return duplicate sequence and any annotation present with valid dataset + * sequence */ public SequenceI deriveSequence(); @@ -342,6 +437,28 @@ public interface SequenceI public AlignmentAnnotation[] getAnnotation(String label); /** + * Returns a (possibly empty) list of any annotations that match on given + * calcId (source) and label (type). Null values do not match. + * + * @param calcId + * @param label + */ + public List getAlignmentAnnotations(String calcId, + String label); + + /** + * Returns a (possibly empty) list of any annotations that match on given + * calcId (source), label (type) and description (observation instance). Null + * values do not match. + * + * @param calcId + * @param label + * @param description + */ + public List getAlignmentAnnotations(String calcId, + String label, String description); + + /** * 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. It will also make a duplicate @@ -355,8 +472,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 @@ -365,26 +482,122 @@ public interface SequenceI public void transferAnnotation(SequenceI entry, Mapping mp); /** - * @param index - * The sequence index in the MSA + * @return The RNA of the sequence in the alignment */ - public void setIndex(int index); + + public RNA getRNA(); /** - * @return The index of the sequence in the alignment + * @param rna + * The RNA. */ - public int getIndex(); + public void setRNA(RNA rna); /** - * @return The RNA of the sequence in the alignment + * + * @return list of insertions (gap characters) in sequence */ + public List getInsertions(); - public RNA getRNA(); + /** + * Given a pdbId String, return the equivalent PDBEntry if available in the + * given sequence + * + * @param pdbId + * @return + */ + public PDBEntry getPDBEntry(String pdbId); /** - * @param rna - * The RNA. + * 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 void setRNA(RNA rna); + public List getPrimaryDBRefs(); + + /** + * Returns a (possibly empty) list of sequence features that overlap the given + * alignment column range, optionally restricted to one or more specified + * feature types. If the range is all gaps, then features which enclose it are + * included (but not contact features). + * + * @param fromCol + * start column of range inclusive (1..) + * @param toCol + * end column of range inclusive (1..) + * @param types + * optional feature types to restrict results to + * @return + */ + List findFeatures(int fromCol, int toCol, + 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(); + + /** + * Replaces every occurrence of c1 in the sequence with c2 and returns the + * number of characters changed + * + * @param c1 + * @param c2 + */ + public int replace(char c1, char c2); + + /** + * Answers the GeneLociI, or null if not known + * + * @return + */ + GeneLociI getGeneLoci(); + + /** + * Sets the mapping to gene loci for the sequence + * + * @param speciesId + * @param assemblyId + * @param chromosomeId + * @param map + */ + void setGeneLoci(String speciesId, String assemblyId, String chromosomeId, + MapList map); + + /** + * Returns the sequence string constructed from the substrings of a sequence + * defined by the int[] ranges provided by an iterator. E.g. the iterator + * could iterate over all visible regions of the alignment + * + * @param it + * the iterator to use + * @return a String corresponding to the sequence + */ + public String getSequenceStringFromIterator(Iterator it); + + /** + * Locate the first position in this sequence which is not contained in an + * iterator region. If no such position exists, return 0 + * + * @param it + * iterator over regions + * @return first residue not contained in regions + */ + public int firstResidueOutsideIterator(Iterator it); + + public void addContactListFor(AlignmentAnnotation annotation, + ContactMatrixI cm); }