Bio/DB/Fasta.pm

filter: Statementstmt 94.5% 138 / 146 Branchbran 72.7% 32 / 44 Conditioncond 71.4% 15 / 21 MC/DCmcdc 30.7% 4 / 13 Subroutinesub 91.6% 22 / 24 Podpod 50.0% 1 / 2 totaltotal 84.8% 212 / 250 CC 32 SCAR 23.4
CC
32
Cov
88%
_calculate_offsets
23.6
subseq
4.0
new
4.0
CRAP 10.4
« Bio/TreeIO/newick.pm ↑ Summary Bio/Matrix/PSM/ProtPsm.pm »
1 #
2 # BioPerl module for Bio::DB::Fasta
3 #
4 # You may distribute this module under the same terms as perl itself
5 #
6  
7  
8 =head1 NAME
9  
10 Bio::DB::Fasta - Fast indexed access to fasta files
11  
12 =head1 SYNOPSIS
13  
14 use Bio::DB::Fasta;
15  
16 # Create database from a directory of Fasta files
17 my $db = Bio::DB::Fasta->new('/path/to/fasta/files/');
18 my @ids = $db->get_all_primary_ids;
19  
20 # Simple access
21 my $seqstr = $db->seq('CHROMOSOME_I', 4_000_000 => 4_100_000);
22 my $revseq = $db->seq('CHROMOSOME_I', 4_100_000 => 4_000_000);
23 my $length = $db->length('CHROMOSOME_I');
24 my $header = $db->header('CHROMOSOME_I');
25 my $alphabet = $db->alphabet('CHROMOSOME_I');
26  
27 # Access to sequence objects. See Bio::PrimarySeqI.
28 my $seq = $db->get_Seq_by_id('CHROMOSOME_I');
29 my $seqstr = $seq->seq;
30 my $subseq = $seq->subseq(4_000_000 => 4_100_000);
31 my $trunc = $seq->trunc(4_000_000 => 4_100_000);
32 my $length = $seq->length;
33  
34 # Loop through sequence objects
35 my $stream = $db->get_PrimarySeq_stream;
36 while (my $seq = $stream->next_seq) {
37 # Bio::PrimarySeqI stuff
38 }
39  
40 # Filehandle access
41 my $fh = Bio::DB::Fasta->newFh('/path/to/fasta/files/');
42 while (my $seq = <$fh>) {
43 # Bio::PrimarySeqI stuff
44 }
45  
46 # Tied hash access
47 tie %sequences,'Bio::DB::Fasta','/path/to/fasta/files/';
48 print $sequences{'CHROMOSOME_I:1,20000'};
49  
50 =head1 DESCRIPTION
51  
52 Bio::DB::Fasta provides indexed access to a single Fasta file, several files,
53 or a directory of files. It provides persistent random access to each sequence
54 entry (either as a Bio::PrimarySeqI-compliant object or a string), and to
55 subsequences within each entry, allowing you to retrieve portions of very large
56 sequences without bringing the entire sequence into memory. Bio::DB::Fasta is
57 based on Bio::DB::IndexedBase. See this module's documentation for details.
58  
59 The Fasta files may contain any combination of nucleotide and protein sequences;
60 during indexing the module guesses the molecular type. Entries may have any line
61 length up to 65,536 characters, and different line lengths are allowed in the
62 same file. However, within a sequence entry, all lines must be the same length
63 except for the last. An error will be thrown if this is not the case.
64  
65 The module uses /^E<gt>(\S+)/ to extract the primary ID of each sequence
66 from the Fasta header. See -makeid in Bio::DB::IndexedBase to pass a callback
67 routine to reversibly modify this primary ID, e.g. if you wish to extract a
68 specific portion of the gi|gb|abc|xyz GenBank IDs.
69  
70 =head1 DATABASE CREATION AND INDEXING
71  
72 The object-oriented constructor is new(), the filehandle constructor is newFh()
73 and the tied hash constructor is tie(). They all allow one to index a single Fasta
74 file, several files, or a directory of files. See Bio::DB::IndexedBase.
75  
76 =head1 SEE ALSO
77  
78 L<Bio::DB::IndexedBase>
79  
80 L<Bio::DB::Qual>
81  
82 L<Bio::PrimarySeqI>
83  
84 =head1 AUTHOR
85  
86 Lincoln Stein E<lt>lstein@cshl.orgE<gt>.
87  
88 Copyright (c) 2001 Cold Spring Harbor Laboratory.
89  
90 This library is free software; you can redistribute it and/or modify
91 it under the same terms as Perl itself. See DISCLAIMER.txt for
92 disclaimers of warranty.
93  
94 =head1 APPENDIX
95  
96 The rest of the documentation details each of the object
97 methods. Internal methods are usually preceded with a _
98  
99 For BioPerl-style access, the following methods are provided:
100  
101 =head2 get_Seq_by_id
102  
103 Title : get_Seq_by_id, get_Seq_by_acc, get_Seq_by_primary_id
104 Usage : my $seq = $db->get_Seq_by_id($id);
105 Function: Given an ID, fetch the corresponding sequence from the database.
106 Returns : A Bio::PrimarySeq::Fasta object (Bio::PrimarySeqI compliant)
107 Note that to save resource, Bio::PrimarySeq::Fasta sequence objects
108 only load the sequence string into memory when requested using seq().
109 See L<Bio::PrimarySeqI> for methods provided by the sequence objects
110 returned from get_Seq_by_id() and get_PrimarySeq_stream().
111 Args : ID
112  
113 =head2 get_PrimarySeq_stream
114  
115 Title : get_PrimarySeq_stream
116 Usage : my $stream = $db->get_PrimarySeq_stream();
117 Function: Get a stream of Bio::PrimarySeq::Fasta objects. The stream supports a
118 single method, next_seq(). Each call to next_seq() returns a new
119 Bio::PrimarySeq::Fasta sequence object, until no more sequences remain.
120 Returns : A Bio::DB::Indexed::Stream object
121 Args : None
122  
123 =head1
124  
125 For simple access, the following methods are provided:
126  
127 =cut
128  
129  
130 package Bio::DB::Fasta;
131 2 $Bio::DB::Fasta::VERSION = '1.7.8';
132 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
133 2 ▶use IO::File;
Subroutine BEGIN: called CC=1 SCAR=0.0
134 2 ▶use File::Spec;
Subroutine BEGIN: called CC=1 SCAR=0.0
135 2 ▶use Bio::PrimarySeqI;
Subroutine BEGIN: called CC=1 SCAR=0.0
136  
137 2 ▶use base qw(Bio::DB::IndexedBase);
Subroutine BEGIN: called CC=1 SCAR=0.0
138  
139 2 our $obj_class = 'Bio::PrimarySeq::Fasta';
140 2 our $file_glob = '*.{fa,FA,fasta,FASTA,fast,FAST,dna,DNA,fna,FNA,faa,FAA,fsa,FSA}';
141  
142  
143 =head2 new
144  
145 Title : new
146 Usage : my $db = Bio::DB::Fasta->new( $path, %options);
147 Function: Initialize a new database object. When indexing a directory, files
148 ending in .fa,fasta,fast,dna,fna,faa,fsa are indexed by default.
149 Returns : A new Bio::DB::Fasta object.
150 Args : A single file, or path to dir, or arrayref of files
151 Optional arguments: see Bio::DB::IndexedBase
152  
153 =cut
154  
155  
156 51 ▶sub _calculate_offsets {
Subroutine _calculate_offsets: called CC=21 SCAR=31.6
157 # Bio::DB::IndexedBase calls this to calculate offsets
158 51 my ($self, $fileno, $file, $offsets) = @_;
159  
160 51 ▶ my $fh = IO::File->new($file) or $self->throw( "Could not open $file: $!");
Branch: 1 branch
BranchTrueFalseTotal
my $fh = "IO::File"->new($file) or $self->throw("Could not open ${file}: $!") 51 0 51
161 51 binmode $fh;
162 51 ▶ warn "Indexing $file\n" if $self->{debug};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"debug"} 0 51 51
163 51 my ($offset, @ids, $linelen, $alphabet, $headerlen, $count, $seq_lines,
164 $last_line, %offsets);
165 51 my ($l3_len, $l2_len, $l_len, $blank_lines) = (0, 0, 0, 0);
166  
167 51 my $termination_length = $self->{termination_length};
168 51 ▶ while (my $line = <$fh>) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined(my $line = readline $fh)) 36311 50 36361
169 # Account for crlf-terminated Windows files
170 36311 ▶ if (index($line, '>') == 0) {
Branch: 2 branches
BranchTrueFalseTotal
if (index($line, '>') == 0) { } 2970 33341 36311
elsif (not $line =~ /\S/) { } 77 33264 33341
171 2970 ▶ if ($line =~ /^>(\S+)/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($line =~ /^>(\S+)/) { } 2969 1 2970
172 print STDERR "Indexed $count sequences...\n"
173 2969 ▶ if $self->{debug} && (++$count%1000) == 0;
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"debug"} and ++$count % 1000 == 0 0 2969 2969
Condition33%1/3
$self->{"debug"} and ++$count % 1000 == 0
!ll&&!rl&&r
296900
MC/DC0%0/2
$self->{"debug"} and ++$count % 1000 == 0
$self->{"debug"} ++$count % 1000 == 0
Truth table33%1/3
A and B
A= $self->{"debug"}B= ++$count % 1000 == 0
ABresult
0X0
100
111
174
175 # please, do not enforce arbitrary line length requirements.
176 # It's good practice but not enforced.
177
178 #$self->_check_linelength($linelen);
179 2969 my $pos = tell($fh);
180 2969 ▶ if (@ids) {
Branch: 1 branch
BranchTrueFalseTotal
if (@ids) 2919 50 2969
181 2919 my $strlen = $pos - $offset - length($line);
182 2919 $strlen -= $termination_length * $seq_lines;
183 2919 my $ppos = &{$self->{packmeth}}($offset, $strlen, $strlen,
184 $linelen, $headerlen, $alphabet, $fileno);
185 2919 $alphabet = Bio::DB::IndexedBase::NA;
186 2919 for my $id (@ids) {
187 2925 $offsets->{$id} = $ppos;
188 }
189 }
190 2969 @ids = $self->_makeid($line);
191 2969 ($offset, $headerlen, $linelen, $seq_lines) = ($pos, length $line, 0, 0);
192 2969 ($l3_len, $l2_len, $l_len, $blank_lines) = (0, 0, 0, 0);
193 } else {
194 # Catch bad header lines, bug 3172
195 1 $self->throw("FASTA header doesn't match '>(\\S+)': $line");
196 }
197 } elsif ($line !~ /\S/) {
198 # Skip blank line
199 77 $blank_lines++;
200 77 next;
201 } else {
202 # Need to check every line :(
203 33264 $l3_len = $l2_len;
204 33264 $l2_len = $l_len;
205 33264 $l_len = length $line;
206 33264 if (Bio::DB::IndexedBase::DIE_ON_MISSMATCHED_LINES) {
207 33264 ▶ if ( ($l3_len > 0) && ($l2_len > 0) && ($l3_len != $l2_len) ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($l3_len > 0 and $l2_len > 0 and $l3_len != $l2_len) 0 33264 33264
Condition66%4/6
$l3_len > 0 and $l2_len > 0 and $l3_len != $l2_len
!ll&&!rl&&r
5916273480
$l3_len > 0 and $l2_len > 0
!ll&&!rl&&r
5916027348
MC/DC0%0/3
$l3_len > 0 and $l2_len > 0 and $l3_len != $l2_len
$l3_len > 0 $l2_len > 0 $l3_len != $l2_len
Truth table50%2/4
A and B and C
A= $l3_len > 0B= $l2_len > 0C= $l3_len != $l2_len
ABCresult
0XX0
10X0
1100
1111
208 0 my $fap = substr($line, 0, 20)."..";
209 0 $self->throw("Each line of the fasta entry must be the same ".
210 "length except the last. Line above #$. '$fap' is $l2_len".
211 " != $l3_len chars.");
212 }
213 33264 ▶ if ($blank_lines) {
Branch: 1 branch
BranchTrueFalseTotal
if ($blank_lines) 0 33264 33264
214 # Blank lines not allowed in entry
215 0 $self->throw("Blank lines can only precede header lines, ".
216 "found preceding line #$.");
217 }
218 }
219 33264 ▶ $linelen ||= length $line;
Condition66%2/3
$linelen ||= length $line
l!l&&r!l&&!r
3030629580
MC/DC0%0/2
$linelen ||= length $line
$linelen length $line
Truth table66%2/3
A ||= B
A= $linelenB= length $line
ABresult
1X1
011
000
220 33264 ▶ $alphabet ||= $self->_guess_alphabet($line);
Condition66%2/3
$alphabet ||= $self->_guess_alphabet($line)
l!l&&r!l&&!r
3030629580
MC/DC0%0/2
$alphabet ||= $self->_guess_alphabet($line)
$alphabet $self->_guess_alphabet($line)
Truth table66%2/3
A ||= B
A= $alphabetB= $self->_guess_alphabet($line)
ABresult
1X1
011
000
221 33264 $seq_lines++;
222 }
223 36233 $last_line = $line;
224 }
225  
226 # Process last entry
227 50 $self->_check_linelength($linelen);
228 50 my $pos = tell $fh;
229 50 ▶ if (@ids) {
Branch: 1 branch
BranchTrueFalseTotal
if (@ids) 50 0 50
230 50 my $strlen = $pos - $offset;
231 50 ▶ if ($linelen == 0) { # yet another pesky empty chr_random.fa file
Branch: 1 branch
BranchTrueFalseTotal
if ($linelen == 0) { } 11 39 50
232 11 $strlen = 0;
233 } else {
234 39 ▶ if ($last_line !~ /\s$/) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($last_line =~ /\s$/) 0 39 39
235 0 $seq_lines--;
236 }
237 39 $strlen -= $termination_length * $seq_lines;
238 }
239 50 my $ppos = &{$self->{packmeth}}($offset, $strlen, $strlen, $linelen,
240 $headerlen, $alphabet, $fileno);
241 50 for my $id (@ids) {
242 51 $offsets->{$id} = $ppos;
243 }
244 }
245  
246 50 return \%offsets;
247 }
248  
249 =head2 seq
250  
251 Title : seq, sequence, subseq
252 Usage : # Entire sequence string
253 my $seqstr = $db->seq($id);
254 # Subsequence
255 my $subseqstr = $db->seq($id, $start, $stop, $strand);
256 # or...
257 my $subseqstr = $db->seq($compound_id);
258 Function: Get a subseq of a sequence from the database. For your convenience,
259 the sequence to extract can be specified with any of the following
260 compound IDs:
261 $db->seq("$id:$start,$stop")
262 $db->seq("$id:$start..$stop")
263 $db->seq("$id:$start-$stop")
264 $db->seq("$id:$start,$stop/$strand")
265 $db->seq("$id:$start..$stop/$strand")
266 $db->seq("$id:$start-$stop/$strand")
267 $db->seq("$id/$strand")
268 In the case of DNA or RNA sequence, if $stop is less than $start,
269 then the reverse complement of the sequence is returned. Avoid using
270 it if possible since this goes against Bio::Seq conventions.
271 Returns : A string
272 Args : ID of sequence to retrieve
273 or
274 Compound ID of subsequence to fetch
275 or
276 ID, optional start (defaults to 1), optional end (defaults to length
277 of sequence) and optional strand (defaults to 1).
278  
279 =cut
280  
281 25 ▶sub subseq {
Subroutine subseq: called CC=4 SCAR=13.9
Pod undocumented
282 25 my ($self, $id, $start, $stop, $strand) = @_;
283 25 ▶ $self->throw('Need to provide a sequence ID') if not defined $id;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $id 0 25 25
284 25 ($id, $start, $stop, $strand) = $self->_parse_compound_id($id, $start, $stop, $strand);
285  
286 25 my $data;
287  
288 25 ▶ my $fh = $self->_fh($id) or return;
Branch: 1 branch
BranchTrueFalseTotal
my $fh = $self->_fh($id) or return 24 1 25
289 24 my $filestart = $self->_calc_offset($id, $start);
290 24 my $filestop = $self->_calc_offset($id, $stop );
291  
292 24 seek($fh, $filestart,0);
293 24 read($fh, $data, $filestop-$filestart+1);
294  
295 24 $data =~ tr/\n\r//d; #strip control characters
296  
297 24 ▶ if ($strand == -1) {
Branch: 1 branch
BranchTrueFalseTotal
if ($strand == -1) 7 17 24
298 # Reverse-complement the sequence
299 7 $data = Bio::PrimarySeqI::_revcom_from_string($self, $data, $self->alphabet($id));
300 }
301 24 return $data;
302 }
303  
304 2 *seq = *sequence = \&subseq;
305  
306  
307 =head2 length
308  
309 Title : length
310 Usage : my $length = $qualdb->length($id);
311 Function: Get the number of residues in the indicated sequence.
312 Returns : Number
313 Args : ID of entry
314  
315 =head2 header
316  
317 Title : header
318 Usage : my $header = $db->header($id);
319 Function: Get the header line (ID and description fields) of the specified
320 sequence.
321 Returns : String
322 Args : ID of sequence
323  
324 =cut
325  
326 2 ▶sub header {
Subroutine header: called CC=3 SCAR=11.0
Pod documented
327 2 my ($self, $id) = @_;
328 2 ▶ $self->throw('Need to provide a sequence ID') if not defined $id;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $id 0 2 2
329 2 my ($offset, $headerlen) = (&{$self->{unpackmeth}}($self->{offsets}{$id}))[0,4];
330 2 $offset -= $headerlen;
331 2 my $data;
332 2 ▶ my $fh = $self->_fh($id) or return;
Branch: 1 branch
BranchTrueFalseTotal
my $fh = $self->_fh($id) or return 2 0 2
333 2 seek($fh, $offset, 0);
334 2 read($fh, $data, $headerlen);
335 # On Windows chomp remove '\n' but leaves '\r'
336 # when reading '\r\n' in binary mode
337 2 $data =~ tr/\n\r//d; #strip control characters
338 2 substr($data, 0, 1) = '';
339 2 return $data;
340 }
341  
342  
343 =head2 alphabet
344  
345 Title : alphabet
346 Usage : my $alphabet = $db->alphabet($id);
347 Function: Get the molecular type of the indicated sequence: dna, rna or protein
348 Returns : String
349 Args : ID of sequence
350  
351 =cut
352  
353  
354 #-------------------------------------------------------------
355 # Bio::PrimarySeqI compatibility
356 #
357 package Bio::PrimarySeq::Fasta;
358 2 $Bio::PrimarySeq::Fasta::VERSION = '1.7.8';
359 2 ▶use overload '""' => 'display_id';
Subroutine BEGIN: called CC=1 SCAR=0.0
360  
361 2 ▶use base qw(Bio::Root::Root Bio::PrimarySeqI);
Subroutine BEGIN: called CC=1 SCAR=0.0
362  
363 18 ▶sub new {
Subroutine new: called CC=4 SCAR=13.9
364 18 my ($class, @args) = @_;
365 18 my $self = $class->SUPER::new(@args);
366 18 my ($db, $id, $start, $stop) = $self->_rearrange(
367 [qw(DATABASE ID START STOP)],
368 @args);
369 18 $self->{db} = $db;
370 18 $self->{id} = $id;
371 18 ▶ $self->{stop} = $stop || $db->length($id);
Condition100%3/3
$stop || $db->length($id)
l!l&&r!l&&!r
3141
MC/DC100%2/2
$stop || $db->length($id)
$stop $db->length($id)
Truth table100%3/3
A || B
A= $stopB= $db->length($id)
ABresult
1X1
011
000
372 18 ▶ $self->{start} = $start || ($self->{stop} > 0 ? 1 : 0); # handle 0-length seqs
Branch: 1 branch
BranchTrueFalseTotal
$self->{'stop'} > 0 ? : 14 1 15
Condition100%3/3
$start || ($self->{'stop'} > 0 ? 1 : 0)
l!l&&r!l&&!r
3141
MC/DC100%2/2
$start || ($self->{'stop'} > 0 ? 1 : 0)
$start ($self->{'stop'} > 0 ? 1 : 0)
Truth table100%3/3
A || B
A= $startB= ($self->{'stop'} > 0 ? 1 : 0)
ABresult
1X1
011
000
373 18 return $self;
374 }
375  
376 0 ▶sub fetch_sequence {
Subroutine fetch_sequence: not called CC=1 SCAR=6.9
377 0 return shift->seq(@_);
378 }
379  
380 4 ▶sub seq {
Subroutine seq: called CC=1 SCAR=0.0
381 4 my $self = shift;
382 4 return $self->{db}->seq($self->{id}, $self->{start}, $self->{stop});
383 }
384  
385 1 ▶sub subseq {
Subroutine subseq: called CC=1 SCAR=0.0
386 1 my $self = shift;
387 1 return $self->trunc(@_)->seq();
388 }
389  
390 2 ▶sub trunc {
Subroutine trunc: called CC=3 SCAR=12.0
391 # Override Bio::PrimarySeqI trunc() method. This way, we create an object
392 # that does not store the sequence in memory.
393 2 my ($self, $start, $stop) = @_;
394 2 ▶ $self->throw("Stop cannot be smaller than start") if $stop < $start;
Branch: 1 branch
BranchTrueFalseTotal
if $stop < $start 0 2 2
395 2 ▶ if ($self->{start} <= $self->{stop}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{'start'} <= $self->{'stop'}) { } 2 0 2
396 2 $start = $self->{start}+$start-1;
397 2 $stop = $self->{start}+$stop-1;
398 } else {
399 0 $start = $self->{start}-($start-1);
400 0 $stop = $self->{start}-($stop-1);
401 }
402 2 return $self->new( $self->{db}, $self->{id}, $start, $stop );
403 }
404  
405 1 ▶sub is_circular {
Subroutine is_circular: called CC=1 SCAR=0.0
406 1 my $self = shift;
407 1 return $self->{is_circular};
408 }
409  
410 9 ▶sub display_id {
Subroutine display_id: called CC=1 SCAR=0.0
411 9 my $self = shift;
412 9 return $self->{id};
413 }
414  
415 1 ▶sub accession_number {
Subroutine accession_number: called CC=1 SCAR=0.0
416 1 my $self = shift;
417 1 return 'unknown';
418 }
419  
420 1 ▶sub primary_id {
Subroutine primary_id: called CC=1 SCAR=0.0
421 # Following Bio::PrimarySeqI, since this sequence has no accession number,
422 # its primary_id should be a stringified memory location.
423 1 my $self = shift;
424 1 return overload::StrVal($self);
425 }
426  
427 0 ▶sub can_call_new {
Subroutine can_call_new: not called CC=1 SCAR=6.9
428 0 return 0;
429 }
430  
431 1 ▶sub alphabet {
Subroutine alphabet: called CC=1 SCAR=0.0
432 1 my $self = shift;
433 1 return $self->{db}->alphabet($self->{id});
434 }
435  
436 1 ▶sub revcom {
Subroutine revcom: called CC=1 SCAR=0.0
437 # Override Bio::PrimarySeqI revcom() with optimized method.
438 1 my $self = shift;
439 1 return $self->new(@{$self}{'db', 'id', 'stop', 'start'});
440 }
441  
442 2 ▶sub length {
Subroutine length: called CC=2 SCAR=6.9
443 # Get length from sequence location, not the sequence string (too expensive)
444 2 my $self = shift;
445 return $self->{start} < $self->{stop} ?
446 $self->{stop} - $self->{start} + 1 :
447 2 ▶ $self->{start} - $self->{stop} + 1 ;
Branch: 1 branch
BranchTrueFalseTotal
$self->{'start'} < $self->{'stop'} ? : 1 1 2
448 }
449  
450 1 ▶sub description {
Subroutine description: called CC=1 SCAR=0.0
451 1 my $self = shift;
452 1 my $header = $self->{'db'}->header($self->{id});
453 # Remove the ID from the header
454 1 return (split(/\s+/, $header, 2))[1];
455 }
456 2 *desc = \&description;
457  
458 2 1;
« Bio/TreeIO/newick.pm ↑ Summary Bio/Matrix/PSM/ProtPsm.pm »