3 # BioPerl module for Bio::Ontology::SimpleOntologyEngine
5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
7 # Cared for by Peter Dimitrov <dimitrov@gnf.org>
9 # Copyright Peter Dimitrov
10 # (c) Peter Dimitrov, dimitrov@gnf.org, 2002.
11 # (c) GNF, Genomics Institute of the Novartis Research Foundation, 2002.
13 # You may distribute this module under the same terms as perl itself.
14 # Refer to the Perl Artistic License (see the license accompanying this
15 # software package, or see http://www.perl.com/language/misc/Artistic.html)
16 # for the terms under which you may use, modify, and redistribute this module.
18 # THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
19 # WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
20 # MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
22 # POD documentation - main docs before the code
26 Bio::Ontology::SimpleOntologyEngine - Implementation of OntologyEngineI interface
30 my $soe = Bio::Ontology::SimpleOntologyEngine->new;
34 This is a "simple" implementation of Bio::Ontology::OntologyEngineI.
40 User feedback is an integral part of the evolution of this and other
41 Bioperl modules. Send your comments and suggestions preferably to
42 the Bioperl mailing list. Your participation is much appreciated.
44 bioperl-l@bioperl.org - General discussion
45 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
49 Please direct usage questions or support issues to the mailing list:
51 I<bioperl-l@bioperl.org>
53 rather than to the module maintainer directly. Many experienced and
54 reponsive experts will be able look at the problem and quickly
55 address it. Please include a thorough description of the problem
56 with code and data examples if at all possible.
60 Report bugs to the Bioperl bug tracking system to help us keep track
61 of the bugs and their resolution. Bug reports can be submitted via
64 http://bugzilla.open-bio.org/
66 =head1 AUTHOR - Peter Dimitrov
68 Email dimitrov@gnf.org
72 Hilmar Lapp, hlapp at gmx.net
76 The rest of the documentation details each of the object methods.
77 Internal methods are usually preceded with a _
82 # Let the code begin...
85 package Bio
::Ontology
::SimpleOntologyEngine
;
88 use Bio
::Ontology
::RelationshipFactory
;
91 use base
qw(Bio::Root::Root Bio::Ontology::OntologyEngineI);
96 Usage : $soe = Bio::Ontology::SimpleOntologyEngine->new;
97 Function: Initializes the ontology engine.
98 Example : $soe = Bio::Ontology::SimpleOntologyEngine->new;
99 Returns : Object of class SimpleOntologyEngine.
105 my ($class, @args) = @_;
106 my $self = $class->SUPER::new
(@args);
109 $self->_term_store( {} );
110 $self->_relationship_store( {} );
111 $self->_inverted_relationship_store( {} );
112 $self->_relationship_type_store( {} );
113 $self->_instantiated_terms_store( {} );
115 # set defaults for the factories
116 $self->relationship_factory(Bio
::Ontology
::RelationshipFactory
->new(
117 -type
=> "Bio::Ontology::Relationship"));
121 =head2 _instantiated_terms_store
123 Title : _instantiated_terms_store
124 Usage : $obj->_instantiated_terms_store($newval)
132 sub _instantiated_terms_store
{
133 my ($self, $value) = @_;
135 if( defined $value) {
136 $self->{'_instantiated_terms_store'} = $value;
138 return $self->{'_instantiated_terms_store'};
141 =head2 mark_instantiated
143 Title : mark_instantiated
144 Usage : $self->mark_instantiated(TermI terms): TermI
145 Function: Marks TermI objects as fully instantiated,
146 allowing for proper counting of the number of terms in the term store.
147 The TermI objects has to be already stored in the term store in order
149 Example : $self->mark_instantiated($term);
150 Returns : its argument or throws an exception if a term is not
152 Args : array of objects of class TermI.
156 sub mark_instantiated
{
157 my ($self, @terms) = @_;
159 foreach my $term (@terms) {
160 $self->throw( "term ".$term->identifier." not in the term store\n" )
161 if !defined $self->_term_store->{$term->identifier};
162 $self->_instantiated_terms_store->{$term->identifier} = 1;
168 =head2 mark_uninstantiated
170 Title : mark_uninstantiated
171 Usage : $self->mark_uninstantiated(TermI terms): TermI
172 Function: Marks TermI objects as not fully instantiated,
173 Example : $self->mark_uninstantiated($term);
174 Returns : its argument or throws an exception if a term is not
175 in the term store(if the term is not marked it does nothing).
176 Args : array of objects of class TermI.
180 sub mark_uninstantiated
{
181 my ($self, @terms) = @_;
183 foreach my $term (@terms) {
184 $self->throw( "term ".$term->identifier." not in the term store\n" )
185 if !defined $self->_term_store->{$term->identifier};
186 delete $self->_instantiated_terms_store->{$term->identifier}
187 if defined $self->_instantiated_terms_store->{$term->identifier};
196 Usage : $obj->_term_store($newval)
199 Returns : reference to an array of Bio::Ontology::TermI objects
200 Args : reference to an array of Bio::Ontology::TermI objects
205 my ($self, $value) = @_;
207 if( defined $value) {
208 if ( defined $self->{'_term_store'}) {
209 $self->throw("_term_store already defined\n");
212 $self->{'_term_store'} = $value;
216 return $self->{'_term_store'};
222 Usage : add_term(TermI term): TermI
223 Function: Adds TermI object to the ontology engine term store.
224 Marks the term fully instantiated by default.
225 Example : $soe->add_term($term)
226 Returns : its argument.
227 Args : object of class TermI.
232 my ($self, $term) = @_;
233 my $term_store = $self->_term_store;
235 if ( defined $term_store -> {$term->identifier}) {
236 $self->throw( "term ".$term->identifier." already defined\n" );
239 $term_store->{$term->identifier} = $term;
240 $self->_instantiated_terms_store->{$term->identifier} = 1;
246 =head2 get_term_by_identifier
248 Title : get_term_by_identifier
249 Usage : get_term_by_identifier(String id): TermI
250 Function: Retrieves terms from the term store by their identifier
251 field, or an empty list if not there.
252 Example : $term = $soe->get_term_by_identifier("IPR000001");
253 Returns : An array of zero or more Bio::Ontology::TermI objects.
254 Args : An array of identifier strings
258 sub get_term_by_identifier
{
259 my ($self, @ids) = @_;
262 foreach my $id (@ids) {
263 my $term = $self->_term_store->{$id};
264 push @ans, $term if defined $term;
270 =head2 _get_number_rels
272 Title : get_number_rels
281 sub _get_number_rels
{
285 foreach my $entry ($self->_relationship_store) {
286 $num_rels += scalar keys %$entry;
291 =head2 _get_number_terms
293 Title : _get_number_terms
302 sub _get_number_terms
{
305 return scalar $self->_filter_unmarked( values %{$self->_term_store} );
309 =head2 _relationship_store
311 Title : _storerelationship_store
312 Usage : $obj->relationship_store($newval)
315 Returns : reference to an array of Bio::Ontology::TermI objects
316 Args : reference to an array of Bio::Ontology::TermI objects
320 sub _relationship_store
{
321 my ($self, $value) = @_;
323 if( defined $value) {
324 if ( defined $self->{'_relationship_store'}) {
325 $self->throw("_relationship_store already defined\n");
328 $self->{'_relationship_store'} = $value;
332 return $self->{'_relationship_store'};
335 =head2 _inverted_relationship_store
337 Title : _inverted_relationship_store
341 Returns : reference to an array of Bio::Ontology::TermI objects
342 Args : reference to an array of Bio::Ontology::TermI objects
346 sub _inverted_relationship_store
{
347 my ($self, $value) = @_;
349 if( defined $value) {
350 if ( defined $self->{'_inverted_relationship_store'}) {
351 $self->throw("_inverted_relationship_store already defined\n");
354 $self->{'_inverted_relationship_store'} = $value;
358 return $self->{'_inverted_relationship_store'};
361 =head2 _relationship_type_store
363 Title : _relationship_type_store
364 Usage : $obj->_relationship_type_store($newval)
367 Returns : reference to an array of Bio::Ontology::RelationshipType objects
368 Args : reference to an array of Bio::Ontology::RelationshipType objects
372 sub _relationship_type_store
{
373 my ($self, $value) = @_;
375 if( defined $value) {
376 if ( defined $self->{'_relationship_type_store'}) {
377 $self->throw("_relationship_type_store already defined\n");
380 $self->{'_relationship_type_store'} = $value;
384 return $self->{'_relationship_type_store'};
387 =head2 _add_relationship_simple
389 Title : _add_relationship_simple
398 sub _add_relationship_simple
{
399 my ($self, $store, $rel, $inverted) = @_;
402 my $subject = $rel->subject_term;
403 my $object = $rel->object_term;
407 $parent_id = $subject ?
$subject->identifier : '';
408 $child_id = $object ?
$object->identifier : '';
411 $parent_id = $object ?
$object->identifier : '';
412 $child_id = $subject ?
$subject->identifier : '';
414 if(defined $store->{$parent_id} && (defined $store->{$parent_id}->{$child_id}) &&
415 ($store->{$parent_id}->{$child_id}->name != $rel->predicate_term->name)){
416 $self->throw("relationship ".Dumper
($rel->predicate_term).
417 " between ".$parent_id." and ".$child_id.
418 " already defined as ".
419 Dumper
($store->{$parent_id}->{$child_id})."\n");
422 $store->{$parent_id}->{$child_id} = $rel->predicate_term;
426 =head2 add_relationship
428 Title : add_relationship
429 Usage : add_relationship(RelationshipI relationship): RelationshipI
430 Function: Adds a relationship object to the ontology engine.
432 Returns : Its argument.
433 Args : A RelationshipI object.
437 sub add_relationship
{
438 my ($self, $rel) = @_;
440 $self->_add_relationship_simple($self->_relationship_store,
442 $self->_add_relationship_simple($self->_inverted_relationship_store,
444 $self->_relationship_type_store->{
445 $self->_unique_termid($rel->predicate_term)} = $rel->predicate_term;
450 =head2 get_relationships
452 Title : get_relationships
453 Usage : get_relationships(): RelationshipI
454 Function: Retrieves all relationship objects.
456 Returns : Array of RelationshipI objects
461 sub get_relationships
{
465 my $store = $self->_relationship_store;
466 my $relfact = $self->relationship_factory();
468 my @parent_ids = $term ?
469 # if a term is supplied then only get the term's parents
470 (map { $_->identifier(); } $self->get_parent_terms($term)) :
471 # otherwise use all parent ids
473 # add the term as a parent too if one is supplied
474 push(@parent_ids,$term->identifier) if $term;
476 foreach my $parent_id (@parent_ids) {
477 my $parent_entry = $store->{$parent_id};
479 # if a term is supplied, add a relationship for the parent to the term
480 # except if the parent is the term itself (we added that one before)
481 if($term && ($parent_id ne $term->identifier())) {
482 my @parent_terms = $self->get_term_by_identifier($parent_id);
483 foreach my $parent_term (@parent_terms) {
485 $relfact->create_object(-object_term
=> $parent_term,
486 -subject_term
=> $term,
488 $parent_entry->{$term->identifier},
489 -ontology
=> $term->ontology())
494 # otherwise, i.e., no term supplied, or the parent equals the
496 my @parent_terms = $term ?
497 ($term) : $self->get_term_by_identifier($parent_id);
498 foreach my $child_id (keys %$parent_entry) {
499 my $rel_info = $parent_entry->{$child_id};
500 my ($subj_term) = $self->get_term_by_identifier($child_id);
502 foreach my $parent_term (@parent_terms) {
504 $relfact->create_object(-object_term
=> $parent_term,
505 -subject_term
=> $subj_term,
506 -predicate_term
=> $rel_info,
507 -ontology
=>$parent_term->ontology
518 =head2 get_all_relationships
520 Title : get_all_relationships
521 Usage : get_all_relationships(): RelationshipI
522 Function: Retrieves all relationship objects.
524 Returns : Array of RelationshipI objects
529 sub get_all_relationships
{
530 return shift->get_relationships();
533 =head2 get_predicate_terms
535 Title : get_predicate_terms
536 Usage : get_predicate_terms(): TermI
537 Function: Retrives all relationship types stored in the engine
539 Returns : reference to an array of Bio::Ontology::RelationshipType objects
544 sub get_predicate_terms
{
547 return values %{$self->_relationship_type_store};
562 my ($self, $term, @rel_types) = @_;
564 foreach my $rel_type (@rel_types) {
565 if($rel_type->identifier || $term->identifier) {
566 return 1 if $rel_type->identifier eq $term->identifier;
568 return 1 if $rel_type->name eq $term->name;
575 =head2 _typed_traversal
577 Title : _typed_traversal
586 sub _typed_traversal
{
587 my ($self, $rel_store, $level, $term_id, @rel_types) = @_;
588 return if !defined($rel_store->{$term_id});
589 my %parent_entry = %{$rel_store->{$term_id}};
590 my @children = keys %parent_entry;
594 if (@rel_types > 0) {
597 foreach my $child_id (@children) {
599 if $self->_is_rel_type( $rel_store->{$term_id}->{$child_id},
609 foreach my $child_id (@ans) {
610 push @ans1, $self->_typed_traversal($rel_store,
611 $level - 1, $child_id, @rel_types)
612 if defined $rel_store->{$child_id};
620 =head2 get_child_terms
622 Title : get_child_terms
623 Usage : get_child_terms(TermI term, TermI predicate_terms): TermI
624 get_child_terms(TermI term, RelationshipType predicate_terms): TermI
625 Function: Retrieves all child terms of a given term, that satisfy a
626 relationship among those that are specified in the second
627 argument or undef otherwise. get_child_terms is a special
628 case of get_descendant_terms, limiting the search to the
631 Returns : Array of TermI objects.
632 Args : First argument is the term of interest, second is the list of
633 relationship type terms.
638 my ($self, $term, @relationship_types) = @_;
640 $self->throw("must provide TermI compliant object")
641 unless defined($term) && $term->isa("Bio::Ontology::TermI");
643 return $self->_filter_unmarked(
644 $self->get_term_by_identifier(
645 $self->_typed_traversal($self->_relationship_store,
648 @relationship_types) ) );
651 =head2 get_descendant_terms
653 Title : get_descendant_terms
654 Usage : get_descendant_terms(TermI term, TermI rel_types): TermI
655 get_child_terms(TermI term, RelationshipType predicate_terms): TermI
656 Function: Retrieves all descendant terms of a given term, that
657 satisfy a relationship among those that are specified in
658 the second argument or undef otherwise. Uses
659 _typed_traversal to find all descendants.
662 Returns : Array of TermI objects.
663 Args : First argument is the term of interest, second is the list of
664 relationship type terms.
668 sub get_descendant_terms
{
669 my ($self, $term, @relationship_types) = @_;
671 $self->throw("must provide TermI compliant object")
672 unless defined($term) && $term->isa("Bio::Ontology::TermI");
674 return $self->_filter_unmarked(
675 $self->_filter_repeated(
676 $self->get_term_by_identifier(
677 $self->_typed_traversal($self->_relationship_store,
680 @relationship_types) ) ) );
683 =head2 get_parent_terms
685 Title : get_parent_terms
686 Usage : get_parent_terms(TermI term, TermI predicate_terms): TermI
687 get_child_terms(TermI term, RelationshipType predicate_terms): TermI
688 Function: Retrieves all parent terms of a given term, that satisfy a
689 relationship among those that are specified in the second
690 argument or undef otherwise. get_parent_terms is a special
691 case of get_ancestor_terms, limiting the search to the
695 Returns : Array of TermI objects.
696 Args : First argument is the term of interest, second is the list of relationship type terms.
700 sub get_parent_terms
{
701 my ($self, $term, @relationship_types) = @_;
702 $self->throw("term must be a valid object, not undef") unless defined $term;
704 return $self->_filter_unmarked(
705 $self->get_term_by_identifier(
706 $self->_typed_traversal($self->_inverted_relationship_store,
709 @relationship_types) ) );
712 =head2 get_ancestor_terms
714 Title : get_ancestor_terms
715 Usage : get_ancestor_terms(TermI term, TermI predicate_terms): TermI
716 get_child_terms(TermI term, RelationshipType predicate_terms): TermI
717 Function: Retrieves all ancestor terms of a given term, that satisfy
718 a relationship among those that are specified in the second
719 argument or undef otherwise. Uses _typed_traversal to find
723 Returns : Array of TermI objects.
724 Args : First argument is the term of interest, second is the list
725 of relationship type terms.
729 sub get_ancestor_terms
{
730 my ($self, $term, @relationship_types) = @_;
731 $self->throw("term must be a valid object, not undef") unless defined $term;
733 return $self->_filter_unmarked(
734 $self->_filter_repeated(
735 $self->get_term_by_identifier(
736 $self->_typed_traversal($self->_inverted_relationship_store,
739 @relationship_types) ) ) );
742 =head2 get_leaf_terms
744 Title : get_leaf_terms
745 Usage : get_leaf_terms(): TermI
746 Function: Retrieves all leaf terms from the ontology. Leaf term is a term w/o descendants.
747 Example : @leaf_terms = $obj->get_leaf_terms()
748 Returns : Array of TermI objects.
757 foreach my $term (values %{$self->_term_store}) {
758 push @leaf_terms, $term
759 if !defined $self->_relationship_store->{$term->identifier} &&
760 defined $self->_instantiated_terms_store->{$term->identifier};
766 =head2 get_root_terms
768 Title : get_root_terms
769 Usage : get_root_terms(): TermI
770 Function: Retrieves all root terms from the ontology. Root term is a term w/o descendants.
771 Example : @root_terms = $obj->get_root_terms()
772 Returns : Array of TermI objects.
781 foreach my $term (values %{$self->_term_store}) {
782 push @root_terms, $term
783 if !defined $self->_inverted_relationship_store->{$term->identifier} &&
784 defined $self->_instantiated_terms_store->{$term->identifier};
790 =head2 _filter_repeated
792 Title : _filter_repeated
793 Usage : @lst = $self->_filter_repeated(@old_lst);
794 Function: Removes repeated terms
796 Returns : List of unique TermI objects
797 Args : List of TermI objects
801 sub _filter_repeated
{
802 my ($self, @args) = @_;
805 foreach my $element (@args) {
806 $h{$element->identifier} = $element if !defined $h{$element->identifier};
814 Title : get_all_terms
815 Usage : get_all_terms(): TermI
816 Function: Retrieves all terms currently stored in the ontology.
817 Example : @all_terms = $obj->get_all_terms()
818 Returns : Array of TermI objects.
826 return $self->_filter_unmarked( values %{$self->_term_store} );
832 Usage : ($term) = $oe->find_terms(-identifier => "SO:0000263");
833 Function: Find term instances matching queries for their attributes.
835 This implementation can efficiently resolve queries by
839 Returns : an array of zero or more Bio::Ontology::TermI objects
840 Args : Named parameters. The following parameters should be recognized
841 by any implementations:
843 -identifier query by the given identifier
844 -name query by the given name
849 my ($self,@args) = @_;
852 my ($id,$name) = $self->_rearrange([qw(IDENTIFIER NAME)],@args);
855 @terms = $self->get_term_by_identifier($id);
857 @terms = $self->get_all_terms();
860 @terms = grep { $_->name() eq $name; } @terms;
866 =head2 relationship_factory
868 Title : relationship_factory
869 Usage : $fact = $obj->relationship_factory()
870 Function: Get/set the object factory to be used when relationship
871 objects are created by the implementation on-the-fly.
874 Returns : value of relationship_factory (a Bio::Factory::ObjectFactoryI
876 Args : on set, a Bio::Factory::ObjectFactoryI compliant object
880 sub relationship_factory
{
883 return $self->{'relationship_factory'} = shift if @_;
884 return $self->{'relationship_factory'};
890 Usage : $fact = $obj->term_factory()
891 Function: Get/set the object factory to be used when term objects are
892 created by the implementation on-the-fly.
894 Note that this ontology engine implementation does not
895 create term objects on the fly, and therefore setting this
896 attribute is meaningless.
899 Returns : value of term_factory (a Bio::Factory::ObjectFactoryI
901 Args : on set, a Bio::Factory::ObjectFactoryI compliant object
909 $self->warn("setting term factory, but ".ref($self).
910 " does not create terms on-the-fly");
911 return $self->{'term_factory'} = shift;
913 return $self->{'term_factory'};
916 =head2 _filter_unmarked
918 Title : _filter_unmarked
919 Usage : _filter_unmarked(TermI terms): TermI
920 Function: Removes the uninstantiated terms from the list of terms
922 Returns : array of fully instantiated TermI objects
923 Args : array of TermI objects
927 sub _filter_unmarked
{
928 my ($self, @terms) = @_;
929 my @filtered_terms = ();
931 if ( scalar(@terms) >= 1) {
932 foreach my $term (@terms) {
933 push @filtered_terms, $term
934 if defined $self->_instantiated_terms_store->{$term->identifier};
938 return @filtered_terms;
941 =head2 remove_term_by_id
943 Title : remove_term_by_id
944 Usage : remove_term_by_id(String id): TermI
945 Function: Removes TermI object from the ontology engine using the
946 string id as an identifier. Current implementation does not
947 enforce consistency of the relationships using that term.
948 Example : $term = $soe->remove_term_by_id($id);
949 Returns : Object of class TermI or undef if not found.
950 Args : The string identifier of a term.
954 sub remove_term_by_id
{
955 my ($self, $id) = @_;
957 if ( $self->get_term_by_identifier($id) ) {
958 my $term = $self->{_term_store
}->{$id};
959 delete $self->{_term_store
}->{$id};
963 $self->warn("Term with id '$id' is not in the term store");
971 Usage : print $sv->to_string();
972 Function: Currently returns formatted string containing the number of
973 terms and number of relationships from the ontology engine.
974 Example : print $sv->to_string();
984 $s .= "-- # Terms:\n";
985 $s .= scalar($self->get_all_terms)."\n";
986 $s .= "-- # Relationships:\n";
987 $s .= $self->_get_number_rels."\n";
992 =head2 _unique_termid
994 Title : _unique_termid
996 Function: Returns a string that can be used as ID using fail-over
999 If the identifier attribute is not set, it uses the
1000 combination of name and ontology name, provided both are
1001 set. If they are not, it returns the name alone.
1003 Note that this is a private method. Call from inheriting
1004 classes but not from outside.
1008 Args : a Bio::Ontology::TermI compliant object
1016 return $term->identifier() if $term->identifier();
1017 my $id = $term->ontology->name() if $term->ontology();
1023 $id .= $term->name();
1027 #################################################################
1029 #################################################################
1031 *get_relationship_types
= \
&get_predicate_terms
;