Bio/Tools/Sim4/Results.pm

filter: Statementstmt 83.4% 101 / 121 Branchbran 58.0% 29 / 50 Conditioncond 33.3% 2 / 6 MC/DCmcdc 0.0% 0 / 4 Subroutinesub 90.0% 9 / 10 Podpod 100% 4 / 4 totaltotal 74.3% 145 / 195 CC 29 SCAR 30.6
CC
29
Cov
75%
parse_next_alignment
33.6
next_exonset
4.5
analysis_method
3.3
CRAP 21.4
« Bio/DB/Flat/BinarySearch.pm ↑ Summary Bio/DB/Query/WebQuery.pm »
1 #
2 # BioPerl module for Bio::Tools::Sim4::Results
3 #
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
5 #
6 # Cared for by Ewan Birney <birney-at-sanger.ac.uk>
7 # and Hilmar Lapp <hlapp-at-gmx.net>
8 #
9 # Copyright Ewan Birney and Hilmar Lapp
10 #
11 # You may distribute this module under the same terms as perl itself
12  
13 # POD documentation - main docs before the code
14  
15 =head1 NAME
16  
17 Bio::Tools::Sim4::Results - Results of one Sim4 run
18  
19 =head1 SYNOPSIS
20  
21 # to preset the order of EST and genomic file as given on the sim4
22 # command line:
23 my $sim4 = Bio::Tools::Sim4::Results->new(-file => 'result.sim4',
24 -estfirst => 1);
25 # to let the order be determined automatically (by length comparison):
26 $sim4 = Bio::Tools::Sim4::Results->new( -file => 'sim4.results' );
27 # filehandle:
28 $sim4 = Bio::Tools::Sim4::Results->new( -fh => \*INPUT );
29  
30 # parse the results
31 while(my $exonset = $sim4->next_exonset()) {
32 # $exonset is-a Bio::SeqFeature::Generic with Bio::Tools::Sim4::Exons
33 # as sub features
34 print "Delimited on sequence ", $exonset->seq_id(),
35 "from ", $exonset->start(), " to ", $exonset->end(), "\n";
36 foreach my $exon ( $exonset->sub_SeqFeature() ) {
37 # $exon is-a Bio::SeqFeature::FeaturePair
38 print "Exon from ", $exon->start, " to ", $exon->end,
39 " on strand ", $exon->strand(), "\n";
40 # you can get out what it matched using the est_hit attribute
41 my $homol = $exon->est_hit();
42 print "Matched to sequence ", $homol->seq_id,
43 " at ", $homol->start," to ", $homol->end, "\n";
44 }
45 }
46  
47 # essential if you gave a filename at initialization (otherwise the file
48 # stays open)
49 $sim4->close();
50  
51 =head1 DESCRIPTION
52  
53 The sim4 module provides a parser and results object for sim4 output. The
54 sim4 results are specialised types of SeqFeatures, meaning you can add them
55 to AnnSeq objects fine, and manipulate them in the "normal" seqfeature manner.
56  
57 The sim4 Exon objects are Bio::SeqFeature::FeaturePair inherited objects. The
58 $esthit = $exon-E<gt>est_hit() is the alignment as a feature on the matching
59 object (normally, an EST), in which the start/end points are where the hit
60 lies.
61  
62 To make this module work sensibly you need to run
63  
64 sim4 genomic.fasta est.database.fasta
65 or
66 sim4 est.fasta genomic.database.fasta
67  
68 To get the sequence identifiers recorded for the first sequence, too, use
69 A=4 as output option for sim4.
70  
71 One fiddle here is that there are only two real possibilities to the matching
72 criteria: either one sequence needs reversing or not. Because of this, it
73 is impossible to tell whether the match is in the forward or reverse strand
74 of the genomic DNA. We solve this here by assuming that the genomic DNA is
75 always forward. As a consequence, the strand attribute of the matching EST is
76 unknown, and the strand attribute of the genomic DNA (i.e., the Exon object)
77 will reflect the direction of the hit.
78  
79 See the documentation of parse_next_alignment() for abilities of the parser
80 to deal with the different output format options of sim4.
81  
82 =head1 FEEDBACK
83  
84 =head2 Mailing Lists
85  
86 User feedback is an integral part of the evolution of this and other
87 Bioperl modules. Send your comments and suggestions preferably to one
88 of the Bioperl mailing lists. Your participation is much appreciated.
89  
90 bioperl-l@bioperl.org - General discussion
91 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
92  
93 =head2 Support
94  
95 Please direct usage questions or support issues to the mailing list:
96  
97 I<bioperl-l@bioperl.org>
98  
99 rather than to the module maintainer directly. Many experienced and
100 reponsive experts will be able look at the problem and quickly
101 address it. Please include a thorough description of the problem
102 with code and data examples if at all possible.
103  
104 =head2 Reporting Bugs
105  
106 Report bugs to the Bioperl bug tracking system to help us keep track
107 the bugs and their resolution. Bug reports can be submitted via the
108 web:
109  
110 https://github.com/bioperl/bioperl-live/issues
111  
112 =head1 AUTHOR - Ewan Birney, Hilmar Lapp
113  
114 Ewan Birney E<lt>birney-at-sanger.ac.ukE<gt>
115 Hilmar Lapp E<lt>hlapp-at-gmx.netE<gt> or E<lt>hilmar.lapp-at-pharma.novartis.comE<gt>.
116  
117 =head1 APPENDIX
118  
119 The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _
120  
121 =cut
122  
123  
124 # Let the code begin...
125  
126  
127 package Bio::Tools::Sim4::Results;
128 2 $Bio::Tools::Sim4::Results::VERSION = '1.7.8';
129 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
130  
131  
132 2 ▶use File::Basename;
Subroutine BEGIN: called CC=1 SCAR=0.0
133 2 ▶use Bio::Root::Root;
Subroutine BEGIN: called CC=1 SCAR=0.0
134 2 ▶use Bio::Tools::Sim4::Exon;
Subroutine BEGIN: called CC=1 SCAR=0.0
135  
136 2 ▶use base qw(Bio::Tools::AnalysisResult);
Subroutine BEGIN: called CC=1 SCAR=0.0
137  
138  
139 2 ▶sub _initialize_state {
Subroutine _initialize_state: called CC=2 SCAR=7.0
140 2 my($self,@args) = @_;
141  
142 # call the inherited method first
143 2 my $make = $self->SUPER::_initialize_state(@args);
144  
145 2 my ($est_is_first) = $self->_rearrange([qw(ESTFIRST)], @args);
146  
147 2 delete($self->{'_est_is_first'});
148 2 ▶ $self->{'_est_is_first'} = $est_is_first if(defined($est_is_first));
Branch: 1 branch
BranchTrueFalseTotal
if defined $est_is_first 0 2 2
149 2 $self->analysis_method("Sim4");
150 }
151  
152 =head2 analysis_method
153  
154 Usage : $sim4->analysis_method();
155 Purpose : Inherited method. Overridden to ensure that the name matches
156 /sim4/i.
157 Returns : String
158 Argument : n/a
159  
160 =cut
161  
162 #-------------
163 20 ▶sub analysis_method {
Subroutine analysis_method: called CC=3 SCAR=12.0
Pod documented
164 #-------------
165 20 my ($self, $method) = @_;
166 20 ▶ if($method && ($method !~ /sim4/i)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($method and not $method =~ /sim4/i) 0 20 20
Condition66%2/3
$method and not $method =~ /sim4/i
!ll&&!rl&&r
1820
MC/DC0%0/2
$method and not $method =~ /sim4/i
$method not $method =~ /sim4/i
Truth table66%2/3
A and not(B)
A= $methodB= not $method =~ /sim4/i
ABresult
0X0
100
111
167 0 $self->throw("method $method not supported in " . ref($self));
168 }
169 20 return $self->SUPER::analysis_method($method);
170 }
171  
172 =head2 parse_next_alignment
173  
174 Title : parse_next_alignment
175 Usage : @exons = $sim4_result->parse_next_alignment;
176 foreach $exon (@exons) {
177 # do something
178 }
179 Function: Parses the next alignment of the Sim4 result file and returns the
180 found exons as an array of Bio::Tools::Sim4::Exon objects. Call
181 this method repeatedly until an empty array is returned to get the
182 results for all alignments.
183  
184 The $exon->seq_id() attribute will be set to the identifier of the
185 respective sequence for both sequences if A=4 was used in the sim4
186 run, and otherwise for the second sequence only. If the output does
187 not contain the identifier, the filename stripped of path and
188 extension is used instead. In addition, the full filename
189 will be recorded for both features ($exon inherits off
190 Bio::SeqFeature::SimilarityPair) as tag 'filename'. The length
191 is accessible via the seqlength() attribute of $exon->query() and
192 $exon->est_hit().
193  
194 Note that this method is capable of dealing with outputs generated
195 with format 0,1,3, and 4 (via the A=n option to sim4). It
196 automatically determines which of the two sequences has been
197 reversed, and adjusts the coordinates for that sequence. It will
198 also detect whether the EST sequence(s) were given as first or as
199 second file to sim4, unless this has been specified at creation
200 time of the object.
201  
202 Example :
203 Returns : An array of Bio::Tools::Sim4::Exon objects
204 Args :
205  
206  
207 =cut
208  
209 3 ▶sub parse_next_alignment {
Subroutine parse_next_alignment: called CC=23 SCAR=35.2
Pod documented
210 3 my ($self) = @_;
211 3 my @exons = ();
212 3 my %seq1props = ();
213 3 my %seq2props = ();
214 # we refer to the properties of each seq by reference
215 3 my ($estseq, $genomseq, $to_reverse);
216 3 my $started = 0;
217 3 my $hit_direction = 1;
218 3 my $output_fmt = 3; # same as 0 and 1 (we cannot deal with A=2 produced
219 # output yet)
220
221 3 ▶ while(defined($_ = $self->_readline())) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined($_ = $self->_readline)) 32 2 34
222 #chomp();
223 #
224 # bascially, each sim4 'hit' starts with seq1...
225 #
226 32 ▶ /^seq1/ && do {
Branch: 1 branch
BranchTrueFalseTotal
/^seq1/ and do { if ($started) { $self->_pushback($_); last; } ; $started = 1; /^seq1\s+=\s+(\S+)\,\s+(\d+)/ or $self->throw("Sim4 parsing error on seq1 [$_] line. Sorry!"); $seq1props{"filename"} = $1; $seq1props{"length"} = $2; next } 4 28 32
227 4 ▶ if($started) {
Branch: 1 branch
BranchTrueFalseTotal
if ($started) 1 3 4
228 1 $self->_pushback($_);
229 1 last;
230 }
231 3 $started = 1;
232  
233 # filename and length of seq 1
234 3 ▶ /^seq1\s+=\s+(\S+)\,\s+(\d+)/ ||
Branch: 1 branch
BranchTrueFalseTotal
/^seq1\s+=\s+(\S+)\,\s+(\d+)/ or $self->throw("Sim4 parsing error on seq1 [$_] line. Sorry!") 3 0 3
235 $self->throw("Sim4 parsing error on seq1 [$_] line. Sorry!");
236 3 $seq1props{'filename'} = $1;
237 3 $seq1props{'length'} = $2;
238 3 next;
239 };
240 28 ▶ /^seq2/ && do {
Branch: 1 branch
BranchTrueFalseTotal
/^seq2/ and do { /^seq2\s+=\s+(\S+)\s+\(>?(\S+)\s*\)\,\s+(\d+)/ or $self->throw("Sim4 parsing error on seq2 [$_] line. Sorry!"); $seq2props{"filename"} = $1; $seq2props{"seqname"} = $2; $seq2props{"length"} = $3; next } 3 25 28
241 # the second hit has also the database name in the >name syntax
242 # (in brackets).
243 3 ▶ /^seq2\s+=\s+(\S+)\s+\(>?(\S+)\s*\)\,\s+(\d+)/||
Branch: 1 branch
BranchTrueFalseTotal
/^seq2\s+=\s+(\S+)\s+\(>?(\S+)\s*\)\,\s+(\d+)/ or $self->throw("Sim4 parsing error on seq2 [$_] line. Sorry!") 3 0 3
244 $self->throw("Sim4 parsing error on seq2 [$_] line. Sorry!");
245 3 $seq2props{'filename'} = $1;
246 3 $seq2props{'seqname'} = $2;
247 3 $seq2props{'length'} = $3;
248 3 next;
249 };
250 25 ▶ if(/^>(\S+)\s*(.*)$/) {
Branch: 1 branch
BranchTrueFalseTotal
if (/^>(\S+)\s*(.*)$/) 0 25 25
251 # output option was A=4, which not only gives the complete
252 # description lines, but also causes the longer sequence to be
253 # reversed if the second file contained one (genomic) sequence
254 0 $seq1props{'seqname'} = $1;
255 0 ▶ $seq1props{'description'} = $2 if $2;
Branch: 1 branch
BranchTrueFalseTotal
if $2 0 0 0
256 0 $output_fmt = 4;
257 # we handle seq1 and seq2 both here
258 0 ▶ if(defined($_ = $self->_readline()) && (/^>(\S+)\s*(.*)$/)) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined($_ = $self->_readline) and /^>(\S+)\s*(.*)$/) 0 0 0
Condition0%0/3
defined($_ = $self->_readline) and /^>(\S+)\s*(.*)$/
!ll&&!rl&&r
000
MC/DC0%0/2
defined($_ = $self->_readline) and /^>(\S+)\s*(.*)$/
defined($_ = $self->_readline) /^>(\S+)\s*(.*)$/
Truth table0%0/3
A and B
A= defined($_ = $self->_readline)B= /^>(\S+)\s*(.*)$/
ABresult
0X0
100
111
259 0 $seq2props{'seqname'} = $1; # redundant, since already set above
260 0 ▶ $seq2props{'description'} = $2 if $2;
Branch: 1 branch
BranchTrueFalseTotal
if $2 0 0 0
261 }
262 0 next;
263 }
264 25 ▶ /^\(complement\)/ && do {
Branch: 1 branch
BranchTrueFalseTotal
/^\(complement\)/ and do { $hit_direction = -1; next } 1 24 25
265 1 $hit_direction = -1;
266 1 next;
267 };
268 # this matches
269 # start-end (start-end) pctid%
270 24 ▶ if(/(\d+)-(\d+)\s+\((\d+)-(\d+)\)\s+(\d+)%/) {
Branch: 1 branch
BranchTrueFalseTotal
if (/(\d+)-(\d+)\s+\((\d+)-(\d+)\)\s+(\d+)%/) 18 6 24
271 18 $seq1props{'start'} = $1;
272 18 $seq1props{'end'} = $2;
273 18 $seq2props{'start'} = $3;
274 18 $seq2props{'end'} = $4;
275 18 my $pctid = $5;
276
277 18 ▶ if(! defined($estseq)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $estseq) 3 15 18
278 # for the first time here: need to set the references referring
279 # to seq1 and seq2
280 3 ▶ if(! exists($self->{'_est_is_first'})) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $self->{"_est_is_first"}) 2 1 3
281 # detect which one is the EST by looking at the lengths,
282 # and assume that this holds throughout the entire result
283 # file (i.e., when this method is called for the next
284 # alignment, this will not be checked again)
285 2 ▶ if($seq1props{'length'} > $seq2props{'length'}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($seq1props{'length'} > $seq2props{'length'}) { } 2 0 2
286 2 $self->{'_est_is_first'} = 0;
287 } else {
288 0 $self->{'_est_is_first'} = 1;
289 }
290 }
291 3 ▶ if($self->{'_est_is_first'}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{'_est_is_first'}) { } 0 3 3
292 0 $estseq = \%seq1props;
293 0 $genomseq = \%seq2props;
294 # if the EST is given first, A=4 selects the genomic
295 # seq for being reversed (reversing the EST is default)
296 0 ▶ $to_reverse = ($output_fmt == 4) ? $genomseq : $estseq;
Branch: 1 branch
BranchTrueFalseTotal
$output_fmt == 4 ? : 0 0 0
297 } else {
298 3 $estseq = \%seq2props;
299 3 $genomseq = \%seq1props;
300 # if the EST is the second, A=4 does not change the
301 # seq being reversed (always the EST is reversed)
302 3 $to_reverse = $estseq;
303 }
304 }
305 18 ▶ if($hit_direction == -1) {
Branch: 1 branch
BranchTrueFalseTotal
if ($hit_direction == -1) 10 8 18
306 # we have to reverse the coordinates of one of both seqs
307 10 my $tmp = $to_reverse->{'start'};
308 $to_reverse->{'start'} =
309 10 $to_reverse->{'length'} - $to_reverse->{'end'} + 1;
310 10 $to_reverse->{'end'} = $to_reverse->{'length'} - $tmp + 1;
311 }
312 # create and initialize the exon object
313 my $exon = Bio::Tools::Sim4::Exon->new(
314 '-start' => $genomseq->{'start'},
315 18 '-end' => $genomseq->{'end'},
316 '-strand' => $hit_direction);
317 18 ▶ if(exists($genomseq->{'seqname'})) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $genomseq->{'seqname'}) { } 0 18 18
318 0 $exon->seq_id($genomseq->{'seqname'});
319 } else {
320 # take filename stripped of path as fall back
321 18 my ($basename) = &File::Basename::fileparse($genomseq->{'filename'}, '\..*');
322 18 $exon->seq_id($basename);
323 }
324 $exon->feature1()->add_tag_value('filename',
325 18 $genomseq->{'filename'});
326 # feature1 is supposed to be initialized to a Similarity object,
327 # but we provide a safety net
328 18 ▶ if($exon->feature1()->can('seqlength')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exon->feature1->can('seqlength')) { } 18 0 18
329 18 $exon->feature1()->seqlength($genomseq->{'length'});
330 } else {
331 $exon->feature1()->add_tag_value('SeqLength',
332 0 $genomseq->{'length'});
333 }
334 # create and initialize the feature wrapping the 'hit' (the EST)
335 my $fea2 = Bio::SeqFeature::Similarity->new(
336 '-start' => $estseq->{'start'},
337 18 '-end' => $estseq->{'end'},
338 '-strand' => 0,
339 '-primary' => "aligning_EST");
340 18 ▶ if(exists($estseq->{'seqname'})) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $estseq->{'seqname'}) { } 18 0 18
341 18 $fea2->seq_id($estseq->{'seqname'});
342 } else {
343 # take filename stripped of path as fall back
344 my ($basename) =
345 0 &File::Basename::fileparse($estseq->{'filename'}, '\..*');
346 0 $fea2->seq_id($basename);
347 }
348 18 $fea2->add_tag_value('filename', $estseq->{'filename'});
349 18 $fea2->seqlength($estseq->{'length'});
350 # store
351 18 $exon->est_hit($fea2);
352 # general properties
353 18 $exon->source_tag($self->analysis_method());
354 18 $exon->percentage_id($pctid);
355 18 $exon->score($exon->percentage_id());
356 # push onto array
357 18 push(@exons, $exon);
358 18 next; # back to while loop
359 }
360 }
361 3 return @exons;
362 }
363  
364 =head2 next_exonset
365  
366 Title : next_exonset
367 Usage : $exonset = $sim4_result->parse_next_exonset;
368 print "Exons start at ", $exonset->start(),
369 "and end at ", $exonset->end(), "\n";
370 foreach $exon ($exonset->sub_SeqFeature()) {
371 # do something
372 }
373 Function: Parses the next alignment of the Sim4 result file and returns the
374 set of exons as a container of features. The container is itself
375 a Bio::SeqFeature::Generic object, with the Bio::Tools::Sim4::Exon
376 objects as sub features. Start, end, and strand of the container
377 will represent the total region covered by the exons of this set.
378  
379 See the documentation of parse_next_alignment() for further
380 reference about parsing and how the information is stored.
381  
382 Example :
383 Returns : An Bio::SeqFeature::Generic object holding Bio::Tools::Sim4::Exon
384 objects as sub features.
385 Args :
386  
387 =cut
388  
389 3 ▶sub next_exonset {
Subroutine next_exonset: called CC=4 SCAR=15.0
Pod documented
390 3 my $self = shift;
391 3 my $exonset;
392  
393 # get the next array of exons
394 3 my @exons = $self->parse_next_alignment();
395 3 ▶ unless( @exons ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@exons) 0 3 3
396 0 ▶ return if eof($self->_fh);
Branch: 1 branch
BranchTrueFalseTotal
if eof $self->_fh 0 0 0
397 0 return $self->next_exonset;
398 }
399 # create the container of exons as a feature object itself, with the
400 # data of the first exon for initialization
401 3 $exonset = Bio::SeqFeature::Generic->new('-start' => $exons[0]->start(),
402 '-end' => $exons[0]->end(),
403 '-strand' => $exons[0]->strand(),
404 '-primary' => "ExonSet");
405 3 $exonset->source_tag($exons[0]->source_tag());
406 3 $exonset->seq_id($exons[0]->seq_id());
407 # now add all exons as sub features, with enabling EXPANsion of the region
408 # covered in total
409 3 foreach my $exon (@exons) {
410 18 $exonset->add_sub_SeqFeature($exon, 'EXPAND');
411 }
412 3 return $exonset;
413 }
414  
415 =head2 next_feature
416  
417 Title : next_feature
418 Usage : while($exonset = $sim4->next_feature()) {
419 # do something
420 }
421 Function: Does the same as L<next_exonset()>. See there for documentation of
422 the functionality. Call this method repeatedly until FALSE is
423 returned.
424  
425 The returned object is actually a SeqFeatureI implementing object.
426 This method is required for classes implementing the
427 SeqAnalysisParserI interface, and is merely an alias for
428 next_exonset() at present.
429  
430 Example :
431 Returns : A Bio::SeqFeature::Generic object.
432 Args :
433  
434 =cut
435  
436 0 ▶sub next_feature {
Subroutine next_feature: not called CC=1 SCAR=6.9
Pod documented
437 0 my ($self,@args) = @_;
438 # even though next_exonset doesn't expect any args (and this method
439 # does neither), we pass on args in order to be prepared if this changes
440 # ever
441 0 return $self->next_exonset(@args);
442 }
443  
444 2 1;
« Bio/DB/Flat/BinarySearch.pm ↑ Summary Bio/DB/Query/WebQuery.pm »