Bio/Ontology/OntologyStore.pm

filter: Statementstmt 59.2% 48 / 81 Branchbran 31.2% 10 / 32 Conditioncond 5.8% 1 / 17 MC/DCmcdc 0.0% 0 / 10 Subroutinesub 83.3% 10 / 12 Podpod 100% 6 / 6 totaltotal 47.4% 75 / 158 CC 25 SCAR 32.6
CC
25
Cov
45%
register_ontology
44.7
remove_ontology
42.0
get_ontology
23.5
CRAP 25.9
« Bio/Matrix/PSM/IO/transfac.pm ↑ Summary Bio/Tools/Coil.pm »
1 #
2 # BioPerl module for Bio::Ontology::OntologyStore
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 # POD documentation - main docs before the code
13  
14 =head1 NAME
15  
16 Bio::Ontology::OntologyStore - A repository of ontologies
17  
18 =head1 SYNOPSIS
19  
20 #----------
21 #SCENARIO 1
22 #----------
23  
24 #make an ontology object manually. via OntologyIO
25 my $io = Bio::OntologyIO->new(
26 #params to fetch Cell Ontology here
27 );
28 my $cell_ontology = $io->next_ontology;
29  
30 #this is a singleton that caches the fact that you've created
31 #a 'Cell Ontology' instance...
32 my $store = Bio::Ontology::OntologyStore->get_instance();
33  
34 #...and it can hand you back a copy of it at any time.
35 my $cell_ontology_copy = $store->get_ontology('Cell Ontology');
36  
37  
38 #----------
39 #SCENARIO 2
40 #----------
41  
42 my $store = Bio::Ontology::OntologyStore->get_instance();
43 #this use case allows the construction of an ontology on
44 #demand just by supplying the name.
45 my $ontology = $store->get_ontology('Sequence Ontology');
46  
47  
48 =head1 DESCRIPTION
49  
50 The primary purpose of this module is that of a singleton repository
51 of L<Bio::Ontology::OntologyI> instances from which an Ontology
52 instance can be retrieved by name or identifier. This enables TermI
53 implementations to return their corresponding OntologyI through using
54 this singleton store instead of storing a direct reference to the
55 Ontology object. The latter would almost inevitably lead to memory
56 cycles, and would therefore potentially blow up an application.
57  
58 =head1 FEEDBACK
59  
60 =head2 Mailing Lists
61  
62 User feedback is an integral part of the evolution of this and other
63 Bioperl modules. Send your comments and suggestions preferably to
64 the Bioperl mailing list. Your participation is much appreciated.
65  
66 bioperl-l@bioperl.org - General discussion
67 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
68  
69 =head2 Support
70  
71 Please direct usage questions or support issues to the mailing list:
72  
73 I<bioperl-l@bioperl.org>
74  
75 rather than to the module maintainer directly. Many experienced and
76 reponsive experts will be able look at the problem and quickly
77 address it. Please include a thorough description of the problem
78 with code and data examples if at all possible.
79  
80 =head2 Reporting Bugs
81  
82 Report bugs to the Bioperl bug tracking system to help us keep track
83 of the bugs and their resolution. Bug reports can be submitted via
84 the web:
85  
86 https://github.com/bioperl/bioperl-live/issues
87  
88 =head1 AUTHOR - Hilmar Lapp
89  
90 Hilmar Lapp E<lt>hlapp@gmx.netE<gt>
91 Allen Day E<lt>allenday@ucla.eduE<gt>
92  
93 =head1 APPENDIX
94  
95 The rest of the documentation details each of the object methods.
96 Internal methods are usually preceded with a _
97  
98 =cut
99  
100  
101 # Let the code begin...
102  
103  
104 package Bio::Ontology::OntologyStore;
105 27 $Bio::Ontology::OntologyStore::VERSION = '1.7.8';
106 27 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
107  
108 # Object preamble - inherits from Bio::Root::Root
109  
110 27 ▶use Bio::Ontology::DocumentRegistry;
Subroutine BEGIN: called CC=1 SCAR=0.0
111 27 ▶use Bio::OntologyIO;
Subroutine BEGIN: called CC=1 SCAR=0.0
112 27 ▶use FileHandle;
Subroutine BEGIN: called CC=1 SCAR=0.0
113 27 ▶use File::Spec::Functions;
Subroutine BEGIN: called CC=1 SCAR=0.0
114  
115  
116 27 ▶use base qw(Bio::Root::Root);
Subroutine BEGIN: called CC=1 SCAR=0.0
117  
118 # these are the static ontology stores by name and by identifier - there is
119 # only one of each in any application
120 27 my %ont_store_by_name = ();
121 27 my %ont_store_by_id = ();
122 27 my %ont_aliases = (
123 'Gene Ontology' => 'Gene_Ontology'
124 );
125 # also, this is really meant as a singleton object, so we try to enforce it
126 27 my $instance = undef;
127  
128 =head2 new
129  
130 Title : new
131 Usage : my $obj = Bio::Ontology::OntologyStore->new();
132 Function: Returns the Bio::Ontology::OntologyStore object.
133  
134 Unlike usual implementations of new, this implementation
135 will try to return a previously instantiated store, if
136 there is any. It is just a synonym for get_instance. In
137 order to avoid ambiguities in your code, you may rather
138 want to call rather get_instance explicitly, which also
139 usually is better associated with this kind of behaviour.
140  
141 Returns : an instance of Bio::Ontology::OntologyStore
142 Args :
143  
144 =cut
145  
146 9 ▶sub new {
Subroutine new: called CC=1 SCAR=0.0
Pod documented
147 9 return shift->get_instance(@_);
148 }
149  
150 =head2 get_instance
151  
152 Title : get_instance
153 Usage :
154 Function: Get an instance of this class for perusal.
155  
156 Since by design this class is meant to be used as a
157 singleton, the implementation will return a previously
158 instantianted store if there is one, and instantiate a new
159 one otherwise. In order to use this class by means of an
160 instance, call this method for added code clarity, not
161 new().
162  
163 Example :
164 Returns : an instance of this class
165 Args : named parameters, if any (currently, there are no
166 class-specific parameters other than those accepted by
167 Bio::Root::Root.
168  
169 See L<Bio::Root::Root>.
170  
171 =cut
172  
173 10 ▶sub get_instance{
Subroutine get_instance: called CC=2 SCAR=6.9
Pod documented
174 10 my ($self,@args) = @_;
175  
176 10 ▶ if(! $instance) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($instance) 4 6 10
177 4 $instance = $self->SUPER::new(@args);
178 }
179 10 return $instance;
180 }
181  
182 =head2 get_ontology
183  
184 Title : get_ontology
185 Usage :
186 Function: Get a previously instantiated and registered instance of
187 this class by name or by identifier.
188  
189 One of the main purposes of this class is to enable TermI
190 implementations to return their respective ontology without
191 keeping a strong reference to the respective ontology
192 object. Only objects previously registered objects can be
193 retrieved.
194  
195 This is a class method, hence you can call it on the class
196 name, without dereferencing an object.
197  
198 Example :
199 Returns : a Bio::Ontology::OntologyI implementing object, or undef
200 if the query could not be satisfied
201 Args : Named parameters specifying the query. The following parameters
202 are recognized:
203 -name query the store for an ontology with the given name
204 -id query for an ontology with the given identifier
205 If both are specified, an implicit AND logical operator is
206 assumed.
207  
208 See L<Bio::Ontology::OntologyI>.
209  
210 =cut
211  
212 1 ▶sub get_ontology{
Subroutine get_ontology: called CC=9 SCAR=31.6
Pod documented
213 1 my ($self,@args) = @_;
214 1 my $ont;
215  
216 1 my ($name,$id) = $self->_rearrange([qw(NAME ID)], @args);
217 1 ▶ if($id) {
Branch: 1 branch
BranchTrueFalseTotal
if ($id) 0 1 1
218 0 $ont = $ont_store_by_id{$id};
219 0 ▶ return unless $ont; # no AND can be satisfied in this case
Branch: 1 branch
BranchTrueFalseTotal
unless $ont 0 0 0
220 }
221  
222 1 ▶ if($name) {
Branch: 1 branch
BranchTrueFalseTotal
if ($name) 1 0 1
223 1 my $o = $ont_store_by_name{$name};
224  
225 1 ▶ if(!$o){
Branch: 1 branch
BranchTrueFalseTotal
unless ($o) 1 0 1
226 1 my $doc_registry = Bio::Ontology::DocumentRegistry->get_instance();
227 1 my($url,$def,$fmt) = $doc_registry->documents($name);
228  
229 1 ▶ if(ref($url) eq 'ARRAY'){
Branch: 2 branches
BranchTrueFalseTotal
if (ref $url eq 'ARRAY') { } 0 1 1
elsif ($url) { } 1 0 1
230 0 my $io = Bio::OntologyIO->new(-url => $url,
231 -defs_url => $def,
232 -format => $fmt,
233 );
234  
235 0 $o = $io->next_ontology();
236 0 $ont_store_by_name{$name} = $o;
237 } elsif($url){
238 1 my $io = Bio::OntologyIO->new(-url => $url,
239 -defs_url => $def,
240 -format => $fmt,
241 );
242 1 $o = $io->next_ontology;
243 0 $ont_store_by_name{$name} = $o;
244 }
245 }
246  
247 0 ▶ if((! $ont) || ($ont->identifier() eq $o->identifier())) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $ont or $ont->identifier eq $o->identifier) { } 0 0 0
Condition0%0/3
not $ont or $ont->identifier eq $o->identifier
l!l&&r!l&&!r
000
MC/DC0%0/2
not $ont or $ont->identifier eq $o->identifier
not $ont $ont->identifier eq $o->identifier
Truth table0%0/3
not(A) or B
A= not $ontB= $ont->identifier eq $o->identifier
ABresult
1X1
011
000
248 0 $ont = $o;
249 } else {
250 0 $ont = undef;
251 }
252 }
253
254 0 return $ont;
255 }
256  
257 =head2 register_ontology
258  
259 Title : register_ontology
260 Usage :
261 Function: Registers the given Ontology object for later retrieval
262 by name and identifier.
263  
264 Example :
265 Returns : TRUE on success and FALSE otherwise
266 Args : the Bio::Ontology::OntologyI object(s) to register
267  
268 See L<Bio::Ontology::OntologyI>.
269  
270 =cut
271  
272 9 ▶sub register_ontology {
Subroutine register_ontology: called CC=10 SCAR=38.0
Pod documented
273 9 my ($self,@args) = @_;
274 9 my $ret = 1;
275 9 foreach my $ont (@args) {
276 9 ▶ if(ref($ont) && $ont->isa('Bio::Ontology::OntologyI')){
Branch: 1 branch
BranchTrueFalseTotal
if (ref $ont and $ont->isa("Bio::Ontology::OntologyI")) 9 0 9
Condition33%1/3
ref $ont and $ont->isa("Bio::Ontology::OntologyI")
!ll&&!rl&&r
009
MC/DC0%0/2
ref $ont and $ont->isa("Bio::Ontology::OntologyI")
ref $ont $ont->isa("Bio::Ontology::OntologyI")
Truth table33%1/3
A and B
A= ref $ontB= $ont->isa("Bio::Ontology::OntologyI")
ABresult
0X0
100
111
277 9 ▶ $ont_store_by_name{$ont->name()} = $ont if $ont->name;
Branch: 1 branch
BranchTrueFalseTotal
if $ont->name 8 1 9
278 9 next;
279 }
280  
281 0 ▶ if(! (ref($ont) && $ont->isa("Bio::Ontology::OntologyI"))) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $ont and $ont->isa("Bio::Ontology::OntologyI")) 0 0 0
Condition0%0/3
ref $ont and $ont->isa("Bio::Ontology::OntologyI")
!ll&&!rl&&r
000
MC/DC0%0/2
ref $ont and $ont->isa("Bio::Ontology::OntologyI")
ref $ont $ont->isa("Bio::Ontology::OntologyI")
Truth table0%0/3
A and B
A= ref $ontB= $ont->isa("Bio::Ontology::OntologyI")
ABresult
0X0
100
111
282 0 ▶ $self->throw((ref($ont) ? ref($ont) : $ont)." does not implement ".
Branch: 1 branch
BranchTrueFalseTotal
ref $ont ? : 0 0 0
283 "Bio::Ontology::OntologyI or is not an object");
284 }
285 0 ▶ if($self->get_ontology(-name => $ont->name())) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->get_ontology("-name", $ont->name)) 0 0 0
286 0 $self->warn("ontology with name \"".$ont->name().
287 "\" already exists in the store, ignoring new one");
288 0 $ret = 0;
289 0 next;
290 }
291 0 ▶ if($self->get_ontology(-id => $ont->identifier())) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->get_ontology("-id", $ont->identifier)) 0 0 0
292 0 $self->warn("ontology with id \"".$ont->identifier().
293 "\" already exists in the store, ignoring new one");
294 0 $ret = 0;
295 0 next;
296 }
297 0 $ont_store_by_name{$ont->name()} = $ont;
298 0 $ont_store_by_id{$ont->identifier()} = $ont;
299 }
300 9 return $ret;
301 }
302  
303 =head2 remove_ontology
304  
305 Title : remove_ontology
306 Usage :
307 Function: Remove the specified ontology from the store.
308 Example :
309 Returns : TRUE on success and FALSE otherwise
310 Args : the Bio::Ontology::OntologyI implementing object(s)
311 to be removed from the store
312  
313 See L<Bio::Ontology::OntologyI>.
314  
315 =cut
316  
317 0 ▶sub remove_ontology{
Subroutine remove_ontology: not called CC=6 SCAR=37.4
Pod documented
318 0 my $self = shift;
319 0 my $ret = 1;
320  
321 0 foreach my $ont (@_) {
322 0 ▶ $self->throw(ref($ont)." does not implement Bio::Ontology::OntologyI")
Branch: 1 branch
BranchTrueFalseTotal
unless $ont and ref $ont and $ont->isa("Bio::Ontology::OntologyI") 0 0 0
Condition0%0/6
$ont and ref $ont and $ont->isa("Bio::Ontology::OntologyI")
!ll&&!rl&&r
000
$ont and ref $ont
!ll&&!rl&&r
000
MC/DC0%0/3
$ont and ref $ont and $ont->isa("Bio::Ontology::OntologyI")
$ont ref $ont $ont->isa("Bio::Ontology::OntologyI")
Truth table0%0/4
A and B and C
A= $ontB= ref $ontC= $ont->isa("Bio::Ontology::OntologyI")
ABCresult
0XX0
10X0
1100
1111
323 unless $ont && ref($ont) && $ont->isa("Bio::Ontology::OntologyI");
324 # remove it from both the id hash and the name hash
325 0 delete $ont_store_by_id{$ont->identifier()};
326 0 ▶ delete $ont_store_by_name{$ont->name()} if $ont->name();
Branch: 1 branch
BranchTrueFalseTotal
if $ont->name 0 0 0
327 }
328 0 return 1;
329 }
330  
331 =head2 guess_ontology()
332  
333 Usage : my $ontology =
334 Bio::Ontology::OntologyStore->guess_ontology('GO:0000001');
335 Function: tries to guess which ontology a term identifier comes from,
336 loads it as necessary,
337 and returns it as a Bio::Ontology::Ontology object.
338 Example :
339 Returns : a Bio::Ontology::Ontology object, or warns and returns undef
340 Args : an ontology term identifier in XXXX:DDDDDDD format.
341 Guessing is based on the XXXX string before the colon.
342  
343 =cut
344  
345 0 ▶sub guess_ontology {
Subroutine guess_ontology: not called CC=2 SCAR=17.9
Pod documented
346 0 my ($self,$id) = @_;
347  
348 0 my($prefix) = $id =~ /^(.+?):.+$/;
349  
350 0 my %prefix = (
351 SO => 'Sequence Ontology',
352 SOFA => 'Sequence Ontology Feature Annotation',
353 GO => 'Gene Ontology',
354 );
355  
356 0 ▶ return $prefix{$prefix} || undef;
Condition0%0/2
$prefix{$prefix} || undef
l!l
00
MC/DC0%0/1
$prefix{$prefix} || undef
$prefix{$prefix}
Truth table0%0/2
A
A= $prefix{$prefix}
Aresult
11
00
357 }
358  
359 27 1;
« Bio/Matrix/PSM/IO/transfac.pm ↑ Summary Bio/Tools/Coil.pm »