Bio/Ontology/OntologyEngineI.pm

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