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 import jalview.util.Platform;
  27
  28 import java.util.ArrayList;
  29 import java.util.Arrays;
  30 import java.util.HashSet;
  31 import java.util.List;
  32 import java.util.Map;
  33 import java.util.Map.Entry;
  34 import java.util.Set;
  35 import java.util.TreeMap;
  36
  37 import intervalstore.api.IntervalI;
  38
  39 /**
  40  * A class that stores sequence features in a way that supports efficient
  41  * querying by type and location (overlap). Intended for (but not limited to)
  42  * storage of features for one sequence.
  43  *
  44  * @author gmcarstairs
  45  *
  46  */
  47 public class SequenceFeatures implements SequenceFeaturesI
  48 {
  49
  50   /*
  51    * map from feature type to structured store of features for that type
  52    * null types are permitted (but not a good idea!)
  53    */
  54   private Map<String, FeatureStoreI> featureStore;
  55
  56   /**
  57    * Constructor
  58    */
  59   public SequenceFeatures()
  60   {
  61     /*
  62      * use a TreeMap so that features are returned in alphabetical order of type
  63      * ? wrap as a synchronized map for add and delete operations
  64      */
  65     // featureStore = Collections
  66     // .synchronizedSortedMap(new TreeMap<String, FeatureStoreI>());
  67     featureStore = new TreeMap<>();
  68   }
  69
  70   /**
  71    * Constructor given a list of features
  72    */
  73   public SequenceFeatures(List<SequenceFeature> features)
  74   {
  75     this();
  76     if (features != null)
  77     {
  78       for (SequenceFeature feature : features)
  79       {
  80         add(feature);
  81       }
  82     }
  83   }
  84
  85   /**
  86    * {@inheritDoc}
  87    */
  88   @Override
  89   public boolean add(SequenceFeature sf)
  90   {
  91     String type = sf.getType();
  92     if (type == null)
  93     {
  94       System.err.println("Feature type may not be null: " + sf.toString());
  95       return false;
  96     }
  97
  98     if (featureStore.get(type) == null)
  99     {
 100       featureStore.put(type, newFeatureStore());
 101     }
 102     return featureStore.get(type).addFeature(sf);
 103   }
 104
 105   private FeatureStoreI newFeatureStore()
 106   {
 107     return (//
 108     Platform.isJS()//
 109             ? new FeatureStoreJS()
 110             : new FeatureStoreImpl());
 111   }
 112
 113   /**
 114    * {@inheritDoc}
 115    */
 116   @Override
 117   public List<SequenceFeature> findFeatures(int from, int to,
 118           String... type)
 119   {
 120     List<SequenceFeature> result = new ArrayList<>();
 121     for (FeatureStoreI featureSet : varargToTypes(type))
 122     {
 123       // System.err.println("SF findFeature " + System.currentTimeMillis()
 124       // + " " + from + " " + to + " "
 125       // + featureSet.getPositionalFeatures().get(0).type);
 126       //
 127       result.addAll(featureSet.findOverlappingFeatures(from, to, null));
 128     }
 129     return result;
 130   }
 131
 132   /**
 133    * {@inheritDoc}
 134    */
 135   @Override
 136   public List<SequenceFeature> getAllFeatures(String... type)
 137   {
 138     List<SequenceFeature> result = new ArrayList<>();
 139
 140     result.addAll(getPositionalFeatures(type));
 141
 142     result.addAll(getNonPositionalFeatures());
 143
 144     return result;
 145   }
 146
 147   /**
 148    * {@inheritDoc}
 149    */
 150   @Override
 151   public List<SequenceFeature> getFeaturesByOntology(String... ontologyTerm)
 152   {
 153     if (ontologyTerm == null || ontologyTerm.length == 0)
 154     {
 155       return new ArrayList<>();
 156     }
 157
 158     Set<String> featureTypes = getFeatureTypes(ontologyTerm);
 159     if (featureTypes.isEmpty())
 160     {
 161       /*
 162        * no features of the specified type or any sub-type
 163        */
 164       return new ArrayList<>();
 165     }
 166
 167     return getAllFeatures(
 168             featureTypes.toArray(new String[featureTypes.size()]));
 169   }
 170
 171   /**
 172    * {@inheritDoc}
 173    */
 174   @Override
 175   public int getFeatureCount(boolean positional, String... type)
 176   {
 177     int result = 0;
 178
 179     for (FeatureStoreI featureSet : varargToTypes(type))
 180     {
 181       result += featureSet.getFeatureCount(positional);
 182     }
 183     return result;
 184   }
 185
 186   /**
 187    * {@inheritDoc}
 188    */
 189   @Override
 190   public int getTotalFeatureLength(String... type)
 191   {
 192     int result = 0;
 193
 194     for (FeatureStoreI featureSet : varargToTypes(type))
 195     {
 196       result += featureSet.getTotalFeatureLength();
 197     }
 198     return result;
 199   }
 200
 201   /**
 202    * {@inheritDoc}
 203    */
 204   @Override
 205   public List<SequenceFeature> getPositionalFeatures(String... type)
 206   {
 207     List<SequenceFeature> result = new ArrayList<>();
 208
 209     for (FeatureStoreI featureSet : varargToTypes(type))
 210     {
 211       featureSet.getPositionalFeatures(result);
 212     }
 213     return result;
 214   }
 215
 216   /**
 217    * A convenience method that converts a vararg for feature types to an
 218    * Iterable over matched feature sets in key order
 219    *
 220    * @param type
 221    * @return
 222    */
 223   protected Iterable<FeatureStoreI> varargToTypes(String... type)
 224   {
 225     if (type == null || type.length == 0)
 226     {
 227       /*
 228        * no vararg parameter supplied - return all
 229        */
 230       return featureStore.values();
 231     }
 232
 233     List<FeatureStoreI> types = new ArrayList<>();
 234     List<String> args = Arrays.asList(type);
 235     for (Entry<String, FeatureStoreI> featureType : featureStore.entrySet())
 236     {
 237       if (args.contains(featureType.getKey()))
 238       {
 239         types.add(featureType.getValue());
 240       }
 241     }
 242     return types;
 243   }
 244
 245   /**
 246    * {@inheritDoc}
 247    */
 248   @Override
 249   public List<SequenceFeature> getContactFeatures(String... type)
 250   {
 251     List<SequenceFeature> result = new ArrayList<>();
 252
 253     for (FeatureStoreI featureSet : varargToTypes(type))
 254     {
 255       featureSet.getContactFeatures(result);
 256     }
 257     return result;
 258   }
 259
 260   /**
 261    * {@inheritDoc}
 262    */
 263   @Override
 264   public List<SequenceFeature> getNonPositionalFeatures(String... type)
 265   {
 266     List<SequenceFeature> result = new ArrayList<>();
 267
 268     for (FeatureStoreI featureSet : varargToTypes(type))
 269     {
 270       featureSet.getNonPositionalFeatures(result);
 271     }
 272     return result;
 273   }
 274
 275   /**
 276    * {@inheritDoc}
 277    */
 278   @Override
 279   public boolean delete(SequenceFeature sf)
 280   {
 281     for (FeatureStoreI featureSet : featureStore.values())
 282     {
 283       if (featureSet.delete(sf))
 284       {
 285         return true;
 286       }
 287     }
 288     return false;
 289   }
 290
 291   /**
 292    * {@inheritDoc}
 293    */
 294   @Override
 295   public boolean hasFeatures()
 296   {
 297     for (FeatureStoreI featureSet : featureStore.values())
 298     {
 299       if (!featureSet.isEmpty())
 300       {
 301         return true;
 302       }
 303     }
 304     return false;
 305   }
 306
 307   /**
 308    * {@inheritDoc}
 309    */
 310   @Override
 311   public Set<String> getFeatureGroups(boolean positionalFeatures,
 312           String... type)
 313   {
 314     Set<String> groups = new HashSet<>();
 315
 316     for (FeatureStoreI featureSet : varargToTypes(type))
 317     {
 318       groups.addAll(featureSet.getFeatureGroups(positionalFeatures));
 319     }
 320
 321     return groups;
 322   }
 323
 324   /**
 325    * {@inheritDoc}
 326    */
 327   @Override
 328   public Set<String> getFeatureTypesForGroups(boolean positionalFeatures,
 329           String... groups)
 330   {
 331     Set<String> result = new HashSet<>();
 332
 333     for (Entry<String, FeatureStoreI> featureType : featureStore.entrySet())
 334     {
 335       Set<String> featureGroups = featureType.getValue()
 336               .getFeatureGroups(positionalFeatures);
 337       for (String group : groups)
 338       {
 339         if (featureGroups.contains(group))
 340         {
 341           /*
 342            * yes this feature type includes one of the query groups
 343            */
 344           result.add(featureType.getKey());
 345           break;
 346         }
 347       }
 348     }
 349
 350     return result;
 351   }
 352
 353   /**
 354    * {@inheritDoc}
 355    */
 356   @Override
 357   public Set<String> getFeatureTypes(String... soTerm)
 358   {
 359     Set<String> types = new HashSet<>();
 360     for (Entry<String, FeatureStoreI> entry : featureStore.entrySet())
 361     {
 362       String type = entry.getKey();
 363       if (!entry.getValue().isEmpty() && isOntologyTerm(type, soTerm))
 364       {
 365         types.add(type);
 366       }
 367     }
 368     return types;
 369   }
 370
 371   /**
 372    * Answers true if the given type matches one of the specified terms (or is a
 373    * sub-type of one in the Sequence Ontology), or if no terms are supplied.
 374    * Answers false if filter terms are specified and the given term does not
 375    * match any of them.
 376    *
 377    * @param type
 378    * @param soTerm
 379    * @return
 380    */
 381   protected boolean isOntologyTerm(String type, String... soTerm)
 382   {
 383     if (soTerm == null || soTerm.length == 0)
 384     {
 385       return true;
 386     }
 387     SequenceOntologyI so = SequenceOntologyFactory.getSequenceOntology();
 388     for (String term : soTerm)
 389     {
 390       if (type.equals(term) || so.isA(type, term))
 391       {
 392         return true;
 393       }
 394     }
 395     return false;
 396   }
 397
 398   /**
 399    * {@inheritDoc}
 400    */
 401   @Override
 402   public float getMinimumScore(String type, boolean positional)
 403   {
 404     return featureStore.containsKey(type)
 405             ? featureStore.get(type).getMinimumScore(positional)
 406             : Float.NaN;
 407   }
 408
 409   /**
 410    * {@inheritDoc}
 411    */
 412   @Override
 413   public float getMaximumScore(String type, boolean positional)
 414   {
 415     return featureStore.containsKey(type)
 416             ? featureStore.get(type).getMaximumScore(positional)
 417             : Float.NaN;
 418   }
 419
 420   /**
 421    * A convenience method to sort features by start position ascending (if on
 422    * forward strand), or end position descending (if on reverse strand)
 423    *
 424    * @param features
 425    * @param forwardStrand
 426    */
 427   public static void sortFeatures(List<? extends IntervalI> features,
 428           final boolean forwardStrand)
 429   {
 430     IntervalI.sortIntervals(features, forwardStrand);
 431   }
 432
 433   /**
 434    * {@inheritDoc} This method is 'semi-optimised': it only inspects features
 435    * for types that include the specified group, but has to inspect every
 436    * feature of those types for matching feature group. This is efficient unless
 437    * a sequence has features that share the same type but are in different
 438    * groups - an unlikely case.
 439    * <p>
 440    * For example, if RESNUM feature is created with group = PDBID, then features
 441    * would only be retrieved for those sequences associated with the target
 442    * PDBID (group).
 443    */
 444   @Override
 445   public List<SequenceFeature> getFeaturesForGroup(boolean positional,
 446           String group, String... type)
 447   {
 448     List<SequenceFeature> result = new ArrayList<>();
 449     for (FeatureStoreI featureSet : varargToTypes(type))
 450     {
 451       if (featureSet.getFeatureGroups(positional).contains(group))
 452       {
 453         result.addAll(featureSet.getFeaturesForGroup(positional, group));
 454       }
 455     }
 456     return result;
 457   }
 458
 459   /**
 460    * {@inheritDoc}
 461    */
 462   @Override
 463   public boolean shiftFeatures(int fromPosition, int shiftBy)
 464   {
 465     boolean modified = false;
 466     for (FeatureStoreI fs : featureStore.values())
 467     {
 468       modified |= fs.shiftFeatures(fromPosition, shiftBy);
 469     }
 470     return modified;
 471   }
 472
 473   /**
 474    * {@inheritDoc}
 475    */
 476   @Override
 477   public void deleteAll()
 478   {
 479     featureStore.clear();
 480   }
 481
 482   /**
 483    * Simplified find for features associated with a given position.
 484    *
 485    * JavaScript set to not use IntervalI, but easily testable by setting false
 486    * to true in javadoc
 487    *
 488    * FeatureRenderer has checked already that featureStore does contain type.
 489    *
 490    * @author Bob Hanson 2019.07.30
 491    */
 492   @Override
 493   public List<SequenceFeature> findFeatures(int pos, String type,
 494           List<SequenceFeature> list)
 495   {
 496     FeatureStoreI fs = featureStore.get(type);
 497     return fs.findOverlappingFeatures(pos, pos, list);
 498   }
 499
 500   // Chrome; developer console closed
 501
 502   // BH 2019.08.01 useIntervalStore true, redraw false:
 503   // Platform: timer mark 13.848 0.367 overviewrender 16000 pixels row:14
 504   // Platform: timer mark 15.391 0.39 overviewrender 16000 pixels row:14
 505   // Platform: timer mark 16.498 0.39 overviewrender 16000 pixels row:14
 506   // Platform: timer mark 17.596 0.401 overviewrender 16000 pixels row:14
 507   // Platform: timer mark 18.738 0.363 overviewrender 16000 pixels row:14
 508   // Platform: timer mark 19.659 0.358 overviewrender 16000 pixels row:14
 509   // Platform: timer mark 20.737 0.359 overviewrender 16000 pixels row:14
 510   // Platform: timer mark 21.797 0.391 overviewrender 16000 pixels row:14
 511   // Platform: timer mark 22.851 0.361 overviewrender 16000 pixels row:14
 512   // Platform: timer mark 24.019 0.395 overviewrender 16000 pixels row:14
 513
 514   // BH 2019.08.01 useIntervalStore false, redraw false:
 515   // Platform: timer mark 19.011 0.181 overviewrender 16000 pixels row:14
 516   // Platform: timer mark 20.311 0.183 overviewrender 16000 pixels row:14
 517   // Platform: timer mark 21.368 0.175 overviewrender 16000 pixels row:14
 518   // Platform: timer mark 22.347 0.178 overviewrender 16000 pixels row:14
 519   // Platform: timer mark 23.605 0.216 overviewrender 16000 pixels row:14
 520   // Platform: timer mark 24.836 0.191 overviewrender 16000 pixels row:14
 521   // Platform: timer mark 26.016 0.181 overviewrender 16000 pixels row:14
 522   // Platform: timer mark 27.278 0.178 overviewrender 16000 pixels row:14
 523   // Platform: timer mark 28.158 0.181 overviewrender 16000 pixels row:14
 524   // Platform: timer mark 29.227 0.196 overviewrender 16000 pixels row:14
 525   // Platform: timer mark 30.1 0.171 overviewrender 16000 pixels row:14
 526   // Platform: timer mark 31.684 0.196 overviewrender 16000 pixels row:14
 527   // Platform: timer mark 32.779 0.18 overviewrender 16000 pixels row:14
 528   // Platform: timer mark 52.355 0.185 overviewrender 16000 pixels row:14
 529   // Platform: timer mark 53.829 0.186 overviewrender 16000 pixels row:14
 530
 531   /**
 532    * @author Bob Hanson 2019.08.01
 533    */
 534   @Override
 535   public boolean hasFeatures(String type)
 536   {
 537     return featureStore.containsKey(type);
 538   }
 539
 540 }