Bio::Ontology::SimpleOntologyEngine - Implementation of OntologyEngineI interface

  my $soe = Bio::Ontology::SimpleOntologyEngine->new;

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

  https://redmine.open-bio.org/projects/bioperl/

 Title   : new
 Usage   : $soe = Bio::Ontology::SimpleOntologyEngine->new;
 Function: Initializes the ontology engine.
 Example : $soe = Bio::Ontology::SimpleOntologyEngine->new;
 Returns : Object of class SimpleOntologyEngine.
 Args    :

 Title   : _instantiated_terms_store
 Usage   : $obj->_instantiated_terms_store($newval)
 Function:
 Example :
 Returns : hash
 Args    : empty hash

 Title   : mark_instantiated
 Usage   : $self->mark_instantiated(TermI terms): TermI
 Function: Marks TermI objects as fully instantiated,
           allowing for proper counting of the number of terms in the term store.
           The TermI objects has to be already stored in the term store in order
           to be marked.
 Example : $self->mark_instantiated($term);
 Returns : its argument or throws an exception if a term is not
           in the term store.
 Args    : array of objects of class TermI.

 Title   : mark_uninstantiated
 Usage   : $self->mark_uninstantiated(TermI terms): TermI
 Function: Marks TermI objects as not fully instantiated,
 Example : $self->mark_uninstantiated($term);
 Returns : its argument or throws an exception if a term is not
           in the term store(if the term is not marked it does nothing).
 Args    : array of objects of class TermI.

 Title   : term_store
 Usage   : $obj->_term_store($newval)
 Function:
 Example :
 Returns : reference to an array of Bio::Ontology::TermI objects
 Args    : reference to an array of Bio::Ontology::TermI objects

 Title   : add_term
 Usage   : add_term(TermI term): TermI
 Function: Adds TermI object to the ontology engine term store.
 Marks the term fully instantiated by default.
 Example : $soe->add_term($term)
 Returns : its argument.
 Args    : object of class TermI.

 Title   : get_term_by_identifier
 Usage   : get_term_by_identifier(String id): TermI
 Function: Retrieves terms from the term store by their identifier
           field, or an empty list if not there.
 Example : $term = $soe->get_term_by_identifier("IPR000001");
 Returns : An array of zero or more Bio::Ontology::TermI objects.
 Args    : An array of identifier strings

 Title   : get_number_rels
 Usage   :
 Function:
 Example :
 Returns :
 Args    :

 Title   : _get_number_terms
 Usage   :
 Function:
 Example :
 Returns :
 Args    :

 Title   : _storerelationship_store
 Usage   : $obj->relationship_store($newval)
 Function:
 Example :
 Returns : reference to an array of Bio::Ontology::TermI objects
 Args    : reference to an array of Bio::Ontology::TermI objects

 Title   : _inverted_relationship_store
 Usage   :
 Function:
 Example :
 Returns : reference to an array of Bio::Ontology::TermI objects
 Args    : reference to an array of Bio::Ontology::TermI objects

 Title   : _relationship_type_store
 Usage   : $obj->_relationship_type_store($newval)
 Function:
 Example :
 Returns : reference to an array of Bio::Ontology::RelationshipType objects
 Args    : reference to an array of Bio::Ontology::RelationshipType objects

 Title   : _add_relationship_simple
 Usage   :
 Function:
 Example :
 Returns :
 Args    :

 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.

 Title   : get_relationships
 Usage   : get_relationships(): RelationshipI
 Function: Retrieves all relationship objects.
 Example :
 Returns : Array of RelationshipI objects
 Args    :

 Title   : get_all_relationships
 Usage   : get_all_relationships(): RelationshipI
 Function: Retrieves all relationship objects.
 Example :
 Returns : Array of RelationshipI objects
 Args    :

 Title   : get_predicate_terms
 Usage   : get_predicate_terms(): TermI
 Function: Retrives all relationship types stored in the engine
 Example :
 Returns : reference to an array of Bio::Ontology::RelationshipType objects
 Args    :

 Title   : _is_rel_type
 Usage   :
 Function:
 Example :
 Returns :
 Args    :

 Title   : _typed_traversal
 Usage   :
 Function:
 Example :
 Returns :
 Args    :

 Title   : get_child_terms
 Usage   : get_child_terms(TermI term, TermI predicate_terms): TermI
           get_child_terms(TermI term, RelationshipType 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.

 Title   : get_descendant_terms
 Usage   : get_descendant_terms(TermI term, TermI rel_types): TermI
           get_child_terms(TermI term, RelationshipType predicate_terms): 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. Uses
           _typed_traversal to find all descendants.

 Example :
 Returns : Array of TermI objects.
 Args    : First argument is the term of interest, second is the list of
           relationship type terms.

 Title   : get_parent_terms
 Usage   : get_parent_terms(TermI term, TermI predicate_terms): TermI
           get_child_terms(TermI term, RelationshipType 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.

 Title   : get_ancestor_terms
 Usage   : get_ancestor_terms(TermI term, TermI predicate_terms): TermI
           get_child_terms(TermI term, RelationshipType 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. Uses _typed_traversal to find
           all ancestors.

 Example :
 Returns : Array of TermI objects.
 Args    : First argument is the term of interest, second is the list
           of relationship type 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    :

 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    :

 Title   : _filter_repeated
 Usage   : @lst = $self->_filter_repeated(@old_lst);
 Function: Removes repeated terms
 Example :
 Returns : List of unique TermI objects
 Args    : List of TermI objects

 Title   : get_all_terms
 Usage   : get_all_terms(): TermI
 Function: Retrieves all terms currently stored in the ontology.
 Example : @all_terms = $obj->get_all_terms()
 Returns : Array of TermI objects.
 Args    :

 Title   : find_terms
 Usage   : ($term) = $oe->find_terms(-identifier => "SO:0000263");
 Function: Find term instances matching queries for their attributes.

           This implementation can efficiently resolve queries by
           identifier.

 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

 Title   : relationship_factory
 Usage   : $fact = $obj->relationship_factory()
 Function: Get/set 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    : on set, a Bio::Factory::ObjectFactoryI compliant object

 Title   : term_factory
 Usage   : $fact = $obj->term_factory()
 Function: Get/set the object factory to be used when term objects are
           created by the implementation on-the-fly.

           Note that this ontology engine implementation does not
           create term objects on the fly, and therefore setting this
           attribute is meaningless.

 Example :
 Returns : value of term_factory (a Bio::Factory::ObjectFactoryI
           compliant object)
 Args    : on set, a Bio::Factory::ObjectFactoryI compliant object

 Title   : _filter_unmarked
 Usage   : _filter_unmarked(TermI terms): TermI
 Function: Removes the uninstantiated terms from the list of terms
 Example :
 Returns : array of fully instantiated TermI objects
 Args    : array of TermI objects

 Title   : remove_term_by_id
 Usage   : remove_term_by_id(String id): TermI
 Function: Removes TermI object from the ontology engine using the
           string id as an identifier. Current implementation does not
           enforce consistency of the relationships using that term.
 Example : $term = $soe->remove_term_by_id($id);
 Returns : Object of class TermI or undef if not found.
 Args    : The string identifier of a term.

 Title   : to_string
 Usage   : print $sv->to_string();
 Function: Currently returns formatted string containing the number of
           terms and number of relationships from the ontology engine.
 Example : print $sv->to_string();
 Returns :
 Args    :

 Title   : _unique_termid
 Usage   :
 Function: Returns a string that can be used as ID using fail-over
           approaches.

           If the identifier attribute is not set, it uses the
           combination of name and ontology name, provided both are
           set. If they are not, it returns the name alone.

           Note that this is a private method. Call from inheriting
           classes but not from outside.

 Example :
 Returns : a string
 Args    : a Bio::Ontology::TermI compliant object

#
# BioPerl module for Bio::Ontology::SimpleOntologyEngine
#
# Please direct questions and support issues to <bioperl-l@bioperl.org>
#
# Cared for by Peter Dimitrov <dimitrov@gnf.org>
#
# Copyright Peter Dimitrov
# (c) Peter Dimitrov, dimitrov@gnf.org, 2002.
# (c) GNF, Genomics Institute of the Novartis Research Foundation, 2002.
#
# You may distribute this module under the same terms as perl itself.
# Refer to the Perl Artistic License (see the license accompanying this
# software package, or see http://www.perl.com/language/misc/Artistic.html)
# for the terms under which you may use, modify, and redistribute this module.
#
# THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
# WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
# MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
#
# POD documentation - main docs before the code

# Let the code begin...

package Bio::Ontology::SimpleOntologyEngine;
use strict;
use Carp;
use Bio::Ontology::RelationshipFactory;
use Data::Dumper;

use base qw(Bio::Root::Root Bio::Ontology::OntologyEngineI);

sub new {
    my ( $class, @args ) = @_;
    my $self = $class->SUPER::new(@args);

    #   my %param = @args;

    $self->_term_store(                  {} );
    $self->_relationship_store(          {} );
    $self->_inverted_relationship_store( {} );
    $self->_relationship_type_store(     {} );
    $self->_instantiated_terms_store(    {} );

    # set defaults for the factories
    $self->relationship_factory(
        Bio::Ontology::RelationshipFactory->new( -type => "Bio::Ontology::Relationship" ) );
    return $self;
}

sub _instantiated_terms_store {
    my ( $self, $value ) = @_;

    if ( defined $value ) {
        $self->{'_instantiated_terms_store'} = $value;
    }
    return $self->{'_instantiated_terms_store'};
}

sub mark_instantiated {
    my ( $self, @terms ) = @_;

    foreach my $term (@terms) {
        $self->throw( "term " . $term->identifier . " not in the term store\n" )
            if !defined $self->_term_store->{ $term->identifier };
        $self->_instantiated_terms_store->{ $term->identifier } = 1;
    }

    return @terms;
}

sub mark_uninstantiated {
    my ( $self, @terms ) = @_;

    foreach my $term (@terms) {
        $self->throw( "term " . $term->identifier . " not in the term store\n" )
            if !defined $self->_term_store->{ $term->identifier };
        delete $self->_instantiated_terms_store->{ $term->identifier }
            if defined $self->_instantiated_terms_store->{ $term->identifier };
    }

    return @terms;
}

sub _term_store {
    my ( $self, $value ) = @_;

    if ( defined $value ) {
        if ( defined $self->{'_term_store'} ) {
            $self->throw("_term_store already defined\n");
        } else {
            $self->{'_term_store'} = $value;
        }
    }

    return $self->{'_term_store'};
}

sub add_term {
    my ( $self, $term ) = @_;
    my $term_store = $self->_term_store;

    if ( defined $term_store->{ $term->identifier } && $self->_instantiated_terms_store->{ $term->identifier }) {
        $self->throw( "term " . $term->identifier . " already defined\n" );
    } else {
        $term_store->{ $term->identifier } = $term;
        $self->_instantiated_terms_store->{ $term->identifier } = 1;
    }

    return $term;
}

sub get_term_by_identifier {
    my ( $self, @ids ) = @_;
    my @ans = ();

    foreach my $id (@ids) {
        my $term = $self->_term_store->{$id};
        push @ans, $term if defined $term;
    }

    return @ans;
}

sub _get_number_rels {
    my ($self) = @_;
    my $num_rels = 0;

    foreach my $entry ( $self->_relationship_store ) {
        $num_rels += scalar keys %$entry;
    }
    return $num_rels;
}

sub _get_number_terms {
    my ($self) = @_;

    return scalar $self->_filter_unmarked( values %{ $self->_term_store } );

}

sub _relationship_store {
    my ( $self, $value ) = @_;

    if ( defined $value ) {
        if ( defined $self->{'_relationship_store'} ) {
            $self->throw("_relationship_store already defined\n");
        } else {
            $self->{'_relationship_store'} = $value;
        }
    }

    return $self->{'_relationship_store'};
}

sub _inverted_relationship_store {
    my ( $self, $value ) = @_;

    if ( defined $value ) {
        if ( defined $self->{'_inverted_relationship_store'} ) {
            $self->throw("_inverted_relationship_store already defined\n");
        } else {
            $self->{'_inverted_relationship_store'} = $value;
        }
    }

    return $self->{'_inverted_relationship_store'};
}

sub _relationship_type_store {
    my ( $self, $value ) = @_;

    if ( defined $value ) {
        if ( defined $self->{'_relationship_type_store'} ) {
            $self->throw("_relationship_type_store already defined\n");
        } else {
            $self->{'_relationship_type_store'} = $value;
        }
    }

    return $self->{'_relationship_type_store'};
}

sub _add_relationship_simple {
    my ( $self, $store, $rel, $inverted ) = @_;

    my $subject = $rel->subject_term
        or $self->throw('cannot add relationship, relationship has no subject_term');
    my $object  = $rel->object_term
        or $self->throw('cannot add relationship, relationship has no object_term');

    my ( $parent_id, $child_id ) = ( $object->identifier, $subject->identifier );
    ( $parent_id, $child_id ) = ( $child_id, $parent_id ) if $inverted;

    if (     defined $store->{$parent_id}
         &&  defined $store->{$parent_id}->{$child_id}
         && $store->{$parent_id}->{$child_id}->name ne $rel->predicate_term->name
     ) {
        $self->throw( "relationship "
                . $rel->predicate_term->name
                . " between "
                . $parent_id . " and "
                . $child_id
                . " already defined as "
                . $store->{$parent_id}->{$child_id}->name
                . "\n" );
    }

    # all is well if we get here
    $store->{$parent_id}->{$child_id} = $rel->predicate_term;
}

sub add_relationship {
    my ( $self, $rel ) = @_;

    $self->_add_relationship_simple( $self->_relationship_store,          $rel, 0 );
    $self->_add_relationship_simple( $self->_inverted_relationship_store, $rel, 1 );
    $self->_relationship_type_store->{ $self->_unique_termid( $rel->predicate_term ) } =
        $rel->predicate_term;

    return $rel;
}

sub get_relationships {
    my $self = shift;
    my $term = shift;
    my @rels;
    my $store   = $self->_relationship_store;
    my $relfact = $self->relationship_factory();

    my @parent_ids = $term
        ?

        # if a term is supplied then only get the term's parents
        ( map { $_->identifier(); } $self->get_parent_terms($term) )
        :

        # otherwise use all parent ids
        ( keys %{$store} );

    # add the term as a parent too if one is supplied
    push( @parent_ids, $term->identifier ) if $term;

    foreach my $parent_id (@parent_ids) {
        my $parent_entry = $store->{$parent_id};

        # if a term is supplied, add a relationship for the parent to the term
        # except if the parent is the term itself (we added that one before)
        if ( $term && ( $parent_id ne $term->identifier() ) ) {
            my @parent_terms = $self->get_term_by_identifier($parent_id);
            foreach my $parent_term (@parent_terms) {
                push(
                    @rels,
                    $relfact->create_object(
                        -object_term    => $parent_term,
                        -subject_term   => $term,
                        -predicate_term => $parent_entry->{ $term->identifier },
                        -ontology       => $term->ontology()
                    )
                );
            }

        } else {

            # otherwise, i.e., no term supplied, or the parent equals the
            # supplied term
            my @parent_terms = $term ? ($term) : $self->get_term_by_identifier($parent_id);
            foreach my $child_id ( keys %$parent_entry ) {
                my $rel_info = $parent_entry->{$child_id};
                my ($subj_term) = $self->get_term_by_identifier($child_id);

                foreach my $parent_term (@parent_terms) {
                    push(
                        @rels,
                        $relfact->create_object(
                            -object_term    => $parent_term,
                            -subject_term   => $subj_term,
                            -predicate_term => $rel_info,
                            -ontology       => $parent_term->ontology
                        )
                    );
                }
            }
        }
    }

    return @rels;
}

sub get_all_relationships {
    return shift->get_relationships();
}

sub get_predicate_terms {
    my ($self) = @_;

    return values %{ $self->_relationship_type_store };
}

sub _is_rel_type {
    my ( $self, $term, @rel_types ) = @_;

    foreach my $rel_type (@rel_types) {
        if ( $rel_type->identifier || $term->identifier ) {
            return 1 if $rel_type->identifier eq $term->identifier;
        } else {
            return 1 if $rel_type->name eq $term->name;
        }
    }

    return 0;
}

sub _typed_traversal {
    my ( $self, $rel_store, $level, $term_id, @rel_types ) = @_;
    return if !defined( $rel_store->{$term_id} );
    my %parent_entry = %{ $rel_store->{$term_id} };
    my @children     = keys %parent_entry;

    my @ans;

    if ( @rel_types > 0 ) {
        @ans = ();

        foreach my $child_id (@children) {
            push @ans, $child_id
                if $self->_is_rel_type( $rel_store->{$term_id}->{$child_id}, @rel_types );
        }
    } else {
        @ans = @children;
    }
    if ( $level < 1 ) {
        my @ans1 = ();

        foreach my $child_id (@ans) {
            push @ans1, $self->_typed_traversal( $rel_store, $level - 1, $child_id, @rel_types )
                if defined $rel_store->{$child_id};
        }
        push @ans, @ans1;
    }

    return @ans;
}

sub get_child_terms {
    my ( $self, $term, @relationship_types ) = @_;

    $self->throw("must provide TermI compliant object")
        unless defined($term) && $term->isa("Bio::Ontology::TermI");

    return $self->_filter_unmarked(
        $self->get_term_by_identifier(
            $self->_typed_traversal(
                $self->_relationship_store, 1, $term->identifier, @relationship_types
            )
        )
    );
}

sub get_descendant_terms {
    my ( $self, $term, @relationship_types ) = @_;

    $self->throw("must provide TermI compliant object")
        unless defined($term) && $term->isa("Bio::Ontology::TermI");

    return $self->_filter_unmarked(
        $self->_filter_repeated(
            $self->get_term_by_identifier(
                $self->_typed_traversal(
                    $self->_relationship_store, 0, $term->identifier, @relationship_types
                )
            )
        )
    );
}

sub get_parent_terms {
    my ( $self, $term, @relationship_types ) = @_;
    $self->throw("term must be a valid object, not undef") unless defined $term;

    return $self->_filter_unmarked(
        $self->get_term_by_identifier(
            $self->_typed_traversal(
                $self->_inverted_relationship_store,
                1, $term->identifier, @relationship_types
            )
        )
    );
}

sub get_ancestor_terms {
    my ( $self, $term, @relationship_types ) = @_;
    $self->throw("term must be a valid object, not undef") unless defined $term;

    return $self->_filter_unmarked(
        $self->_filter_repeated(
            $self->get_term_by_identifier(
                $self->_typed_traversal(
                    $self->_inverted_relationship_store, 0,
                    $term->identifier,                   @relationship_types
                )
            )
        )
    );
}

sub get_leaf_terms {
    my ($self) = @_;
    my @leaf_terms;

    foreach my $term ( values %{ $self->_term_store } ) {
        push @leaf_terms, $term
            if !defined $self->_relationship_store->{ $term->identifier }
                && defined $self->_instantiated_terms_store->{ $term->identifier };
    }

    return @leaf_terms;
}

sub get_root_terms {
    my ($self) = @_;
    my @root_terms;

    foreach my $term ( values %{ $self->_term_store } ) {
        push @root_terms, $term
            if !defined $self->_inverted_relationship_store->{ $term->identifier }
                && defined $self->_instantiated_terms_store->{ $term->identifier };
    }

    return @root_terms;
}

sub _filter_repeated {
    my ( $self, @args ) = @_;
    my %h;

    foreach my $element (@args) {
        $h{ $element->identifier } = $element if !defined $h{ $element->identifier };
    }

    return values %h;
}

sub get_all_terms {
    my ($self) = @_;

    return $self->_filter_unmarked( values %{ $self->_term_store } );
}

sub find_terms {
    my ( $self, @args ) = @_;
    my @terms;

    my ( $id, $name ) = $self->_rearrange( [qw(IDENTIFIER NAME)], @args );

    if ( defined($id) ) {
        @terms = $self->get_term_by_identifier($id);
    } else {
        @terms = $self->get_all_terms();
    }
    if ( defined($name) ) {
        @terms = grep { $_->name() eq $name; } @terms;
    }
    return @terms;
}

sub relationship_factory {
    my $self = shift;

    return $self->{'relationship_factory'} = shift if @_;
    return $self->{'relationship_factory'};
}

sub term_factory {
    my $self = shift;

    if (@_) {
        $self->warn(
            "setting term factory, but " . ref($self) . " does not create terms on-the-fly" );
        return $self->{'term_factory'} = shift;
    }
    return $self->{'term_factory'};
}

sub _filter_unmarked {
    my ( $self, @terms ) = @_;
    my @filtered_terms = ();

    if ( scalar(@terms) >= 1 ) {
        foreach my $term (@terms) {
            push @filtered_terms, $term
                if defined $self->_instantiated_terms_store->{ $term->identifier };
        }
    }

    return @filtered_terms;
}

sub remove_term_by_id {
    my ( $self, $id ) = @_;

    if ( $self->get_term_by_identifier($id) ) {
        my $term = $self->{_term_store}->{$id};
        delete $self->{_term_store}->{$id};
        return $term;
    } else {
        $self->warn("Term with id '$id' is not in the term store");
        return;
    }
}

sub to_string {
    my ($self) = @_;
    my $s = "";

    $s .= "-- # Terms:\n";
    $s .= scalar( $self->get_all_terms ) . "\n";
    $s .= "-- # Relationships:\n";
    $s .= $self->_get_number_rels . "\n";

    return $s;
}

sub _unique_termid {
    my $self = shift;
    my $term = shift;

    return $term->identifier() if $term->identifier();
    my $id = $term->ontology->name() if $term->ontology();
    if ($id) {
        $id .= '|';
    } else {
        $id = '';
    }
    $id .= $term->name();
}

#################################################################
# aliases
#################################################################

*get_relationship_types = \&get_predicate_terms;

1;