Bio/Ontology/OntologyI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Ontology::OntologyI
   4 #
   5 # Cared for by Hilmar Lapp <hlapp at gmx.net>
   6 #
   7 # Copyright Hilmar Lapp
   8 #
   9 # You may distribute this module under the same terms as perl itself
  10
  11 #
  12 # (c) Hilmar Lapp, hlapp at gmx.net, 2003.
  13 # (c) GNF, Genomics Institute of the Novartis Research Foundation, 2003.
  14 #
  15 # You may distribute this module under the same terms as perl itself.
  16 # Refer to the Perl Artistic License (see the license accompanying this
  17 # software package, or see http://www.perl.com/language/misc/Artistic.html)
  18 # for the terms under which you may use, modify, and redistribute this module.
  19 #
  20 # THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
  21 # WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  22 # MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  23 #
  24
  25 # POD documentation - main docs before the code
  26
  27 =head1 NAME
  28
  29 Bio::Ontology::OntologyI - Interface for an ontology implementation
  30
  31 =head1 SYNOPSIS
  32
  33     # see method documentation
  34
  35 =head1 DESCRIPTION
  36
  37 This describes the minimal interface an ontology implementation must
  38 provide. In essence, it represents a namespace with description on top
  39 of the query interface OntologyEngineI.
  40
  41 This interface inherits from L<Bio::Ontology::OntologyEngineI>.
  42
  43 =head1 FEEDBACK
  44
  45 =head2 Mailing Lists
  46
  47 User feedback is an integral part of the evolution of this and other
  48 Bioperl modules. Send your comments and suggestions preferably to
  49 the Bioperl mailing list.  Your participation is much appreciated.
  50
  51   bioperl-l@bioperl.org                  - General discussion
  52   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  53
  54 =head2 Reporting Bugs
  55
  56 Report bugs to the Bioperl bug tracking system to help us keep track
  57 of the bugs and their resolution. Bug reports can be submitted via
  58 email or the web:
  59
  60   http://bugzilla.open-bio.org/
  61
  62 =head1 AUTHOR - Hilmar Lapp
  63
  64 Email hlapp at gmx.net
  65
  66 =head1 APPENDIX
  67
  68 The rest of the documentation details each of the object methods.
  69 Internal methods are usually preceded with a _
  70
  71 =cut
  72
  73
  74 # Let the code begin...
  75
  76
  77 package Bio::Ontology::OntologyI;
  78 use strict;
  79
  80
  81 use base qw(Bio::Ontology::OntologyEngineI);
  82
  83 =head1  Methods defined in this interface.
  84
  85 =cut
  86
  87 =head2 name
  88
  89  Title   : name
  90  Usage   : $obj->name($newval)
  91  Function: Get/set the name of this ontology.
  92  Example :
  93  Returns : value of name (a scalar)
  94  Args    :
  95
  96 =cut
  97
  98 sub name{
  99     shift->throw_not_implemented();
 100 }
 101
 102 =head2 authority
 103
 104  Title   : authority
 105  Usage   : $auth = $obj->authority()
 106  Function: Get/set the authority for this ontology, for instance the
 107            DNS base for the organization granting the name of the
 108            ontology and identifiers for the terms.
 109
 110            This attribute is optional and should not generally
 111            expected by applications to have been set. It is here to
 112            follow the rules for namespaces, which ontologies serve as
 113            for terms.
 114
 115  Example :
 116  Returns : value of authority (a scalar)
 117  Args    :
 118
 119 =cut
 120
 121 sub authority{
 122     shift->throw_not_implemented();
 123 }
 124
 125 =head2 identifier
 126
 127  Title   : identifier
 128  Usage   : $id = $obj->identifier()
 129  Function: Get an identifier for this ontology.
 130
 131            This is primarily intended for look-up purposes. Clients
 132            should not expect the value to be modifiable, and it may
 133            not be allowed to set its value from outside. Also, the
 134            identifier's uniqueness may only hold within the scope of a
 135            particular application's run time, i.e., it may be a memory
 136            location.
 137
 138  Example :
 139  Returns : value of identifier (a scalar)
 140  Args    :
 141
 142 =cut
 143
 144 sub identifier{
 145     shift->throw_not_implemented();
 146 }
 147
 148 =head2 definition
 149
 150  Title   : definition
 151  Usage   : $def = $obj->definition()
 152  Function: Get a descriptive definition for this ontology.
 153  Example :
 154  Returns : value of definition (a scalar)
 155  Args    :
 156
 157 =cut
 158
 159 sub definition{
 160     shift->throw_not_implemented();
 161 }
 162
 163 =head2 close
 164
 165  Title   : close
 166  Usage   :
 167  Function: Release any resources this ontology may occupy. In order
 168            to efficiently release used memory or file handles, you
 169            should call this method once you are finished with an
 170            ontology.
 171
 172  Example :
 173  Returns : TRUE on success and FALSE otherwise
 174  Args    : none
 175
 176 =cut
 177
 178 sub close{
 179     shift->throw_not_implemented();
 180 }
 181
 182 =head1 Methods inherited from L<Bio::Ontology::OntologyEngineI>
 183
 184 Their documentations are copied here for completeness. In most use
 185 cases, you will want to access the query methods of an ontology, not
 186 just the name and description ...
 187
 188 =cut
 189
 190 =head2 add_term
 191
 192  Title   : add_term
 193  Usage   : add_term(TermI term): TermI
 194  Function: Adds TermI object to the ontology engine term store.
 195
 196            For ease of use, if the ontology property of the term
 197            object was not set, an implementation is encouraged to set
 198            it to itself upon adding the term.
 199
 200  Example : $oe->add_term($term)
 201  Returns : its argument.
 202  Args    : object of class TermI.
 203
 204 =cut
 205
 206 =head2 add_relationship
 207
 208  Title   : add_relationship
 209  Usage   : add_relationship(RelationshipI relationship): RelationshipI
 210  Function: Adds a relationship object to the ontology engine.
 211  Example :
 212  Returns : Its argument.
 213  Args    : A RelationshipI object.
 214
 215 =cut
 216
 217 =head2 get_relationships
 218
 219  Title   : get_relationships
 220  Usage   : get_relationships(TermI term): RelationshipI
 221  Function: Retrieves all relationship objects from this ontology engine,
 222            or all relationships of a term if a term is supplied.
 223  Example :
 224  Returns : Array of Bio::Ontology::RelationshipI objects
 225  Args    : None, or a Bio::Ontology::TermI compliant object for which
 226            to retrieve the relationships.
 227
 228 =cut
 229
 230 =head2 get_predicate_terms
 231
 232  Title   : get_predicate_terms
 233  Usage   : get_predicate_terms(): TermI[]
 234  Function:
 235  Example :
 236  Returns :
 237  Args    :
 238
 239 =cut
 240
 241 =head2 get_child_terms
 242
 243  Title   : get_child_terms
 244  Usage   : get_child_terms(TermI term, TermI predicate_terms): TermI
 245  Function: Retrieves all child terms of a given term, that satisfy a
 246            relationship among those that are specified in the second
 247            argument or undef otherwise. get_child_terms is a special
 248            case of get_descendant_terms, limiting the search to the
 249            direct descendants.
 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 =head2 get_descendant_terms
 259
 260  Title   : get_descendant_terms
 261  Usage   : get_descendant_terms(TermI term, TermI rel_types): TermI
 262  Function: Retrieves all descendant terms of a given term, that
 263            satisfy a relationship among those that are specified in
 264            the second argument or undef otherwise.
 265  Example :
 266  Returns : Array of TermI objects.
 267  Args    : First argument is the term of interest, second is the list
 268            of relationship type terms.
 269
 270 =cut
 271
 272 =head2 get_parent_terms
 273
 274  Title   : get_parent_terms
 275  Usage   : get_parent_terms(TermI term, TermI predicate_terms): TermI
 276  Function: Retrieves all parent terms of a given term, that satisfy a
 277            relationship among those that are specified in the second
 278            argument or undef otherwise. get_parent_terms is a special
 279            case of get_ancestor_terms, limiting the search to the
 280            direct ancestors.
 281
 282  Example :
 283  Returns : Array of TermI objects.
 284  Args    : First argument is the term of interest, second is the list
 285            of relationship type terms.
 286
 287 =cut
 288
 289 =head2 get_ancestor_terms
 290
 291  Title   : get_ancestor_terms
 292  Usage   : get_ancestor_terms(TermI term, TermI predicate_terms): TermI
 293  Function: Retrieves all ancestor terms of a given term, that satisfy
 294            a relationship among those that are specified in the second
 295            argument or undef otherwise.
 296
 297  Example :
 298  Returns : Array of TermI objects.
 299  Args    : First argument is the term of interest, second is the list
 300            of relationship type terms.
 301
 302 =cut
 303
 304 =head2 get_leaf_terms
 305
 306  Title   : get_leaf_terms
 307  Usage   : get_leaf_terms(): TermI
 308  Function: Retrieves all leaf terms from the ontology. Leaf term is a
 309            term w/o descendants.
 310
 311  Example : @leaf_terms = $obj->get_leaf_terms()
 312  Returns : Array of TermI objects.
 313  Args    :
 314
 315 =cut
 316
 317 =head2 get_root_terms()
 318
 319  Title   : get_root_terms
 320  Usage   : get_root_terms(): TermI
 321  Function: Retrieves all root terms from the ontology. Root term is a
 322            term w/o descendants.
 323
 324  Example : @root_terms = $obj->get_root_terms()
 325  Returns : Array of TermI objects.
 326  Args    :
 327
 328 =cut
 329
 330 =head2 get_all_terms
 331
 332  Title   : get_all_terms
 333  Usage   : get_all_terms: TermI
 334  Function: Retrieves all terms from the ontology.
 335
 336            We do not mandate an order here in which the terms are
 337            returned. In fact, the default implementation will return
 338            them in unpredictable order.
 339
 340  Example : @terms = $obj->get_all_terms()
 341  Returns : Array of TermI objects.
 342  Args    :
 343
 344 =cut
 345
 346
 347 =head2 find_terms
 348
 349  Title   : find_terms
 350  Usage   : ($term) = $oe->find_terms(-identifier => "SO:0000263");
 351  Function: Find term instances matching queries for their attributes.
 352
 353            An implementation may not support querying for arbitrary
 354            attributes, but can generally be expected to accept
 355            -identifier and -name as queries. If both are provided,
 356            they are implicitly intersected.
 357
 358  Example :
 359  Returns : an array of zero or more Bio::Ontology::TermI objects
 360  Args    : Named parameters. The following parameters should be recognized
 361            by any implementation:
 362
 363               -identifier    query by the given identifier
 364               -name          query by the given name
 365
 366 =cut
 367
 368 =head1 Factory for relationships and terms
 369
 370 =cut
 371
 372 =head2 relationship_factory
 373
 374  Title   : relationship_factory
 375  Usage   : $fact = $obj->relationship_factory()
 376  Function: Get (and set, if the implementation supports it) the object
 377            factory to be used when relationship objects are created by
 378            the implementation on-the-fly.
 379
 380  Example :
 381  Returns : value of relationship_factory (a Bio::Factory::ObjectFactoryI
 382            compliant object)
 383  Args    :
 384
 385 =cut
 386
 387 sub relationship_factory{
 388     return shift->throw_not_implemented();
 389 }
 390
 391 =head2 term_factory
 392
 393  Title   : term_factory
 394  Usage   : $fact = $obj->term_factory()
 395  Function: Get (and set, if the implementation supports it) the object
 396            factory to be used when term objects are created by
 397            the implementation on-the-fly.
 398
 399  Example :
 400  Returns : value of term_factory (a Bio::Factory::ObjectFactoryI
 401            compliant object)
 402  Args    :
 403
 404 =cut
 405
 406 sub term_factory{
 407     return shift->throw_not_implemented();
 408 }
 409
 410 1;