src/jalview/datamodel/features/SequenceFeatures.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
   4  *
   5  * This file is part of Jalview.
   6  *
   7  * Jalview is free software: you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation, either version 3
  10  * of the License, or (at your option) any later version.
  11  *
  12  * Jalview is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  19  * The Jalview Authors are detailed in the 'AUTHORS' file.
  20  */
  21 package jalview.datamodel.features;
  22
  23 import jalview.datamodel.SequenceFeature;
  24 import jalview.io.gff.SequenceOntologyFactory;
  25 import jalview.io.gff.SequenceOntologyI;
  26
  27 import java.util.ArrayList;
  28 import java.util.HashSet;
  29 import java.util.List;
  30 import java.util.Map;
  31 import java.util.Map.Entry;
  32 import java.util.Set;
  33 import java.util.TreeMap;
  34
  35 import intervalstore.api.IntervalI;
  36
  37 /**
  38  * A class that stores sequence features in a way that supports efficient
  39  * querying by type and location (overlap). Intended for (but not limited to)
  40  * storage of features for one sequence.
  41  *
  42  * @author gmcarstairs
  43  *
  44  */
  45 public class SequenceFeatures implements SequenceFeaturesI
  46 {
  47
  48   /*
  49    * map from feature type to structured store of features for that type
  50    * null types are permitted (but not a good idea!)
  51    */
  52   private Map<String, FeatureStore> featureStore;
  53
  54   /**
  55    * Constructor
  56    */
  57   public SequenceFeatures()
  58   {
  59     /*
  60      * use a TreeMap so that features are returned in alphabetical order of type
  61      * ? wrap as a synchronized map for add and delete operations
  62      */
  63     // featureStore = Collections
  64     // .synchronizedSortedMap(new TreeMap<String, FeatureStore>());
  65     featureStore = new TreeMap<>();
  66   }
  67
  68   /**
  69    * Constructor given a list of features
  70    */
  71   public SequenceFeatures(List<SequenceFeature> features)
  72   {
  73     this();
  74     if (features != null)
  75     {
  76       for (SequenceFeature feature : features)
  77       {
  78         add(feature);
  79       }
  80     }
  81   }
  82
  83   /**
  84    * {@inheritDoc}
  85    */
  86   @Override
  87   public boolean add(SequenceFeature sf)
  88   {
  89     String type = sf.getType();
  90     if (type == null)
  91     {
  92       System.err.println("Feature type may not be null: " + sf.toString());
  93       return false;
  94     }
  95
  96     if (featureStore.get(type) == null)
  97     {
  98       featureStore.put(type, new FeatureStore());
  99     }
 100     return featureStore.get(type).addFeature(sf);
 101   }
 102
 103   /**
 104    * {@inheritDoc}
 105    */
 106   @Override
 107   public List<SequenceFeature> findFeatures(int from, int to,
 108           String... type)
 109   {
 110     List<SequenceFeature> result = new ArrayList<>();
 111
 112     for (FeatureStore featureSet : varargToTypes(type))
 113     {
 114       result.addAll(featureSet.findOverlappingFeatures(from, to));
 115     }
 116
 117     return result;
 118   }
 119
 120   /**
 121    * {@inheritDoc}
 122    */
 123   @Override
 124   public List<SequenceFeature> getAllFeatures(String... type)
 125   {
 126     List<SequenceFeature> result = new ArrayList<>();
 127
 128     result.addAll(getPositionalFeatures(type));
 129
 130     result.addAll(getNonPositionalFeatures());
 131
 132     return result;
 133   }
 134
 135   /**
 136    * {@inheritDoc}
 137    */
 138   @Override
 139   public List<SequenceFeature> getFeaturesByOntology(String... ontologyTerm)
 140   {
 141     if (ontologyTerm == null || ontologyTerm.length == 0)
 142     {
 143       return new ArrayList<>();
 144     }
 145
 146     Set<String> featureTypes = getFeatureTypes(ontologyTerm);
 147     if (featureTypes.isEmpty())
 148     {
 149       /*
 150        * no features of the specified type or any sub-type
 151        */
 152       return new ArrayList<>();
 153     }
 154
 155     return getAllFeatures(featureTypes.toArray(new String[featureTypes
 156             .size()]));
 157   }
 158
 159   /**
 160    * {@inheritDoc}
 161    */
 162   @Override
 163   public int getFeatureCount(boolean positional, String... type)
 164   {
 165     int result = 0;
 166
 167     for (FeatureStore featureSet : varargToTypes(type))
 168     {
 169       result += featureSet.getFeatureCount(positional);
 170     }
 171     return result;
 172   }
 173
 174   /**
 175    * {@inheritDoc}
 176    */
 177   @Override
 178   public int getTotalFeatureLength(String... type)
 179   {
 180     int result = 0;
 181
 182     for (FeatureStore featureSet : varargToTypes(type))
 183     {
 184       result += featureSet.getTotalFeatureLength();
 185     }
 186     return result;
 187   }
 188
 189   /**
 190    * {@inheritDoc}
 191    */
 192   @Override
 193   public List<SequenceFeature> getPositionalFeatures(String... type)
 194   {
 195     List<SequenceFeature> result = new ArrayList<>();
 196
 197     for (FeatureStore featureSet : varargToTypes(type))
 198     {
 199       result.addAll(featureSet.getPositionalFeatures());
 200     }
 201     return result;
 202   }
 203
 204   /**
 205    * A convenience method that converts a vararg for feature types to an
 206    * Iterable over matched feature sets. If no types are specified, all feature
 207    * sets are returned. If one or more types are specified, feature sets for
 208    * those types are returned, preserving the order of the types.
 209    *
 210    * @param type
 211    * @return
 212    */
 213   protected Iterable<FeatureStore> varargToTypes(String... type)
 214   {
 215     if (type == null || type.length == 0)
 216     {
 217       /*
 218        * no vararg parameter supplied - return all
 219        */
 220       return featureStore.values();
 221     }
 222
 223     List<FeatureStore> types = new ArrayList<>();
 224     for (String theType : type)
 225     {
 226       if (theType != null && featureStore.containsKey(theType))
 227       {
 228         types.add(featureStore.get(theType));
 229       }
 230     }
 231     return types;
 232   }
 233
 234   /**
 235    * {@inheritDoc}
 236    */
 237   @Override
 238   public List<SequenceFeature> getContactFeatures(String... type)
 239   {
 240     List<SequenceFeature> result = new ArrayList<>();
 241
 242     for (FeatureStore featureSet : varargToTypes(type))
 243     {
 244       result.addAll(featureSet.getContactFeatures());
 245     }
 246     return result;
 247   }
 248
 249   /**
 250    * {@inheritDoc}
 251    */
 252   @Override
 253   public List<SequenceFeature> getNonPositionalFeatures(String... type)
 254   {
 255     List<SequenceFeature> result = new ArrayList<>();
 256
 257     for (FeatureStore featureSet : varargToTypes(type))
 258     {
 259       result.addAll(featureSet.getNonPositionalFeatures());
 260     }
 261     return result;
 262   }
 263
 264   /**
 265    * {@inheritDoc}
 266    */
 267   @Override
 268   public boolean delete(SequenceFeature sf)
 269   {
 270     for (FeatureStore featureSet : featureStore.values())
 271     {
 272       if (featureSet.delete(sf))
 273       {
 274         return true;
 275       }
 276     }
 277     return false;
 278   }
 279
 280   /**
 281    * {@inheritDoc}
 282    */
 283   @Override
 284   public boolean hasFeatures()
 285   {
 286     for (FeatureStore featureSet : featureStore.values())
 287     {
 288       if (!featureSet.isEmpty())
 289       {
 290         return true;
 291       }
 292     }
 293     return false;
 294   }
 295
 296   /**
 297    * {@inheritDoc}
 298    */
 299   @Override
 300   public Set<String> getFeatureGroups(boolean positionalFeatures,
 301           String... type)
 302   {
 303     Set<String> groups = new HashSet<>();
 304
 305     for (FeatureStore featureSet : varargToTypes(type))
 306     {
 307       groups.addAll(featureSet.getFeatureGroups(positionalFeatures));
 308     }
 309
 310     return groups;
 311   }
 312
 313   /**
 314    * {@inheritDoc}
 315    */
 316   @Override
 317   public Set<String> getFeatureTypesForGroups(boolean positionalFeatures,
 318           String... groups)
 319   {
 320     Set<String> result = new HashSet<>();
 321
 322     for (Entry<String, FeatureStore> featureType : featureStore.entrySet())
 323     {
 324       Set<String> featureGroups = featureType.getValue().getFeatureGroups(
 325               positionalFeatures);
 326       for (String group : groups)
 327       {
 328         if (featureGroups.contains(group))
 329         {
 330           /*
 331            * yes this feature type includes one of the query groups
 332            */
 333           result.add(featureType.getKey());
 334           break;
 335         }
 336       }
 337     }
 338
 339     return result;
 340   }
 341
 342   /**
 343    * {@inheritDoc}
 344    */
 345   @Override
 346   public Set<String> getFeatureTypes(String... soTerm)
 347   {
 348     Set<String> types = new HashSet<>();
 349     for (Entry<String, FeatureStore> entry : featureStore.entrySet())
 350     {
 351       String type = entry.getKey();
 352       if (!entry.getValue().isEmpty() && isOntologyTerm(type, soTerm))
 353       {
 354         types.add(type);
 355       }
 356     }
 357     return types;
 358   }
 359
 360   /**
 361    * Answers true if the given type matches one of the specified terms (or is a
 362    * sub-type of one in the Sequence Ontology), or if no terms are supplied.
 363    * Answers false if filter terms are specified and the given term does not
 364    * match any of them.
 365    *
 366    * @param type
 367    * @param soTerm
 368    * @return
 369    */
 370   protected boolean isOntologyTerm(String type, String... soTerm)
 371   {
 372     if (soTerm == null || soTerm.length == 0)
 373     {
 374       return true;
 375     }
 376     SequenceOntologyI so = SequenceOntologyFactory.getInstance();
 377     for (String term : soTerm)
 378     {
 379       if (type.equals(term) || so.isA(type, term))
 380       {
 381         return true;
 382       }
 383     }
 384     return false;
 385   }
 386
 387   /**
 388    * {@inheritDoc}
 389    */
 390   @Override
 391   public float getMinimumScore(String type, boolean positional)
 392   {
 393     return featureStore.containsKey(type) ? featureStore.get(type)
 394             .getMinimumScore(positional) : Float.NaN;
 395   }
 396
 397   /**
 398    * {@inheritDoc}
 399    */
 400   @Override
 401   public float getMaximumScore(String type, boolean positional)
 402   {
 403     return featureStore.containsKey(type) ? featureStore.get(type)
 404             .getMaximumScore(positional) : Float.NaN;
 405   }
 406
 407   /**
 408    * A convenience method to sort features by start position ascending (if on
 409    * forward strand), or end position descending (if on reverse strand)
 410    *
 411    * @param features
 412    * @param forwardStrand
 413    */
 414   public static void sortFeatures(List<? extends IntervalI> features,
 415           final boolean forwardStrand)
 416   {
 417     IntervalI.sortIntervals(features, forwardStrand);
 418   }
 419
 420   /**
 421    * {@inheritDoc} This method is 'semi-optimised': it only inspects features
 422    * for types that include the specified group, but has to inspect every
 423    * feature of those types for matching feature group. This is efficient unless
 424    * a sequence has features that share the same type but are in different
 425    * groups - an unlikely case.
 426    * <p>
 427    * For example, if RESNUM feature is created with group = PDBID, then features
 428    * would only be retrieved for those sequences associated with the target
 429    * PDBID (group).
 430    */
 431   @Override
 432   public List<SequenceFeature> getFeaturesForGroup(boolean positional,
 433           String group, String... type)
 434   {
 435     List<SequenceFeature> result = new ArrayList<>();
 436     for (FeatureStore featureSet : varargToTypes(type))
 437     {
 438       if (featureSet.getFeatureGroups(positional).contains(group))
 439       {
 440         result.addAll(featureSet.getFeaturesForGroup(positional, group));
 441       }
 442     }
 443     return result;
 444   }
 445
 446   /**
 447    * {@inheritDoc}
 448    */
 449   @Override
 450   public boolean shiftFeatures(int fromPosition, int shiftBy)
 451   {
 452     boolean modified = false;
 453     for (FeatureStore fs : featureStore.values())
 454     {
 455       modified |= fs.shiftFeatures(fromPosition, shiftBy);
 456     }
 457     return modified;
 458   }
 459
 460   /**
 461    * {@inheritDoc}
 462    */
 463   @Override
 464   public void deleteAll()
 465   {
 466     featureStore.clear();
 467   }
 468 }