src/jalview/datamodel/ontology/OntologyI.java

   1 package jalview.datamodel.ontology;
   2
   3 import java.util.List;
   4 import java.util.Map;
   5 import java.util.Set;
   6
   7 public interface OntologyI
   8 {
   9   /**
  10    * Answers true if the term can be identified in the ontology (possibly by id,
  11    * description or alias), else false
  12    *
  13    * @param term
  14    * @return
  15    */
  16   boolean isValidTerm(String term);
  17
  18   /**
  19    * Answers true if <code>childTerm</code> is the same as, or a sub-type
  20    * (specialisation of) <code>parentTerm</code>, else false
  21    *
  22    * @param childTerm
  23    * @param parentTerm
  24    * @return
  25    */
  26   boolean isA(String childTerm, String parentTerm);
  27
  28   /**
  29    * Answers those terms in the given set which are not child terms of some
  30    * other term in the set. That is, returns a set of parent terms. The input
  31    * set is not modified.
  32    *
  33    * @param terms
  34    * @return
  35    */
  36   Set<String> getParentTerms(Set<String> terms);
  37
  38   /**
  39    * Answers a (possibly empty) list of those terms in the supplied list which
  40    * are a child (directly or indirectly) of <code>parent</code>. The parent
  41    * term itself is not included (even if in the input list)
  42    *
  43    * @param parent
  44    * @param terms
  45    * @return
  46    */
  47   List<String> getChildTerms(String parent, List<String> terms);
  48
  49   /**
  50    * Answers a (possibly empty) list of the immediate parent terms of the given
  51    * term
  52    *
  53    * @param term
  54    * @return
  55    */
  56   List<String> getParents(String term);
  57
  58   /**
  59    * Returns a sorted list of all valid terms queried for (i.e. terms processed
  60    * which were valid in the SO), using the friendly description.
  61    *
  62    * This can be used to check that any hard-coded stand-in for the full SO
  63    * includes all the terms needed for correct processing.
  64    *
  65    * @return
  66    */
  67   List<String> termsFound();
  68
  69   /**
  70    * Returns a sorted list of all invalid terms queried for (i.e. terms
  71    * processed which were not found in the SO), using the friendly description.
  72    *
  73    * This can be used to report any 'non-compliance' in data, and/or to report
  74    * valid terms missing from any hard-coded stand-in for the full SO.
  75    *
  76    * @return
  77    */
  78   List<String> termsNotFound();
  79
  80   /**
  81    * Answers the top level parent terms (normally only one) for the given term,
  82    * that is, those that have no parent themselves. Answers null if {@code term}
  83    * is not a sequence ontology term. Answers a list just containing
  84    * {@code term} if it is a valid term with no parent.
  85    *
  86    * @param term
  87    * @return
  88    */
  89   List<String> getRootParents(String term);
  90
  91   /**
  92    * Answers a (possibly empty) map of any Ontology terms (from the given term
  93    * and its parents) which subsume one or more of the target terms. The map key
  94    * is an ontology term, and the entry is the list of target terms that are
  95    * sub-terms of the key.
  96    * <p>
  97    * For example if {@code stop_gained} and {@code stop_lost} are known feature
  98    * types, then SO term {@ nonsynonymous_variant} is the first common parent of
  99    * both terms
 100    *
 101    * @param givenTerm
 102    *          the term to search from
 103    * @param targetTerms
 104    *          candidate terms to 'capture' in ontology groupings
 105    * @return
 106    */
 107   Map<String, List<String>> findSequenceOntologyGroupings(String givenTerm,
 108           List<String> targetTerms);
 109 }