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.Collections;
  31 import java.util.HashSet;
  32 import java.util.List;
  33 import java.util.Map;
  34 import java.util.Map.Entry;
  35 import java.util.Set;
  36 import java.util.TreeMap;
  37
  38 import intervalstore.api.IntervalI;
  39
  40 /**
  41  * A class that stores sequence features in a way that supports efficient
  42  * querying by type and location (overlap). Intended for (but not limited to)
  43  * storage of features for one sequence.
  44  *
  45  * @author gmcarstairs
  46  *
  47  */
  48 public class SequenceFeatures implements SequenceFeaturesI
  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, FeatureStore> 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, FeatureStore>());
  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, new FeatureStore());
 101     }
 102     return featureStore.get(type).addFeature(sf);
 103   }
 104
 105   /**
 106    * {@inheritDoc}
 107    */
 108   @Override
 109   public List<SequenceFeature> findFeatures(int from, int to,
 110           String... type)
 111   {
 112     List<SequenceFeature> result = new ArrayList<>();
 113     for (FeatureStore featureSet : varargToTypes(type))
 114     {
 115       featureSet.findFeatures(from, to, result);
 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(
 156             featureTypes.toArray(new String[featureTypes.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       featureSet.getPositionalFeatures(result);
 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 in key order
 207    *
 208    * @param type
 209    * @return
 210    */
 211   protected Iterable<FeatureStore> varargToTypes(String... type)
 212   {
 213     if (type == null || type.length == 0)
 214     {
 215       /*
 216        * no vararg parameter supplied - return all
 217        */
 218       return featureStore.values();
 219     }
 220
 221     List<FeatureStore> types = new ArrayList<>();
 222     List<String> args = Arrays.asList(type);
 223     for (Entry<String, FeatureStore> featureType : featureStore.entrySet())
 224     {
 225       if (args.contains(featureType.getKey()))
 226       {
 227         types.add(featureType.getValue());
 228       }
 229     }
 230     return types;
 231   }
 232
 233   /**
 234    * {@inheritDoc}
 235    */
 236   @Override
 237   public List<SequenceFeature> getContactFeatures(String... type)
 238   {
 239     List<SequenceFeature> result = new ArrayList<>();
 240
 241     for (FeatureStore featureSet : varargToTypes(type))
 242     {
 243       featureSet.getContactFeatures(result);
 244     }
 245     return result;
 246   }
 247
 248   /**
 249    * {@inheritDoc}
 250    */
 251   @Override
 252   public List<SequenceFeature> getNonPositionalFeatures(String... type)
 253   {
 254     List<SequenceFeature> result = new ArrayList<>();
 255
 256     for (FeatureStore featureSet : varargToTypes(type))
 257     {
 258       featureSet.getNonPositionalFeatures(result);
 259     }
 260     return result;
 261   }
 262
 263   /**
 264    * {@inheritDoc}
 265    */
 266   @Override
 267   public boolean delete(SequenceFeature sf)
 268   {
 269     for (FeatureStore featureSet : featureStore.values())
 270     {
 271       if (featureSet.delete(sf))
 272       {
 273         return true;
 274       }
 275     }
 276     return false;
 277   }
 278
 279   /**
 280    * {@inheritDoc}
 281    */
 282   @Override
 283   public boolean hasFeatures()
 284   {
 285     for (FeatureStore featureSet : featureStore.values())
 286     {
 287       if (!featureSet.isEmpty())
 288       {
 289         return true;
 290       }
 291     }
 292     return false;
 293   }
 294
 295   /**
 296    * {@inheritDoc}
 297    */
 298   @Override
 299   public Set<String> getFeatureGroups(boolean positionalFeatures,
 300           String... type)
 301   {
 302     // BH 2020.03.21 This is the set that orders the list of groups
 303     // at the top of the FeatureSettings panel.
 304     Set<String> groups = Platform.getJavaOrderedHashSet();
 305
 306     for (FeatureStore featureSet : varargToTypes(type))
 307     {
 308       groups.addAll(featureSet.getFeatureGroups(positionalFeatures));
 309     }
 310
 311     return groups;
 312   }
 313
 314   /**
 315    * {@inheritDoc}
 316    */
 317   @Override
 318   public Set<String> getFeatureTypesForGroups(boolean positionalFeatures,
 319           String... groups)
 320   {
 321     // BH 2020.03.21 This set is the one that sets the initial ordering for
 322     // feature rendering. We set it to new HashSet<>(16,0.75) to force it to
 323     // be backed by a Java hash-ordered HashMap instead of a JavaScript Map.
 324     Set<String> result = Platform.getJavaOrderedHashSet();
 325
 326     for (Entry<String, FeatureStore> featureType : featureStore.entrySet())
 327     {
 328       Set<String> featureGroups = featureType.getValue()
 329               .getFeatureGroups(positionalFeatures);
 330       for (String group : groups)
 331       {
 332         if (featureGroups.contains(group))
 333         {
 334           /*
 335            * yes this feature type includes one of the query groups
 336            */
 337           result.add(featureType.getKey());
 338           break;
 339         }
 340       }
 341     }
 342
 343     return result;
 344   }
 345
 346   /**
 347    * {@inheritDoc}
 348    */
 349   @Override
 350   public Set<String> getFeatureTypes(String... soTerm)
 351   {
 352     Set<String> types = new HashSet<>(15, 0.75f);
 353     for (Entry<String, FeatureStore> entry : featureStore.entrySet())
 354     {
 355       String type = entry.getKey();
 356       if (!entry.getValue().isEmpty() && isOntologyTerm(type, soTerm))
 357       {
 358         types.add(type);
 359       }
 360     }
 361     return types;
 362   }
 363
 364   /**
 365    * Answers true if the given type matches one of the specified terms (or is a
 366    * sub-type of one in the Sequence Ontology), or if no terms are supplied.
 367    * Answers false if filter terms are specified and the given term does not
 368    * match any of them.
 369    *
 370    * @param type
 371    * @param soTerm
 372    * @return
 373    */
 374   protected boolean isOntologyTerm(String type, String... soTerm)
 375   {
 376     if (soTerm == null || soTerm.length == 0)
 377     {
 378       return true;
 379     }
 380     SequenceOntologyI so = SequenceOntologyFactory.getSequenceOntology();
 381     for (String term : soTerm)
 382     {
 383       if (type.equals(term) || so.isA(type, term))
 384       {
 385         return true;
 386       }
 387     }
 388     return false;
 389   }
 390
 391   /**
 392    * {@inheritDoc}
 393    */
 394   @Override
 395   public float getMinimumScore(String type, boolean positional)
 396   {
 397     return featureStore.containsKey(type)
 398             ? featureStore.get(type).getMinimumScore(positional)
 399             : Float.NaN;
 400   }
 401
 402   /**
 403    * {@inheritDoc}
 404    */
 405   @Override
 406   public float getMaximumScore(String type, boolean positional)
 407   {
 408     return featureStore.containsKey(type)
 409             ? featureStore.get(type).getMaximumScore(positional)
 410             : Float.NaN;
 411   }
 412
 413   /**
 414    * A convenience method to sort features by start position ascending (if on
 415    * forward strand), or end position descending (if on reverse strand)
 416    *
 417    * @param features
 418    * @param forwardStrand
 419    */
 420   public static void sortFeatures(List<? extends IntervalI> features,
 421           final boolean forwardStrand)
 422   {
 423     Collections.sort(features,
 424             forwardStrand ? IntervalI.COMPARE_BEGIN_ASC
 425                     : IntervalI.COMPARE_END_DESC);
 426   }
 427
 428   /**
 429    * {@inheritDoc} This method is 'semi-optimised': it only inspects features
 430    * for types that include the specified group, but has to inspect every
 431    * feature of those types for matching feature group. This is efficient unless
 432    * a sequence has features that share the same type but are in different
 433    * groups - an unlikely case.
 434    * <p>
 435    * For example, if RESNUM feature is created with group = PDBID, then features
 436    * would only be retrieved for those sequences associated with the target
 437    * PDBID (group).
 438    */
 439   @Override
 440   public List<SequenceFeature> getFeaturesForGroup(boolean positional,
 441           String group, String... type)
 442   {
 443     List<SequenceFeature> result = new ArrayList<>();
 444     for (FeatureStore featureSet : varargToTypes(type))
 445     {
 446       if (featureSet.getFeatureGroups(positional).contains(group))
 447       {
 448         result.addAll(featureSet.getFeaturesForGroup(positional, group));
 449       }
 450     }
 451     return result;
 452   }
 453
 454   /**
 455    * {@inheritDoc}
 456    */
 457   @Override
 458   public boolean shiftFeatures(int fromPosition, int shiftBy)
 459   {
 460     boolean modified = false;
 461     for (FeatureStore fs : featureStore.values())
 462     {
 463       modified |= fs.shiftFeatures(fromPosition, shiftBy);
 464     }
 465     return modified;
 466   }
 467
 468   /**
 469    * {@inheritDoc}
 470    */
 471   @Override
 472   public void deleteAll()
 473   {
 474     featureStore.clear();
 475   }
 476
 477   @Override
 478   public List<SequenceFeature> findFeatures(int pos, String type,
 479           List<SequenceFeature> list)
 480   {
 481     FeatureStore fs = featureStore.get(type);
 482     if (fs == null)
 483     {
 484       return list == null ? new ArrayList<>() : list;
 485     }
 486     return fs.findFeatures(pos, pos, list);
 487   }
 488
 489   @Override
 490   public boolean hasFeatures(String type)
 491   {
 492     return featureStore.containsKey(type)
 493             && !featureStore.get(type).isEmpty();
 494   }
 495
 496 }