Bio/OntologyIO.pm

filter: Statementstmt 94.4% 51 / 54 Branchbran 71.4% 10 / 14 Conditioncond 33.3% 1 / 3 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 90.0% 9 / 10 Podpod 75.0% 3 / 4 totaltotal 85.0% 74 / 87 CC 9 SCAR 8.8
CC
9
Cov
87%
new
4.1
_map_format
3.0
_load_format_module
2.0
CRAP 2.4
« Bio/Tree/TreeI.pm ↑ Summary Bio/Matrix/PSM/Psm.pm »
1 #
2 # BioPerl module for Bio::OntologyIO
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::OntologyIO - Parser factory for Ontology formats
31  
32 =head1 SYNOPSIS
33  
34 use Bio::OntologyIO;
35  
36 my $parser = Bio::OntologyIO->new(-format => "go",
37 -file=> $file);
38  
39 while(my $ont = $parser->next_ontology()) {
40 print "read ontology ",$ont->name()," with ",
41 scalar($ont->get_root_terms)," root terms, and ",
42 scalar($ont->get_leaf_terms)," leaf terms\n";
43 }
44  
45 =head1 DESCRIPTION
46  
47 This is the parser factory for different ontology sources and
48 formats. Conceptually, it is very similar to L<Bio::SeqIO>, but the
49 difference is that the chunk of data returned as an object is an
50 entire ontology.
51  
52 =head1 FEEDBACK
53  
54 =head2 Mailing Lists
55  
56 User feedback is an integral part of the evolution of this and other
57 Bioperl modules. Send your comments and suggestions preferably to
58 the Bioperl mailing list. Your participation is much appreciated.
59  
60 bioperl-l@bioperl.org - General discussion
61 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
62  
63 =head2 Support
64  
65 Please direct usage questions or support issues to the mailing list:
66  
67 I<bioperl-l@bioperl.org>
68  
69 rather than to the module maintainer directly. Many experienced and
70 reponsive experts will be able look at the problem and quickly
71 address it. Please include a thorough description of the problem
72 with code and data examples if at all possible.
73  
74 =head2 Reporting Bugs
75  
76 Report bugs to the Bioperl bug tracking system to help us keep track
77 of the bugs and their resolution. Bug reports can be submitted via
78 the web:
79  
80 https://github.com/bioperl/bioperl-live/issues
81  
82 =head1 AUTHOR - Hilmar Lapp
83  
84 Email hlapp at gmx.net
85  
86 =head1 APPENDIX
87  
88 The rest of the documentation details each of the object methods.
89 Internal methods are usually preceded with a _
90  
91 =cut
92  
93  
94 # Let the code begin...
95  
96  
97 package Bio::OntologyIO;
98 28 $Bio::OntologyIO::VERSION = '1.7.8';
99 28 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
100  
101 # Object preamble - inherits from Bio::Root::Root
102  
103  
104 28 ▶use base qw(Bio::Root::Root Bio::Root::IO);
Subroutine BEGIN: called CC=1 SCAR=0.0
105  
106 #
107 # Maps from format name to driver suitable for the format.
108 #
109 28 my %format_driver_map = (
110 "go" => "goflat",
111 "so" => "soflat",
112 "interpro" => "InterProParser",
113 "interprosax" => "Handlers::InterPro_BioSQL_Handler",
114 "evoc" => "simplehierarchy",
115 "obo" => "obo"
116 );
117  
118 =head2 new
119  
120 Title : new
121 Usage : my $parser = Bio::OntologyIO->new(-format => 'go', @args);
122 Function: Returns a stream of ontologies opened on the specified input
123 for the specified format.
124 Returns : An ontology parser (an instance of Bio::OntologyIO) initialized
125 for the specified format.
126 Args : Named parameters. Common parameters are
127  
128 -format - the format of the input; the following are
129 presently supported:
130 goflat: DAG-Edit Gene Ontology flat files
131 go : synonymous to goflat
132 soflat: DAG-Edit Sequence Ontology flat files
133 so : synonymous to soflat
134 simplehierarchy: text format with one term per line
135 and indentation giving the hierarchy
136 evoc : synonymous to simplehierarchy
137 interpro: InterPro XML
138 interprosax: InterPro XML - this is actually not a
139 Bio::OntologyIO compliant parser; instead it
140 persists terms as they are encountered.
141 L<Bio::OntologyIO::Handlers::InterPro_BioSQL_Handler>
142 obo : OBO format style from Gene Ontology Consortium
143 -file - the file holding the data
144 -fh - the stream providing the data (-file and -fh are
145 mutually exclusive)
146 -ontology_name - the name of the ontology
147 -engine - the L<Bio::Ontology::OntologyEngineI> object
148 to be reused (will be created otherwise); note
149 that every L<Bio::Ontology::OntologyI> will
150 qualify as well since that one inherits from the
151 former.
152 -term_factory - the ontology term factory to use. Provide a
153 value only if you know what you are doing.
154  
155 DAG-Edit flat file parsers will usually also accept the
156 following parameters.
157  
158 -defs_file - the name of the file holding the term
159 definitions
160 -files - an array ref holding the file names (for GO,
161 there will usually be 3 files: component.ontology,
162 function.ontology, process.ontology)
163  
164 Other parameters are specific to the parsers.
165  
166 =cut
167  
168 16 ▶sub new {
Subroutine new: called CC=4 SCAR=14.0
Pod documented
169 16 my ($caller,@args) = @_;
170 16 ▶ my $class = ref($caller) || $caller;
Condition33%1/3
ref $caller || $caller
l!l&&r!l&&!r
0160
MC/DC0%0/2
ref $caller || $caller
ref $caller $caller
Truth table33%1/3
A || B
A= ref $callerB= $caller
ABresult
1X1
011
000
171 # or do we want to call SUPER on an object if $caller is an
172 # object?
173 16 ▶ if( $class =~ /Bio::OntologyIO::(\S+)/ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($class =~ /Bio::OntologyIO::(\S+)/) { } 8 8 16
174 8 my ($self) = $class->SUPER::new(@args);
175 8 $self->_initialize(@args);
176 8 return $self;
177 } else {
178 8 my %param = @args;
179 8 @param{ map { lc $_ } keys %param } = values %param; # lowercase keys
180 8 my $format = $class->_map_format($param{'-format'});
181  
182 # normalize capitalization
183 8 ▶ return unless( $class->_load_format_module($format) );
Branch: 1 branch
BranchTrueFalseTotal
unless $class->_load_format_module($format) 0 8 8
184 8 return "Bio::OntologyIO::$format"->new(@args);
185 }
186  
187 }
188  
189  
190 =head2 format
191  
192 Title : format
193 Usage : $format = $parser->format()
194 Function: Get the ontology format
195 Returns : ontology format
196 Args : none
197  
198 =cut
199  
200 # format() method inherited from Bio::Root::IO
201  
202  
203 8 ▶sub _initialize {
Subroutine _initialize: called CC=2 SCAR=7.0
204 8 my($self, @args) = @_;
205  
206 # initialize factories etc
207 8 my ($eng,$fact,$ontname) =
208 $self->_rearrange([qw(TERM_FACTORY)
209 ], @args);
210 # term object factory
211 8 ▶ $self->term_factory($fact) if $fact;
Branch: 1 branch
BranchTrueFalseTotal
if $fact 0 8 8
212  
213 # initialize the Bio::Root::IO part
214 8 $self->_initialize_io(@args);
215 }
216  
217 =head2 next_ontology
218  
219 Title : next_ontology
220 Usage : $ont = $stream->next_ontology()
221 Function: Reads the next ontology object from the stream and returns it.
222 Returns : a L<Bio::Ontology::OntologyI> compliant object, or undef at the
223 end of the stream
224 Args : none
225  
226  
227 =cut
228  
229 0 ▶sub next_ontology {
Subroutine next_ontology: not called CC=1 SCAR=6.9
Pod documented
230 0 shift->throw_not_implemented();
231 }
232  
233 =head2 term_factory
234  
235 Title : term_factory
236 Usage : $obj->term_factory($newval)
237 Function: Get/set the ontology term factory to use.
238  
239 As a user of this module it is not necessary to call this
240 method as there will be default. In order to change the
241 default, the easiest way is to instantiate
242 L<Bio::Ontology::TermFactory> with the proper -type
243 argument. Most if not all parsers will actually use this
244 very implementation, so even easier than the aforementioned
245 way is to simply call
246 $ontio->term_factory->type("Bio::Ontology::MyTerm").
247  
248 Example :
249 Returns : value of term_factory (a Bio::Factory::ObjectFactoryI object)
250 Args : on set, new value (a Bio::Factory::ObjectFactoryI object, optional)
251  
252  
253 =cut
254  
255 2500 ▶sub term_factory{
Subroutine term_factory: called CC=2 SCAR=6.9
Pod documented
256 2500 my $self = shift;
257  
258 2500 ▶ return $self->{'term_factory'} = shift if @_;
Branch: 1 branch
BranchTrueFalseTotal
if @_ 8 2492 2500
259 2492 return $self->{'term_factory'};
260 }
261  
262 =head1 Private Methods
263  
264 Some of these are actually 'protected' in OO speak, which means you
265 may or will want to utilize them in a derived ontology parser, but
266 you should not call them from outside.
267  
268 =cut
269  
270 =head2 _load_format_module
271  
272 Title : _load_format_module
273 Usage : *INTERNAL OntologyIO stuff*
274 Function: Loads up (like use) a module at run time on demand
275 Example :
276 Returns :
277 Args :
278  
279 =cut
280  
281 8 ▶sub _load_format_module {
Subroutine _load_format_module: called CC=2 SCAR=7.1
282 8 my ($self, $format) = @_;
283 8 my $module = "Bio::OntologyIO::" . $format;
284 8 my $ok;
285  
286 8 eval {
287 8 $ok = $self->_load_module($module);
288 };
289 8 ▶ if ( $@ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 8 8
290 0 print STDERR <<END;
291 $self: $format cannot be found
292 Exception $@
293 For more information about the OntologyIO system please see the docs.
294 This includes ways of checking for formats at compile time, not run time
295 END
296 }
297 8 return $ok;
298 }
299  
300 8 ▶sub DESTROY {
Subroutine DESTROY: called CC=1 SCAR=0.0
301 8 my $self = shift;
302  
303 8 $self->close();
304 }
305  
306 8 ▶sub _map_format {
Subroutine _map_format: called CC=3 SCAR=11.1
307 8 my $self = shift;
308 8 my $format = shift;
309 8 my $mod;
310  
311 8 ▶ if($format) {
Branch: 1 branch
BranchTrueFalseTotal
if ($format) { } 8 0 8
312 8 $mod = $format_driver_map{lc($format)};
313 8 ▶ $mod = lc($format) unless $mod;
Branch: 1 branch
BranchTrueFalseTotal
unless $mod 2 6 8
314 } else {
315 0 $self->throw("unable to guess ontology format, specify -format");
316 }
317 8 return $mod;
318 }
319  
320 99 ▶sub unescape {
Subroutine unescape: called CC=1 SCAR=0.0
Pod undocumented
321 99 my( $self, $ref ) = @_;
322 99 $ref =~ s/&lt\\;/\</g;
323 99 $ref =~ s/&gt\\;/\>/g;
324 99 $ref =~ s/&pct\\;/\%/g;
325 99 $ref =~ s/\\n/\n/g;
326 99 $ref =~ s/\\t/\t/g;
327 99 return $ref;
328 }
329  
330 28 1;
« Bio/Tree/TreeI.pm ↑ Summary Bio/Matrix/PSM/Psm.pm »