Bio::O...ntology(3pm)

📦
version 1.7.8 · 3 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

okay so bestie, this is the manual page for Bio::Ontology::Ontology (3pm), and it's giving standard implementation of an Ontology energy 💅 it's long so buckle up, this is part 1 🎀

🌸 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. Like, it does exactly what it says on the tin, no extra sparkle, and honestly? That's the vibe 🫶

The query functions are implemented by delegation to an OntologyEngineI implementation. So all the actual querying gets handed off to the engine — this class is basically the main character that delegates, iykyk 💅

📬 FEEDBACK 📬

💌 Mailing Lists 💌

User feedback is an integral part of the evolution of this and other Bioperl modules, fr fr. Send your comments and suggestions preferably to the Bioperl mailing list. Your participation is much appreciated, bestie 🌸

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. The way that so many experienced and responsive experts will be able look at the problem and quickly address it 😭 so please include a thorough description of the problem with code and data examples if at all possible. Give them everything, no gatekeeping 🙈

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

So new builds you a brand new Bio::Ontology::Ontology object, and it takes any number of named arguments 🦋 the ones it recognizes are -name, -authority, -identifier, and -engine (and that engine defaults to Bio::Ontology::SimpleOntologyEngine — the little default that could 💖). Peep the matching get/set methods for the deets on each property.

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

Get it, set it, it's the name of the ontology. That's it, that's the method 💅

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

Get/set the authority for this ontology — think the DNS base for the org that granted the ontology's name and the identifiers for the terms 🏛️

Heads up bestie: this attribute is optional and applications should not generally expect it to have been set. It exists to follow the rules for namespaces, which ontologies serve as for terms. So like, don't count on it being there, k? 😭

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

Get/set a descriptive definition of the ontology. Describe your ontology, bestie, it deserves it 🫶

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

Grab an identifier for this ontology.

Okay so important things, no cap: this is primarily for look-up purposes. The value is not modifiable and is determined automatically by the implementation. Also — and this is the part people always forget — the identifier's uniqueness only holds within the scope of a particular application's run time, since it is derived from a memory location 💀 so don't go treating it like some globally unique forever-ID, it's not that girl.

🧹 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

Releases any resources this ontology may occupy. In order to efficiently release unused memory or file handles, you should call this method once you're finished with an ontology — like closing the app when you're done, it's just polite 🎀

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)

Get/set the ontology engine to which all the query methods delegate 🔥 this is the one doing the actual work while this class sits there looking pretty, main character energy fr.

Returns an object implementing Bio::Ontology::OntologyEngineI; on set, the new value is an object implementing Bio::Ontology::OntologyEngineI, or undef ✨

See Bio::Ontology::OntologyEngineI 🦋

🧬 Methods defined in Bio::Ontology::OntologyEngineI 🧬

These are the ones the interface Bio::Ontology::OntologyEngineI says you gotta have. Every engine out there is expected to bring these, so here's the whole lineup 💖

add_term

  • Title: add_term
  • Usage: add_term(TermI term): TermI
  • Function: drops a TermI object into the ontology engine's term store. And okay, small lil detail — if the ontology property of the term object was not set already, this implementation will set it to itself while adding the term. so it never shows up to the party unaffiliated 💅
  • Example: $oe->add_term($term)
  • Returns: its argument. literally just hands it right back to you 🫶
  • Args: an 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. (and yes bestie, that second Usage line really does say add_relatioship — that's how it's written in the source, not my typo, we do not "fix" it, we respect it 👑)
  • Example: the original leaves this one blank 🙈
  • Returns: its argument.
  • Args: a RelationshipI object.

get_relationship_type

  • Title: get_relationship_type
  • Usage: get_relationship_type(scalar): RelationshipTypeI
  • Function: grabs a relationshiptype object back out of the ontology engine. you ask by name, it hands you the whole vibe 🦋
  • Example: blank in the original 💀
  • Returns: a RelationshipTypeI object.
  • Args: the name (a scalar) of the RelationshipTypeI object you're manifesting.

