t/AlignIO/AlignIO.t: fix number of tests in plan (fixup c523e6bed866)
[bioperl-live.git] / Bio / SearchIO / IteratedSearchResultEventBuilder.pm
blob96192d7af8a062fe800e49492cbce35aaef98b46
1 #------------------------------------------------------------------
3 # BioPerl module for Bio::SearchIO::IteratedSearchResultEventBuilder
5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
7 # Cared for by Steve Chervitz <sac@bioperl.org> and Jason Stajich <jason@bioperl.org>
9 # Copyright Steve Chervitz
11 # You may distribute this module under the same terms as perl itself
12 #------------------------------------------------------------------
14 # POD documentation - main docs before the code
16 =head1 NAME
18 Bio::SearchIO::IteratedSearchResultEventBuilder - Event Handler for
19 SearchIO events.
21 =head1 SYNOPSIS
23 # Do not use this object directly, this object is part of the SearchIO
24 # event based parsing system.
26 =head1 DESCRIPTION
28 This object handles Search Events generated by the SearchIO classes
29 and build appropriate Bio::Search::* objects from them.
31 =head1 FEEDBACK
33 =head2 Mailing Lists
35 User feedback is an integral part of the evolution of this and other
36 Bioperl modules. Send your comments and suggestions preferably to
37 the Bioperl mailing list. Your participation is much appreciated.
39 bioperl-l@bioperl.org - General discussion
40 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
42 =head2 Support
44 Please direct usage questions or support issues to the mailing list:
46 I<bioperl-l@bioperl.org>
48 rather than to the module maintainer directly. Many experienced and
49 reponsive experts will be able look at the problem and quickly
50 address it. Please include a thorough description of the problem
51 with code and data examples if at all possible.
53 =head2 Reporting Bugs
55 Report bugs to the Bioperl bug tracking system to help us keep track
56 of the bugs and their resolution. Bug reports can be submitted via the
57 web:
59 https://github.com/bioperl/bioperl-live/issues
61 =head1 AUTHOR - Steve Chervitz
63 Email sac-at-bioperl.org
65 =head1 CONTRIBUTORS
67 Parts of code based on SearchResultEventBuilder by Jason Stajich
68 jason@bioperl.org
70 Sendu Bala, bix@sendu.me.uk
72 =head1 APPENDIX
74 The rest of the documentation details each of the object methods.
75 Internal methods are usually preceded with a _
77 =cut
80 # Let the code begin...
83 package Bio::SearchIO::IteratedSearchResultEventBuilder;
85 use strict;
87 use Bio::Factory::ObjectFactory;
89 use base qw(Bio::SearchIO::SearchResultEventBuilder);
91 =head2 new
93 Title : new
94 Usage : my $obj = Bio::SearchIO::IteratedSearchResultEventBuilder->new();
95 Function: Builds a new Bio::SearchIO::IteratedSearchResultEventBuilder object
96 Returns : Bio::SearchIO::IteratedSearchResultEventBuilder
97 Args : -hsp_factory => Bio::Factory::ObjectFactoryI
98 -hit_factory => Bio::Factory::ObjectFactoryI
99 -result_factory => Bio::Factory::ObjectFactoryI
100 -iteration_factory => Bio::Factory::ObjectFactoryI
101 -inclusion_threshold => e-value threshold for inclusion in the
102 PSI-BLAST score matrix model (blastpgp)
103 -signif => float or scientific notation number to be used
104 as a P- or Expect value cutoff
105 -score => integer or scientific notation number to be used
106 as a blast score value cutoff
107 -bits => integer or scientific notation number to be used
108 as a bit score value cutoff
109 -hit_filter => reference to a function to be used for
110 filtering hits based on arbitrary criteria.
112 See L<Bio::SearchIO::SearchResultEventBuilder> for more information
114 =cut
116 sub new {
117 my ($class,@args) = @_;
118 my $self = $class->SUPER::new(@args);
119 my ($resultF, $iterationF, $hitF, $hspF) =
120 $self->_rearrange([qw(RESULT_FACTORY
121 ITERATION_FACTORY
122 HIT_FACTORY
123 HSP_FACTORY)],@args);
124 $self->_init_parse_params(@args);
126 # Note that we need to override the setting of result and factories here
127 # so that we can set different default factories than are set by the super class.
128 $self->register_factory('result', $resultF ||
129 Bio::Factory::ObjectFactory->new(
130 -type => 'Bio::Search::Result::BlastResult',
131 -interface => 'Bio::Search::Result::ResultI'));
133 $self->register_factory('hit', $hitF ||
134 Bio::Factory::ObjectFactory->new(
135 -type => 'Bio::Search::Hit::BlastHit',
136 -interface => 'Bio::Search::Hit::HitI'));
138 $self->register_factory('hsp', $hspF ||
139 Bio::Factory::ObjectFactory->new(
140 -type => 'Bio::Search::HSP::GenericHSP',
141 -interface => 'Bio::Search::HSP::HSPI'));
143 # TODO: Change this to BlastIteration (maybe)
144 $self->register_factory('iteration', $iterationF ||
145 Bio::Factory::ObjectFactory->new(
146 -type => 'Bio::Search::Iteration::GenericIteration',
147 -interface => 'Bio::Search::Iteration::IterationI'));
149 return $self;
152 =head2 will_handle
154 Title : will_handle
155 Usage : if( $handler->will_handle($event_type) ) { ... }
156 Function: Tests if this event builder knows how to process a specific event
157 Returns : boolean
158 Args : event type name
160 =cut
162 sub will_handle{
163 my ($self,$type) = @_;
164 # these are the events we recognize
165 return ( $type eq 'hsp' || $type eq 'hit' || $type eq 'result'
166 || $type eq 'iteration' || $type eq 'newhits' || $type eq 'oldhits' );
169 =head2 SAX methods
171 =cut
173 =head2 start_result
175 Title : start_result
176 Usage : $handler->start_result($resulttype)
177 Function: Begins a result event cycle
178 Returns : none
179 Args : Type of Report
181 =cut
183 sub start_result {
184 my $self = shift;
185 #print STDERR "ISREB: start_result()\n";
186 $self->SUPER::start_result(@_);
187 $self->{'_iterations'} = [];
188 $self->{'_iteration_count'} = 0;
189 $self->{'_old_hit_names'} = undef;
190 $self->{'_hit_names_below'} = undef;
191 return;
194 =head2 start_iteration
196 Title : start_iteration
197 Usage : $handler->start_iteration()
198 Function: Starts an Iteration event cycle
199 Returns : none
200 Args : type of event and associated hashref
202 =cut
204 sub start_iteration {
205 my ($self,$type) = @_;
207 #print STDERR "ISREB: start_iteration()\n";
208 $self->{'_iteration_count'}++;
210 # Reset arrays for the various classes of hits.
211 # $self->{'_newhits_unclassified'} = [];
212 $self->{'_newhits_below'} = [];
213 $self->{'_newhits_not_below'} = [];
214 $self->{'_oldhits_below'} = [];
215 $self->{'_oldhits_newly_below'} = [];
216 $self->{'_oldhits_not_below'} = [];
217 $self->{'_hitcount'} = 0;
218 return;
222 =head2 end_iteration
224 Title : end_iteration
225 Usage : $handler->end_iteration()
226 Function: Ends an Iteration event cycle
227 Returns : Bio::Search::Iteration object
228 Args : type of event and associated hashref
230 =cut
232 sub end_iteration {
233 my ($self,$type,$data) = @_;
235 # print STDERR "ISREB: end_iteration()\n";
237 my %args = map { my $v = $data->{$_}; s/ITERATION//; ($_ => $v); }
238 grep { /^ITERATION/ } keys %{$data};
240 $args{'-number'} = $self->{'_iteration_count'};
241 $args{'-oldhits_below'} = $self->{'_oldhits_below'};
242 $args{'-oldhits_newly_below'} = $self->{'_oldhits_newly_below'};
243 $args{'-oldhits_not_below'} = $self->{'_oldhits_not_below'};
244 $args{'-newhits_below'} = $self->{'_newhits_below'};
245 $args{'-newhits_not_below'} = $self->{'_newhits_not_below'};
246 $args{'-hit_factory'} = $self->factory('hit');
248 my $it = $self->factory('iteration')->create_object(%args);
249 push @{$self->{'_iterations'}}, $it;
250 return $it;
253 # Title : _add_hit (private function for internal use only)
254 # Purpose : Applies hit filtering and calls _store_hit if it passes filtering.
255 # Argument: Bio::Search::Hit::HitI object
257 sub _add_hit {
258 my ($self, $hit) = @_;
260 my $hit_name = uc($hit->{-name});
261 my $hit_signif = $hit->{-significance};
262 my $ithresh = $self->{'_inclusion_threshold'};
264 # Test significance using custom function (if supplied)
265 my $add_hit = 1;
267 my $hit_filter = $self->{'_hit_filter'};
269 if($hit_filter) {
270 # since &hit_filter is out of our control and would expect a HitI object,
271 # we're forced to make one for it
272 $hit = $self->factory('hit')->create_object(%{$hit});
273 $add_hit = 0 unless &$hit_filter($hit);
275 else {
276 if($self->{'_confirm_significance'}) {
277 $add_hit = 0 unless $hit_signif <= $self->{'_max_significance'};
279 if($self->{'_confirm_score'}) {
280 my $hit_score = $hit->{-score} || $hit->{-hsps}->[0]->{-score};
281 $add_hit = 0 unless $hit_score >= $self->{'_min_score'};
283 if($self->{'_confirm_bits'}) {
284 my $hit_bits = $hit->{-bits} || $hit->{-hsps}->[0]->{-bits};
285 $add_hit = 0 unless $hit_bits >= $self->{'_min_bits'};
289 $add_hit && $self->_store_hit($hit, $hit_name, $hit_signif);
290 # Building hit lookup hashes for determining if the hit is old/new and
291 # above/below threshold.
292 $self->{'_old_hit_names'}->{$hit_name}++;
293 $self->{'_hit_names_below'}->{$hit_name}++ if $hit_signif <= $ithresh;
296 # Title : _store_hit (private function for internal use only)
297 # Purpose : Collects hit objects into defined sets that are useful for
298 # analyzing PSI-blast results.
299 # These are ultimately added to the iteration object in end_iteration().
301 # Strategy:
302 # Primary split = old vs. new
303 # Secondary split = below vs. above threshold
304 # 1. Has this hit occurred in a previous iteration?
305 # 1.1. If yes, was it below threshold?
306 # 1.1.1. If yes, ---> [oldhits_below]
307 # 1.1.2. If no, is it now below threshold?
308 # 1.1.2.1. If yes, ---> [oldhits_newly_below]
309 # 1.1.2.2. If no, ---> [oldhits_not_below]
310 # 1.2. If no, is it below threshold?
311 # 1.2.1. If yes, ---> [newhits_below]
312 # 1.2.2. If no, ---> [newhits_not_below]
313 # 1.2.3. If don't know (no inclusion threshold data), ---> [newhits_unclassified]
314 # Note: As long as there's a default inclusion threshold,
315 # there won't be an unclassified set.
317 # For the first iteration, it might be nice to detect non-PSI blast reports
318 # and put the hits in the unclassified set.
319 # However, it shouldn't matter where the hits get put for the first iteration
320 # for non-PSI blast reports since they'll get flattened out in the
321 # result and iteration search objects.
323 sub _store_hit {
324 my ($self, $hit, $hit_name, $hit_signif) = @_;
326 my $ithresh = $self->{'_inclusion_threshold'};
328 # This is the assumption leading to Bug 1986. The assumption here is that
329 # the hit name is unique (and thus new), therefore any subsequent encounters
330 # with a hit containing the same name are filed as old hits. This isn't
331 # always true (see the bug report for a few examples). Adding an explicit
332 # check for the presence of iterations, adding to new hits otherwise.
334 if (exists $self->{'_old_hit_names'}->{$hit_name}
335 && scalar @{$self->{_iterations}}) {
336 if (exists $self->{'_hit_names_below'}->{$hit_name}) {
337 push @{$self->{'_oldhits_below'}}, $hit;
338 } elsif ($hit_signif <= $ithresh) {
339 push @{$self->{'_oldhits_newly_below'}}, $hit;
340 } else {
341 push @{$self->{'_oldhits_not_below'}}, $hit;
343 } else {
344 if ($hit_signif <= $ithresh) {
345 push @{$self->{'_newhits_below'}}, $hit;
346 } else {
347 push @{$self->{'_newhits_not_below'}}, $hit;
350 $self->{'_hitcount'}++;