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