Provided by: libbio-perl-perl_1.7.8-1_all bug

NAME

       Bio::Ontology::Ontology - standard implementation of an Ontology

SYNOPSIS

           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 => '02', -name => "Bioperl");
           my $obf = Bio::Ontology::Term->new(-identifier => '01', -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());

DESCRIPTION

       This is a no-frills implementation of Bio::Ontology::OntologyI.

       The query functions are implemented by delegation to an OntologyEngineI implementation.

FEEDBACK

   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.

         bioperl-l@bioperl.org                  - General discussion
         http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       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.

   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:

         https://github.com/bioperl/bioperl-live/issues

AUTHOR - Hilmar Lapp

       Email hlapp at gmx.net

APPENDIX

       The rest of the documentation details each of the object methods.  Internal methods are
       usually preceded with a _

   new
        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.

Methods from Bio::Ontology::OntologyI

   name
        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)

   authority
        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)

   definition
        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)

   identifier
        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's uniqueness will only
                  hold within the scope of a particular application's run
                  time since it is derived from a memory location.

        Example :
        Returns : value of identifier (a scalar)
        Args    :

   close
        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

Implementation-specific public methods

   engine
        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)

       See Bio::Ontology::OntologyEngineI.

Methods defined in Bio::Ontology::OntologyEngineI

   add_term
        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.

   add_relationship
        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.

   get_relationship_type
        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.

   get_relationships
        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

   get_predicate_terms
        Title   : get_predicate_terms
        Usage   : get_predicate_terms(): TermI
        Function: Retrieves all relationship types.
        Example :
        Returns : Array of TermI objects
        Args    :

   get_child_terms
        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.

   get_descendant_terms
        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.

   get_parent_terms
        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.

   get_ancestor_terms
        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.

   get_leaf_terms
        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    :

   get_root_terms()
        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    :

   get_all_terms
        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    :

   find_terms
        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

   find_identical_terms
        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

   find_similar_terms
        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

   find_identically_named_terms
        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

Factory for relationships and terms

   relationship_factory
        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    :

   term_factory
        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    :

   annotation
        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)