branch-1-6/Bio/Search/Hit/HMMERHit.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Search::Hit::HMMERHit
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Jason Stajich <jason@bioperl.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::Search::Hit::HMMERHit - A Hit module for HMMER hits
  18
  19 =head1 SYNOPSIS
  20
  21     use Bio::Search::Hit::HMMERHit;
  22     my $hit = Bio::Search::Hit::HMMERHit->new();
  23     # use it in the same way as Bio::Search::Hit::GenericHit
  24
  25 =head1 DESCRIPTION
  26
  27 This is a specialization of L<Bio::Search::Hit::GenericHit>.  There
  28 are a few news methods L<next_domain> and L<domains>.  Note that
  29 L<bits> and L<iteration> make no sense for this object and will
  30 return 0.
  31
  32 =head1 FEEDBACK
  33
  34 =head2 Mailing Lists
  35
  36 User feedback is an integral part of the evolution of this and other
  37 Bioperl modules. Send your comments and suggestions preferably to
  38 the Bioperl mailing list.  Your participation is much appreciated.
  39
  40   bioperl-l@bioperl.org                  - General discussion
  41   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  42
  43 =head2 Support
  44
  45 Please direct usage questions or support issues to the mailing list:
  46
  47 I<bioperl-l@bioperl.org>
  48
  49 rather than to the module maintainer directly. Many experienced and
  50 reponsive experts will be able look at the problem and quickly
  51 address it. Please include a thorough description of the problem
  52 with code and data examples if at all possible.
  53
  54 =head2 Reporting Bugs
  55
  56 Report bugs to the Bioperl bug tracking system to help us keep track
  57 of the bugs and their resolution. Bug reports can be submitted via the
  58 web:
  59
  60   http://bugzilla.open-bio.org/
  61
  62 =head1 AUTHOR - Jason Stajich
  63
  64 Email jason@bioperl.org
  65
  66 =head1 APPENDIX
  67
  68 The rest of the documentation details each of the object methods.
  69 Internal methods are usually preceded with a _
  70
  71 =cut
  72
  73
  74 # Let the code begin...
  75
  76
  77 package Bio::Search::Hit::HMMERHit;
  78 use strict;
  79
  80
  81 use base qw(Bio::Search::Hit::GenericHit);
  82
  83 =head2 new
  84
  85  Title   : new
  86  Usage   : my $obj = Bio::Search::Hit::HMMERHit->new();
  87  Function: Builds a new Bio::Search::Hit::HMMERHit object
  88  Returns : Bio::Search::Hit::HMMERHit
  89  Args    :
  90
  91  Plus the Bio::Search::Hit::GenericHit inherited params
  92            -name         => Name of Hit (required)
  93            -description  => Description (optional)
  94            -accession    => Accession number (optional)
  95            -length       => Length of the Hit (optional)
  96            -score        => Raw Score for the Hit (optional)
  97            -significance => Significance value for the Hit (optional)
  98            -algorithm    => Algorithm used (BLASTP, FASTX, etc...)
  99            -hsps         => Array ref of HSPs for this Hit.
 100
 101
 102 =cut
 103
 104
 105 =head2 next_domain
 106
 107  Title   : next_domain
 108  Usage   : my $domain = $hit->next_domain();
 109  Function: An alias for L<next_hsp()>, this will return the next HSP
 110  Returns : L<Bio::Search::HSP::HSPI> object
 111  Args    : none
 112
 113
 114 =cut
 115
 116 sub next_domain{ shift->next_hsp }
 117
 118 =head2 domains
 119
 120  Title   : domains
 121  Usage   : my @domains = $hit->domains();
 122  Function: An alias for L<hsps()>, this will return the full list of hsps
 123  Returns : array of L<Bio::Search::HSP::HSPI> objects
 124  Args    : none
 125
 126
 127 =cut
 128
 129 sub domains{ shift->hsps() }
 130
 131
 132 =head2 inherited Bio::Search::Hit::GenericHit methods
 133
 134 =cut
 135
 136 =head2 add_hsp
 137
 138  Title   : add_hsp
 139  Usage   : $hit->add_hsp($hsp)
 140  Function: Add a HSP to the collection of HSPs for a Hit
 141  Returns : number of HSPs in the Hit
 142  Args    : Bio::Search::HSP::HSPI object
 143
 144
 145 =cut
 146
 147 =head2 Bio::Search::Hit::HitI methods
 148
 149 =cut
 150
 151 =head2 name
 152
 153  Title   : name
 154  Usage   : $hit_name = $hit->name();
 155  Function: returns the name of the Hit sequence
 156  Returns : a scalar string
 157  Args    : [optional] scalar string to set the name
 158
 159 =cut
 160
 161 =head2 accession
 162
 163  Title   : accession
 164  Usage   : $acc = $hit->accession();
 165  Function: Retrieve the accession (if available) for the hit
 166  Returns : a scalar string (empty string if not set)
 167  Args    : none
 168
 169 =cut
 170
 171 =head2 description
 172
 173  Title   : description
 174  Usage   : $desc = $hit->description();
 175  Function: Retrieve the description for the hit
 176  Returns : a scalar string
 177  Args    : [optional] scalar string to set the descrition
 178
 179 =cut
 180
 181 =head2 length
 182
 183  Title   : length
 184  Usage   : my $len = $hit->length
 185  Function: Returns the length of the hit
 186  Returns : integer
 187  Args    : [optional] integer to set the length
 188
 189 =cut
 190
 191 =head2 algorithm
 192
 193  Title   : algorithm
 194  Usage   : $alg = $hit->algorithm();
 195  Function: Gets the algorithm specification that was used to obtain the hit
 196            For BLAST, the algorithm denotes what type of sequence was aligned
 197            against what (BLASTN: dna-dna, BLASTP prt-prt, BLASTX translated
 198            dna-prt, TBLASTN prt-translated dna, TBLASTX translated
 199            dna-translated dna).
 200  Returns : a scalar string
 201  Args    : [optional] scalar string to set the algorithm
 202
 203 =cut
 204
 205 =head2 raw_score
 206
 207  Title   : raw_score
 208  Usage   : $score = $hit->raw_score();
 209  Function: Gets the "raw score" generated by the algorithm.  What
 210            this score is exactly will vary from algorithm to algorithm,
 211            returning undef if unavailable.
 212  Returns : a scalar value
 213  Args    : [optional] scalar value to set the raw score
 214
 215 =cut
 216
 217 =head2 significance
 218
 219  Title   : significance
 220  Usage   : $significance = $hit->significance();
 221  Function: Used to obtain the E or P value of a hit, i.e. the probability that
 222            this particular hit was obtained purely by random chance.  If
 223            information is not available (nor calculatable from other
 224            information sources), return undef.
 225  Returns : a scalar value or undef if unavailable
 226  Args    : [optional] scalar value to set the significance
 227
 228 =cut
 229
 230 =head2 bits
 231
 232  Usage     : $hit_object->bits();
 233  Purpose   : Gets the bit score of the best HSP for the current hit.
 234  Example   : $bits = $hit_object->bits();
 235  Returns   : Integer or undef if bit score is not set
 236  Argument  : n/a
 237
 238 See Also   : L<score()|score>
 239
 240 =cut
 241
 242 sub bits { return 0 }
 243
 244 =head2 next_hsp
 245
 246  Title    : next_hsp
 247  Usage    : while( $hsp = $obj->next_hsp()) { ... }
 248  Function : Returns the next available High Scoring Pair
 249  Example  :
 250  Returns  : Bio::Search::HSP::HSPI object or null if finished
 251  Args     : none
 252
 253 =cut
 254
 255 =head2 hsps
 256
 257  Usage     : $hit_object->hsps();
 258  Purpose   : Get a list containing all HSP objects.
 259            : Get the numbers of HSPs for the current hit.
 260  Example   : @hsps = $hit_object->hsps();
 261            : $num  = $hit_object->hsps();  # alternatively, use num_hsps()
 262  Returns   : Array context : list of Bio::Search::HSP::BlastHSP.pm objects.
 263            : Scalar context: integer (number of HSPs).
 264            :                 (Equivalent to num_hsps()).
 265  Argument  : n/a. Relies on wantarray
 266  Throws    : Exception if the HSPs have not been collected.
 267
 268 See Also   : L<hsp()|hsp>, L<num_hsps()|num_hsps>
 269
 270 =cut
 271
 272 =head2 num_hsps
 273
 274  Usage     : $hit_object->num_hsps();
 275  Purpose   : Get the number of HSPs for the present Blast hit.
 276  Example   : $nhsps = $hit_object->num_hsps();
 277  Returns   : Integer
 278  Argument  : n/a
 279  Throws    : Exception if the HSPs have not been collected.
 280
 281 See Also   : L<hsps()|hsps>
 282
 283 =cut
 284
 285 =head2 rewind
 286
 287  Title   : rewind
 288  Usage   : $hit->rewind;
 289  Function: Allow one to reset the HSP iteration to the beginning
 290            Since this is an in-memory implementation
 291  Returns : none
 292  Args    : none
 293
 294 =cut
 295
 296 =head2 iteration
 297
 298  Title   : iteration
 299  Usage   : $obj->iteration($newval)
 300  Function: PSI-BLAST iteration
 301  Returns : value of iteration
 302  Args    : newvalue (optional)
 303
 304
 305 =cut
 306
 307
 308 sub iteration { return 0 }
 309
 310 1;