1
# $Id: OntologyI.pm,v 1.6 2003/03/27 08:59:29 lapp Exp $
3
# BioPerl module for Bio::Ontology::OntologyI
5
# Cared for by Hilmar Lapp <hlapp at gmx.net>
7
# Copyright Hilmar Lapp
9
# You may distribute this module under the same terms as perl itself
12
# (c) Hilmar Lapp, hlapp at gmx.net, 2003.
13
# (c) GNF, Genomics Institute of the Novartis Research Foundation, 2003.
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.
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.
25
# POD documentation - main docs before the code
29
Bio::Ontology::OntologyI - Interface for an ontology implementation
33
# see method documentation
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.
41
This interface inherits from L<Bio::Ontology::OntologyEngineI>.
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.
51
bioperl-l@bioperl.org - General discussion
52
http://bioperl.org/MailList.shtml - About the mailing lists
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
60
http://bugzilla.bioperl.org/
62
=head1 AUTHOR - Hilmar Lapp
64
Email hlapp at gmx.net
68
Additional contributors names and emails here
72
The rest of the documentation details each of the object methods.
73
Internal methods are usually preceded with a _
78
# Let the code begin...
81
package Bio::Ontology::OntologyI;
85
use Bio::Ontology::OntologyEngineI;
87
@ISA = qw( Bio::Ontology::OntologyEngineI );
89
=head1 Methods defined in this interface.
96
Usage : $obj->name($newval)
97
Function: Get/set the name of this ontology.
99
Returns : value of name (a scalar)
106
shift->throw_not_implemented();
112
Usage : $auth = $obj->authority()
113
Function: Get/set the authority for this ontology, for instance the
114
DNS base for the organization granting the name of the
115
ontology and identifiers for the terms.
117
This attribute is optional and should not generally
118
expected by applications to have been set. It is here to
119
follow the rules for namespaces, which ontologies serve as
123
Returns : value of authority (a scalar)
130
shift->throw_not_implemented();
136
Usage : $id = $obj->identifier()
137
Function: Get an identifier for this ontology.
139
This is primarily intended for look-up purposes. Clients
140
should not expect the value to be modifiable, and it may
141
not be allowed to set its value from outside. Also, the
142
identifier's uniqueness may only hold within the scope of a
143
particular application's run time, i.e., it may be a memory
147
Returns : value of identifier (a scalar)
154
shift->throw_not_implemented();
160
Usage : $def = $obj->definition()
161
Function: Get a descriptive definition for this ontology.
163
Returns : value of definition (a scalar)
170
shift->throw_not_implemented();
177
Function: Release any resources this ontology may occupy. In order
178
to efficiently release used memory or file handles, you
179
should call this method once you are finished with an
183
Returns : TRUE on success and FALSE otherwise
190
shift->throw_not_implemented();
193
=head1 Methods inherited from L<Bio::Ontology::OntologyEngineI>
195
Their documentations are copied here for completeness. In most use
196
cases, you will want to access the query methods of an ontology, not
197
just the name and description ...
204
Usage : add_term(TermI term): TermI
205
Function: Adds TermI object to the ontology engine term store.
207
For ease of use, if the ontology property of the term
208
object was not set, an implementation is encouraged to set
209
it to itself upon adding the term.
211
Example : $oe->add_term($term)
212
Returns : its argument.
213
Args : object of class TermI.
218
=head2 add_relationship
220
Title : add_relationship
221
Usage : add_relationship(RelationshipI relationship): RelationshipI
222
Function: Adds a relationship object to the ontology engine.
224
Returns : Its argument.
225
Args : A RelationshipI object.
230
=head2 get_relationships
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.
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.
244
=head2 get_predicate_terms
246
Title : get_predicate_terms
247
Usage : get_predicate_terms(): TermI[]
256
=head2 get_child_terms
258
Title : get_child_terms
259
Usage : get_child_terms(TermI term, TermI[] predicate_terms): TermI[]
260
Function: Retrieves all child terms of a given term, that satisfy a
261
relationship among those that are specified in the second
262
argument or undef otherwise. get_child_terms is a special
263
case of get_descendant_terms, limiting the search to the
267
Returns : Array of TermI objects.
268
Args : First argument is the term of interest, second is the list
269
of relationship type terms.
274
=head2 get_descendant_terms
276
Title : get_descendant_terms
277
Usage : get_descendant_terms(TermI term, TermI[] rel_types): TermI[]
278
Function: Retrieves all descendant terms of a given term, that
279
satisfy a relationship among those that are specified in
280
the second argument or undef otherwise.
282
Returns : Array of TermI objects.
283
Args : First argument is the term of interest, second is the list
284
of relationship type terms.
289
=head2 get_parent_terms
291
Title : get_parent_terms
292
Usage : get_parent_terms(TermI term, TermI[] predicate_terms): TermI[]
293
Function: Retrieves all parent terms of a given term, that satisfy a
294
relationship among those that are specified in the second
295
argument or undef otherwise. get_parent_terms is a special
296
case of get_ancestor_terms, limiting the search to the
300
Returns : Array of TermI objects.
301
Args : First argument is the term of interest, second is the list
302
of relationship type terms.
307
=head2 get_ancestor_terms
309
Title : get_ancestor_terms
310
Usage : get_ancestor_terms(TermI term, TermI[] predicate_terms): TermI[]
311
Function: Retrieves all ancestor terms of a given term, that satisfy
312
a relationship among those that are specified in the second
313
argument or undef otherwise.
316
Returns : Array of TermI objects.
317
Args : First argument is the term of interest, second is the list
318
of relationship type terms.
323
=head2 get_leaf_terms
325
Title : get_leaf_terms
326
Usage : get_leaf_terms(): TermI[]
327
Function: Retrieves all leaf terms from the ontology. Leaf term is a
328
term w/o descendants.
330
Example : @leaf_terms = $obj->get_leaf_terms()
331
Returns : Array of TermI objects.
337
=head2 get_root_terms()
339
Title : get_root_terms
340
Usage : get_root_terms(): TermI[]
341
Function: Retrieves all root terms from the ontology. Root term is a
342
term w/o descendants.
344
Example : @root_terms = $obj->get_root_terms()
345
Returns : Array of TermI objects.
353
Title : get_all_terms
354
Usage : get_all_terms: TermI[]
355
Function: Retrieves all terms from the ontology.
357
We do not mandate an order here in which the terms are
358
returned. In fact, the default implementation will return
359
them in unpredictable order.
361
Example : @terms = $obj->get_all_terms()
362
Returns : Array of TermI objects.
372
Usage : ($term) = $oe->find_terms(-identifier => "SO:0000263");
373
Function: Find term instances matching queries for their attributes.
375
An implementation may not support querying for arbitrary
376
attributes, but can generally be expected to accept
377
-identifier and -name as queries. If both are provided,
378
they are implicitly intersected.
381
Returns : an array of zero or more Bio::Ontology::TermI objects
382
Args : Named parameters. The following parameters should be recognized
383
by any implementation:
385
-identifier query by the given identifier
386
-name query by the given name
391
=head1 Factory for relationships and terms
395
=head2 relationship_factory
397
Title : relationship_factory
398
Usage : $fact = $obj->relationship_factory()
399
Function: Get (and set, if the implementation supports it) the object
400
factory to be used when relationship objects are created by
401
the implementation on-the-fly.
404
Returns : value of relationship_factory (a Bio::Factory::ObjectFactoryI
411
sub relationship_factory{
412
return shift->throw_not_implemented();
418
Usage : $fact = $obj->term_factory()
419
Function: Get (and set, if the implementation supports it) the object
420
factory to be used when term objects are created by
421
the implementation on-the-fly.
424
Returns : value of term_factory (a Bio::Factory::ObjectFactoryI
432
return shift->throw_not_implemented();
added
removed
Bio/Ontology/OntologyI.pm
