/ 
bioperl-1.4
/ Bio::Ontology::Ontology

NAME

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

SYNOPSIS

use Bio::Ontology::Ontology;

# create ontology object
my $ont = Bio::Ontology::Ontology->new(-name => "OBF");

# add terms, relationships ...
my $bp = Bio::Ontology::Term->new(-name => "Bioperl");
my $obf = Bio::Ontology::Term->new(-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/MailList.shtml  - About the mailing lists

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:

http://bugzilla.bioperl.org/

AUTHOR - Hilmar Lapp

Email hlapp at gmx.net

CONTRIBUTORS

Additional contributors names and emails here

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 = new Bio::Ontology::Ontology();
Function: Builds a new Bio::Ontology::Ontology object
Returns : an instance of Bio::Ontology::Ontology
Args    :

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 L<Bio::Ontology::OntologyEngineI>
Args    : on set, new value (an object implementing
          L<Bio::Ontology::OntologyEngineI>, or  undef)

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_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 descendants.

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

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    :