|
0
|
1 # $Id: OntologyI.pm,v 1.2.2.4 2003/03/27 10:07:56 lapp Exp $
|
|
|
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/MailList.shtml - 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.bioperl.org/
|
|
|
61
|
|
|
62 =head1 AUTHOR - Hilmar Lapp
|
|
|
63
|
|
|
64 Email hlapp at gmx.net
|
|
|
65
|
|
|
66 =head1 CONTRIBUTORS
|
|
|
67
|
|
|
68 Additional contributors names and emails here
|
|
|
69
|
|
|
70 =head1 APPENDIX
|
|
|
71
|
|
|
72 The rest of the documentation details each of the object methods.
|
|
|
73 Internal methods are usually preceded with a _
|
|
|
74
|
|
|
75 =cut
|
|
|
76
|
|
|
77
|
|
|
78 # Let the code begin...
|
|
|
79
|
|
|
80
|
|
|
81 package Bio::Ontology::OntologyI;
|
|
|
82 use vars qw(@ISA);
|
|
|
83 use strict;
|
|
|
84
|
|
|
85 use Bio::Ontology::OntologyEngineI;
|
|
|
86
|
|
|
87 @ISA = qw( Bio::Ontology::OntologyEngineI );
|
|
|
88
|
|
|
89 =head1 Methods defined in this interface.
|
|
|
90
|
|
|
91 =cut
|
|
|
92
|
|
|
93 =head2 name
|
|
|
94
|
|
|
95 Title : name
|
|
|
96 Usage : $obj->name($newval)
|
|
|
97 Function: Get/set the name of this ontology.
|
|
|
98 Example :
|
|
|
99 Returns : value of name (a scalar)
|
|
|
100 Args :
|
|
|
101
|
|
|
102
|
|
|
103 =cut
|
|
|
104
|
|
|
105 sub name{
|
|
|
106 shift->throw_not_implemented();
|
|
|
107 }
|
|
|
108
|
|
|
109 =head2 authority
|
|
|
110
|
|
|
111 Title : authority
|
|
|
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.
|
|
|
116
|
|
|
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
|
|
|
120 for terms.
|
|
|
121
|
|
|
122 Example :
|
|
|
123 Returns : value of authority (a scalar)
|
|
|
124 Args :
|
|
|
125
|
|
|
126
|
|
|
127 =cut
|
|
|
128
|
|
|
129 sub authority{
|
|
|
130 shift->throw_not_implemented();
|
|
|
131 }
|
|
|
132
|
|
|
133 =head2 identifier
|
|
|
134
|
|
|
135 Title : identifier
|
|
|
136 Usage : $id = $obj->identifier()
|
|
|
137 Function: Get an identifier for this ontology.
|
|
|
138
|
|
|
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
|
|
|
144 location.
|
|
|
145
|
|
|
146 Example :
|
|
|
147 Returns : value of identifier (a scalar)
|
|
|
148 Args :
|
|
|
149
|
|
|
150
|
|
|
151 =cut
|
|
|
152
|
|
|
153 sub identifier{
|
|
|
154 shift->throw_not_implemented();
|
|
|
155 }
|
|
|
156
|
|
|
157 =head2 definition
|
|
|
158
|
|
|
159 Title : definition
|
|
|
160 Usage : $def = $obj->definition()
|
|
|
161 Function: Get a descriptive definition for this ontology.
|
|
|
162 Example :
|
|
|
163 Returns : value of definition (a scalar)
|
|
|
164 Args :
|
|
|
165
|
|
|
166
|
|
|
167 =cut
|
|
|
168
|
|
|
169 sub definition{
|
|
|
170 shift->throw_not_implemented();
|
|
|
171 }
|
|
|
172
|
|
|
173 =head2 close
|
|
|
174
|
|
|
175 Title : close
|
|
|
176 Usage :
|
|
|
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
|
|
|
180 ontology.
|
|
|
181
|
|
|
182 Example :
|
|
|
183 Returns : TRUE on success and FALSE otherwise
|
|
|
184 Args : none
|
|
|
185
|
|
|
186
|
|
|
187 =cut
|
|
|
188
|
|
|
189 sub close{
|
|
|
190 shift->throw_not_implemented();
|
|
|
191 }
|
|
|
192
|
|
|
193 =head1 Methods inherited from L<Bio::Ontology::OntologyEngineI>
|
|
|
194
|
|
|
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 ...
|
|
|
198
|
|
|
199 =cut
|
|
|
200
|
|
|
201 =head2 add_term
|
|
|
202
|
|
|
203 Title : add_term
|
|
|
204 Usage : add_term(TermI term): TermI
|
|
|
205 Function: Adds TermI object to the ontology engine term store.
|
|
|
206
|
|
|
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.
|
|
|
210
|
|
|
211 Example : $oe->add_term($term)
|
|
|
212 Returns : its argument.
|
|
|
213 Args : object of class TermI.
|
|
|
214
|
|
|
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
|
|
|
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
|
|
|
242 =cut
|
|
|
243
|
|
|
244 =head2 get_predicate_terms
|
|
|
245
|
|
|
246 Title : get_predicate_terms
|
|
|
247 Usage : get_predicate_terms(): TermI[]
|
|
|
248 Function:
|
|
|
249 Example :
|
|
|
250 Returns :
|
|
|
251 Args :
|
|
|
252
|
|
|
253
|
|
|
254 =cut
|
|
|
255
|
|
|
256 =head2 get_child_terms
|
|
|
257
|
|
|
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
|
|
|
264 direct descendants.
|
|
|
265
|
|
|
266 Example :
|
|
|
267 Returns : Array of TermI objects.
|
|
|
268 Args : First argument is the term of interest, second is the list
|
|
|
269 of relationship type terms.
|
|
|
270
|
|
|
271
|
|
|
272 =cut
|
|
|
273
|
|
|
274 =head2 get_descendant_terms
|
|
|
275
|
|
|
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.
|
|
|
281 Example :
|
|
|
282 Returns : Array of TermI objects.
|
|
|
283 Args : First argument is the term of interest, second is the list
|
|
|
284 of relationship type terms.
|
|
|
285
|
|
|
286
|
|
|
287 =cut
|
|
|
288
|
|
|
289 =head2 get_parent_terms
|
|
|
290
|
|
|
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
|
|
|
297 direct ancestors.
|
|
|
298
|
|
|
299 Example :
|
|
|
300 Returns : Array of TermI objects.
|
|
|
301 Args : First argument is the term of interest, second is the list
|
|
|
302 of relationship type terms.
|
|
|
303
|
|
|
304
|
|
|
305 =cut
|
|
|
306
|
|
|
307 =head2 get_ancestor_terms
|
|
|
308
|
|
|
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.
|
|
|
314
|
|
|
315 Example :
|
|
|
316 Returns : Array of TermI objects.
|
|
|
317 Args : First argument is the term of interest, second is the list
|
|
|
318 of relationship type terms.
|
|
|
319
|
|
|
320
|
|
|
321 =cut
|
|
|
322
|
|
|
323 =head2 get_leaf_terms
|
|
|
324
|
|
|
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.
|
|
|
329
|
|
|
330 Example : @leaf_terms = $obj->get_leaf_terms()
|
|
|
331 Returns : Array of TermI objects.
|
|
|
332 Args :
|
|
|
333
|
|
|
334
|
|
|
335 =cut
|
|
|
336
|
|
|
337 =head2 get_root_terms()
|
|
|
338
|
|
|
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.
|
|
|
343
|
|
|
344 Example : @root_terms = $obj->get_root_terms()
|
|
|
345 Returns : Array of TermI objects.
|
|
|
346 Args :
|
|
|
347
|
|
|
348
|
|
|
349 =cut
|
|
|
350
|
|
|
351 =head2 get_all_terms
|
|
|
352
|
|
|
353 Title : get_all_terms
|
|
|
354 Usage : get_all_terms: TermI[]
|
|
|
355 Function: Retrieves all terms from the ontology.
|
|
|
356
|
|
|
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.
|
|
|
360
|
|
|
361 Example : @terms = $obj->get_all_terms()
|
|
|
362 Returns : Array of TermI objects.
|
|
|
363 Args :
|
|
|
364
|
|
|
365
|
|
|
366 =cut
|
|
|
367
|
|
|
368
|
|
|
369 =head2 find_terms
|
|
|
370
|
|
|
371 Title : find_terms
|
|
|
372 Usage : ($term) = $oe->find_terms(-identifier => "SO:0000263");
|
|
|
373 Function: Find term instances matching queries for their attributes.
|
|
|
374
|
|
|
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.
|
|
|
379
|
|
|
380 Example :
|
|
|
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:
|
|
|
384
|
|
|
385 -identifier query by the given identifier
|
|
|
386 -name query by the given name
|
|
|
387
|
|
|
388
|
|
|
389 =cut
|
|
|
390
|
|
|
391 =head1 Factory for relationships and terms
|
|
|
392
|
|
|
393 =cut
|
|
|
394
|
|
|
395 =head2 relationship_factory
|
|
|
396
|
|
|
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.
|
|
|
402
|
|
|
403 Example :
|
|
|
404 Returns : value of relationship_factory (a Bio::Factory::ObjectFactoryI
|
|
|
405 compliant object)
|
|
|
406 Args :
|
|
|
407
|
|
|
408
|
|
|
409 =cut
|
|
|
410
|
|
|
411 sub relationship_factory{
|
|
|
412 return shift->throw_not_implemented();
|
|
|
413 }
|
|
|
414
|
|
|
415 =head2 term_factory
|
|
|
416
|
|
|
417 Title : term_factory
|
|
|
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.
|
|
|
422
|
|
|
423 Example :
|
|
|
424 Returns : value of term_factory (a Bio::Factory::ObjectFactoryI
|
|
|
425 compliant object)
|
|
|
426 Args :
|
|
|
427
|
|
|
428
|
|
|
429 =cut
|
|
|
430
|
|
|
431 sub term_factory{
|
|
|
432 return shift->throw_not_implemented();
|
|
|
433 }
|
|
|
434
|
|
|
435 1;
|
