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
  91 use strict;
  92
  93
  94 use base qw(Bio::Ontology::OntologyEngineI);
  95
  96 =head1  Methods defined in this interface.
  97
  98 =cut
  99
 100 =head2 name
 101
 102  Title   : name
 103  Usage   : $obj->name($newval)
 104  Function: Get/set the name of this ontology.
 105  Example :
 106  Returns : value of name (a scalar)
 107  Args    :
 108
 109 =cut
 110
 111 sub name{
 112     shift->throw_not_implemented();
 113 }
 114
 115 =head2 authority
 116
 117  Title   : authority
 118  Usage   : $auth = $obj->authority()
 119  Function: Get/set the authority for this ontology, for instance the
 120            DNS base for the organization granting the name of the
 121            ontology and identifiers for the terms.
 122
 123            This attribute is optional and should not generally
 124            expected by applications to have been set. It is here to
 125            follow the rules for namespaces, which ontologies serve as
 126            for terms.
 127
 128  Example :
 129  Returns : value of authority (a scalar)
 130  Args    :
 131
 132 =cut
 133
 134 sub authority{
 135     shift->throw_not_implemented();
 136 }
 137
 138 =head2 identifier
 139
 140  Title   : identifier
 141  Usage   : $id = $obj->identifier()
 142  Function: Get an identifier for this ontology.
 143
 144            This is primarily intended for look-up purposes. Clients
 145            should not expect the value to be modifiable, and it may
 146            not be allowed to set its value from outside. Also, the
 147            identifier's uniqueness may only hold within the scope of a
 148            particular application's run time, i.e., it may be a memory
 149            location.
 150
 151  Example :
 152  Returns : value of identifier (a scalar)
 153  Args    :
 154
 155 =cut
 156
 157 sub identifier{
 158     shift->throw_not_implemented();
 159 }
 160
 161 =head2 definition
 162
 163  Title   : definition
 164  Usage   : $def = $obj->definition()
 165  Function: Get a descriptive definition for this ontology.
 166  Example :
 167  Returns : value of definition (a scalar)
 168  Args    :
 169
 170 =cut
 171
 172 sub definition{
 173     shift->throw_not_implemented();
 174 }
 175
 176 =head2 close
 177
 178  Title   : close
 179  Usage   :
 180  Function: Release any resources this ontology may occupy. In order
 181            to efficiently release used memory or file handles, you
 182            should call this method once you are finished with an
 183            ontology.
 184
 185  Example :
 186  Returns : TRUE on success and FALSE otherwise
 187  Args    : none
 188
 189 =cut
 190
 191 sub close{
 192     shift->throw_not_implemented();
 193 }
 194
 195 =head1 Methods inherited from L<Bio::Ontology::OntologyEngineI>
 196
 197 Their documentations are copied here for completeness. In most use
 198 cases, you will want to access the query methods of an ontology, not
 199 just the name and description ...
 200
 201 =cut
 202
 203 =head2 add_term
 204
 205  Title   : add_term
 206  Usage   : add_term(TermI term): TermI
 207  Function: Adds TermI object to the ontology engine term store.
 208
 209            For ease of use, if the ontology property of the term
 210            object was not set, an implementation is encouraged to set
 211            it to itself upon adding the term.
 212
 213  Example : $oe->add_term($term)
 214  Returns : its argument.
 215  Args    : object of class TermI.
 216
 217 =cut
 218
 219 =head2 add_relationship
 220
 221  Title   : add_relationship
 222  Usage   : add_relationship(RelationshipI relationship): RelationshipI
 223  Function: Adds a relationship object to the ontology engine.
 224  Example :
 225  Returns : Its argument.
 226  Args    : A RelationshipI object.
 227
 228 =cut
 229
 230 =head2 get_relationships
 231
 232  Title   : get_relationships
 233  Usage   : get_relationships(TermI term): RelationshipI
 234  Function: Retrieves all relationship objects from this ontology engine,
 235            or all relationships of a term if a term is supplied.
 236  Example :
 237  Returns : Array of Bio::Ontology::RelationshipI objects
 238  Args    : None, or a Bio::Ontology::TermI compliant object for which
 239            to retrieve the relationships.
 240
 241 =cut
 242
 243 =head2 get_predicate_terms
 244
 245  Title   : get_predicate_terms
 246  Usage   : get_predicate_terms(): TermI[]
 247  Function:
 248  Example :
 249  Returns :
 250  Args    :
 251
 252 =cut
 253
 254 =head2 get_child_terms
 255
 256  Title   : get_child_terms
 257  Usage   : get_child_terms(TermI term, TermI predicate_terms): TermI
 258  Function: Retrieves all child terms of a given term, that satisfy a
 259            relationship among those that are specified in the second
 260            argument or undef otherwise. get_child_terms is a special
 261            case of get_descendant_terms, limiting the search to the
 262            direct descendants.
 263
 264  Example :
 265  Returns : Array of TermI objects.
 266  Args    : First argument is the term of interest, second is the list
 267            of relationship type terms.
 268
 269 =cut
 270
 271 =head2 get_descendant_terms
 272
 273  Title   : get_descendant_terms
 274  Usage   : get_descendant_terms(TermI term, TermI rel_types): TermI
 275  Function: Retrieves all descendant terms of a given term, that
 276            satisfy a relationship among those that are specified in
 277            the second argument or undef otherwise.
 278  Example :
 279  Returns : Array of TermI objects.
 280  Args    : First argument is the term of interest, second is the list
 281            of relationship type terms.
 282
 283 =cut
 284
 285 =head2 get_parent_terms
 286
 287  Title   : get_parent_terms
 288  Usage   : get_parent_terms(TermI term, TermI predicate_terms): TermI
 289  Function: Retrieves all parent terms of a given term, that satisfy a
 290            relationship among those that are specified in the second
 291            argument or undef otherwise. get_parent_terms is a special
 292            case of get_ancestor_terms, limiting the search to the
 293            direct ancestors.
 294
 295  Example :
 296  Returns : Array of TermI objects.
 297  Args    : First argument is the term of interest, second is the list
 298            of relationship type terms.
 299
 300 =cut
 301
 302 =head2 get_ancestor_terms
 303
 304  Title   : get_ancestor_terms
 305  Usage   : get_ancestor_terms(TermI term, TermI predicate_terms): TermI
 306  Function: Retrieves all ancestor terms of a given term, that satisfy
 307            a relationship among those that are specified in the second
 308            argument or undef otherwise.
 309
 310  Example :
 311  Returns : Array of TermI objects.
 312  Args    : First argument is the term of interest, second is the list
 313            of relationship type terms.
 314
 315 =cut
 316
 317 =head2 get_leaf_terms
 318
 319  Title   : get_leaf_terms
 320  Usage   : get_leaf_terms(): TermI
 321  Function: Retrieves all leaf terms from the ontology. Leaf term is a
 322            term w/o descendants.
 323
 324  Example : @leaf_terms = $obj->get_leaf_terms()
 325  Returns : Array of TermI objects.
 326  Args    :
 327
 328 =cut
 329
 330 =head2 get_root_terms()
 331
 332  Title   : get_root_terms
 333  Usage   : get_root_terms(): TermI
 334  Function: Retrieves all root terms from the ontology. Root term is a
 335            term w/o descendants.
 336
 337  Example : @root_terms = $obj->get_root_terms()
 338  Returns : Array of TermI objects.
 339  Args    :
 340
 341 =cut
 342
 343 =head2 get_all_terms
 344
 345  Title   : get_all_terms
 346  Usage   : get_all_terms: TermI
 347  Function: Retrieves all terms from the ontology.
 348
 349            We do not mandate an order here in which the terms are
 350            returned. In fact, the default implementation will return
 351            them in unpredictable order.
 352
 353  Example : @terms = $obj->get_all_terms()
 354  Returns : Array of TermI objects.
 355  Args    :
 356
 357 =cut
 358
 359
 360 =head2 find_terms
 361
 362  Title   : find_terms
 363  Usage   : ($term) = $oe->find_terms(-identifier => "SO:0000263");
 364  Function: Find term instances matching queries for their attributes.
 365
 366            An implementation may not support querying for arbitrary
 367            attributes, but can generally be expected to accept
 368            -identifier and -name as queries. If both are provided,
 369            they are implicitly intersected.
 370
 371  Example :
 372  Returns : an array of zero or more Bio::Ontology::TermI objects
 373  Args    : Named parameters. The following parameters should be recognized
 374            by any implementation:
 375
 376               -identifier    query by the given identifier
 377               -name          query by the given name
 378
 379 =cut
 380
 381 =head1 Factory for relationships and terms
 382
 383 =cut
 384
 385 =head2 relationship_factory
 386
 387  Title   : relationship_factory
 388  Usage   : $fact = $obj->relationship_factory()
 389  Function: Get (and set, if the implementation supports it) the object
 390            factory to be used when relationship objects are created by
 391            the implementation on-the-fly.
 392
 393  Example :
 394  Returns : value of relationship_factory (a Bio::Factory::ObjectFactoryI
 395            compliant object)
 396  Args    :
 397
 398 =cut
 399
 400 sub relationship_factory{
 401     return shift->throw_not_implemented();
 402 }
 403
 404 =head2 term_factory
 405
 406  Title   : term_factory
 407  Usage   : $fact = $obj->term_factory()
 408  Function: Get (and set, if the implementation supports it) the object
 409            factory to be used when term objects are created by
 410            the implementation on-the-fly.
 411
 412  Example :
 413  Returns : value of term_factory (a Bio::Factory::ObjectFactoryI
 414            compliant object)
 415  Args    :
 416
 417 =cut
 418
 419 sub term_factory{
 420     return shift->throw_not_implemented();
 421 }
 422
 423 1;