2 # BioPerl module for Bio::Ontology::SimpleOntologyEngine
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
6 # Cared for by Peter Dimitrov <dimitrov@gnf.org>
8 # Copyright Peter Dimitrov
9 # (c) Peter Dimitrov, dimitrov@gnf.org, 2002.
10 # (c) GNF, Genomics Institute of the Novartis Research Foundation, 2002.
12 # You may distribute this module under the same terms as perl itself.
13 # Refer to the Perl Artistic License (see the license accompanying this
14 # software package, or see http://www.perl.com/language/misc/Artistic.html)
15 # for the terms under which you may use, modify, and redistribute this module.
17 # THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
18 # WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
19 # MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
21 # POD documentation - main docs before the code
25 Bio::Ontology::SimpleOntologyEngine - Implementation of OntologyEngineI interface
29 my $soe = Bio::Ontology::SimpleOntologyEngine->new;
33 This is a "simple" implementation of Bio::Ontology::OntologyEngineI.
39 User feedback is an integral part of the evolution of this and other
40 Bioperl modules. Send your comments and suggestions preferably to
41 the Bioperl mailing list. Your participation is much appreciated.
43 bioperl-l@bioperl.org - General discussion
44 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
48 Please direct usage questions or support issues to the mailing list:
50 I<bioperl-l@bioperl.org>
52 rather than to the module maintainer directly. Many experienced and
53 reponsive experts will be able look at the problem and quickly
54 address it. Please include a thorough description of the problem
55 with code and data examples if at all possible.
59 Report bugs to the Bioperl bug tracking system to help us keep track
60 of the bugs and their resolution. Bug reports can be submitted via
63 https://github.com/bioperl/bioperl-live/issues
65 =head1 AUTHOR - Peter Dimitrov
67 Email dimitrov@gnf.org
71 Hilmar Lapp, hlapp at gmx.net
75 The rest of the documentation details each of the object methods.
76 Internal methods are usually preceded with a _
80 # Let the code begin...
82 package Bio
::Ontology
::SimpleOntologyEngine
;
85 use Bio
::Ontology
::RelationshipFactory
;
88 use base
qw(Bio::Root::Root Bio::Ontology::OntologyEngineI);
93 Usage : $soe = Bio::Ontology::SimpleOntologyEngine->new;
94 Function: Initializes the ontology engine.
95 Example : $soe = Bio::Ontology::SimpleOntologyEngine->new;
96 Returns : Object of class SimpleOntologyEngine.
102 my ( $class, @args ) = @_;
103 my $self = $class->SUPER::new
(@args);
107 $self->_term_store( {} );
108 $self->_relationship_store( {} );
109 $self->_inverted_relationship_store( {} );
110 $self->_relationship_type_store( {} );
111 $self->_instantiated_terms_store( {} );
113 # set defaults for the factories
114 $self->relationship_factory(
115 Bio
::Ontology
::RelationshipFactory
->new( -type
=> "Bio::Ontology::Relationship" ) );
119 =head2 _instantiated_terms_store
121 Title : _instantiated_terms_store
122 Usage : $obj->_instantiated_terms_store($newval)
130 sub _instantiated_terms_store
{
131 my ( $self, $value ) = @_;
133 if ( defined $value ) {
134 $self->{'_instantiated_terms_store'} = $value;
136 return $self->{'_instantiated_terms_store'};
139 =head2 mark_instantiated
141 Title : mark_instantiated
142 Usage : $self->mark_instantiated(TermI terms): TermI
143 Function: Marks TermI objects as fully instantiated,
144 allowing for proper counting of the number of terms in the term store.
145 The TermI objects has to be already stored in the term store in order
147 Example : $self->mark_instantiated($term);
148 Returns : its argument or throws an exception if a term is not
150 Args : array of objects of class TermI.
154 sub mark_instantiated
{
155 my ( $self, @terms ) = @_;
157 foreach my $term (@terms) {
158 $self->throw( "term " . $term->identifier . " not in the term store\n" )
159 if !defined $self->_term_store->{ $term->identifier };
160 $self->_instantiated_terms_store->{ $term->identifier } = 1;
166 =head2 mark_uninstantiated
168 Title : mark_uninstantiated
169 Usage : $self->mark_uninstantiated(TermI terms): TermI
170 Function: Marks TermI objects as not fully instantiated,
171 Example : $self->mark_uninstantiated($term);
172 Returns : its argument or throws an exception if a term is not
173 in the term store(if the term is not marked it does nothing).
174 Args : array of objects of class TermI.
178 sub mark_uninstantiated
{
179 my ( $self, @terms ) = @_;
181 foreach my $term (@terms) {
182 $self->throw( "term " . $term->identifier . " not in the term store\n" )
183 if !defined $self->_term_store->{ $term->identifier };
184 delete $self->_instantiated_terms_store->{ $term->identifier }
185 if defined $self->_instantiated_terms_store->{ $term->identifier };
194 Usage : $obj->_term_store($newval)
197 Returns : reference to an array of Bio::Ontology::TermI objects
198 Args : reference to an array of Bio::Ontology::TermI objects
203 my ( $self, $value ) = @_;
205 if ( defined $value ) {
206 if ( defined $self->{'_term_store'} ) {
207 $self->throw("_term_store already defined\n");
209 $self->{'_term_store'} = $value;
213 return $self->{'_term_store'};
219 Usage : add_term(TermI term): TermI
220 Function: Adds TermI object to the ontology engine term store.
221 Marks the term fully instantiated by default.
222 Example : $soe->add_term($term)
223 Returns : its argument.
224 Args : object of class TermI.
229 my ( $self, $term ) = @_;
230 my $term_store = $self->_term_store;
232 if ( defined $term_store->{ $term->identifier } && $self->_instantiated_terms_store->{ $term->identifier }) {
233 $self->throw( "term " . $term->identifier . " already defined\n" );
235 $term_store->{ $term->identifier } = $term;
236 $self->_instantiated_terms_store->{ $term->identifier } = 1;
242 =head2 get_term_by_identifier
244 Title : get_term_by_identifier
245 Usage : get_term_by_identifier(String id): TermI
246 Function: Retrieves terms from the term store by their identifier
247 field, or an empty list if not there.
248 Example : $term = $soe->get_term_by_identifier("IPR000001");
249 Returns : An array of zero or more Bio::Ontology::TermI objects.
250 Args : An array of identifier strings
254 sub get_term_by_identifier
{
255 my ( $self, @ids ) = @_;
258 foreach my $id (@ids) {
259 my $term = $self->_term_store->{$id};
260 push @ans, $term if defined $term;
266 =head2 _get_number_rels
268 Title : get_number_rels
277 sub _get_number_rels
{
281 foreach my $entry ( $self->_relationship_store ) {
282 $num_rels += scalar keys %$entry;
287 =head2 _get_number_terms
289 Title : _get_number_terms
298 sub _get_number_terms
{
301 return scalar $self->_filter_unmarked( values %{ $self->_term_store } );
305 =head2 _relationship_store
307 Title : _storerelationship_store
308 Usage : $obj->relationship_store($newval)
311 Returns : reference to an array of Bio::Ontology::TermI objects
312 Args : reference to an array of Bio::Ontology::TermI objects
316 sub _relationship_store
{
317 my ( $self, $value ) = @_;
319 if ( defined $value ) {
320 if ( defined $self->{'_relationship_store'} ) {
321 $self->throw("_relationship_store already defined\n");
323 $self->{'_relationship_store'} = $value;
327 return $self->{'_relationship_store'};
330 =head2 _inverted_relationship_store
332 Title : _inverted_relationship_store
336 Returns : reference to an array of Bio::Ontology::TermI objects
337 Args : reference to an array of Bio::Ontology::TermI objects
341 sub _inverted_relationship_store
{
342 my ( $self, $value ) = @_;
344 if ( defined $value ) {
345 if ( defined $self->{'_inverted_relationship_store'} ) {
346 $self->throw("_inverted_relationship_store already defined\n");
348 $self->{'_inverted_relationship_store'} = $value;
352 return $self->{'_inverted_relationship_store'};
355 =head2 _relationship_type_store
357 Title : _relationship_type_store
358 Usage : $obj->_relationship_type_store($newval)
361 Returns : reference to an array of Bio::Ontology::RelationshipType objects
362 Args : reference to an array of Bio::Ontology::RelationshipType objects
366 sub _relationship_type_store
{
367 my ( $self, $value ) = @_;
369 if ( defined $value ) {
370 if ( defined $self->{'_relationship_type_store'} ) {
371 $self->throw("_relationship_type_store already defined\n");
373 $self->{'_relationship_type_store'} = $value;
377 return $self->{'_relationship_type_store'};
380 =head2 _add_relationship_simple
382 Title : _add_relationship_simple
391 sub _add_relationship_simple
{
392 my ( $self, $store, $rel, $inverted ) = @_;
394 my $subject = $rel->subject_term
395 or $self->throw('cannot add relationship, relationship has no subject_term');
396 my $object = $rel->object_term
397 or $self->throw('cannot add relationship, relationship has no object_term');
399 my ( $parent_id, $child_id ) = ( $object->identifier, $subject->identifier );
400 ( $parent_id, $child_id ) = ( $child_id, $parent_id ) if $inverted;
402 if ( defined $store->{$parent_id}
403 && defined $store->{$parent_id}->{$child_id}
404 && $store->{$parent_id}->{$child_id}->name ne $rel->predicate_term->name
406 $self->throw( "relationship "
407 . $rel->predicate_term->name
409 . $parent_id . " and "
411 . " already defined as "
412 . $store->{$parent_id}->{$child_id}->name
416 # all is well if we get here
417 $store->{$parent_id}->{$child_id} = $rel->predicate_term;
420 =head2 add_relationship
422 Title : add_relationship
423 Usage : add_relationship(RelationshipI relationship): RelationshipI
424 Function: Adds a relationship object to the ontology engine.
426 Returns : Its argument.
427 Args : A RelationshipI object.
431 sub add_relationship
{
432 my ( $self, $rel ) = @_;
434 $self->_add_relationship_simple( $self->_relationship_store, $rel, 0 );
435 $self->_add_relationship_simple( $self->_inverted_relationship_store, $rel, 1 );
436 $self->_relationship_type_store->{ $self->_unique_termid( $rel->predicate_term ) } =
437 $rel->predicate_term;
442 =head2 get_relationships
444 Title : get_relationships
445 Usage : get_relationships(): RelationshipI
446 Function: Retrieves all relationship objects.
448 Returns : Array of RelationshipI objects
453 sub get_relationships
{
457 my $store = $self->_relationship_store;
458 my $relfact = $self->relationship_factory();
460 my @parent_ids = $term
463 # if a term is supplied then only get the term's parents
464 ( map { $_->identifier(); } $self->get_parent_terms($term) )
467 # otherwise use all parent ids
470 # add the term as a parent too if one is supplied
471 push( @parent_ids, $term->identifier ) if $term;
473 foreach my $parent_id (@parent_ids) {
474 my $parent_entry = $store->{$parent_id};
476 # if a term is supplied, add a relationship for the parent to the term
477 # except if the parent is the term itself (we added that one before)
478 if ( $term && ( $parent_id ne $term->identifier() ) ) {
479 my @parent_terms = $self->get_term_by_identifier($parent_id);
480 foreach my $parent_term (@parent_terms) {
483 $relfact->create_object(
484 -object_term
=> $parent_term,
485 -subject_term
=> $term,
486 -predicate_term
=> $parent_entry->{ $term->identifier },
487 -ontology
=> $term->ontology()
494 # otherwise, i.e., no term supplied, or the parent equals the
496 my @parent_terms = $term ?
($term) : $self->get_term_by_identifier($parent_id);
497 foreach my $child_id ( keys %$parent_entry ) {
498 my $rel_info = $parent_entry->{$child_id};
499 my ($subj_term) = $self->get_term_by_identifier($child_id);
501 foreach my $parent_term (@parent_terms) {
504 $relfact->create_object(
505 -object_term
=> $parent_term,
506 -subject_term
=> $subj_term,
507 -predicate_term
=> $rel_info,
508 -ontology
=> $parent_term->ontology
519 =head2 get_all_relationships
521 Title : get_all_relationships
522 Usage : get_all_relationships(): RelationshipI
523 Function: Retrieves all relationship objects.
525 Returns : Array of RelationshipI objects
530 sub get_all_relationships
{
531 return shift->get_relationships();
534 =head2 get_predicate_terms
536 Title : get_predicate_terms
537 Usage : get_predicate_terms(): TermI
538 Function: Retrives all relationship types stored in the engine
540 Returns : reference to an array of Bio::Ontology::RelationshipType objects
545 sub get_predicate_terms
{
548 return values %{ $self->_relationship_type_store };
563 my ( $self, $term, @rel_types ) = @_;
565 foreach my $rel_type (@rel_types) {
566 if ( $rel_type->identifier || $term->identifier ) {
567 return 1 if $rel_type->identifier eq $term->identifier;
569 return 1 if $rel_type->name eq $term->name;
576 =head2 _typed_traversal
578 Title : _typed_traversal
587 sub _typed_traversal
{
588 my ( $self, $rel_store, $level, $term_id, @rel_types ) = @_;
589 return if !defined( $rel_store->{$term_id} );
590 my %parent_entry = %{ $rel_store->{$term_id} };
591 my @children = keys %parent_entry;
595 if ( @rel_types > 0 ) {
598 foreach my $child_id (@children) {
600 if $self->_is_rel_type( $rel_store->{$term_id}->{$child_id}, @rel_types );
608 foreach my $child_id (@ans) {
609 push @ans1, $self->_typed_traversal( $rel_store, $level - 1, $child_id, @rel_types )
610 if defined $rel_store->{$child_id};
618 =head2 get_child_terms
620 Title : get_child_terms
621 Usage : get_child_terms(TermI term, TermI predicate_terms): TermI
622 get_child_terms(TermI term, RelationshipType predicate_terms): TermI
623 Function: Retrieves all child terms of a given term, that satisfy a
624 relationship among those that are specified in the second
625 argument or undef otherwise. get_child_terms is a special
626 case of get_descendant_terms, limiting the search to the
629 Returns : Array of TermI objects.
630 Args : First argument is the term of interest, second is the list of
631 relationship type terms.
635 sub get_child_terms
{
636 my ( $self, $term, @relationship_types ) = @_;
638 $self->throw("must provide TermI compliant object")
639 unless defined($term) && $term->isa("Bio::Ontology::TermI");
641 return $self->_filter_unmarked(
642 $self->get_term_by_identifier(
643 $self->_typed_traversal(
644 $self->_relationship_store, 1, $term->identifier, @relationship_types
650 =head2 get_descendant_terms
652 Title : get_descendant_terms
653 Usage : get_descendant_terms(TermI term, TermI rel_types): TermI
654 get_child_terms(TermI term, RelationshipType predicate_terms): TermI
655 Function: Retrieves all descendant terms of a given term, that
656 satisfy a relationship among those that are specified in
657 the second argument or undef otherwise. Uses
658 _typed_traversal to find all descendants.
661 Returns : Array of TermI objects.
662 Args : First argument is the term of interest, second is the list of
663 relationship type terms.
667 sub get_descendant_terms
{
668 my ( $self, $term, @relationship_types ) = @_;
670 $self->throw("must provide TermI compliant object")
671 unless defined($term) && $term->isa("Bio::Ontology::TermI");
673 return $self->_filter_unmarked(
674 $self->_filter_repeated(
675 $self->get_term_by_identifier(
676 $self->_typed_traversal(
677 $self->_relationship_store, 0, $term->identifier, @relationship_types
684 =head2 get_parent_terms
686 Title : get_parent_terms
687 Usage : get_parent_terms(TermI term, TermI predicate_terms): TermI
688 get_child_terms(TermI term, RelationshipType predicate_terms): TermI
689 Function: Retrieves all parent terms of a given term, that satisfy a
690 relationship among those that are specified in the second
691 argument or undef otherwise. get_parent_terms is a special
692 case of get_ancestor_terms, limiting the search to the
696 Returns : Array of TermI objects.
697 Args : First argument is the term of interest, second is the list of relationship type terms.
701 sub get_parent_terms
{
702 my ( $self, $term, @relationship_types ) = @_;
703 $self->throw("term must be a valid object, not undef") unless defined $term;
705 return $self->_filter_unmarked(
706 $self->get_term_by_identifier(
707 $self->_typed_traversal(
708 $self->_inverted_relationship_store,
709 1, $term->identifier, @relationship_types
715 =head2 get_ancestor_terms
717 Title : get_ancestor_terms
718 Usage : get_ancestor_terms(TermI term, TermI predicate_terms): TermI
719 get_child_terms(TermI term, RelationshipType predicate_terms): TermI
720 Function: Retrieves all ancestor terms of a given term, that satisfy
721 a relationship among those that are specified in the second
722 argument or undef otherwise. Uses _typed_traversal to find
726 Returns : Array of TermI objects.
727 Args : First argument is the term of interest, second is the list
728 of relationship type terms.
732 sub get_ancestor_terms
{
733 my ( $self, $term, @relationship_types ) = @_;
734 $self->throw("term must be a valid object, not undef") unless defined $term;
736 return $self->_filter_unmarked(
737 $self->_filter_repeated(
738 $self->get_term_by_identifier(
739 $self->_typed_traversal(
740 $self->_inverted_relationship_store, 0,
741 $term->identifier, @relationship_types
748 =head2 get_leaf_terms
750 Title : get_leaf_terms
751 Usage : get_leaf_terms(): TermI
752 Function: Retrieves all leaf terms from the ontology. Leaf term is a term w/o descendants.
753 Example : @leaf_terms = $obj->get_leaf_terms()
754 Returns : Array of TermI objects.
763 foreach my $term ( values %{ $self->_term_store } ) {
764 push @leaf_terms, $term
765 if !defined $self->_relationship_store->{ $term->identifier }
766 && defined $self->_instantiated_terms_store->{ $term->identifier };
772 =head2 get_root_terms
774 Title : get_root_terms
775 Usage : get_root_terms(): TermI
776 Function: Retrieves all root terms from the ontology. Root term is a term w/o descendants.
777 Example : @root_terms = $obj->get_root_terms()
778 Returns : Array of TermI objects.
787 foreach my $term ( values %{ $self->_term_store } ) {
788 push @root_terms, $term
789 if !defined $self->_inverted_relationship_store->{ $term->identifier }
790 && defined $self->_instantiated_terms_store->{ $term->identifier };
796 =head2 _filter_repeated
798 Title : _filter_repeated
799 Usage : @lst = $self->_filter_repeated(@old_lst);
800 Function: Removes repeated terms
802 Returns : List of unique TermI objects
803 Args : List of TermI objects
807 sub _filter_repeated
{
808 my ( $self, @args ) = @_;
811 foreach my $element (@args) {
812 $h{ $element->identifier } = $element if !defined $h{ $element->identifier };
820 Title : get_all_terms
821 Usage : get_all_terms(): TermI
822 Function: Retrieves all terms currently stored in the ontology.
823 Example : @all_terms = $obj->get_all_terms()
824 Returns : Array of TermI objects.
832 return $self->_filter_unmarked( values %{ $self->_term_store } );
838 Usage : ($term) = $oe->find_terms(-identifier => "SO:0000263");
839 Function: Find term instances matching queries for their attributes.
841 This implementation can efficiently resolve queries by
845 Returns : an array of zero or more Bio::Ontology::TermI objects
846 Args : Named parameters. The following parameters should be recognized
847 by any implementations:
849 -identifier query by the given identifier
850 -name query by the given name
855 my ( $self, @args ) = @_;
858 my ( $id, $name ) = $self->_rearrange( [qw(IDENTIFIER NAME)], @args );
860 if ( defined($id) ) {
861 @terms = $self->get_term_by_identifier($id);
863 @terms = $self->get_all_terms();
865 if ( defined($name) ) {
866 @terms = grep { $_->name() eq $name; } @terms;
871 =head2 relationship_factory
873 Title : relationship_factory
874 Usage : $fact = $obj->relationship_factory()
875 Function: Get/set the object factory to be used when relationship
876 objects are created by the implementation on-the-fly.
879 Returns : value of relationship_factory (a Bio::Factory::ObjectFactoryI
881 Args : on set, a Bio::Factory::ObjectFactoryI compliant object
885 sub relationship_factory
{
888 return $self->{'relationship_factory'} = shift if @_;
889 return $self->{'relationship_factory'};
895 Usage : $fact = $obj->term_factory()
896 Function: Get/set the object factory to be used when term objects are
897 created by the implementation on-the-fly.
899 Note that this ontology engine implementation does not
900 create term objects on the fly, and therefore setting this
901 attribute is meaningless.
904 Returns : value of term_factory (a Bio::Factory::ObjectFactoryI
906 Args : on set, a Bio::Factory::ObjectFactoryI compliant object
915 "setting term factory, but " . ref($self) . " does not create terms on-the-fly" );
916 return $self->{'term_factory'} = shift;
918 return $self->{'term_factory'};
921 =head2 _filter_unmarked
923 Title : _filter_unmarked
924 Usage : _filter_unmarked(TermI terms): TermI
925 Function: Removes the uninstantiated terms from the list of terms
927 Returns : array of fully instantiated TermI objects
928 Args : array of TermI objects
932 sub _filter_unmarked
{
933 my ( $self, @terms ) = @_;
934 my @filtered_terms = ();
936 if ( scalar(@terms) >= 1 ) {
937 foreach my $term (@terms) {
938 push @filtered_terms, $term
939 if defined $self->_instantiated_terms_store->{ $term->identifier };
943 return @filtered_terms;
946 =head2 remove_term_by_id
948 Title : remove_term_by_id
949 Usage : remove_term_by_id(String id): TermI
950 Function: Removes TermI object from the ontology engine using the
951 string id as an identifier. Current implementation does not
952 enforce consistency of the relationships using that term.
953 Example : $term = $soe->remove_term_by_id($id);
954 Returns : Object of class TermI or undef if not found.
955 Args : The string identifier of a term.
959 sub remove_term_by_id
{
960 my ( $self, $id ) = @_;
962 if ( $self->get_term_by_identifier($id) ) {
963 my $term = $self->{_term_store
}->{$id};
964 delete $self->{_term_store
}->{$id};
967 $self->warn("Term with id '$id' is not in the term store");
975 Usage : print $sv->to_string();
976 Function: Currently returns formatted string containing the number of
977 terms and number of relationships from the ontology engine.
978 Example : print $sv->to_string();
988 $s .= "-- # Terms:\n";
989 $s .= scalar( $self->get_all_terms ) . "\n";
990 $s .= "-- # Relationships:\n";
991 $s .= $self->_get_number_rels . "\n";
996 =head2 _unique_termid
998 Title : _unique_termid
1000 Function: Returns a string that can be used as ID using fail-over
1003 If the identifier attribute is not set, it uses the
1004 combination of name and ontology name, provided both are
1005 set. If they are not, it returns the name alone.
1007 Note that this is a private method. Call from inheriting
1008 classes but not from outside.
1012 Args : a Bio::Ontology::TermI compliant object
1016 sub _unique_termid
{
1020 return $term->identifier() if $term->identifier();
1021 my $id = $term->ontology->name() if $term->ontology();
1027 $id .= $term->name();
1030 #################################################################
1032 #################################################################
1034 *get_relationship_types
= \
&get_predicate_terms
;