lib/Bio/SearchIO/Writer/HSPTableWriter.pm

   1
   2 =head1 NAME
   3
   4 Bio::SearchIO::Writer::HSPTableWriter - Tab-delimited data for Bio::Search::HSP::HSPI objects
   5
   6 =head1 SYNOPSIS
   7
   8 =head2 Example 1: Using the default columns
   9
  10     use Bio::SearchIO;
  11     use Bio::SearchIO::Writer::HSPTableWriter;
  12
  13     my $in = Bio::SearchIO->new();
  14
  15     my $writer = Bio::SearchIO::Writer::HSPTableWriter->new();
  16
  17     my $out = Bio::SearchIO->new( -writer => $writer );
  18
  19     while ( my $result = $in->next_result() ) {
  20         $out->write_result($result, ($in->report_count - 1 ? 0 : 1) );
  21     }
  22
  23 =head2 Example 2: Specifying a subset of columns
  24
  25     use Bio::SearchIO;
  26     use Bio::SearchIO::Writer::HSPTableWriter;
  27
  28     my $in = Bio::SearchIO->new();
  29
  30     my $writer = Bio::SearchIO::Writer::HSPTableWriter->new(
  31                                   -columns => [qw(
  32                                                   query_name
  33                                                   query_length
  34                                                   hit_name
  35                                                   hit_length
  36                                                   rank
  37                                                   frac_identical_query
  38                                                   expect
  39                                                   )]  );
  40
  41     my $out = Bio::SearchIO->new( -writer => $writer,
  42                                   -file   => ">searchio.out" );
  43
  44     while ( my $result = $in->next_result() ) {
  45         $out->write_result($result, ($in->report_count - 1 ? 0 : 1) );
  46     }
  47
  48 =head2 Custom Labels
  49
  50 You can also specify different column labels if you don't want to use
  51 the defaults.  Do this by specifying a C<-labels> hash reference
  52 parameter when creating the HSPTableWriter object.  The keys of the
  53 hash should be the column number (left-most column = 1) for the label(s)
  54 you want to specify. Here's an example:
  55
  56     my $writer = Bio::SearchIO::Writer::HSPTableWriter->new(
  57                                -columns => [qw( query_name
  58                                                 query_length
  59                                                 hit_name
  60                                                 hit_length  )],
  61                                -labels  => { 1 => 'QUERY_GI',
  62                                              3 => 'HIT_IDENTIFIER' } );
  63
  64
  65 =head1 DESCRIPTION
  66
  67 Bio::SearchIO::Writer::HSPTableWriter generates output at the finest
  68 level of granularity for data within a search result. Data for each HSP
  69 within each hit in a search result is output in tab-delimited format,
  70 one row per HSP.
  71
  72 =head2 Available Columns
  73
  74 Here are the columns that can be specified in the C<-columns>
  75 parameter when creating a HSPTableWriter object.  If a C<-columns> parameter
  76 is not specified, this list, in this order, will be used as the default.
  77
  78     query_name             # Sequence identifier of the query.
  79     query_length           # Full length of the query sequence
  80     hit_name               # Sequence identifier of the hit
  81     hit_length             # Full length of the hit sequence
  82     round                  # Round number for hit (PSI-BLAST)
  83     rank
  84     expect                 # Expect value for the alignment
  85     score                  # Score for the alignment (e.g., BLAST score)
  86     bits                   # Bit score for the alignment
  87     frac_identical_query   # fraction of identical substitutions in query
  88     frac_identical_hit     # fraction of identical substitutions in hit
  89     frac_conserved_query   # fraction of conserved substitutions in query
  90     frac_conserved_hit     # fraction of conserved substitutions in hit
  91     length_aln_query       # Length of the aligned portion of the query sequence
  92     length_aln_hit         # Length of the aligned portion of the hit sequence
  93     gaps_query             # Number of gap characters in the aligned query sequence
  94     gaps_hit               # Number of gap characters in the aligned hit sequence
  95     gaps_total             # Number of gap characters in the aligned query and hit sequences
  96     start_query            # Starting coordinate of the aligned portion of the query sequence
  97     end_query              # Ending coordinate of the aligned portion of the query sequence
  98     start_hit              # Starting coordinate of the aligned portion of the hit sequence
  99     end_hit                # Ending coordinate of the aligned portion of the hit sequence
 100     strand_query           # Strand of the aligned query sequence
 101     strand_hit             # Strand of the aligned hit sequence
 102     frame                  # Reading frame of the aligned query sequence
 103     hit_description        # Full description of the hit sequence
 104     query_description      # Full description of the query sequence
 105     frac_identical_total   # fraction of total identical substitutions
 106     frac_conserved_total   # fraction of total conserved substitutions
 107
 108 For more details about these columns, see the documentation for the
 109 corresponding method in Bio::Search::HSP::HSPI.
 110
 111 =head1 TODO
 112
 113 Figure out the best way to incorporate algorithm-specific score columns.
 114 The best route is probably to have algorith-specific subclasses
 115 (e.g., BlastHSPTableWriter, FastaHSPTableWriter).
 116
 117 =head1 FEEDBACK
 118
 119 =head2 Mailing Lists
 120
 121 User feedback is an integral part of the evolution of this and other
 122 Bioperl modules.  Send your comments and suggestions preferably to one
 123 of the Bioperl mailing lists.  Your participation is much appreciated.
 124
 125   bioperl-l@bioperl.org                  - General discussion
 126   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
 127
 128 =head2 Support
 129
 130 Please direct usage questions or support issues to the mailing list:
 131
 132 I<bioperl-l@bioperl.org>
 133
 134 rather than to the module maintainer directly. Many experienced and
 135 reponsive experts will be able look at the problem and quickly
 136 address it. Please include a thorough description of the problem
 137 with code and data examples if at all possible.
 138
 139 =head2 Reporting Bugs
 140
 141 Report bugs to the Bioperl bug tracking system to help us keep track
 142 the bugs and their resolution. Bug reports can be submitted via the
 143 web:
 144
 145   https://github.com/bioperl/bioperl-live/issues
 146
 147 =head1 AUTHOR
 148
 149 Steve Chervitz E<lt>sac@bioperl.orgE<gt>
 150
 151 See L<the FEEDBACK section | FEEDBACK> for where to send bug reports
 152 and comments.
 153
 154 =head1 COPYRIGHT
 155
 156 Copyright (c) 2001 Steve Chervitz. All Rights Reserved.
 157
 158 This library is free software; you can redistribute it and/or modify
 159 it under the same terms as Perl itself.
 160
 161 =head1 DISCLAIMER
 162
 163 This software is provided "as is" without warranty of any kind.
 164
 165 =head1 SEE ALSO
 166
 167     Bio::SearchIO::Writer::HitTableWriter
 168     Bio::SearchIO::Writer::ResultTableWriter
 169
 170 =head1 METHODS
 171
 172 =cut
 173
 174 package Bio::SearchIO::Writer::HSPTableWriter;
 175
 176 use strict;
 177
 178 use base qw(Bio::SearchIO::Writer::ResultTableWriter);
 179
 180
 181 # Array fields: column, object, method[/argument], printf format, column label
 182 # Methods for result object are defined in Bio::Search::Result::ResultI.
 183 # Methods for hit object are defined in Bio::Search::Hit::HitI.
 184 # Methods for hsp object are defined in Bio::Search::HSP::HSPI.
 185 # Tech note: If a bogus method is supplied, it will result in all values to be zero.
 186 #            Don't know why this is.
 187 # TODO (maybe): Allow specification of signif_format (i.e., separate mantissa/exponent)
 188 my %column_map = (
 189                   'query_name'            => ['1', 'result', 'query_name', 's', 'QUERY' ],
 190                   'query_length'          => ['2', 'result', 'query_length', 'd', 'LEN_Q'],
 191                   'hit_name'              => ['3', 'hit', 'name', 's', 'HIT'],
 192                   'hit_length'            => ['4', 'hit', 'hit_length', 'd', 'LEN_H'],
 193                   'round'                 => ['5', 'hit', 'iteration', 'd', 'ROUND', 'hit'],
 194                   'rank'                  => ['6', 'hsp', 'rank', 'd', 'RANK'],
 195                   'expect'                => ['7', 'hsp', 'expect', '.1e', 'EXPCT'],
 196                   'score'                 => ['8', 'hsp', 'score', 'd', 'SCORE'],
 197                   'bits'                  => ['9', 'hsp', 'bits', 'd', 'BITS'],
 198                   'frac_identical_query'  => ['10', 'hsp', 'frac_identical/query', '.2f', 'FR_IDQ'],
 199                   'frac_identical_hit'    => ['11', 'hsp', 'frac_identical/hit', '.2f', 'FR_IDH'],
 200                   'frac_conserved_query'  => ['12', 'hsp', 'frac_conserved/query', '.2f', 'FR_CNQ'],
 201                   'frac_conserved_hit'    => ['13', 'hsp', 'frac_conserved/hit', '.2f', 'FR_CNH'],
 202                   'length_aln_query'      => ['14', 'hsp', 'length/query', 'd', 'LN_ALQ'],
 203                   'length_aln_hit'        => ['15', 'hsp', 'length/hit', 'd', 'LN_ALH'],
 204                   'gaps_query'            => ['16', 'hsp', 'gaps/query', 'd', 'GAPS_Q'],
 205                   'gaps_hit'              => ['17', 'hsp', 'gaps/hit', 'd', 'GAPS_H'],
 206                   'gaps_total'            => ['18', 'hsp', 'gaps/total', 'd', 'GAPS_QH'],
 207                   'start_query'           => ['19', 'hsp', 'start/query', 'd', 'START_Q'],
 208                   'end_query'             => ['20', 'hsp', 'end/query', 'd', 'END_Q'],
 209                   'start_hit'             => ['21', 'hsp', 'start/hit', 'd', 'START_H'],
 210                   'end_hit'               => ['22', 'hsp', 'end/hit', 'd', 'END_H'],
 211                   'strand_query'          => ['23', 'hsp', 'strand/query', 'd', 'STRND_Q'],
 212                   'strand_hit'            => ['24', 'hsp', 'strand/hit', 'd', 'STRND_H'],
 213                   'frame_hit'             => ['25', 'hsp', 'frame/hit', 's', 'FRAME_H'],
 214                   'frame_query'           => ['26', 'hsp', 'frame/query', 's', 'FRAME_Q'],
 215                   'hit_description'       => ['27', 'hit', 'hit_description', 's', 'DESC_H'],
 216                   'query_description'     => ['28', 'result', 'query_description', 's', 'DESC_Q'],
 217                   'frac_identical_total'  => ['29', 'hsp', 'frac_identical/total', '.2f', 'FR_IDT'],
 218                   'frac_conserved_total'  => ['30', 'hsp', 'frac_conserved/total', '.2f', 'FR_CNT'],
 219                  );
 220
 221 sub column_map { return %column_map }
 222
 223 =head2 to_string()
 224
 225 Note: this method is not intended for direct use.
 226 The SearchIO::write_result() method calls it automatically
 227 if the writer is hooked up to a SearchIO object as illustrated in
 228 L<the SYNOPSIS section | SYNOPSIS>.
 229
 230  Title     : to_string()
 231            :
 232  Usage     : print $writer->to_string( $result_obj, [$include_labels] );
 233            :
 234  Argument  : $result_obj = A Bio::Search::Result::ResultI object
 235            : $include_labels = boolean, if true column labels are included (default: false)
 236            :
 237  Returns   : String containing tab-delimited set of data for each HSP
 238            : in each Hit of the supplied ResultI object.
 239            :
 240  Throws    : n/a
 241
 242 =cut
 243
 244 sub to_string {
 245     my ($self, $result, $include_labels) = @_;
 246
 247     my $str = $include_labels ? $self->column_labels() : '';
 248     my ($resultfilter,$hitfilter,
 249         $hspfilter) = ( $self->filter('RESULT'),
 250                         $self->filter('HIT'),
 251                         $self->filter('HSP'));
 252     if( ! defined $resultfilter || &{$resultfilter}($result) ) {
 253         my $func_ref = $self->row_data_func;
 254         my $printf_fmt = $self->printf_fmt;
 255         $result->can('rewind') &&
 256             $result->rewind(); # insure we're at the beginning
 257         while( my $hit = $result->next_hit) {
 258             next if( defined $hitfilter && ! &{$hitfilter}($hit) );
 259             $hit->can('rewind') && $hit->rewind;# insure we're at the beginning
 260             while(my $hsp = $hit->next_hsp) {
 261             next if ( defined $hspfilter && ! &{$hspfilter}($hsp));
 262             my @row_data  = &{$func_ref}($result, $hit, $hsp);
 263             $str .= sprintf("$printf_fmt\n", map {$_ || ($printf_fmt eq 's' ? '' : 0)} @row_data);
 264             }
 265         }
 266     }
 267     $str =~ s/\t\n/\n/gs;
 268     return $str;
 269 }
 270
 271 =head2 end_report
 272
 273  Title   : end_report
 274  Usage   : $self->end_report()
 275  Function: The method to call when ending a report, this is
 276            mostly for cleanup for formats which require you to
 277            have something at the end of the document.  Nothing for
 278            a text message.
 279  Returns : string
 280  Args    : none
 281
 282 =cut
 283
 284 sub end_report {
 285     return '';
 286 }
 287
 288 =head2 filter
 289
 290  Title   : filter
 291  Usage   : $writer->filter('hsp', \&hsp_filter);
 292  Function: Filter out either at HSP,Hit,or Result level
 293  Returns : none
 294  Args    : string => data type,
 295            CODE reference
 296
 297
 298 =cut
 299
 300
 301 1;