src/jalview/datamodel/features/SequenceFeaturesI.java

   1 package jalview.datamodel.features;
   2
   3 import jalview.datamodel.SequenceFeature;
   4
   5 import java.util.List;
   6 import java.util.Set;
   7
   8 public interface SequenceFeaturesI
   9 {
  10
  11   /**
  12    * Adds one sequence feature to the store, and returns true, unless the
  13    * feature is already contained in the store, in which case this method
  14    * returns false. Containment is determined by SequenceFeature.equals()
  15    * comparison. Answers false, and does not add the feature, if feature type is
  16    * null.
  17    *
  18    * @param sf
  19    */
  20   boolean add(SequenceFeature sf);
  21
  22   /**
  23    * Returns a (possibly empty) list of features, optionally restricted to
  24    * specified types, which overlap the given (inclusive) sequence position
  25    * range. Contact features are included if either start or end (or both) lie
  26    * within the range. Non-contact features which span the range are also
  27    * included.
  28    *
  29    * @param from
  30    * @param to
  31    * @param type
  32    * @return
  33    */
  34   List<SequenceFeature> findFeatures(int from, int to,
  35           String... type);
  36
  37   /**
  38    * Answers a list of all features stored, in no particular guaranteed order.
  39    * Positional features may optionally be restricted to specified types, but
  40    * all non-positional features (if any) are always returned.
  41    * <p>
  42    * To filter non-positional features by type, use
  43    * getNonPositionalFeatures(type).
  44    *
  45    * @param type
  46    * @return
  47    */
  48   List<SequenceFeature> getAllFeatures(String... type);
  49
  50   /**
  51    * Answers a list of all positional (or non-positional) features which are in
  52    * the specified feature group, optionally restricted to features of specified
  53    * types.
  54    *
  55    * @param positional
  56    *          if true returns positional features, else non-positional features
  57    * @param group
  58    *          the feature group to be matched (which may be null)
  59    * @param type
  60    *          optional feature types to filter by
  61    * @return
  62    */
  63   List<SequenceFeature> getFeaturesForGroup(boolean positional,
  64           String group, String... type);
  65
  66   /**
  67    * Answers a list of all features stored, whose type either matches one of the
  68    * given ontology terms, or is a specialisation of a term in the Sequence
  69    * Ontology. Results are returned in no particular guaranteed order.
  70    *
  71    * @param ontologyTerm
  72    * @return
  73    */
  74   List<SequenceFeature> getFeaturesByOntology(String... ontologyTerm);
  75
  76   /**
  77    * Answers the number of (positional or non-positional) features, optionally
  78    * restricted to specified feature types. Contact features are counted as 1.
  79    *
  80    * @param positional
  81    * @param type
  82    * @return
  83    */
  84   int getFeatureCount(boolean positional, String... type);
  85
  86   /**
  87    * Answers the total length of positional features, optionally restricted to
  88    * specified feature types. Contact features are counted as length 1.
  89    *
  90    * @param type
  91    * @return
  92    */
  93   int getTotalFeatureLength(String... type);
  94
  95   /**
  96    * Answers a list of all positional features, optionally restricted to
  97    * specified types, in no particular guaranteed order
  98    *
  99    * @param type
 100    * @return
 101    */
 102   List<SequenceFeature> getPositionalFeatures(
 103           String... type);
 104
 105   /**
 106    * Answers a list of all contact features, optionally restricted to specified
 107    * types, in no particular guaranteed order
 108    *
 109    * @return
 110    */
 111   List<SequenceFeature> getContactFeatures(String... type);
 112
 113   /**
 114    * Answers a list of all non-positional features, optionally restricted to
 115    * specified types, in no particular guaranteed order
 116    *
 117    * @param type
 118    *          if no type is specified, all are returned
 119    * @return
 120    */
 121   List<SequenceFeature> getNonPositionalFeatures(
 122           String... type);
 123
 124   /**
 125    * Deletes the given feature from the store, returning true if it was found
 126    * (and deleted), else false. This method makes no assumption that the feature
 127    * is in the 'expected' place in the store, in case it has been modified since
 128    * it was added.
 129    *
 130    * @param sf
 131    */
 132   boolean delete(SequenceFeature sf);
 133
 134   /**
 135    * Answers true if this store contains at least one feature, else false
 136    *
 137    * @return
 138    */
 139   boolean hasFeatures();
 140
 141   /**
 142    * Returns a set of the distinct feature groups present in the collection. The
 143    * set may include null. The boolean parameter determines whether the groups
 144    * for positional or for non-positional features are returned. The optional
 145    * type parameter may be used to restrict to groups for specified feature
 146    * types.
 147    *
 148    * @param positionalFeatures
 149    * @param type
 150    * @return
 151    */
 152   Set<String> getFeatureGroups(boolean positionalFeatures,
 153           String... type);
 154
 155   /**
 156    * Answers the set of distinct feature types for which there is at least one
 157    * feature with one of the given feature group(s). The boolean parameter
 158    * determines whether the groups for positional or for non-positional features
 159    * are returned.
 160    *
 161    * @param positionalFeatures
 162    * @param groups
 163    * @return
 164    */
 165   Set<String> getFeatureTypesForGroups(
 166           boolean positionalFeatures, String... groups);
 167
 168   /**
 169    * Answers a set of the distinct feature types for which a feature is stored.
 170    * The types may optionally be restricted to those which match, or are a
 171    * subtype of, given sequence ontology terms
 172    *
 173    * @return
 174    */
 175   Set<String> getFeatureTypes(String... soTerm);
 176
 177   /**
 178    * Answers the minimum score held for positional or non-positional features
 179    * for the specified type. This may be Float.NaN if there are no features, or
 180    * none has a non-NaN score.
 181    *
 182    * @param type
 183    * @param positional
 184    * @return
 185    */
 186   float getMinimumScore(String type, boolean positional);
 187
 188   /**
 189    * Answers the maximum score held for positional or non-positional features
 190    * for the specified type. This may be Float.NaN if there are no features, or
 191    * none has a non-NaN score.
 192    *
 193    * @param type
 194    * @param positional
 195    * @return
 196    */
 197   float getMaximumScore(String type, boolean positional);
 198
 199   /**
 200    * Adds the shift amount to the start and end of all positional features whose
 201    * start position is at or after fromPosition. Returns true if at least one
 202    * feature was shifted, else false.
 203    *
 204    * @param fromPosition
 205    * @param shiftBy
 206    */
 207   boolean shiftFeatures(int fromPosition, int shiftBy);
 208
 209   /**
 210    * Deletes all positional and non-positional features
 211    */
 212   void deleteAll();
 213 }