Bio/SearchIO/sim4.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::SearchIO::sim4
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Jason Stajich <jason-at-bioperl-dot-org>
   8 #
   9 # Copyright Jason Stajich
  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::SearchIO::sim4 - parser for Sim4 alignments
  18
  19 =head1 SYNOPSIS
  20
  21   # do not use this module directly, it is a driver for SearchIO
  22   use Bio::SearchIO;
  23   my $searchio = Bio::SearchIO->new(-file => 'results.sim4',
  24                                    -format => 'sim4');
  25
  26   while ( my $result = $searchio->next_result ) {
  27       while ( my $hit = $result->next_hit ) {
  28           while ( my $hsp = $hit->next_hsp ) {
  29               # ...
  30           }
  31       }
  32   }
  33
  34 =head1 DESCRIPTION
  35
  36 This is a driver for the SearchIO system for parsing Sim4.
  37 http://globin.cse.psu.edu/html/docs/sim4.html
  38
  39 Cannot parse LAV or 'exon file' formats (A=2 or A=5)
  40
  41 =head1 FEEDBACK
  42
  43 =head2 Mailing Lists
  44
  45 User feedback is an integral part of the evolution of this and other
  46 Bioperl modules. Send your comments and suggestions preferably to
  47 the Bioperl mailing list.  Your participation is much appreciated.
  48
  49   bioperl-l@bioperl.org                  - General discussion
  50   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  51
  52 =head2 Support
  53
  54 Please direct usage questions or support issues to the mailing list:
  55
  56 L<bioperl-l@bioperl.org>
  57
  58 rather than to the module maintainer directly. Many experienced and
  59 reponsive experts will be able look at the problem and quickly
  60 address it. Please include a thorough description of the problem
  61 with code and data examples if at all possible.
  62
  63 =head2 Reporting Bugs
  64
  65 Report bugs to the Bioperl bug tracking system to help us keep track
  66 of the bugs and their resolution. Bug reports can be submitted via the
  67 web:
  68
  69   http://bugzilla.open-bio.org/
  70
  71 =head1 AUTHOR - Jason Stajich
  72
  73 Email jason-at-bioperl-dot-org
  74
  75 =head1 CONTRIBUTORS
  76
  77 Luc Gauthier (lgauthie@hotmail.com)
  78
  79 =head1 APPENDIX
  80
  81 The rest of the documentation details each of the object methods.
  82 Internal methods are usually preceded with a _
  83
  84 =cut
  85
  86
  87 # Let the code begin...
  88
  89
  90 package Bio::SearchIO::sim4;
  91
  92 use strict;
  93 use vars qw($DEFAULTFORMAT %ALIGN_TYPES
  94             %MAPPING %MODEMAP $DEFAULT_WRITER_CLASS);
  95
  96 use POSIX;
  97 use Bio::SearchIO::SearchResultEventBuilder;
  98
  99 use base qw(Bio::SearchIO);
 100
 101 $DEFAULTFORMAT = 'SIM4';
 102 $DEFAULT_WRITER_CLASS = 'Bio::Search::Writer::HitTableWriter';
 103
 104 %ALIGN_TYPES = (
 105     0 => 'Ruler',
 106     1 => 'Query',
 107     2 => 'Mid',
 108     3 => 'Sbjct'
 109 );
 110
 111 %MODEMAP = (
 112     'Sim4Output' => 'result',
 113     'Hit'        => 'hit',
 114     'Hsp'        => 'hsp'
 115 );
 116
 117 %MAPPING = (
 118     'Hsp_query-from'=>  'HSP-query_start',
 119     'Hsp_query-to'  =>  'HSP-query_end',
 120     'Hsp_qseq'      =>  'HSP-query_seq',
 121     'Hsp_qlength'   =>  'HSP-query_length',
 122     'Hsp_querygaps'  => 'HSP-query_gaps',
 123     'Hsp_hit-from'  =>  'HSP-hit_start',
 124     'Hsp_hit-to'    =>  'HSP-hit_end',
 125     'Hsp_hseq'      =>  'HSP-hit_seq',
 126     'Hsp_hlength'   =>  'HSP-hit_length',
 127     'Hsp_hitgaps'    => 'HSP-hit_gaps',
 128     'Hsp_midline'   =>  'HSP-homology_seq',
 129     'Hsp_score'     =>  'HSP-score',
 130     'Hsp_align-len' =>  'HSP-hsp_length',
 131     'Hsp_identity'  =>  'HSP-identical',
 132
 133     'Hit_id'        => 'HIT-name',
 134     'Hit_desc'      => 'HIT-description',
 135     'Hit_len'       => 'HIT-length',
 136
 137     'Sim4Output_program'   => 'RESULT-algorithm_name',
 138     'Sim4Output_query-def' => 'RESULT-query_name',
 139     'Sim4Output_query-desc'=> 'RESULT-query_description',
 140     'Sim4Output_query-len' => 'RESULT-query_length',
 141 );
 142
 143
 144
 145 =head2 new
 146
 147  Title   : new
 148  Usage   : my $obj = Bio::SearchIO::sim4->new();
 149  Function: Builds a new Bio::SearchIO::sim4 object
 150  Returns : an instance of Bio::SearchIO::sim4
 151  Args    :
 152
 153
 154 =cut
 155
 156
 157 =head2 next_result
 158
 159  Title   : next_result
 160  Usage   : my $result = $searchio->next_result;
 161  Function: Returns the next Result from a search
 162  Returns : Bio::Search::Result::ResultI object
 163  Args    : none
 164
 165 =cut
 166
 167 sub next_result {
 168     my ($self) = @_;
 169     local $/ = "\n";
 170     local $_;
 171
 172     # Declare/adjust needed variables
 173     $self->{'_last_data'} = '';
 174     my ($seentop, $qfull, @hsps, %alignment, $format);
 175     my $hit_direction = 1;
 176
 177     # Start document and main element
 178     $self->start_document();
 179     $self->start_element({'Name' => 'Sim4Output'});
 180     my $lastquery = '';
 181     # Read output report until EOF
 182     while( defined($_ = $self->_readline) ) {
 183         # Skip empty lines, chomp filled ones
 184         next if( /^\s+$/); chomp;
 185
 186         # Make sure sim4 output format is not 2 or 5
 187         if (!$seentop) {
 188             if ( /^\#:lav/ ) { $format = 2; }
 189             elsif ( /^<|>/ ) { $format = 5; }
 190             $self->throw("Bio::SearchIO::sim4 module cannot parse 'type $format' outputs.") if $format;
 191         }
 192
 193         # This line indicates the start of a new hit
 194         if( /^seq1\s*=\s*(\S+),\s+(\d+)/ ) {
 195             my ($nm,$desc) = ($1,$2);
 196             # First hit? Adjust some parameters if so
 197             if ( ! $seentop ) {
 198                 $self->element( {'Name' => 'Sim4Output_query-def',
 199                                  'Data' => $nm} );
 200                 $self->element( {'Name' => 'Sim4Output_query-len',
 201                                  'Data' => $desc} );
 202                 $seentop = 1;
 203             } elsif( $nm ne $lastquery ) {
 204                 $self->_pushback($_);
 205                 last;
 206             }
 207             $lastquery = $nm;
 208             # A previous HSP may need to be ended
 209             $self->end_element({'Name' => 'Hsp'}) if ( $self->in_element('hsp') );
 210             # A previous hit exists? End it and reset needed variables
 211             if ( $self->in_element('hit') ) {
 212                 foreach (@hsps) {
 213                     $self->start_element({'Name' => 'Hsp'});
 214                     while (my ($name, $data) = each %$_) {
 215                         $self->{'_currentHSP'}{$name} = $data;
 216                     }
 217                     $self->end_element({'Name' => 'Hsp'});
 218                     $self->{'_currentHSP'} = {};
 219                 }
 220                 $format = 0 if @hsps;
 221                 @hsps = ();
 222                 %alignment = ();
 223                 $qfull = 0;
 224                 $hit_direction = 1;
 225                 $self->end_element({'Name' => 'Hit'});
 226             }
 227
 228         # This line describes the current hit... so let's start it
 229         } elsif( /^seq2\s*=\s*(\S+)\s+\(>?(\S+)\s*\),\s*(\d+)/ ) {
 230             $self->start_element({'Name' => 'Hit'});
 231             $self->element( {'Name' => 'Hit_id', 'Data' => $2} );
 232             $self->element( {'Name' => 'Hit_desc', 'Data' => $1} );
 233             $self->element( {'Name' => 'Hit_len', 'Data' => $3} );
 234
 235         # This line may give additional details about query or subject
 236         } elsif( /^>(\S+)\s*(.*)?/ ) {
 237             # Previous line was query details... this time subject details
 238             if( $qfull )  {
 239                 $format = 4 if !$format;
 240                 $self->element({'Name' => 'Hit_desc', 'Data' => $2});
 241             # First line of this type is always query details for a given hit
 242             } else {
 243                 $self->element({'Name' => 'Sim4Output_query-desc', 'Data' => $2});
 244                 $qfull = 1;
 245             }
 246
 247         # This line indicates that subject is on reverse strand
 248         } elsif( /^\(complement\)/ ) {
 249             $hit_direction = -1;
 250
 251         # This line describes the current HSP... so add it to @hsps array
 252         } elsif( /^\(?(\d+)\-(\d+)\)?\s+\(?(\d+)\-(\d+)\)?\s+(\d+)/ ) {
 253                 my ($qs,$qe,$hs,$he,$pid) = ($1,$2,$3,$4,$5);
 254                 push @hsps, {
 255                     'Hsp_query-from' => $qs,
 256                     'Hsp_query-to' => $qe,
 257                     'Hsp_hit-from' => $hit_direction >= 0 ? $hs : $he,
 258                     'Hsp_hit-to' => $hit_direction >= 0 ? $he : $hs,
 259                     'Hsp_identity' => 0, #can't determine correctly from raw pct
 260                     'Hsp_qlength' => abs($qe - $qs) + 1,
 261                     'Hsp_hlength' => abs($he - $hs) + 1,
 262                     'Hsp_align-len' => abs($qe - $qs) + 1,
 263                 };
 264
 265         # This line indicates the start of an alignment block
 266         } elsif( /^\s+(\d+)\s/ ) {
 267             # Store the current alignment block in a hash
 268             for( my $i = 0; defined($_) && $i < 4; $i++ ) {
 269                 my ($start, $string) = /^\s+(\d*)\s(.*)/;
 270                 $alignment{$ALIGN_TYPES{$i}} = { start => $start, string => $i != 2
 271                     ? $string
 272                     : (' ' x (length($alignment{$ALIGN_TYPES{$i-1}}{string}) - length($string))) . $string
 273                 };
 274                 $_ = $self->_readline();
 275             }
 276
 277             # 'Ruler' line indicates the start of a new HSP
 278             if ($alignment{Ruler}{start} == 0) {
 279                 $format = @hsps ? 3 : 1 if !$format;
 280                 # A previous HSP may need to be ended
 281                 $self->end_element({'Name' => 'Hsp'}) if ( $self->in_element('hsp') );
 282                 # Start the new HSP and fill the '_currentHSP' property with available details
 283                 $self->start_element({'Name' => 'Hsp'});
 284                 $self->{'_currentHSP'} = @hsps ? shift @hsps : {
 285                     'Hsp_query-from' => $alignment{Query}{start},
 286                     'Hsp_hit-from' => $alignment{Sbjct}{start},
 287                 }
 288             }
 289
 290             # Midline indicates a boundary between two HSPs
 291             if ( $alignment{Mid}{string} =~ /<|>/g ) {
 292                 my ($hsp_start, $hsp_end);
 293                 # Are we currently in an open HSP?
 294                 if ( $self->in_element('hsp') ) {
 295                     # Find end pos, adjust 'gaps', 'seq' and 'midline' properties... then close HSP
 296                     $hsp_end = (pos $alignment{Mid}{string}) - 1;
 297                     $self->{'_currentHSP'}{'Hsp_querygaps'} +=
 298                         ($self->{'_currentHSP'}{'Hsp_qseq'} .= substr($alignment{Query}{string}, 0, $hsp_end)) =~ s/ /-/g;
 299                     $self->{'_currentHSP'}{'Hsp_hitgaps'} +=
 300                         ($self->{'_currentHSP'}{'Hsp_hseq'} .= substr($alignment{Sbjct}{string}, 0, $hsp_end)) =~ s/ /-/g;
 301                     ($self->{'_currentHSP'}{'Hsp_midline'} .= substr($alignment{Mid}{string}, 0, $hsp_end)) =~ s/-/ /g;
 302                     $self->end_element({'Name' => 'Hsp'});
 303
 304                     # Does a new HSP start in the current alignment block?
 305                     if ( $alignment{Mid}{string} =~ /\|/g ) {
 306                         # Find start pos, start new HSP and fill it with available details
 307                         $hsp_start = (pos $alignment{Mid}{string}) - 1;
 308                         $self->start_element({'Name' => 'Hsp'});
 309                         $self->{'_currentHSP'} = @hsps ? shift @hsps : {};
 310                         $self->{'_currentHSP'}{'Hsp_querygaps'} +=
 311                             ($self->{'_currentHSP'}{'Hsp_qseq'} = substr($alignment{Query}{string}, $hsp_start)) =~ s/ /-/g;
 312                         $self->{'_currentHSP'}{'Hsp_hitgaps'} +=
 313                             ($self->{'_currentHSP'}{'Hsp_hseq'} = substr($alignment{Sbjct}{string}, $hsp_start)) =~ s/ /-/g;
 314                         ($self->{'_currentHSP'}{'Hsp_midline'} = substr($alignment{Mid}{string}, $hsp_start)) =~ s/-/ /g;
 315                     }
 316                 }
 317                 # No HSP is currently open...
 318                 else {
 319                     # Find start pos, start new HSP and fill it with available
 320                     # details then skip to next alignment block
 321                     $hsp_start = index($alignment{Mid}{string}, '|');
 322                     $self->start_element({'Name' => 'Hsp'});
 323                     $self->{'_currentHSP'} = @hsps ? shift @hsps : {
 324                         'Hsp_query-from' => $alignment{Query}{start},
 325                     };
 326                     $self->{'_currentHSP'}{'Hsp_querygaps'} +=
 327                         ($self->{'_currentHSP'}{'Hsp_qseq'} = substr($alignment{Query}{string}, $hsp_start)) =~ s/ /-/g;
 328                     $self->{'_currentHSP'}{'Hsp_hitgaps'} +=
 329                         ($self->{'_currentHSP'}{'Hsp_hseq'} = substr($alignment{Sbjct}{string}, $hsp_start)) =~ s/ /-/g;
 330                     ($self->{'_currentHSP'}{'Hsp_midline'} = substr($alignment{Mid}{string}, $hsp_start)) =~ s/-/ /g;
 331                     next;
 332                 }
 333             }
 334             # Current alignment block does not contain HSPs boundary
 335             else {
 336                 # Start a new HSP if none is currently open
 337                 # (Happens if last boundary finished at the very end of previous block)
 338                 if ( !$self->in_element('hsp') ) {
 339                     $self->start_element({'Name' => 'Hsp'});
 340                     $self->{'_currentHSP'} = @hsps ? shift @hsps : {
 341                         'Hsp_query-from' => $alignment{Query}{start},
 342                         'Hsp_hit-from' => $alignment{Sbjct}{start},
 343                     }
 344                 }
 345                 # Adjust details of the current HSP
 346                 $self->{'_currentHSP'}{'Hsp_query-from'} ||=
 347                     $alignment{Query}{start} -
 348                     length($self->{'_currentHSP'}{'Hsp_qseq'} || '');
 349                 $self->{'_currentHSP'}{'Hsp_hit-from'} ||=
 350                     $alignment{Sbjct}{start} -
 351                     length($self->{'_currentHSP'}{'Hsp_hseq'} || '');
 352                 $self->{'_currentHSP'}{'Hsp_querygaps'} +=
 353                     ($self->{'_currentHSP'}{'Hsp_qseq'} .=
 354                      $alignment{Query}{string}) =~ s/ /-/g;
 355                 $self->{'_currentHSP'}{'Hsp_hitgaps'} +=
 356                     ($self->{'_currentHSP'}{'Hsp_hseq'} .=
 357                      $alignment{Sbjct}{string}) =~ s/ /-/g;
 358                 ($self->{'_currentHSP'}{'Hsp_midline'} .=
 359                  $alignment{Mid}{string}) =~ s/-/ /g;
 360             }
 361         }
 362     }
 363
 364     # We are done reading the sim4 report, end everything and return
 365     if( $seentop ) {
 366         # end HSP if needed
 367         $self->end_element({'Name' => 'Hsp'}) if ( $self->in_element('hsp') );
 368         # end Hit if needed
 369         if ( $self->in_element('hit') ) {
 370             foreach (@hsps) {
 371                 $self->start_element({'Name' => 'Hsp'});
 372                 while (my ($name, $data) = each %$_) {
 373                     $self->{'_currentHSP'}{$name} = $data;
 374                 }
 375                 $self->end_element({'Name' => 'Hsp'});
 376             }
 377             $self->end_element({'Name' => 'Hit'});
 378         }
 379         # adjust result's algorithm name, end output and return
 380         $self->element({'Name' => 'Sim4Output_program',
 381                         'Data' => $DEFAULTFORMAT . ' (A=' . (defined $format ? $format : '?') . ')'});
 382         $self->end_element({'Name' => 'Sim4Output'});
 383         return $self->end_document();
 384     }
 385     return;
 386 }
 387
 388 =head2 start_element
 389
 390  Title   : start_element
 391  Usage   : $eventgenerator->start_element
 392  Function: Handles a start element event
 393  Returns : none
 394  Args    : hashref with at least 2 keys 'Data' and 'Name'
 395
 396
 397 =cut
 398
 399 sub start_element{
 400    my ($self,$data) = @_;
 401    # we currently don't care about attributes
 402    my $nm = $data->{'Name'};
 403    my $type = $MODEMAP{$nm};
 404
 405    if( $type ) {
 406        if( $self->_will_handle($type) ) {
 407            my $func = sprintf("start_%s",lc $type);
 408            $self->_eventHandler->$func($data->{'Attributes'});
 409        }
 410        unshift @{$self->{'_elements'}}, $type;
 411
 412        if($type eq 'result') {
 413            $self->{'_values'} = {};
 414            $self->{'_result'}= undef;
 415        }
 416    }
 417
 418 }
 419
 420 =head2 end_element
 421
 422  Title   : start_element
 423  Usage   : $eventgenerator->end_element
 424  Function: Handles an end element event
 425  Returns : none
 426  Args    : hashref with at least 2 keys 'Data' and 'Name'
 427
 428
 429 =cut
 430
 431 sub end_element {
 432     my ($self,$data) = @_;
 433     my $nm = $data->{'Name'};
 434     my $type = $MODEMAP{$nm};
 435     my $rc;
 436
 437     if( $nm eq 'Hsp' ) {
 438         $self->{'_currentHSP'}{'Hsp_midline'} ||= '';
 439         $self->{'_currentHSP'}{'Hsp_query-to'} ||=
 440             $self->{'_currentHSP'}{'Hsp_query-from'} + length($self->{'_currentHSP'}{'Hsp_qseq'}) - 1 - $self->{'_currentHSP'}{'Hsp_querygaps'};
 441         $self->{'_currentHSP'}{'Hsp_hit-to'} ||=
 442             $self->{'_currentHSP'}{'Hsp_hit-from'} + length($self->{'_currentHSP'}{'Hsp_hseq'}) - 1 - $self->{'_currentHSP'}{'Hsp_hitgaps'};
 443         $self->{'_currentHSP'}{'Hsp_identity'} ||=
 444             ($self->{'_currentHSP'}{'Hsp_midline'} =~ tr/\|//);
 445         $self->{'_currentHSP'}{'Hsp_qlength'} ||= abs($self->{'_currentHSP'}{'Hsp_query-to'} - $self->{'_currentHSP'}{'Hsp_query-from'}) + 1;
 446         $self->{'_currentHSP'}{'Hsp_hlength'} ||= abs($self->{'_currentHSP'}{'Hsp_hit-to'} - $self->{'_currentHSP'}{'Hsp_hit-from'}) + 1;
 447         $self->{'_currentHSP'}{'Hsp_align-len'} ||= abs($self->{'_currentHSP'}{'Hsp_query-to'} - $self->{'_currentHSP'}{'Hsp_query-from'}) + 1;
 448         $self->{'_currentHSP'}{'Hsp_score'} ||= int(100 * ($self->{'_currentHSP'}{'Hsp_identity'} / $self->{'_currentHSP'}{'Hsp_align-len'}));
 449         foreach (keys %{$self->{'_currentHSP'}}) {
 450             $self->element({'Name' => $_, 'Data' => delete ${$self->{'_currentHSP'}}{$_}});
 451         }
 452     }
 453
 454     if( $type = $MODEMAP{$nm} ) {
 455         if( $self->_will_handle($type) ) {
 456             my $func = sprintf("end_%s",lc $type);
 457             $rc = $self->_eventHandler->$func($self->{'_reporttype'},
 458                                               $self->{'_values'});
 459         }
 460         shift @{$self->{'_elements'}};
 461
 462     } elsif( $MAPPING{$nm} ) {
 463
 464         if ( ref($MAPPING{$nm}) =~ /hash/i ) {
 465             my $key = (keys %{$MAPPING{$nm}})[0];
 466             $self->{'_values'}->{$key}->{$MAPPING{$nm}->{$key}} = $self->{'_last_data'};
 467         } else {
 468             $self->{'_values'}->{$MAPPING{$nm}} = $self->{'_last_data'};
 469         }
 470     } else {
 471         $self->debug( "unknown nm $nm, ignoring\n");
 472     }
 473     $self->{'_last_data'} = ''; # remove read data if we are at
 474                                 # end of an element
 475     $self->{'_result'} = $rc if( defined $type && $type eq 'result' );
 476     return $rc;
 477 }
 478
 479 =head2 element
 480
 481  Title   : element
 482  Usage   : $eventhandler->element({'Name' => $name, 'Data' => $str});
 483  Function: Convience method that calls start_element, characters, end_element
 484  Returns : none
 485  Args    : Hash ref with the keys 'Name' and 'Data'
 486
 487
 488 =cut
 489
 490 sub element{
 491    my ($self,$data) = @_;
 492    $self->start_element($data);
 493    $self->characters($data);
 494    $self->end_element($data);
 495 }
 496
 497 =head2 characters
 498
 499  Title   : characters
 500  Usage   : $eventgenerator->characters($str)
 501  Function: Send a character events
 502  Returns : none
 503  Args    : string
 504
 505
 506 =cut
 507
 508 sub characters{
 509    my ($self,$data) = @_;
 510    return unless ( defined $data->{'Data'} && $data->{'Data'} !~ /^\s+$/ );
 511
 512    if( $self->in_element('hsp') &&
 513        $data->{'Name'} =~ /Hsp\_(qseq|hseq|midline)/ ) {
 514        $self->{'_last_hspdata'}->{$data->{'Name'}} .= $data->{'Data'};
 515    }
 516
 517    $self->{'_last_data'} = $data->{'Data'};
 518 }
 519
 520 =head2 within_element
 521
 522  Title   : within_element
 523  Usage   : if( $eventgenerator->within_element($element) ) {}
 524  Function: Test if we are within a particular element
 525            This is different than 'in' because within can be tested
 526            for a whole block.
 527  Returns : boolean
 528  Args    : string element name
 529
 530
 531 =cut
 532
 533 sub within_element{
 534    my ($self,$name) = @_;
 535    return 0 if ( ! defined $name &&
 536                  ! defined  $self->{'_elements'} ||
 537                  scalar @{$self->{'_elements'}} == 0) ;
 538    foreach (  @{$self->{'_elements'}} ) {
 539        if( $_ eq $name  ) {
 540            return 1;
 541        }
 542    }
 543    return 0;
 544 }
 545
 546
 547 =head2 in_element
 548
 549  Title   : in_element
 550  Usage   : if( $eventgenerator->in_element($element) ) {}
 551  Function: Test if we are in a particular element
 552            This is different than 'in' because within can be tested
 553            for a whole block.
 554  Returns : boolean
 555  Args    : string element name
 556
 557
 558 =cut
 559
 560 sub in_element{
 561    my ($self,$name) = @_;
 562    return 0 if ! defined $self->{'_elements'}->[0];
 563    return ( $self->{'_elements'}->[0] eq $name)
 564 }
 565
 566 =head2 start_document
 567
 568  Title   : start_document
 569  Usage   : $eventgenerator->start_document
 570  Function: Handle a start document event
 571  Returns : none
 572  Args    : none
 573
 574
 575 =cut
 576
 577 sub start_document{
 578     my ($self) = @_;
 579     $self->{'_lasttype'} = '';
 580     $self->{'_values'} = {};
 581     $self->{'_result'}= undef;
 582     $self->{'_elements'} = [];
 583     $self->{'_reporttype'} = $DEFAULTFORMAT;
 584 }
 585
 586
 587 =head2 end_document
 588
 589  Title   : end_document
 590  Usage   : $eventgenerator->end_document
 591  Function: Handles an end document event
 592  Returns : Bio::Search::Result::ResultI object
 593  Args    : none
 594
 595
 596 =cut
 597
 598 sub end_document{
 599    my ($self,@args) = @_;
 600    return $self->{'_result'};
 601 }
 602
 603
 604 sub write_result {
 605    my ($self, $blast, @args) = @_;
 606
 607    if( not defined($self->writer) ) {
 608        $self->warn("Writer not defined. Using a $DEFAULT_WRITER_CLASS");
 609        $self->writer( $DEFAULT_WRITER_CLASS->new() );
 610    }
 611    $self->SUPER::write_result( $blast, @args );
 612 }
 613
 614 sub result_count {
 615     return 1; # can a sim4 report contain more than one result?
 616 }
 617
 618 sub report_count { shift->result_count }
 619
 620 =head2 _will_handle
 621
 622  Title   : _will_handle
 623  Usage   : Private method. For internal use only.
 624               if( $self->_will_handle($type) ) { ... }
 625  Function: Provides an optimized way to check whether or not an element of a
 626            given type is to be handled.
 627  Returns : Reference to EventHandler object if the element type is to be handled.
 628            undef if the element type is not to be handled.
 629  Args    : string containing type of element.
 630
 631 Optimizations:
 632
 633   1. Using the cached pointer to the EventHandler to minimize repeated lookups.
 634   2. Caching the will_handle status for each type that is encountered
 635      so that it only need be checked by calling handler->will_handle($type) once.
 636
 637 This does not lead to a major savings by itself (only 5-10%).
 638 In combination with other optimizations, or for large parse jobs, the
 639 savings good be significant.
 640
 641 To test against the unoptimized version, remove the parentheses from
 642 around the third term in the ternary " ? : " operator and add two
 643 calls to $self-E<gt>_eventHandler().
 644
 645 =cut
 646
 647 sub _will_handle {
 648     my ($self,$type) = @_;
 649     my $handler = $self->{'_handler_cache'} ||= $self->_eventHandler;
 650
 651     my $will_handle = defined($self->{'_will_handle_cache'}->{$type})
 652                              ? $self->{'_will_handle_cache'}->{$type}
 653                              : ($self->{'_will_handle_cache'}->{$type} =
 654                                $handler->will_handle($type));
 655
 656     return $will_handle ? $handler : undef;
 657 }
 658
 659 1;