get_relationships

  • Title: get_relationships
  • Usage: get_relationships(TermI term): RelationshipI[]
  • Function: pulls all the relationship objects in the ontology, or all the relationships of one specific term if you give it one.
  • Example: also blank in the original 🫠
  • Returns: an 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. every last one ✨
  • Example: blank, bestie 😭
  • Returns: an array of TermI objects.
  • Args: nothing. zero. empty. the Args line is just vibes 🎀

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 the ones you listed in the second argument — or undef otherwise. get_child_terms is a special case of get_descendant_terms, it just limits the search to the direct descendants. so like, the immediate children, not the whole extended family 🌸
⚠️ heads up bestie: a returned term may possibly live 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 have to filter the returned array yourself. no cap.
  • Example: blank in the original 🙈
  • Returns: an 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 the ones specified in the second argument, or undef otherwise. the whole bloodline, not just the direct kids 💜
⚠️ same warning, same energy: 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. want only descendants within this ontology? filter the returned array. periodt.
  • Example: blank 💀
  • Returns: an 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 the ones 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. the parents. the ones who raised it 🫶
⚠️ yes bestie, same caveat: 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. (that's the original's wording, and yes it says "descendants" on a parents method — we keep it exactly as written 😭)
  • Example: blank in the original 🫠
  • Returns: an 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 the ones specified in the second argument, or undef otherwise. go all the way up the family tree, bestie 🌈
⚠️ and once more for the people in the back: 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: blank 🙈
  • Returns: an 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. a leaf term is a term w/o descendants. the ends of the branches, the ones with no children, absolute final girls 💅
  • Example: @leaf_terms = $obj->get_leaf_terms()
  • Returns: an array of TermI objects.
  • Args: nothing at all 🎀

get_root_terms()

  • Title: get_root_terms
  • Usage: get_root_terms(): TermI
  • Function: retrieves all root terms from the ontology. a root term is a term w/o parents. the origin story, the main characters at the very top 👑
  • Example: @root_terms = $obj->get_root_terms()
  • Returns: an array of TermI objects.
  • Args: nothing 💖

get_all_terms

  • Title: get_all_terms
  • Usage: get_all_terms: TermI
  • Function: retrieves all terms from the ontology. every single one.
📢 okay important: we do not mandate an order here in which the terms are returned. in fact, the default implementation will return them in an unpredictable order. so do not assume a sort, bestie, it's giving chaos 🌪️
  • Example: @terms = $obj->get_all_terms()
  • Returns: an array of TermI objects.
  • Args: nothing ✨

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. and if you give it both, they are implicitly intersected. so it's an AND situation, not an OR situation, iykyk 🔥

  • Example: blank in the original 🫠
  • 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. no fuzzy business, exact match only 🎯
  • Example: blank 🙈
  • 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. this one's the chill one, it's flexible, it gets the vibe 🌸
  • Example: blank 💀
  • 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. just the name field, bestie, we're being precise here 💅
  • Example: blank in the original 🫠
  • Returns: an array of zero or more Bio::Ontology::TermI objects.
  • Args: a Bio::Ontology::TermI object.

🏭 Factory for relationships and terms 🏭

Where the objects get made on the fly. obsessed honestly ✨

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. so if your engine likes to spawn relationships mid-thought, this is the plug 🎀
  • Example: blank 🙈
  • Returns: the value of relationship_factory (a Bio::Factory::ObjectFactoryI compliant object)
  • Args: nothing listed 🫶

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. same energy, different object type 💜
  • Example: blank 💀
  • Returns: the value of term_factory (a Bio::Factory::ObjectFactoryI compliant object)
  • Args: nothing listed 🌈

annotation

  • Title: annotation
  • Usage: $annos = $obj->annotation()
  • Function: get/set the Bio::Annotation::Collection object. this collection holds Bio::Annotation::SimpleValue objects that store header information — like the version and date that live in the header section of an Ontology file. the metadata corner, the receipts, the lore 📜
  • Example: blank in the original 🫠
  • Returns: the value of annotation (a Bio::Annotation::Collection compliant object)
  • Args: a Bio::Annotation::Collection object (optional)

and that's the whole page, bestie 🥹💖

this was generated from the perl v5.32.1 distribution, dated 2021-08-15, and the page itself is Bio::O...ntology(3pm) — user contributed perl documentation, as always. go read the source, it slays, and remember: the vibe changes, the facts do not 🫶✨

📦 where this page comes from