Bio/Search/HSP/HMMERHSP.pm

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