| 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 | 28 | $Bio::Ontology::OntologyI::VERSION = '1.7.8'; | |
| 91 | 28 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 92 | |||
| 93 | |||
| 94 | 28 | ▶ | use base qw(Bio::Ontology::OntologyEngineI); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 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 | 0 | ▶ | sub name{ |
|
Subroutine
name: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 112 | 0 | 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 | 0 | ▶ | sub authority{ |
|
Subroutine
authority: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 135 | 0 | 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 | 0 | ▶ | sub identifier{ |
|
Subroutine
identifier: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 158 | 0 | 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 | 0 | ▶ | sub definition{ |
|
Subroutine
definition: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 173 | 0 | 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 | 0 | ▶ | sub close{ |
|
Subroutine
close: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 192 | 0 | 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 | 0 | ▶ | sub relationship_factory{ |
|
Subroutine
relationship_factory: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 401 | 0 | 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 | 0 | ▶ | sub term_factory{ |
|
Subroutine
term_factory: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 420 | 0 | return shift->throw_not_implemented(); | |
| 421 | } | ||
| 422 | |||
| 423 | 28 | 1; | |