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.Arrays;
  29 import java.util.HashSet;
  30 import java.util.List;
  31 import java.util.Map;
  32 import java.util.Map.Entry;
  33 import java.util.Set;
  34 import java.util.TreeMap;
  35
  36 import intervalstore.api.IntervalI;
  37
  38 /**
  39  * A class that stores sequence features in a way that supports efficient
  40  * querying by type and location (overlap). Intended for (but not limited to)
  41  * storage of features for one sequence.
  42  *
  43  * @author gmcarstairs
  44  *
  45  */
  46 public class SequenceFeatures implements SequenceFeaturesI
  47 {
  48
  49   /*
  50    * map from feature type to structured store of features for that type
  51    * null types are permitted (but not a good idea!)
  52    */
  53   private Map<String, FeatureStore> featureStore;
  54
  55   /**
  56    * Constructor
  57    */
  58   public SequenceFeatures()
  59   {
  60     /*
  61      * use a TreeMap so that features are returned in alphabetical order of type
  62      * ? wrap as a synchronized map for add and delete operations
  63      */
  64     // featureStore = Collections
  65     // .synchronizedSortedMap(new TreeMap<String, FeatureStore>());
  66     featureStore = new TreeMap<>();
  67   }
  68
  69   /**
  70    * Constructor given a list of features
  71    */
  72   public SequenceFeatures(List<SequenceFeature> features)
  73   {
  74     this();
  75     if (features != null)
  76     {
  77       for (SequenceFeature feature : features)
  78       {
  79         add(feature);
  80       }
  81     }
  82   }
  83
  84   /**
  85    * {@inheritDoc}
  86    */
  87   @Override
  88   public boolean add(SequenceFeature sf)
  89   {
  90     String type = sf.getType();
  91     if (type == null)
  92     {
  93       System.err.println("Feature type may not be null: " + sf.toString());
  94       return false;
  95     }
  96
  97     if (featureStore.get(type) == null)
  98     {
  99       featureStore.put(type, new FeatureStore());
 100     }
 101     return featureStore.get(type).addFeature(sf);
 102   }
 103
 104   /**
 105    * {@inheritDoc}
 106    */
 107   @Override
 108   public List<SequenceFeature> findFeatures(int from, int to,
 109           String... type)
 110   {
 111     List<SequenceFeature> result = new ArrayList<>();
 112     for (FeatureStore featureSet : varargToTypes(type))
 113     {
 114       result.addAll(featureSet.findOverlappingFeatures(from, to));
 115     }
 116     return result;
 117   }
 118
 119   /**
 120    * {@inheritDoc}
 121    */
 122   @Override
 123   public List<SequenceFeature> getAllFeatures(String... type)
 124   {
 125     List<SequenceFeature> result = new ArrayList<>();
 126
 127     result.addAll(getPositionalFeatures(type));
 128
 129     result.addAll(getNonPositionalFeatures());
 130
 131     return result;
 132   }
 133
 134   /**
 135    * {@inheritDoc}
 136    */
 137   @Override
 138   public List<SequenceFeature> getFeaturesByOntology(String... ontologyTerm)
 139   {
 140     if (ontologyTerm == null || ontologyTerm.length == 0)
 141     {
 142       return new ArrayList<>();
 143     }
 144
 145     Set<String> featureTypes = getFeatureTypes(ontologyTerm);
 146     if (featureTypes.isEmpty())
 147     {
 148       /*
 149        * no features of the specified type or any sub-type
 150        */
 151       return new ArrayList<>();
 152     }
 153
 154     return getAllFeatures(featureTypes.toArray(new String[featureTypes
 155             .size()]));
 156   }
 157
 158   /**
 159    * {@inheritDoc}
 160    */
 161   @Override
 162   public int getFeatureCount(boolean positional, String... type)
 163   {
 164     int result = 0;
 165
 166     for (FeatureStore featureSet : varargToTypes(type))
 167     {
 168       result += featureSet.getFeatureCount(positional);
 169     }
 170     return result;
 171   }
 172
 173   /**
 174    * {@inheritDoc}
 175    */
 176   @Override
 177   public int getTotalFeatureLength(String... type)
 178   {
 179     int result = 0;
 180
 181     for (FeatureStore featureSet : varargToTypes(type))
 182     {
 183       result += featureSet.getTotalFeatureLength();
 184     }
 185     return result;
 186   }
 187
 188   /**
 189    * {@inheritDoc}
 190    */
 191   @Override
 192   public List<SequenceFeature> getPositionalFeatures(String... type)
 193   {
 194     List<SequenceFeature> result = new ArrayList<>();
 195
 196     for (FeatureStore featureSet : varargToTypes(type))
 197     {
 198       result.addAll(featureSet.getPositionalFeatures());
 199     }
 200     return result;
 201   }
 202
 203   /**
 204    * A convenience method that converts a vararg for feature types to an
 205    * Iterable over matched feature sets in key order
 206    *
 207    * @param type
 208    * @return
 209    */
 210   protected Iterable<FeatureStore> varargToTypes(String... type)
 211   {
 212     if (type == null || type.length == 0)
 213     {
 214       /*
 215        * no vararg parameter supplied - return all
 216        */
 217       return featureStore.values();
 218     }
 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       result.addAll(featureSet.getContactFeatures());
 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       result.addAll(featureSet.getNonPositionalFeatures());
 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     Set<String> groups = new HashSet<>();
 303
 304     for (FeatureStore featureSet : varargToTypes(type))
 305     {
 306       groups.addAll(featureSet.getFeatureGroups(positionalFeatures));
 307     }
 308
 309     return groups;
 310   }
 311
 312   /**
 313    * {@inheritDoc}
 314    */
 315   @Override
 316   public Set<String> getFeatureTypesForGroups(boolean positionalFeatures,
 317           String... groups)
 318   {
 319     Set<String> result = new HashSet<>();
 320
 321     for (Entry<String, FeatureStore> featureType : featureStore.entrySet())
 322     {
 323       Set<String> featureGroups = featureType.getValue().getFeatureGroups(
 324               positionalFeatures);
 325       for (String group : groups)
 326       {
 327         if (featureGroups.contains(group))
 328         {
 329           /*
 330            * yes this feature type includes one of the query groups
 331            */
 332           result.add(featureType.getKey());
 333           break;
 334         }
 335       }
 336     }
 337
 338     return result;
 339   }
 340
 341   /**
 342    * {@inheritDoc}
 343    */
 344   @Override
 345   public Set<String> getFeatureTypes(String... soTerm)
 346   {
 347     Set<String> types = new HashSet<>();
 348     for (Entry<String, FeatureStore> entry : featureStore.entrySet())
 349     {
 350       String type = entry.getKey();
 351       if (!entry.getValue().isEmpty() && isOntologyTerm(type, soTerm))
 352       {
 353         types.add(type);
 354       }
 355     }
 356     return types;
 357   }
 358
 359   /**
 360    * Answers true if the given type matches one of the specified terms (or is a
 361    * sub-type of one in the Sequence Ontology), or if no terms are supplied.
 362    * Answers false if filter terms are specified and the given term does not
 363    * match any of them.
 364    *
 365    * @param type
 366    * @param soTerm
 367    * @return
 368    */
 369   protected boolean isOntologyTerm(String type, String... soTerm)
 370   {
 371     if (soTerm == null || soTerm.length == 0)
 372     {
 373       return true;
 374     }
 375     SequenceOntologyI so = SequenceOntologyFactory.getSequenceOntology();
 376     for (String term : soTerm)
 377     {
 378       if (type.equals(term) || so.isA(type, term))
 379       {
 380         return true;
 381       }
 382     }
 383     return false;
 384   }
 385
 386   /**
 387    * {@inheritDoc}
 388    */
 389   @Override
 390   public float getMinimumScore(String type, boolean positional)
 391   {
 392     return featureStore.containsKey(type) ? featureStore.get(type)
 393             .getMinimumScore(positional) : Float.NaN;
 394   }
 395
 396   /**
 397    * {@inheritDoc}
 398    */
 399   @Override
 400   public float getMaximumScore(String type, boolean positional)
 401   {
 402     return featureStore.containsKey(type) ? featureStore.get(type)
 403             .getMaximumScore(positional) : Float.NaN;
 404   }
 405
 406   /**
 407    * A convenience method to sort features by start position ascending (if on
 408    * forward strand), or end position descending (if on reverse strand)
 409    *
 410    * @param features
 411    * @param forwardStrand
 412    */
 413   public static void sortFeatures(List<? extends IntervalI> features,
 414           final boolean forwardStrand)
 415   {
 416     IntervalI.sortIntervals(features, forwardStrand);
 417   }
 418
 419   /**
 420    * {@inheritDoc} This method is 'semi-optimised': it only inspects features
 421    * for types that include the specified group, but has to inspect every
 422    * feature of those types for matching feature group. This is efficient unless
 423    * a sequence has features that share the same type but are in different
 424    * groups - an unlikely case.
 425    * <p>
 426    * For example, if RESNUM feature is created with group = PDBID, then features
 427    * would only be retrieved for those sequences associated with the target
 428    * PDBID (group).
 429    */
 430   @Override
 431   public List<SequenceFeature> getFeaturesForGroup(boolean positional,
 432           String group, String... type)
 433   {
 434     List<SequenceFeature> result = new ArrayList<>();
 435     for (FeatureStore featureSet : varargToTypes(type))
 436     {
 437       if (featureSet.getFeatureGroups(positional).contains(group))
 438       {
 439         result.addAll(featureSet.getFeaturesForGroup(positional, group));
 440       }
 441     }
 442     return result;
 443   }
 444
 445   /**
 446    * {@inheritDoc}
 447    */
 448   @Override
 449   public boolean shiftFeatures(int fromPosition, int shiftBy)
 450   {
 451     boolean modified = false;
 452     for (FeatureStore fs : featureStore.values())
 453     {
 454       modified |= fs.shiftFeatures(fromPosition, shiftBy);
 455     }
 456     return modified;
 457   }
 458
 459   /**
 460    * {@inheritDoc}
 461    */
 462   @Override
 463   public void deleteAll()
 464   {
 465     featureStore.clear();
 466   }
 467
 468   /**
 469    * Simplified find for features associated with a given position.
 470    *
 471    * @author Bob Hanson 2019.07.30
 472    */
 473   @Override
 474   public void findFeatures(int pos, String type, List<SequenceFeature> list)
 475   {
 476     FeatureStore fs = featureStore.get(type);
 477     if (fs != null)
 478     {
 479       fs.findOverlappingFeatures(pos, list);
 480     }
 481   }
 482
 483
 484 }