.\" 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::Ontology 3pm"
.TH Bio::Ontology::Ontology 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::Ontology \- standard implementation of an Ontology
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Bio::Ontology::Ontology;
\&    use Bio::Ontology::Term;
\&
\&    # create ontology object
\&    my $ont = Bio::Ontology::Ontology\->new(\-name => "OBF");
\&
\&    # add terms, relationships ...
\&    my $bp = Bio::Ontology::Term\->new(\-identifier => \*(Aq02\*(Aq, \-name => "Bioperl");
\&    my $obf = Bio::Ontology::Term\->new(\-identifier => \*(Aq01\*(Aq, \-name => "OBF");
\&    my $partof = Bio::Ontology::RelationshipType\->get_instance("PART_OF");
\&    $ont\->add_term($bp);
\&    $ont\->add_term($obf);
\&    $ont\->add_relationship($bp, $obf, $partof);
\&
\&    # then query
\&    my @terms = $ont\->get_root_terms(); # "OBF"
\&    my @desc = $ont\->get_descendant_terms($terms[0], $partof); # "Bioperl"
\&    # ... see methods for other ways to query
\&
\&    # for advanced users, you can re\-use the query engine outside of an
\&    # ontology to let one instance manage multiple ontologies
\&    my $ont2 = Bio::Ontology::Ontology\->new(\-name => "Foundations",
\&                                            \-engine => $ont\->engine());
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a no-frills implementation of Bio::Ontology::OntologyI.
.PP
The query functions are implemented by delegation to an
OntologyEngineI implementation.
.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 \- Hilmar Lapp"
.IX Header "AUTHOR - Hilmar Lapp"
Email hlapp at gmx.net
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _
.SS "new"
.IX Subsection "new"
.Vb 6
\& Title   : new
\& Usage   : my $obj = Bio::Ontology::Ontology\->new();
\& Function: Builds a new Bio::Ontology::Ontology object
\& Returns : an instance of Bio::Ontology::Ontology
\& Args    : any number of named arguments. The following names will be
\&           recognized by this module:
\&
\&            \-name         the name of the ontology
\&            \-authority    the name of the authority for the ontology
\&            \-identifier   an identifier for the ontology, if any
\&            \-engine       the Bio::Ontology::OntologyEngineI
\&                          implementation that this instance should use;
\&                          default is Bio::Ontology::SimpleOntologyEngine
\&
\&            See the corresponding get/set methods for further documentation
\&            on individual properties.
.Ve
.SH "Methods from Bio::Ontology::OntologyI"
.IX Header "Methods from Bio::Ontology::OntologyI"
.SS "name"
.IX Subsection "name"
.Vb 6
\& Title   : name
\& Usage   : $obj\->name($newval)
\& Function: Get/set the name of the ontology.
\& Example :
\& Returns : value of name (a scalar)
\& Args    : on set, new value (a scalar or undef, optional)
.Ve
.SS "authority"
.IX Subsection "authority"
.Vb 5
\& Title   : authority
\& Usage   : $obj\->authority($newval)
\& Function: Get/set the authority for this ontology, for instance the
\&           DNS base for the organization granting the name of the
\&           ontology and identifiers for the terms.
\&
\&           This attribute is optional and should not generally
\&           expected by applications to have been set. It is here to
\&           follow the rules for namespaces, which ontologies serve as
\&           for terms.
\&
\& Example :
\& Returns : value of authority (a scalar)
\& Args    : on set, new value (a scalar or undef, optional)
.Ve
.SS "definition"
.IX Subsection "definition"
.Vb 6
\& Title   : definition
\& Usage   : $obj\->definition($newval)
\& Function: Get/set a descriptive definition of the ontology.
\& Example :
\& Returns : value of definition (a scalar)
\& Args    : on set, new value (a scalar or undef, optional)
.Ve
.SS "identifier"
.IX Subsection "identifier"
.Vb 3
\& Title   : identifier
\& Usage   : $id = $obj\->identifier()
\& Function: Get an identifier for this ontology.
\&
\&           This is primarily intended for look\-up purposes. The value
\&           is not modifiable and is determined automatically by the
\&           implementation.  Also, the identifier\*(Aqs uniqueness will only
\&           hold within the scope of a particular application\*(Aqs run
\&           time since it is derived from a memory location.
\&
\& Example :
\& Returns : value of identifier (a scalar)
\& Args    :
.Ve
.SS "close"
.IX Subsection "close"
.Vb 6
\& Title   : close
\& Usage   :
\& Function: Release any resources this ontology may occupy. In order
\&           to efficiently release unused memory or file handles, you
\&           should call this method once you are finished with an
\&           ontology.
\&
\& Example :
\& Returns : TRUE on success and FALSE otherwise
\& Args    : none
.Ve
.SH "Implementation-specific public methods"
.IX Header "Implementation-specific public methods"
.SS "engine"
.IX Subsection "engine"
.Vb 8
\& Title   : engine
\& Usage   : $engine = $obj\->engine()
\& Function: Get/set the ontology engine to which all the query methods
\&           delegate.
\& Example :
\& Returns : an object implementing Bio::Ontology::OntologyEngineI
\& Args    : on set, new value (an object implementing
\&           Bio::Ontology::OntologyEngineI, or  undef)
.Ve
.PP
See Bio::Ontology::OntologyEngineI.
.SH "Methods defined in Bio::Ontology::OntologyEngineI"
.IX Header "Methods defined in Bio::Ontology::OntologyEngineI"
.SS "add_term"
.IX Subsection "add_term"
.Vb 3
\& Title   : add_term
\& Usage   : add_term(TermI term): TermI
\& Function: Adds TermI object to the ontology engine term store
\&
\&           If the ontology property of the term object was not set,
\&           this implementation will set it to itself upon adding the
\&           term.
\&
\& Example : $oe\->add_term($term)
\& Returns : its argument.
\& Args    : object of class TermI.
.Ve
.SS "add_relationship"
.IX Subsection "add_relationship"
.Vb 7
\& Title   : add_relationship
\& Usage   : add_relationship(RelationshipI relationship): RelationshipI
\&           add_relatioship(TermI subject, TermI predicate, TermI object)
\& Function: Adds a relationship object to the ontology engine.
\& Example :
\& Returns : Its argument.
\& Args    : A RelationshipI object.
.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 7
\& Title   : get_relationships
\& Usage   : get_relationships(TermI term): RelationshipI[]
\& Function: Retrieves all relationship objects in the ontology, or all
\&           relationships of a given term.
\& Example :
\& Returns : Array of Bio::Ontology::RelationshipI objects
\& Args    : Optionally, a Bio::Ontology::TermI compliant object
.Ve
.SS "get_predicate_terms"
.IX Subsection "get_predicate_terms"
.Vb 6
\& Title   : get_predicate_terms
\& Usage   : get_predicate_terms(): TermI
\& Function: Retrieves all relationship types.
\& Example :
\& Returns : Array of TermI objects
\& 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.
\&
\&           Note that a returned term may possibly be in another
\&           ontology than this one, because the underlying engine may
\&           manage multiple ontologies and the relationships of terms
\&           between them. If you only want descendants within this
\&           ontology, you need to filter the returned array.
\&
\& 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 5
\& 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.
\&
\&           Note that a returned term may possibly be in another
\&           ontology than this one, because the underlying engine may
\&           manage multiple ontologies and the relationships of terms
\&           between them. If you only want descendants within this
\&           ontology, you need to filter the returned array.
\&
\& 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.
\&
\&           Note that a returned term may possibly be in another
\&           ontology than this one, because the underlying engine may
\&           manage multiple ontologies and the relationships of terms
\&           between them. If you only want descendants within this
\&           ontology, you need to filter the returned array.
\&
\& 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.
\&
\&           Note that a returned term may possibly be in another
\&           ontology than this one, because the underlying engine may
\&           manage multiple ontologies and the relationships of terms
\&           between them. If you only want descendants within this
\&           ontology, you need to filter the returned array.
\&
\& 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 "\fBget_root_terms()\fP"
.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 parents.
\&
\& Example : @root_terms = $obj\->get_root_terms()
\& Returns : Array of TermI objects.
\& Args    :
.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.
\&
\&           We do not mandate an order here in which the terms are
\&           returned. In fact, the default implementation will return
\&           them in unpredictable order.
\&
\& 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 implementations:
\&
\&              \-identifier    query by the given identifier
\&              \-name          query by the given name
.Ve
.SS "find_identical_terms"
.IX Subsection "find_identical_terms"
.Vb 7
\& Title   : find_identical_terms
\& Usage   : ($term) = $oe\->find_identical_terms($term0);
\& Function: Find term instances where name or synonym
\&           matches the query exactly
\& Example :
\& Returns : an array of zero or more Bio::Ontology::TermI objects
\& Args    : a Bio::Ontology::TermI object
.Ve
.SS "find_similar_terms"
.IX Subsection "find_similar_terms"
.Vb 7
\& Title   : find_similar_terms
\& Usage   : ($term) = $oe\->find_similar_terms($term0);
\& Function: Find term instances where name or synonym, or part of one,
\&           matches the query.
\& Example :
\& Returns : an array of zero or more Bio::Ontology::TermI objects
\& Args    : a Bio::Ontology::TermI object
.Ve
.SS "find_identically_named_terms"
.IX Subsection "find_identically_named_terms"
.Vb 7
\& Title   : find_identically_named_terms
\& Usage   : ($term) = $oe\->find_identically_named_terms($term0);
\& Function: Find term instances where names match the query term
\&           name exactly
\& Example :
\& Returns : an array of zero or more Bio::Ontology::TermI objects
\& Args    : a Bio::Ontology::TermI object
.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 engine 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::ObjectFactoryI
\&           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 engine 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::ObjectFactoryI
\&           compliant object)
\& Args    :
.Ve
.SS "annotation"
.IX Subsection "annotation"
.Vb 7
\& Title   : annotation
\& Usage   : $annos = $obj\->annotation()
\& Function: Get/Set the Bio::Annotation::Collection object
\&           The collection contains Bio::Annotation::SimpleValue
\&           objects to store header information like the version
\&           and date present in the header section of an Ontology
\&           file.
\&
\& Example :
\& Returns : value of annotation (a Bio::Annotation::Collection
\&           compliant object)
\& Args    : A Bio::Annotation::Collection object (Optional)
.Ve