.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::Ontology::OntologyEngineI 3pm"
.TH Bio::Ontology::OntologyEngineI 3pm "2021-08-15" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::Ontology::OntologyEngineI \- Interface a minimal Ontology implementation should satisfy
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    # see documentation of methods
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This describes the minimal interface an ontology query engine should
provide.  It intentionally does not make explicit references to the
ontology being a \s-1DAG,\s0 nor does it mandate that the ontology be a
vocabulary. Rather, it tries to generically express what should be
accessible (queriable) about an ontology.
.PP
The idea is to allow for different implementations for different
purposes, which may then differ as to which operations are efficient
and which are not, and how much richer the functionality is on top of
this minimalistic set of methods. Check modules in the Bio::Ontology
namespace to find out which implementations exist. At the time of
writing, there is a SimpleOntologyEngine (which does not use
Graph.pm), and a Graph.pm\-based implementation in SimpleGOEngine.
.PP
Ontology parsers in Bio::OntologyIO are required to return an
implementation of this interface.
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "Mailing Lists"
User feedback is an integral part of the evolution of this and other
Bioperl modules. Send your comments and suggestions preferably to
the Bioperl mailing list.  Your participation is much appreciated.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
rather than to the module maintainer directly. Many experienced and 
reponsive experts will be able look at the problem and quickly 
address it. Please include a thorough description of the problem 
with code and data examples if at all possible.
.SS "Reporting Bugs"
.IX Subsection "Reporting Bugs"
Report bugs to the Bioperl bug tracking system to help us keep track
of the bugs and their resolution. Bug reports can be submitted via
the web:
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR \- Peter Dimitrov"
.IX Header "AUTHOR - Peter Dimitrov"
Email dimitrov@gnf.org
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _
.SS "add_term"
.IX Subsection "add_term"
.Vb 6
\& Title   : add_term
\& Usage   : add_term(TermI term): TermI
\& Function: Adds TermI object to the ontology engine term store
\& Example : $oe\->add_term($term)
\& Returns : its argument.
\& Args    : object of class TermI.
.Ve
.SS "add_relationship"
.IX Subsection "add_relationship"
.Vb 6
\& Title   : add_relationship
\& Usage   : add_relationship(RelationshipI relationship): RelationshipI
\& Function: Adds a relationship object to the ontology engine.
\& Example :
\& Returns : Its argument.
\& Args    : A RelationshipI object.
.Ve
.SS "add_relationship_type"
.IX Subsection "add_relationship_type"
.Vb 7
\& Title   : add_relationship_type
\& Usage   : add_relationship_type(scalar,OntologyI ontology)
\& Function: Adds a relationshiptype object to the ontology engine.
\& Example :
\& Returns : 1 on success, undef on failure
\& Args    : The name(scalar) of the relationshiptype, and the OntologyI 
\&           it is to be added to.
.Ve
.SS "get_relationship_type"
.IX Subsection "get_relationship_type"
.Vb 6
\& Title   : get_relationship_type
\& Usage   : get_relationship_type(scalar): RelationshipTypeI
\& Function: Get a relationshiptype object from the ontology engine.
\& Example :
\& Returns : A RelationshipTypeI object.
\& Args    : The name (scalar) of the RelationshipTypeI object desired.
.Ve
.SS "get_relationships"
.IX Subsection "get_relationships"
.Vb 8
\& Title   : get_relationships
\& Usage   : get_relationships(TermI term): RelationshipI
\& Function: Retrieves all relationship objects from this ontology engine,
\&           or all relationships of a term if a term is supplied.
\& Example :
\& Returns : Array of Bio::Ontology::RelationshipI objects
\& Args    : None, or a Bio::Ontology::TermI compliant object for which
\&           to retrieve the relationships.
.Ve
.SS "get_predicate_terms"
.IX Subsection "get_predicate_terms"
.Vb 6
\& Title   : get_predicate_terms
\& Usage   : get_predicate_terms(): TermI
\& Function:
\& Example :
\& Returns :
\& Args    :
.Ve
.SS "get_child_terms"
.IX Subsection "get_child_terms"
.Vb 7
\& Title   : get_child_terms
\& Usage   : get_child_terms(TermI term, TermI predicate_terms): TermI
\& Function: Retrieves all child terms of a given term, that satisfy a
\&           relationship among those that are specified in the second
\&           argument or undef otherwise. get_child_terms is a special
\&           case of get_descendant_terms, limiting the search to the
\&           direct descendants.
\&
\& Example :
\& Returns : Array of TermI objects.
\& Args    : First argument is the term of interest, second is the list
\&           of relationship type terms.
.Ve
.SS "get_descendant_terms"
.IX Subsection "get_descendant_terms"
.Vb 9
\& Title   : get_descendant_terms
\& Usage   : get_descendant_terms(TermI term, TermI rel_types): TermI
\& Function: Retrieves all descendant terms of a given term, that
\&           satisfy a relationship among those that are specified in
\&           the second argument or undef otherwise. 
\& Example :
\& Returns : Array of TermI objects.
\& Args    : First argument is the term of interest, second is the list
\&           of relationship type terms.
.Ve
.SS "get_parent_terms"
.IX Subsection "get_parent_terms"
.Vb 7
\& Title   : get_parent_terms
\& Usage   : get_parent_terms(TermI term, TermI predicate_terms): TermI
\& Function: Retrieves all parent terms of a given term, that satisfy a
\&           relationship among those that are specified in the second
\&           argument or undef otherwise. get_parent_terms is a special
\&           case of get_ancestor_terms, limiting the search to the
\&           direct ancestors.
\&
\& Example :
\& Returns : Array of TermI objects.
\& Args    : First argument is the term of interest, second is the list
\&           of relationship type terms.
.Ve
.SS "get_ancestor_terms"
.IX Subsection "get_ancestor_terms"
.Vb 5
\& Title   : get_ancestor_terms
\& Usage   : get_ancestor_terms(TermI term, TermI predicate_terms): TermI
\& Function: Retrieves all ancestor terms of a given term, that satisfy
\&           a relationship among those that are specified in the second
\&           argument or undef otherwise. 
\&
\& Example :
\& Returns : Array of TermI objects.
\& Args    : First argument is the term of interest, second is the list
\&           of relationship type terms.
.Ve
.SS "get_leaf_terms"
.IX Subsection "get_leaf_terms"
.Vb 4
\& Title   : get_leaf_terms
\& Usage   : get_leaf_terms(): TermI
\& Function: Retrieves all leaf terms from the ontology. Leaf term is a
\&           term w/o descendants.
\&
\& Example : @leaf_terms = $obj\->get_leaf_terms()
\& Returns : Array of TermI objects.
\& Args    :
.Ve
.SS "get_root_terms"
.IX Subsection "get_root_terms"
.Vb 4
\& Title   : get_root_terms
\& Usage   : get_root_terms(): TermI
\& Function: Retrieves all root terms from the ontology. Root term is a
\&           term w/o ancestors.
\&
\& Example : @root_terms = $obj\->get_root_terms()
\& Returns : Array of TermI objects.
\& Args    :
.Ve
.SH "Factory for relationships and terms"
.IX Header "Factory for relationships and terms"
.SS "relationship_factory"
.IX Subsection "relationship_factory"
.Vb 5
\& Title   : relationship_factory
\& Usage   : $fact = $obj\->relationship_factory()
\& Function: Get (and set, if the implementation supports it) the object
\&           factory to be used when relationship objects are created by
\&           the implementation on\-the\-fly.
\&
\& Example : 
\& Returns : value of relationship_factory (a Bio::Factory::ObjectFactory
\&           compliant object)
\& Args    :
.Ve
.SS "term_factory"
.IX Subsection "term_factory"
.Vb 5
\& Title   : term_factory
\& Usage   : $fact = $obj\->term_factory()
\& Function: Get (and set, if the implementation supports it) the object
\&           factory to be used when term objects are created by
\&           the implementation on\-the\-fly.
\&
\& Example : 
\& Returns : value of term_factory (a Bio::Factory::ObjectFactory
\&           compliant object)
\& Args    :
.Ve
.SH "Decorator Methods"
.IX Header "Decorator Methods"
.Vb 4
\& These methods come with a default implementation that uses the
\& abstract methods defined for this interface. This may not be very
\& efficient, and hence implementors are encouraged to override these
\& methods if they can provide more efficient implementations.
.Ve
.SS "get_all_terms"
.IX Subsection "get_all_terms"
.Vb 3
\& Title   : get_all_terms
\& Usage   : get_all_terms: TermI
\& Function: Retrieves all terms from the ontology.
\&
\&           This is more a decorator method. We provide a default
\&           implementation here that loops over all root terms and gets
\&           all descendants for each root term. The overall union of
\&           terms is then made unique by name and ontology.
\&
\&           We do not mandate an order here in which the terms are
\&           returned. In fact, the default implementation will return
\&           them in unpredictable order.
\&
\&           Engine implementations that can provide a more efficient
\&           method for obtaining all terms should definitely override
\&           this.
\&
\& Example : @terms = $obj\->get_all_terms()
\& Returns : Array of TermI objects.
\& Args    :
.Ve
.SS "find_terms"
.IX Subsection "find_terms"
.Vb 3
\& Title   : find_terms
\& Usage   : ($term) = $oe\->find_terms(\-identifier => "SO:0000263");
\& Function: Find term instances matching queries for their attributes.
\&
\&           An implementation may not support querying for arbitrary
\&           attributes, but can generally be expected to accept
\&           \-identifier and \-name as queries. If both are provided,
\&           they are implicitly intersected.
\&
\& Example :
\& Returns : an array of zero or more Bio::Ontology::TermI objects
\& Args    : Named parameters. The following parameters should be recognized
\&           by any implementation:
\&
\&              \-identifier    query by the given identifier
\&              \-name          query by the given name
.Ve
.SH "Experimental API method proposals"
.IX Header "Experimental API method proposals"
.Vb 5
\& Ontologies are a very new domain in bioperl, and we are not sure yet
\& what we will want to do on and with ontologies in which
\& situation. The methods from here on downwards are solely API
\& descriptions to solicit comment and feedback; the chance of any of
\& those being actually implemented already is very slim.
\&
\& Disclaimer: As long as an API method stays in this section, it is
\& subject to change, possibly even radical change or complete
\& deletion. If it\*(Aqs not implemented yet (most likely it isn\*(Aqt),
\& implement yourself at your own risk.
\&
\& So far for the disclaimer. The reason the API description is here,
\& however, is to solicit feedback. Please feel encouraged to share your
\& opinion, regardless of what it is (a notable difference of this API
\& method to others is that there is actually no working code behind it
\& \- so the defense line is non\-existent for practical purposes).
.Ve
.SS "common_ancestor_path"
.IX Subsection "common_ancestor_path"
.Vb 6
\& Title   : common_ancestor_path
\& Usage   :
\& Function: Get the paths from two terms A and B to term C, such that
\&           there is no other term D to which A and B would have a shorter
\&           path, provided there is a term C to which both A and B are
\&           connected by a path.
\&
\&           Note that the path to the common ancestor between A and A
\&           exists, has distance zero, and predicate "identity".
\&
\&           The search for the common ancestor C can be further
\&           constrained by supplying a predicate term. If supplied, the
\&           predicates of the two paths (A,C) and (B,C) must have a
\&           common ancestor identical to the predicate, or that has a
\&           path to the predicate.
\&
\& Example :
\& Returns : The path of the first term to the common ancestor in scalar
\&           context, and both paths in list context. Paths are
\&           Bio::Ontology::PathI compliant objects.
\& Args    : The two terms (Bio::Ontology::TermI objects), and optionally
\&           a constraining common predicate (Bio::Ontology::TermI object).
\&           The latter may also be given as a scalar, in which case it
\&           is treated as a boolean that, if TRUE, means that the two paths
\&           must have identical predicates in order to be returned.
.Ve