Variation/IO.pm

filter: Statementstmt 68.4% 26 / 38 Branchbran 40.0% 4 / 10 Conditioncond 50.0% 4 / 8 MC/DCmcdc 0.0% 0 / 4 Subroutinesub 55.5% 5 / 9 Podpod 100% 5 / 5 totaltotal 59.4% 44 / 74 CC 9 SCAR 13.5
CC
9
Cov
61%
_guess_format
6.0
new
5.5
_load_format_module
2.0
CRAP 3.9
« Variation/AAReverseMutate.pm ↑ Summary Variation/SNP.pm »
1 #
2 # BioPerl module for Bio::Variation::IO
3 #
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
5 #
6 # Cared for by Heikki Lehvaslaiho <heikki-at-bioperl-dot-org>
7 #
8 # Copyright Heikki Lehvaslaiho
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::Variation::IO - Handler for sequence variation IO Formats
17  
18 =head1 SYNOPSIS
19  
20 use Bio::Variation::IO;
21  
22 $in = Bio::Variation::IO->new(-file => "inputfilename" ,
23 -format => 'flat');
24 $out = Bio::Variation::IO->new(-file => ">outputfilename" ,
25 -format => 'xml');
26  
27 while ( my $seq = $in->next() ) {
28 $out->write($seq);
29 }
30  
31 # or
32  
33 use Bio::Variation::IO;
34  
35 #input file format can be read from the file extension (dat|xml)
36 $in = Bio::Variation::IO->newFh(-file => "inputfilename");
37 $out = Bio::Variation::IO->newFh(-format => 'xml');
38  
39 # World's shortest flat<->xml format converter:
40 print $out $_ while <$in>;
41  
42 =head1 DESCRIPTION
43  
44 Bio::Variation::IO is a handler module for the formats in the
45 Variation IO set (eg, Bio::Variation::IO::flat). It is the officially
46 sanctioned way of getting at the format objects, which most people
47 should use.
48  
49 The structure, conventions and most of the code is inherited from
50 L<Bio::SeqIO> module. The main difference is that instead of using
51 methods next_seq and write_seq, you drop '_seq' from the method names.
52  
53 The idea is that you request a stream object for a particular format.
54 All the stream objects have a notion of an internal file that is read
55 from or written to. A particular SeqIO object instance is configured
56 for either input or output. A specific example of a stream object is
57 the Bio::Variation::IO::flat object.
58  
59 Each stream object has functions
60  
61 $stream->next();
62  
63 and
64  
65 $stream->write($seqDiff);
66  
67 also
68  
69 $stream->type() # returns 'INPUT' or 'OUTPUT'
70  
71 As an added bonus, you can recover a filehandle that is tied to the
72 SeqIO object, allowing you to use the standard E<lt>E<gt> and print
73 operations to read and write sequence objects:
74  
75 use Bio::Variation::IO;
76  
77 $stream = Bio::Variation::IO->newFh(-format => 'flat');
78 # read from standard input
79  
80 while ( $seq = <$stream> ) {
81 # do something with $seq
82 }
83  
84 and
85  
86 print $stream $seq; # when stream is in output mode
87  
88 This makes the simplest ever reformatter
89  
90 #!/usr/local/bin/perl
91  
92 $format1 = shift;
93 $format2 = shift;
94  
95 use Bio::Variation::IO;
96  
97 $in = Bio::Variation::IO->newFh(-format => $format1 );
98 $out = Bio::Variation::IO->newFh(-format => $format2 );
99  
100 print $out $_ while <$in>;
101  
102  
103 =head1 CONSTRUCTORS
104  
105 =head2 Bio::Variation::IO-E<gt>new()
106  
107 $seqIO = Bio::Variation::IO->new(-file => 'filename', -format=>$format);
108 $seqIO = Bio::Variation::IO->new(-fh => \*FILEHANDLE, -format=>$format);
109 $seqIO = Bio::Variation::IO->new(-format => $format);
110  
111 The new() class method constructs a new Bio::Variation::IO object. The
112 returned object can be used to retrieve or print BioSeq objects. new()
113 accepts the following parameters:
114  
115 =over 4
116  
117 =item -file
118  
119 A file path to be opened for reading or writing. The usual Perl
120 conventions apply:
121  
122 'file' # open file for reading
123 '>file' # open file for writing
124 '>>file' # open file for appending
125 '+<file' # open file read/write
126 'command |' # open a pipe from the command
127 '| command' # open a pipe to the command
128  
129 =item -fh
130  
131 You may provide new() with a previously-opened filehandle. For
132 example, to read from STDIN:
133  
134 $seqIO = Bio::Variation::IO->new(-fh => \*STDIN);
135  
136 Note that you must pass filehandles as references to globs.
137  
138 If neither a filehandle nor a filename is specified, then the module
139 will read from the @ARGV array or STDIN, using the familiar E<lt>E<gt>
140 semantics.
141  
142 =item -format
143  
144 Specify the format of the file. Supported formats include:
145  
146 flat pseudo EMBL format
147 xml seqvar xml format
148  
149 If no format is specified and a filename is given, then the module
150 will attempt to deduce it from the filename. If this is unsuccessful,
151 Fasta format is assumed.
152  
153 The format name is case insensitive. 'FLAT', 'Flat' and 'flat' are
154 all supported.
155  
156 =back
157  
158 =head2 Bio::Variation::IO-E<gt>newFh()
159  
160 $fh = Bio::Variation::IO->newFh(-fh => \*FILEHANDLE, -format=>$format);
161 $fh = Bio::Variation::IO->newFh(-format => $format);
162 # etc.
163  
164 #e.g.
165 $out = Bio::Variation::IO->newFh( '-FORMAT' => 'flat');
166 print $out $seqDiff;
167  
168 This constructor behaves like new(), but returns a tied filehandle
169 rather than a Bio::Variation::IO object. You can read sequences from this
170 object using the familiar E<lt>E<gt> operator, and write to it using print().
171 The usual array and $_ semantics work. For example, you can read all
172 sequence objects into an array like this:
173  
174 @mutations = <$fh>;
175  
176 Other operations, such as read(), sysread(), write(), close(), and printf()
177 are not supported.
178  
179 =head1 OBJECT METHODS
180  
181 See below for more detailed summaries. The main methods are:
182  
183 =head2 $sequence = $seqIO-E<gt>next()
184  
185 Fetch the next sequence from the stream.
186  
187 =head2 $seqIO-E<gt>write($sequence [,$another_sequence,...])
188  
189 Write the specified sequence(s) to the stream.
190  
191 =head2 TIEHANDLE(), READLINE(), PRINT()
192  
193 These provide the tie interface. See L<perltie> for more details.
194  
195 =head1 FEEDBACK
196  
197 =head2 Mailing Lists
198  
199 User feedback is an integral part of the evolution of this and other
200 Bioperl modules. Send your comments and suggestions preferably to the
201 Bioperl mailing lists Your participation is much appreciated.
202  
203 bioperl-l@bioperl.org - General discussion
204 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
205  
206 =head2 Support
207  
208 Please direct usage questions or support issues to the mailing list:
209  
210 I<bioperl-l@bioperl.org>
211  
212 rather than to the module maintainer directly. Many experienced and
213 reponsive experts will be able look at the problem and quickly
214 address it. Please include a thorough description of the problem
215 with code and data examples if at all possible.
216  
217 =head2 Reporting Bugs
218  
219 Report bugs to the Bioperl bug tracking system to help us keep track
220 the bugs and their resolution. Bug reports can be submitted via the
221 web:
222  
223 https://github.com/bioperl/bioperl-live/issues
224  
225 =head1 AUTHOR - Heikki Lehvaslaiho
226  
227 Email: heikki-at-bioperl-dot-org
228  
229 =head1 APPENDIX
230  
231 The rest of the documentation details each of the object
232 methods. Internal methods are usually preceded with a _
233  
234 =cut
235  
236 # Let the code begin...
237  
238 package Bio::Variation::IO;
239 3 $Bio::Variation::IO::VERSION = '1.7.5';
240 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
241  
242  
243 3 ▶use base qw(Bio::SeqIO Bio::Root::IO);
Subroutine BEGIN: called CC=1 SCAR=0.0
244  
245 =head2 new
246  
247 Title : new
248 Usage : $stream = Bio::Variation::IO->new(-file => $filename, -format => 'Format')
249 Function: Returns a new seqstream
250 Returns : A Bio::Variation::IO::Handler initialised with the appropriate format
251 Args : -file => $filename
252 -format => format
253 -fh => filehandle to attach to
254  
255 =cut
256  
257  
258 4 ▶sub new {
Subroutine new: called CC=5 SCAR=17.1
Pod documented
259 4 my ($class, %param) = @_;
260 4 my ($format);
261  
262 4 @param{ map { lc $_ } keys %param } = values %param; # lowercase keys
263 $format = $param{'-format'}
264 4 ▶ || $class->_guess_format( $param{-file} || $ARGV[0] )
Condition50%4/8
$param{'-format'} || $class->_guess_format($param{'-file'} || $ARGV[0]) || 'flat'
l!l
40
$param{"-format"} or $class->_guess_format($param{"-file"} || $ARGV[0])
l!l&&r!l&&!r
220
$param{'-file'} || $ARGV[0]
l!l&&r!l&&!r
200
MC/DC0%0/2
$param{'-format'} || $class->_guess_format($param{'-file'} || $ARGV[0]) || 'flat'
$param{"-format"} $class->_guess_format($param{"-file"} || $ARGV[0])
MC/DC0%0/2
$param{'-file'} || $ARGV[0]
$param{'-file'} $ARGV[0]
Truth table66%2/3
A or B
A= $param{"-format"}B= $class->_guess_format($param{"-file"} || $ARGV[0])
ABresult
1X1
011
000
Truth table33%1/3
A || B
A= $param{'-file'}B= $ARGV[0]
ABresult
1X1
011
000
265 || 'flat';
266 4 $format = "\L$format"; # normalize capitalization to lower case
267  
268 4 ▶ return unless $class->_load_format_module($format);
Branch: 1 branch
BranchTrueFalseTotal
unless $class->_load_format_module($format) 0 4 4
269 4 return "Bio::Variation::IO::$format"->new(%param);
270 }
271  
272  
273 =head2 format
274  
275 Title : format
276 Usage : $format = $stream->format()
277 Function: Get the variation format
278 Returns : variation format
279 Args : none
280  
281 =cut
282  
283 # format() method inherited from Bio::Root::IO
284  
285  
286 4 ▶sub _load_format_module {
Subroutine _load_format_module: called CC=2 SCAR=7.1
287 4 my ($class, $format) = @_;
288 4 my $module = "Bio::Variation::IO::" . $format;
289 4 my $ok;
290 4 eval {
291 4 $ok = $class->_load_module($module);
292 };
293 4 ▶ if ( $@ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 4 4
294 0 print STDERR <<END;
295 $class: $format cannot be found
296 Exception $@
297 For more information about the IO system please see the IO docs.
298 This includes ways of checking for formats at compile time, not run time
299 END
300 ;
301 }
302 4 return $ok;
303 }
304  
305 =head2 next
306  
307 Title : next
308 Usage : $seqDiff = $stream->next
309 Function: reads the next $seqDiff object from the stream
310 Returns : a Bio::Variation::SeqDiff object
311 Args :
312  
313 =cut
314  
315 0 ▶sub next {
Subroutine next: not called CC=1 SCAR=6.9
Pod documented
316 0 my ($self, $seq) = @_;
317 0 $self->throw("Sorry, you cannot read from a generic Bio::Variation::IO object.");
318 }
319  
320 0 ▶sub next_seq {
Subroutine next_seq: not called CC=1 SCAR=6.9
Pod documented
321 0 my ($self, $seq) = @_;
322 0 $self->throw("These are not sequence objects. Use method 'next' instead of 'next_seq'.");
323 0 $self->next($seq);
324 }
325  
326 =head2 write
327  
328 Title : write
329 Usage : $stream->write($seq)
330 Function: writes the $seq object into the stream
331 Returns : 1 for success and 0 for error
332 Args : Bio::Variation::SeqDiff object
333  
334 =cut
335  
336 0 ▶sub write {
Subroutine write: not called CC=1 SCAR=6.9
Pod documented
337 0 my ($self, $seq) = @_;
338 0 $self->throw("Sorry, you cannot write to a generic Bio::Variation::IO object.");
339 }
340  
341 0 ▶sub write_seq {
Subroutine write_seq: not called CC=1 SCAR=6.9
Pod documented
342 0 my ($self, $seq) = @_;
343 0 $self->warn("These are not sequence objects. Use method 'write' instead of 'write_seq'.");
344 0 $self->write($seq);
345 }
346  
347 =head2 _guess_format
348  
349 Title : _guess_format
350 Usage : $obj->_guess_format($filename)
351 Function:
352 Example :
353 Returns : guessed format of filename (lower case)
354 Args :
355  
356 =cut
357  
358 2 ▶sub _guess_format {
Subroutine _guess_format: called CC=4 SCAR=17.9
359 2 my $class = shift;
360 2 ▶ return unless $_ = shift;
Branch: 1 branch
BranchTrueFalseTotal
unless $_ = shift() 0 2 2
361 2 ▶ return 'flat' if /\.dat$/i;
Branch: 1 branch
BranchTrueFalseTotal
if /\.dat$/i 2 0 2
362 0 ▶ return 'xml' if /\.xml$/i;
Branch: 1 branch
BranchTrueFalseTotal
if /\.xml$/i 0 0 0
363 }
364  
365  
366 3 1;
« Variation/AAReverseMutate.pm ↑ Summary Variation/SNP.pm »