Bio/Ontology/OntologyEngineI.pm

filter: Statementstmt 26.1% 11 / 42 Branchbran 0.0% 0 / 2 Conditioncond 0.0% 0 / 6 MC/DCmcdc 0.0% 0 / 3 Subroutinesub 15.0% 3 / 20 Podpod 100% 17 / 17 totaltotal 34.4% 31 / 90 CC 4 SCAR 16.1
CC
4
Cov
22%
find_terms
20.0
add_term
2.0
add_relationship
2.0
CRAP 5.0
« Bio/Tools/Primer/Assessor/Base.pm ↑ Summary Bio/Tools/RepeatMasker.pm »
1 #
2 # BioPerl module for OntologyEngineI
3 #
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
5 #
6 # Cared for by Peter Dimitrov <dimitrov@gnf.org>
7 #
8 # (c) Peter Dimitrov
9 # (c) GNF, Genomics Institute of the Novartis Research Foundation, 2002.
10 #
11 # You may distribute this module under the same terms as perl itself.
12 # Refer to the Perl Artistic License (see the license accompanying this
13 # software package, or see http://www.perl.com/language/misc/Artistic.html)
14 # for the terms under which you may use, modify, and redistribute this module.
15 #
16 # THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
17 # WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
18 # MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
19 #
20 # You may distribute this module under the same terms as perl itself
21  
22 # POD documentation - main docs before the code
23  
24 =head1 NAME
25  
26 Bio::Ontology::OntologyEngineI - Interface a minimal Ontology implementation should satisfy
27  
28 =head1 SYNOPSIS
29  
30 # see documentation of methods
31  
32 =head1 DESCRIPTION
33  
34 This describes the minimal interface an ontology query engine should
35 provide. It intentionally does not make explicit references to the
36 ontology being a DAG, nor does it mandate that the ontology be a
37 vocabulary. Rather, it tries to generically express what should be
38 accessible (queriable) about an ontology.
39  
40 The idea is to allow for different implementations for different
41 purposes, which may then differ as to which operations are efficient
42 and which are not, and how much richer the functionality is on top of
43 this minimalistic set of methods. Check modules in the Bio::Ontology
44 namespace to find out which implementations exist. At the time of
45 writing, there is a SimpleOntologyEngine (which does not use
46 Graph.pm), and a Graph.pm-based implementation in SimpleGOEngine.
47  
48 Ontology parsers in Bio::OntologyIO are required to return an
49 implementation of this interface.
50  
51 =head1 FEEDBACK
52  
53 =head2 Mailing Lists
54  
55 User feedback is an integral part of the evolution of this and other
56 Bioperl modules. Send your comments and suggestions preferably to
57 the Bioperl mailing list. Your participation is much appreciated.
58  
59 bioperl-l@bioperl.org - General discussion
60 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
61  
62 =head2 Support
63  
64 Please direct usage questions or support issues to the mailing list:
65  
66 I<bioperl-l@bioperl.org>
67  
68 rather than to the module maintainer directly. Many experienced and
69 reponsive experts will be able look at the problem and quickly
70 address it. Please include a thorough description of the problem
71 with code and data examples if at all possible.
72  
73 =head2 Reporting Bugs
74  
75 Report bugs to the Bioperl bug tracking system to help us keep track
76 of the bugs and their resolution. Bug reports can be submitted via
77 the web:
78  
79 https://github.com/bioperl/bioperl-live/issues
80  
81 =head1 AUTHOR - Peter Dimitrov
82  
83 Email dimitrov@gnf.org
84  
85 =head1 APPENDIX
86  
87 The rest of the documentation details each of the object methods.
88 Internal methods are usually preceded with a _
89  
90 =cut
91  
92  
93 # Let the code begin...
94  
95  
96 package Bio::Ontology::OntologyEngineI;
97 30 $Bio::Ontology::OntologyEngineI::VERSION = '1.7.8';
98 30 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
99 30 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
100  
101 30 ▶use base qw(Bio::Root::RootI);
Subroutine BEGIN: called CC=1 SCAR=0.0
102  
103 =head2 add_term
104  
105 Title : add_term
106 Usage : add_term(TermI term): TermI
107 Function: Adds TermI object to the ontology engine term store
108 Example : $oe->add_term($term)
109 Returns : its argument.
110 Args : object of class TermI.
111  
112 =cut
113  
114 0 ▶sub add_term{
Subroutine add_term: not called CC=1 SCAR=6.9
Pod documented
115 0 shift->throw_not_implemented();
116 }
117  
118 =head2 add_relationship
119  
120 Title : add_relationship
121 Usage : add_relationship(RelationshipI relationship): RelationshipI
122 Function: Adds a relationship object to the ontology engine.
123 Example :
124 Returns : Its argument.
125 Args : A RelationshipI object.
126  
127 =cut
128  
129 0 ▶sub add_relationship{
Subroutine add_relationship: not called CC=1 SCAR=6.9
Pod documented
130 0 shift->throw_not_implemented();
131 }
132  
133 =head2 add_relationship_type
134  
135 Title : add_relationship_type
136 Usage : add_relationship_type(scalar,OntologyI ontology)
137 Function: Adds a relationshiptype object to the ontology engine.
138 Example :
139 Returns : 1 on success, undef on failure
140 Args : The name(scalar) of the relationshiptype, and the OntologyI
141 it is to be added to.
142  
143 =cut
144  
145 0 ▶sub add_relationship_type{
Subroutine add_relationship_type: not called CC=1 SCAR=6.9
Pod documented
146 0 shift->throw_not_implemented();
147 }
148  
149 =head2 get_relationship_type
150  
151 Title : get_relationship_type
152 Usage : get_relationship_type(scalar): RelationshipTypeI
153 Function: Get a relationshiptype object from the ontology engine.
154 Example :
155 Returns : A RelationshipTypeI object.
156 Args : The name (scalar) of the RelationshipTypeI object desired.
157  
158 =cut
159  
160 0 ▶sub get_relationship_type{
Subroutine get_relationship_type: not called CC=1 SCAR=6.9
Pod documented
161 0 shift->throw_not_implemented();
162 }
163  
164 =head2 get_relationships
165  
166 Title : get_relationships
167 Usage : get_relationships(TermI term): RelationshipI
168 Function: Retrieves all relationship objects from this ontology engine,
169 or all relationships of a term if a term is supplied.
170 Example :
171 Returns : Array of Bio::Ontology::RelationshipI objects
172 Args : None, or a Bio::Ontology::TermI compliant object for which
173 to retrieve the relationships.
174  
175 =cut
176  
177 0 ▶sub get_relationships{
Subroutine get_relationships: not called CC=1 SCAR=6.9
Pod documented
178 0 shift->throw_not_implemented();
179 }
180  
181 =head2 get_predicate_terms
182  
183 Title : get_predicate_terms
184 Usage : get_predicate_terms(): TermI
185 Function:
186 Example :
187 Returns :
188 Args :
189  
190 =cut
191  
192 0 ▶sub get_predicate_terms{
Subroutine get_predicate_terms: not called CC=1 SCAR=6.9
Pod documented
193 0 shift->throw_not_implemented();
194 }
195  
196 =head2 get_child_terms
197  
198 Title : get_child_terms
199 Usage : get_child_terms(TermI term, TermI predicate_terms): TermI
200 Function: Retrieves all child terms of a given term, that satisfy a
201 relationship among those that are specified in the second
202 argument or undef otherwise. get_child_terms is a special
203 case of get_descendant_terms, limiting the search to the
204 direct descendants.
205  
206 Example :
207 Returns : Array of TermI objects.
208 Args : First argument is the term of interest, second is the list
209 of relationship type terms.
210  
211 =cut
212  
213 0 ▶sub get_child_terms{
Subroutine get_child_terms: not called CC=1 SCAR=6.9
Pod documented
214 0 shift->throw_not_implemented();
215 }
216  
217 =head2 get_descendant_terms
218  
219 Title : get_descendant_terms
220 Usage : get_descendant_terms(TermI term, TermI rel_types): TermI
221 Function: Retrieves all descendant terms of a given term, that
222 satisfy a relationship among those that are specified in
223 the second argument or undef otherwise.
224 Example :
225 Returns : Array of TermI objects.
226 Args : First argument is the term of interest, second is the list
227 of relationship type terms.
228  
229 =cut
230  
231 0 ▶sub get_descendant_terms{
Subroutine get_descendant_terms: not called CC=1 SCAR=6.9
Pod documented
232 0 shift->throw_not_implemented();
233 }
234  
235 =head2 get_parent_terms
236  
237 Title : get_parent_terms
238 Usage : get_parent_terms(TermI term, TermI predicate_terms): TermI
239 Function: Retrieves all parent terms of a given term, that satisfy a
240 relationship among those that are specified in the second
241 argument or undef otherwise. get_parent_terms is a special
242 case of get_ancestor_terms, limiting the search to the
243 direct ancestors.
244  
245 Example :
246 Returns : Array of TermI objects.
247 Args : First argument is the term of interest, second is the list
248 of relationship type terms.
249  
250 =cut
251  
252 0 ▶sub get_parent_terms{
Subroutine get_parent_terms: not called CC=1 SCAR=6.9
Pod documented
253 0 shift->throw_not_implemented();
254 }
255  
256 =head2 get_ancestor_terms
257  
258 Title : get_ancestor_terms
259 Usage : get_ancestor_terms(TermI term, TermI predicate_terms): TermI
260 Function: Retrieves all ancestor terms of a given term, that satisfy
261 a relationship among those that are specified in the second
262 argument or undef otherwise.
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 0 ▶sub get_ancestor_terms{
Subroutine get_ancestor_terms: not called CC=1 SCAR=6.9
Pod documented
272 0 shift->throw_not_implemented();
273 }
274  
275 =head2 get_leaf_terms
276  
277 Title : get_leaf_terms
278 Usage : get_leaf_terms(): TermI
279 Function: Retrieves all leaf terms from the ontology. Leaf term is a
280 term w/o descendants.
281  
282 Example : @leaf_terms = $obj->get_leaf_terms()
283 Returns : Array of TermI objects.
284 Args :
285  
286 =cut
287  
288 0 ▶sub get_leaf_terms{
Subroutine get_leaf_terms: not called CC=1 SCAR=6.9
Pod documented
289 0 shift->throw_not_implemented();
290 }
291  
292 =head2 get_root_terms
293  
294 Title : get_root_terms
295 Usage : get_root_terms(): TermI
296 Function: Retrieves all root terms from the ontology. Root term is a
297 term w/o ancestors.
298  
299 Example : @root_terms = $obj->get_root_terms()
300 Returns : Array of TermI objects.
301 Args :
302  
303 =cut
304  
305 0 ▶sub get_root_terms{
Subroutine get_root_terms: not called CC=1 SCAR=6.9
Pod documented
306 0 shift->throw_not_implemented();
307 }
308  
309 =head1 Factory for relationships and terms
310  
311 =cut
312  
313 =head2 relationship_factory
314  
315 Title : relationship_factory
316 Usage : $fact = $obj->relationship_factory()
317 Function: Get (and set, if the implementation supports it) the object
318 factory to be used when relationship objects are created by
319 the implementation on-the-fly.
320  
321 Example :
322 Returns : value of relationship_factory (a Bio::Factory::ObjectFactory
323 compliant object)
324 Args :
325  
326 =cut
327  
328 0 ▶sub relationship_factory{
Subroutine relationship_factory: not called CC=1 SCAR=6.9
Pod documented
329 0 return shift->throw_not_implemented();
330 }
331  
332 =head2 term_factory
333  
334 Title : term_factory
335 Usage : $fact = $obj->term_factory()
336 Function: Get (and set, if the implementation supports it) the object
337 factory to be used when term objects are created by
338 the implementation on-the-fly.
339  
340 Example :
341 Returns : value of term_factory (a Bio::Factory::ObjectFactory
342 compliant object)
343 Args :
344  
345 =cut
346  
347 0 ▶sub term_factory{
Subroutine term_factory: not called CC=1 SCAR=6.9
Pod documented
348 0 return shift->throw_not_implemented();
349 }
350  
351 =head1 Decorator Methods
352  
353 These methods come with a default implementation that uses the
354 abstract methods defined for this interface. This may not be very
355 efficient, and hence implementors are encouraged to override these
356 methods if they can provide more efficient implementations.
357  
358 =cut
359  
360 =head2 get_all_terms
361  
362 Title : get_all_terms
363 Usage : get_all_terms: TermI
364 Function: Retrieves all terms from the ontology.
365  
366 This is more a decorator method. We provide a default
367 implementation here that loops over all root terms and gets
368 all descendants for each root term. The overall union of
369 terms is then made unique by name and ontology.
370  
371 We do not mandate an order here in which the terms are
372 returned. In fact, the default implementation will return
373 them in unpredictable order.
374  
375 Engine implementations that can provide a more efficient
376 method for obtaining all terms should definitely override
377 this.
378  
379 Example : @terms = $obj->get_all_terms()
380 Returns : Array of TermI objects.
381 Args :
382  
383 =cut
384  
385 0 ▶sub get_all_terms{
Subroutine get_all_terms: not called CC=1 SCAR=6.9
Pod documented
386 0 my $self = shift;
387 # get all root nodes
388 0 my @roots = $self->get_root_terms();
389 # accumulate all descendants for each root term
390 0 my @terms = map { $self->get_descendant_terms($_); } @roots;
391 # add on the root terms themselves
392 0 push(@terms, @roots);
393 # make unique by name and ontology
394 0 my %name_map = map { ($_->name."@".$_->ontology->name, $_); } @terms;
395 # done
396 0 return values %name_map;
397 }
398  
399 =head2 find_terms
400  
401 Title : find_terms
402 Usage : ($term) = $oe->find_terms(-identifier => "SO:0000263");
403 Function: Find term instances matching queries for their attributes.
404  
405 An implementation may not support querying for arbitrary
406 attributes, but can generally be expected to accept
407 -identifier and -name as queries. If both are provided,
408 they are implicitly intersected.
409  
410 Example :
411 Returns : an array of zero or more Bio::Ontology::TermI objects
412 Args : Named parameters. The following parameters should be recognized
413 by any implementation:
414  
415 -identifier query by the given identifier
416 -name query by the given name
417  
418 =cut
419  
420 0 ▶sub find_terms{
Subroutine find_terms: not called CC=4 SCAR=30.0
Pod documented
421 0 my $self = shift;
422 0 my %params = @_;
423 0 @params{ map { lc $_; } keys %params } = values %params; # lowercase keys
424  
425 my @terms = grep {
426 0 my $ok = exists($params{-identifier}) ?
427 0 ▶ $_->identifier() eq $params{-identifier} : 1;
Branch: 1 branch
BranchTrueFalseTotal
exists $params{'-identifier'} ? : 0 0 0
428 $ok && ((! exists($params{-name})) ||
429 0 ▶ ($_->name() eq $params{-name}));
Condition0%0/6
$ok && (!exists $params{'-name'} || $_->name eq $params{'-name'})
!ll&&!rl&&r
000
not exists $params{"-name"} or $_->name eq $params{"-name"}
l!l&&r!l&&!r
000
MC/DC0%0/3
$ok && (!exists $params{'-name'} || $_->name eq $params{'-name'})
$ok not exists $params{"-name"} $_->name eq $params{"-name"}
Truth table0%0/4
A && not(B) or C
A= $okB= not exists $params{"-name"}C= $_->name eq $params{"-name"}
ABCresult
0XX0
1000
11X1
1011
430 } $self->get_all_terms();
431 0 return @terms;
432 }
433  
434 =head1 Experimental API method proposals
435  
436 Ontologies are a very new domain in bioperl, and we are not sure yet
437 what we will want to do on and with ontologies in which
438 situation. The methods from here on downwards are solely API
439 descriptions to solicit comment and feedback; the chance of any of
440 those being actually implemented already is very slim.
441  
442 Disclaimer: As long as an API method stays in this section, it is
443 subject to change, possibly even radical change or complete
444 deletion. If it's not implemented yet (most likely it isn't),
445 implement yourself at your own risk.
446  
447 So far for the disclaimer. The reason the API description is here,
448 however, is to solicit feedback. Please feel encouraged to share your
449 opinion, regardless of what it is (a notable difference of this API
450 method to others is that there is actually no working code behind it
451 - so the defense line is non-existent for practical purposes).
452  
453 =cut
454  
455 =head2 common_ancestor_path
456  
457 Title : common_ancestor_path
458 Usage :
459 Function: Get the paths from two terms A and B to term C, such that
460 there is no other term D to which A and B would have a shorter
461 path, provided there is a term C to which both A and B are
462 connected by a path.
463  
464 Note that the path to the common ancestor between A and A
465 exists, has distance zero, and predicate "identity".
466  
467 The search for the common ancestor C can be further
468 constrained by supplying a predicate term. If supplied, the
469 predicates of the two paths (A,C) and (B,C) must have a
470 common ancestor identical to the predicate, or that has a
471 path to the predicate.
472  
473 Example :
474 Returns : The path of the first term to the common ancestor in scalar
475 context, and both paths in list context. Paths are
476 Bio::Ontology::PathI compliant objects.
477 Args : The two terms (Bio::Ontology::TermI objects), and optionally
478 a constraining common predicate (Bio::Ontology::TermI object).
479 The latter may also be given as a scalar, in which case it
480 is treated as a boolean that, if TRUE, means that the two paths
481 must have identical predicates in order to be returned.
482  
483 =cut
484  
485 0 ▶sub common_ancestor_path{
Subroutine common_ancestor_path: not called CC=1 SCAR=6.9
Pod documented
486 0 return shift->throw_not_implemented();
487 }
488  
489 30 1;
« Bio/Tools/Primer/Assessor/Base.pm ↑ Summary Bio/Tools/RepeatMasker.pm »