lib/Bio/Ontology/OntologyI.pm

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