Bio/Ontology/OntologyEngineI.pm

   1 #
   2 # BioPerl module for OntologyEngineI
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Peter Dimitrov <dimitrov@gnf.org>
   7 #
   8 # (c) Peter Dimitrov
   9 # (c) GNF, Genomics Institute of the Novartis Research Foundation, 2002.
  10 #
  11 # You may distribute this module under the same terms as perl itself.
  12 # Refer to the Perl Artistic License (see the license accompanying this
  13 # software package, or see http://www.perl.com/language/misc/Artistic.html)
  14 # for the terms under which you may use, modify, and redistribute this module.
  15 #
  16 # THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
  17 # WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  18 # MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  19 #
  20 # You may distribute this module under the same terms as perl itself
  21
  22 # POD documentation - main docs before the code
  23
  24 =head1 NAME
  25
  26 Bio::Ontology::OntologyEngineI - Interface a minimal Ontology implementation should satisfy
  27
  28 =head1 SYNOPSIS
  29
  30     # see documentation of methods
  31
  32 =head1 DESCRIPTION
  33
  34 This describes the minimal interface an ontology query engine should
  35 provide.  It intentionally does not make explicit references to the
  36 ontology being a DAG, nor does it mandate that the ontology be a
  37 vocabulary. Rather, it tries to generically express what should be
  38 accessible (queriable) about an ontology.
  39
  40 The idea is to allow for different implementations for different
  41 purposes, which may then differ as to which operations are efficient
  42 and which are not, and how much richer the functionality is on top of
  43 this minimalistic set of methods. Check modules in the Bio::Ontology
  44 namespace to find out which implementations exist. At the time of
  45 writing, there is a SimpleOntologyEngine (which does not use
  46 Graph.pm), and a Graph.pm-based implementation in SimpleGOEngine.
  47
  48 Ontology parsers in Bio::OntologyIO are required to return an
  49 implementation of this interface.
  50
  51 =head1 FEEDBACK
  52
  53 =head2 Mailing Lists
  54
  55 User feedback is an integral part of the evolution of this and other
  56 Bioperl modules. Send your comments and suggestions preferably to
  57 the Bioperl mailing list.  Your participation is much appreciated.
  58
  59   bioperl-l@bioperl.org                  - General discussion
  60   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  61
  62 =head2 Support
  63
  64 Please direct usage questions or support issues to the mailing list:
  65
  66 I<bioperl-l@bioperl.org>
  67
  68 rather than to the module maintainer directly. Many experienced and
  69 reponsive experts will be able look at the problem and quickly
  70 address it. Please include a thorough description of the problem
  71 with code and data examples if at all possible.
  72
  73 =head2 Reporting Bugs
  74
  75 Report bugs to the Bioperl bug tracking system to help us keep track
  76 of the bugs and their resolution. Bug reports can be submitted via
  77 the web:
  78
  79   https://github.com/bioperl/bioperl-live/issues
  80
  81 =head1 AUTHOR - Peter Dimitrov
  82
  83 Email dimitrov@gnf.org
  84
  85 =head1 APPENDIX
  86
  87 The rest of the documentation details each of the object methods.
  88 Internal methods are usually preceded with a _
  89
  90 =cut
  91
  92
  93 # Let the code begin...
  94
  95
  96 package Bio::Ontology::OntologyEngineI;
  97 use strict;
  98 use Carp;
  99
 100 use base qw(Bio::Root::RootI);
 101
 102 =head2 add_term
 103
 104  Title   : add_term
 105  Usage   : add_term(TermI term): TermI
 106  Function: Adds TermI object to the ontology engine term store
 107  Example : $oe->add_term($term)
 108  Returns : its argument.
 109  Args    : object of class TermI.
 110
 111 =cut
 112
 113 sub add_term{
 114     shift->throw_not_implemented();
 115 }
 116
 117 =head2 add_relationship
 118
 119  Title   : add_relationship
 120  Usage   : add_relationship(RelationshipI relationship): RelationshipI
 121  Function: Adds a relationship object to the ontology engine.
 122  Example :
 123  Returns : Its argument.
 124  Args    : A RelationshipI object.
 125
 126 =cut
 127
 128 sub add_relationship{
 129     shift->throw_not_implemented();
 130 }
 131
 132 =head2 add_relationship_type
 133
 134  Title   : add_relationship_type
 135  Usage   : add_relationship_type(scalar,OntologyI ontology)
 136  Function: Adds a relationshiptype object to the ontology engine.
 137  Example :
 138  Returns : 1 on success, undef on failure
 139  Args    : The name(scalar) of the relationshiptype, and the OntologyI
 140            it is to be added to.
 141
 142 =cut
 143
 144 sub add_relationship_type{
 145     shift->throw_not_implemented();
 146 }
 147
 148 =head2 get_relationship_type
 149
 150  Title   : get_relationship_type
 151  Usage   : get_relationship_type(scalar): RelationshipTypeI
 152  Function: Get a relationshiptype object from the ontology engine.
 153  Example :
 154  Returns : A RelationshipTypeI object.
 155  Args    : The name (scalar) of the RelationshipTypeI object desired.
 156
 157 =cut
 158
 159 sub get_relationship_type{
 160     shift->throw_not_implemented();
 161 }
 162
 163 =head2 get_relationships
 164
 165  Title   : get_relationships
 166  Usage   : get_relationships(TermI term): RelationshipI
 167  Function: Retrieves all relationship objects from this ontology engine,
 168            or all relationships of a term if a term is supplied.
 169  Example :
 170  Returns : Array of Bio::Ontology::RelationshipI objects
 171  Args    : None, or a Bio::Ontology::TermI compliant object for which
 172            to retrieve the relationships.
 173
 174 =cut
 175
 176 sub get_relationships{
 177     shift->throw_not_implemented();
 178 }
 179
 180 =head2 get_predicate_terms
 181
 182  Title   : get_predicate_terms
 183  Usage   : get_predicate_terms(): TermI
 184  Function:
 185  Example :
 186  Returns :
 187  Args    :
 188
 189 =cut
 190
 191 sub get_predicate_terms{
 192     shift->throw_not_implemented();
 193 }
 194
 195 =head2 get_child_terms
 196
 197  Title   : get_child_terms
 198  Usage   : get_child_terms(TermI term, TermI predicate_terms): TermI
 199  Function: Retrieves all child terms of a given term, that satisfy a
 200            relationship among those that are specified in the second
 201            argument or undef otherwise. get_child_terms is a special
 202            case of get_descendant_terms, limiting the search to the
 203            direct descendants.
 204
 205  Example :
 206  Returns : Array of TermI objects.
 207  Args    : First argument is the term of interest, second is the list
 208            of relationship type terms.
 209
 210 =cut
 211
 212 sub get_child_terms{
 213     shift->throw_not_implemented();
 214 }
 215
 216 =head2 get_descendant_terms
 217
 218  Title   : get_descendant_terms
 219  Usage   : get_descendant_terms(TermI term, TermI rel_types): TermI
 220  Function: Retrieves all descendant terms of a given term, that
 221            satisfy a relationship among those that are specified in
 222            the second argument or undef otherwise.
 223  Example :
 224  Returns : Array of TermI objects.
 225  Args    : First argument is the term of interest, second is the list
 226            of relationship type terms.
 227
 228 =cut
 229
 230 sub get_descendant_terms{
 231     shift->throw_not_implemented();
 232 }
 233
 234 =head2 get_parent_terms
 235
 236  Title   : get_parent_terms
 237  Usage   : get_parent_terms(TermI term, TermI predicate_terms): TermI
 238  Function: Retrieves all parent terms of a given term, that satisfy a
 239            relationship among those that are specified in the second
 240            argument or undef otherwise. get_parent_terms is a special
 241            case of get_ancestor_terms, limiting the search to the
 242            direct ancestors.
 243
 244  Example :
 245  Returns : Array of TermI objects.
 246  Args    : First argument is the term of interest, second is the list
 247            of relationship type terms.
 248
 249 =cut
 250
 251 sub get_parent_terms{
 252     shift->throw_not_implemented();
 253 }
 254
 255 =head2 get_ancestor_terms
 256
 257  Title   : get_ancestor_terms
 258  Usage   : get_ancestor_terms(TermI term, TermI predicate_terms): TermI
 259  Function: Retrieves all ancestor terms of a given term, that satisfy
 260            a relationship among those that are specified in the second
 261            argument or undef otherwise.
 262
 263  Example :
 264  Returns : Array of TermI objects.
 265  Args    : First argument is the term of interest, second is the list
 266            of relationship type terms.
 267
 268 =cut
 269
 270 sub get_ancestor_terms{
 271     shift->throw_not_implemented();
 272 }
 273
 274 =head2 get_leaf_terms
 275
 276  Title   : get_leaf_terms
 277  Usage   : get_leaf_terms(): TermI
 278  Function: Retrieves all leaf terms from the ontology. Leaf term is a
 279            term w/o descendants.
 280
 281  Example : @leaf_terms = $obj->get_leaf_terms()
 282  Returns : Array of TermI objects.
 283  Args    :
 284
 285 =cut
 286
 287 sub get_leaf_terms{
 288     shift->throw_not_implemented();
 289 }
 290
 291 =head2 get_root_terms
 292
 293  Title   : get_root_terms
 294  Usage   : get_root_terms(): TermI
 295  Function: Retrieves all root terms from the ontology. Root term is a
 296            term w/o ancestors.
 297
 298  Example : @root_terms = $obj->get_root_terms()
 299  Returns : Array of TermI objects.
 300  Args    :
 301
 302 =cut
 303
 304 sub get_root_terms{
 305     shift->throw_not_implemented();
 306 }
 307
 308 =head1 Factory for relationships and terms
 309
 310 =cut
 311
 312 =head2 relationship_factory
 313
 314  Title   : relationship_factory
 315  Usage   : $fact = $obj->relationship_factory()
 316  Function: Get (and set, if the implementation supports it) the object
 317            factory to be used when relationship objects are created by
 318            the implementation on-the-fly.
 319
 320  Example :
 321  Returns : value of relationship_factory (a Bio::Factory::ObjectFactory
 322            compliant object)
 323  Args    :
 324
 325 =cut
 326
 327 sub relationship_factory{
 328     return shift->throw_not_implemented();
 329 }
 330
 331 =head2 term_factory
 332
 333  Title   : term_factory
 334  Usage   : $fact = $obj->term_factory()
 335  Function: Get (and set, if the implementation supports it) the object
 336            factory to be used when term objects are created by
 337            the implementation on-the-fly.
 338
 339  Example :
 340  Returns : value of term_factory (a Bio::Factory::ObjectFactory
 341            compliant object)
 342  Args    :
 343
 344 =cut
 345
 346 sub term_factory{
 347     return shift->throw_not_implemented();
 348 }
 349
 350 =head1 Decorator Methods
 351
 352  These methods come with a default implementation that uses the
 353  abstract methods defined for this interface. This may not be very
 354  efficient, and hence implementors are encouraged to override these
 355  methods if they can provide more efficient implementations.
 356
 357 =cut
 358
 359 =head2 get_all_terms
 360
 361  Title   : get_all_terms
 362  Usage   : get_all_terms: TermI
 363  Function: Retrieves all terms from the ontology.
 364
 365            This is more a decorator method. We provide a default
 366            implementation here that loops over all root terms and gets
 367            all descendants for each root term. The overall union of
 368            terms is then made unique by name and ontology.
 369
 370            We do not mandate an order here in which the terms are
 371            returned. In fact, the default implementation will return
 372            them in unpredictable order.
 373
 374            Engine implementations that can provide a more efficient
 375            method for obtaining all terms should definitely override
 376            this.
 377
 378  Example : @terms = $obj->get_all_terms()
 379  Returns : Array of TermI objects.
 380  Args    :
 381
 382 =cut
 383
 384 sub get_all_terms{
 385     my $self = shift;
 386     # get all root nodes
 387     my @roots = $self->get_root_terms();
 388     # accumulate all descendants for each root term
 389     my @terms = map { $self->get_descendant_terms($_); } @roots;
 390     # add on the root terms themselves
 391     push(@terms, @roots);
 392     # make unique by name and ontology
 393     my %name_map = map { ($_->name."@".$_->ontology->name, $_); } @terms;
 394     # done
 395     return values %name_map;
 396 }
 397
 398 =head2 find_terms
 399
 400  Title   : find_terms
 401  Usage   : ($term) = $oe->find_terms(-identifier => "SO:0000263");
 402  Function: Find term instances matching queries for their attributes.
 403
 404            An implementation may not support querying for arbitrary
 405            attributes, but can generally be expected to accept
 406            -identifier and -name as queries. If both are provided,
 407            they are implicitly intersected.
 408
 409  Example :
 410  Returns : an array of zero or more Bio::Ontology::TermI objects
 411  Args    : Named parameters. The following parameters should be recognized
 412            by any implementation:
 413
 414               -identifier    query by the given identifier
 415               -name          query by the given name
 416
 417 =cut
 418
 419 sub find_terms{
 420     my $self = shift;
 421     my %params = @_;
 422     @params{ map { lc $_; } keys %params } = values %params; # lowercase keys
 423
 424     my @terms = grep {
 425         my $ok = exists($params{-identifier}) ?
 426             $_->identifier() eq $params{-identifier} : 1;
 427         $ok && ((! exists($params{-name})) ||
 428                 ($_->name() eq $params{-name}));
 429     } $self->get_all_terms();
 430     return @terms;
 431 }
 432
 433 =head1 Experimental API method proposals
 434
 435  Ontologies are a very new domain in bioperl, and we are not sure yet
 436  what we will want to do on and with ontologies in which
 437  situation. The methods from here on downwards are solely API
 438  descriptions to solicit comment and feedback; the chance of any of
 439  those being actually implemented already is very slim.
 440
 441  Disclaimer: As long as an API method stays in this section, it is
 442  subject to change, possibly even radical change or complete
 443  deletion. If it's not implemented yet (most likely it isn't),
 444  implement yourself at your own risk.
 445
 446  So far for the disclaimer. The reason the API description is here,
 447  however, is to solicit feedback. Please feel encouraged to share your
 448  opinion, regardless of what it is (a notable difference of this API
 449  method to others is that there is actually no working code behind it
 450  - so the defense line is non-existent for practical purposes).
 451
 452 =cut
 453
 454 =head2 common_ancestor_path
 455
 456  Title   : common_ancestor_path
 457  Usage   :
 458  Function: Get the paths from two terms A and B to term C, such that
 459            there is no other term D to which A and B would have a shorter
 460            path, provided there is a term C to which both A and B are
 461            connected by a path.
 462
 463            Note that the path to the common ancestor between A and A
 464            exists, has distance zero, and predicate "identity".
 465
 466            The search for the common ancestor C can be further
 467            constrained by supplying a predicate term. If supplied, the
 468            predicates of the two paths (A,C) and (B,C) must have a
 469            common ancestor identical to the predicate, or that has a
 470            path to the predicate.
 471
 472  Example :
 473  Returns : The path of the first term to the common ancestor in scalar
 474            context, and both paths in list context. Paths are
 475            Bio::Ontology::PathI compliant objects.
 476  Args    : The two terms (Bio::Ontology::TermI objects), and optionally
 477            a constraining common predicate (Bio::Ontology::TermI object).
 478            The latter may also be given as a scalar, in which case it
 479            is treated as a boolean that, if TRUE, means that the two paths
 480            must have identical predicates in order to be returned.
 481
 482 =cut
 483
 484 sub common_ancestor_path{
 485     return shift->throw_not_implemented();
 486 }
 487
 488 1;