Bio/Search/HSP/HMMERHSP.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Search::HSP::HMMERHSP
   4 #
   5 # Cared for by Jason Stajich <jason@bioperl.org>
   6 #
   7 # Copyright Jason Stajich
   8 #
   9 # You may distribute this module under the same terms as perl itself
  10
  11 # POD documentation - main docs before the code
  12
  13 =head1 NAME
  14
  15 Bio::Search::HSP::HMMERHSP - A HSP object for HMMER results
  16
  17 =head1 SYNOPSIS
  18
  19     use Bio::Search::HSP::HMMERHSP;
  20     # us it just like a Bio::Search::HSP::GenericHSP object
  21
  22 =head1 DESCRIPTION
  23
  24 This object is a specialization of L<Bio::Search::HSP::GenericHSP>.
  25
  26 =head1 FEEDBACK
  27
  28 =head2 Mailing Lists
  29
  30 User feedback is an integral part of the evolution of this and other
  31 Bioperl modules. Send your comments and suggestions preferably to
  32 the Bioperl mailing list.  Your participation is much appreciated.
  33
  34   bioperl-l@bioperl.org              - General discussion
  35   http://bioperl.org/MailList.shtml  - About the mailing lists
  36
  37 =head2 Reporting Bugs
  38
  39 Report bugs to the Bioperl bug tracking system to help us keep track
  40 of the bugs and their resolution. Bug reports can be submitted via
  41 email or the web:
  42
  43   bioperl-bugs@bioperl.org
  44   http://bugzilla.bioperl.org/
  45
  46 =head1 AUTHOR - Jason Stajich
  47
  48 Email jason@bioperl.org
  49
  50 Describe contact details here
  51
  52 =head1 CONTRIBUTORS
  53
  54 Additional contributors names and emails here
  55
  56 =head1 APPENDIX
  57
  58 The rest of the documentation details each of the object methods.
  59 Internal methods are usually preceded with a _
  60
  61 =cut
  62
  63
  64 # Let the code begin...
  65
  66
  67 package Bio::Search::HSP::HMMERHSP;
  68 use vars qw(@ISA);
  69 use strict;
  70 use Bio::Search::HSP::GenericHSP;
  71
  72 @ISA = qw(Bio::Search::HSP::GenericHSP);
  73
  74 =head2 new
  75
  76  Title   : new
  77  Usage   : my $obj = new Bio::Search::HSP::HMMERHSP();
  78  Function: Builds a new Bio::Search::HSP::HMMERHSP object
  79  Returns : Bio::Search::HSP::HMMERHSP
  80  Args    :
  81
  82 Plus Bio::Seach::HSP::GenericHSP methods
  83
  84            -algorithm => algorithm used (BLASTP, TBLASTX, FASTX, etc)
  85            -evalue    => evalue
  86            -pvalue    => pvalue
  87            -bits      => bit value for HSP
  88            -score     => score value for HSP (typically z-score but depends on
  89                                               analysis)
  90            -hsp_length=> Length of the HSP (including gaps)
  91            -identical => # of residues that that matched identically
  92            -conserved => # of residues that matched conservatively
  93                            (only protein comparisions;
  94                             conserved == identical in nucleotide comparisons)
  95            -hsp_gaps   => # of gaps in the HSP
  96            -query_gaps => # of gaps in the query in the alignment
  97            -hit_gaps   => # of gaps in the subject in the alignment
  98            -query_name  => HSP Query sequence name (if available)
  99            -query_start => HSP Query start (in original query sequence coords)
 100            -query_end   => HSP Query end (in original query sequence coords)
 101            -hit_name    => HSP Hit sequence name (if available)
 102            -hit_start   => HSP Hit start (in original hit sequence coords)
 103            -hit_end     => HSP Hit end (in original hit sequence coords)
 104            -hit_length  => total length of the hit sequence
 105            -query_length=> total length of the query sequence
 106            -query_seq   => query sequence portion of the HSP
 107            -hit_seq     => hit sequence portion of the HSP
 108            -homology_seq=> homology sequence for the HSP
 109            -hit_frame   => hit frame (only if hit is translated protein)
 110            -query_frame => query frame (only if query is translated protein)
 111
 112 =cut
 113
 114 =head2 Bio::Search::HSP::HSPI methods
 115
 116 Implementation of Bio::Search::HSP::HSPI methods follow
 117
 118 =head2 algorithm
 119
 120  Title   : algorithm
 121  Usage   : my $r_type = $hsp->algorithm
 122  Function: Obtain the name of the algorithm used to obtain the HSP
 123  Returns : string (e.g., BLASTP)
 124  Args    : [optional] scalar string to set value
 125
 126 =cut
 127
 128 =head2 pvalue
 129
 130  Title   : pvalue
 131  Usage   : my $pvalue = $hsp->pvalue();
 132  Function: Returns the P-value for this HSP or undef
 133  Returns : float or exponential (2e-10)
 134            P-value is not defined with NCBI Blast2 reports.
 135  Args    : [optional] numeric to set value
 136
 137 =cut
 138
 139 =head2 evalue
 140
 141  Title   : evalue
 142  Usage   : my $evalue = $hsp->evalue();
 143  Function: Returns the e-value for this HSP
 144  Returns : float or exponential (2e-10)
 145  Args    : [optional] numeric to set value
 146
 147 =cut
 148
 149 =head2 frac_identical
 150
 151  Title   : frac_identical
 152  Usage   : my $frac_id = $hsp->frac_identical( ['query'|'hit'|'total'] );
 153  Function: Returns the fraction of identitical positions for this HSP
 154  Returns : Float in range 0.0 -> 1.0
 155  Args    : arg 1:  'query' = num identical / length of query seq (without gaps)
 156                    'hit'   = num identical / length of hit seq (without gaps)
 157                    'total' = num identical / length of alignment (with gaps)
 158                    default = 'total'
 159            arg 2: [optional] frac identical value to set for the type requested
 160
 161 =cut
 162
 163 =head2 frac_conserved
 164
 165  Title    : frac_conserved
 166  Usage    : my $frac_cons = $hsp->frac_conserved( ['query'|'hit'|'total'] );
 167  Function : Returns the fraction of conserved positions for this HSP.
 168             This is the fraction of symbols in the alignment with a
 169             positive score.
 170  Returns : Float in range 0.0 -> 1.0
 171  Args    : arg 1: 'query' = num conserved / length of query seq (without gaps)
 172                   'hit'   = num conserved / length of hit seq (without gaps)
 173                   'total' = num conserved / length of alignment (with gaps)
 174                   default = 'total'
 175            arg 2: [optional] frac conserved value to set for the type requested
 176
 177 =cut
 178
 179 =head2 gaps
 180
 181  Title    : gaps
 182  Usage    : my $gaps = $hsp->gaps( ['query'|'hit'|'total'] );
 183  Function : Get the number of gaps in the query, hit, or total alignment.
 184  Returns  : Integer, number of gaps or 0 if none
 185  Args     : arg 1: 'query' = num gaps in query seq
 186                    'hit'   = num gaps in hit seq
 187                    'total' = num gaps in whole alignment
 188                    default = 'total'
 189             arg 2: [optional] integer gap value to set for the type requested
 190
 191 =cut
 192
 193 =head2 query_string
 194
 195  Title   : query_string
 196  Usage   : my $qseq = $hsp->query_string;
 197  Function: Retrieves the query sequence of this HSP as a string
 198  Returns : string
 199  Args    : [optional] string to set for query sequence
 200
 201
 202 =cut
 203
 204 =head2 hit_string
 205
 206  Title   : hit_string
 207  Usage   : my $hseq = $hsp->hit_string;
 208  Function: Retrieves the hit sequence of this HSP as a string
 209  Returns : string
 210  Args    : [optional] string to set for hit sequence
 211
 212
 213 =cut
 214
 215
 216 =head2 homology_string
 217
 218  Title   : homology_string
 219  Usage   : my $homo_string = $hsp->homology_string;
 220  Function: Retrieves the homology sequence for this HSP as a string.
 221          : The homology sequence is the string of symbols in between the
 222          : query and hit sequences in the alignment indicating the degree
 223          : of conservation (e.g., identical, similar, not similar).
 224  Returns : string
 225  Args    : [optional] string to set for homology sequence
 226
 227 =cut
 228
 229 =head2 length
 230
 231  Title    : length
 232  Usage    : my $len = $hsp->length( ['query'|'hit'|'total'] );
 233  Function : Returns the length of the query or hit in the alignment
 234             (without gaps)
 235             or the aggregate length of the HSP (including gaps;
 236             this may be greater than either hit or query )
 237  Returns  : integer
 238  Args     : arg 1: 'query' = length of query seq (without gaps)
 239                    'hit'   = length of hit seq (without gaps)
 240                    'total' = length of alignment (with gaps)
 241                    default = 'total'
 242             arg 2: [optional] integer length value to set for specific type
 243
 244 =cut
 245
 246 =head2 percent_identity
 247
 248  Title   : percent_identity
 249  Usage   : my $percentid = $hsp->percent_identity()
 250  Function: Returns the calculated percent identity for an HSP
 251  Returns : floating point between 0 and 100
 252  Args    : none
 253
 254
 255 =cut
 256
 257
 258 =head2 frame
 259
 260  Title   : frame
 261  Usage   : $hsp->frame($queryframe,$subjectframe)
 262  Function: Set the Frame for both query and subject and insure that
 263            they agree.
 264            This overrides the frame() method implementation in
 265            FeaturePair.
 266  Returns : array of query and subjects if return type wants an array
 267            or query frame if defined or subject frame
 268  Args    : none
 269  Note    : Frames are stored in the GFF way (0-2) not 1-3
 270            as they are in BLAST (negative frames are deduced by checking
 271                                  the strand of the query or hit)
 272
 273 =cut
 274
 275
 276 =head2 get_aln
 277
 278  Title   : get_aln
 279  Usage   : my $aln = $hsp->gel_aln
 280  Function: Returns a Bio::SimpleAlign representing the HSP alignment
 281  Returns : Bio::SimpleAlign
 282  Args    : none
 283
 284 =cut
 285
 286 sub get_aln {
 287     my ($self) = shift;
 288     $self->warn("Innapropriate to build a Bio::SimpleAlign from a HMMER HSP object");
 289     return undef;
 290 }
 291
 292 =head2 num_conserved
 293
 294  Title   : num_conserved
 295  Usage   : $obj->num_conserved($newval)
 296  Function: returns the number of conserved residues in the alignment
 297  Returns : inetger
 298  Args    : integer (optional)
 299
 300
 301 =cut
 302
 303 =head2 num_identical
 304
 305  Title   : num_identical
 306  Usage   : $obj->num_identical($newval)
 307  Function: returns the number of identical residues in the alignment
 308  Returns : integer
 309  Args    : integer (optional)
 310
 311
 312 =cut
 313
 314 =head2 seq_inds
 315
 316  Title   : seq_inds
 317  Purpose   : Get a list of residue positions (indices) for all identical
 318            : or conserved residues in the query or sbjct sequence.
 319  Example   : @s_ind = $hsp->seq_inds('query', 'identical');
 320            : @h_ind = $hsp->seq_inds('hit', 'conserved');
 321            : @h_ind = $hsp->seq_inds('hit', 'conserved', 1);
 322  Returns   : List of integers
 323            : May include ranges if collapse is true.
 324  Argument  : seq_type  = 'query' or 'hit' or 'sbjct'  (default = query)
 325            :  ('sbjct' is synonymous with 'hit')
 326            : class     = 'identical' or 'conserved' or 'nomatch' or 'gap'
 327            :              (default = identical)
 328            :              (can be shortened to 'id' or 'cons')
 329            :
 330            : collapse  = boolean, if true, consecutive positions are merged
 331            :             using a range notation, e.g., "1 2 3 4 5 7 9 10 11"
 332            :             collapses to "1-5 7 9-11". This is useful for
 333            :             consolidating long lists. Default = no collapse.
 334  Throws    : n/a.
 335  Comments  :
 336
 337 See Also   : L<Bio::Search::BlastUtils::collapse_nums()|Bio::Search::BlastUtils>, L<Bio::Search::Hit::HitI::seq_inds()|Bio::Search::Hit::HitI>
 338
 339 =cut
 340
 341 =head2 Inherited from Bio::SeqFeature::SimilarityPair
 342
 343 These methods come from Bio::SeqFeature::SimilarityPair
 344
 345 =head2 query
 346
 347  Title   : query
 348  Usage   : my $query = $hsp->query
 349  Function: Returns a SeqFeature representing the query in the HSP
 350  Returns : Bio::SeqFeature::Similarity
 351  Args    : [optional] new value to set
 352
 353
 354 =head2 hit
 355
 356  Title   : hit
 357  Usage   : my $hit = $hsp->hit
 358  Function: Returns a SeqFeature representing the hit in the HSP
 359  Returns : Bio::SeqFeature::Similarity
 360  Args    : [optional] new value to set
 361
 362
 363 =head2 significance
 364
 365  Title   : significance
 366  Usage   : $evalue = $obj->significance();
 367            $obj->significance($evalue);
 368  Function: Get/Set the significance value
 369  Returns : numeric
 370  Args    : [optional] new value to set
 371
 372
 373 =head2 score
 374
 375  Title   : score
 376  Usage   : my $score = $hsp->score();
 377  Function: Returns the score for this HSP or undef
 378  Returns : numeric
 379  Args    : [optional] numeric to set value
 380
 381 =cut
 382
 383 =head2 bits
 384
 385  Title   : bits
 386  Usage   : my $bits = $hsp->bits();
 387  Function: Returns the bit value for this HSP or undef
 388  Returns : numeric
 389  Args    : none
 390
 391 =cut
 392
 393
 394 1;