NAME

Bio::Search::HSP::BlastHSP - Bioperl BLAST High-Scoring Pair object

SYNOPSIS

DESCRIPTION

A Bio::Search::HSP::BlastHSP object provides an interface to data obtained in a single alignment section of a Blast report (known as a "High-scoring Segment Pair"). This is essentially a pairwise alignment with score information.

BlastHSP objects are accessed via Bio::Search::Hit::BlastHit objects after parsing a BLAST report using the Bio::SearchIO system.

The construction of BlastHSP objects is performed by Bio::Factory::BlastHitFactory in a process that is orchestrated by the Blast parser (Bio::SearchIO::psiblast). The resulting BlastHSPs are then accessed via Bio::Search::Hit::BlastHit). Therefore, you do not need to use Bio::Search::HSP::BlastHSP) directly. If you need to construct BlastHSPs directly, see the new() function for details.

For Bio::SearchIO BLAST parsing usage examples, see the examples/search-blast directory of the Bioperl distribution.

Start and End coordinates

Sequence endpoints are swapped so that start is always less than end. This affects For TBLASTN/X hits on the minus strand. Strand information can be recovered using the strand() method. This normalization step is standard Bioperl practice. It also facilitates use of range information by methods such as match().

Supports BLAST versions 1.x and 2.x, gapped and ungapped.

Bio::Search::HSP::BlastHSP.pm has the ability to extract a list of all residue indices for identical and conservative matches along both query and sbjct sequences. Since this degree of detail is not always needed, this behavior does not occur during construction of the BlastHSP object. These data will automatically be collected as necessary as the BlastHSP.pm object is used.

DEPENDENCIES

Bio::Search::HSP::BlastHSP.pm is a concrete class that inherits from Bio::SeqFeature::SimilarityPair and Bio::Search::HSP::HSPI. Bio::Seq and Bio::SimpleAlign are employed for creating sequence and alignment objects, respectively.

Relationship to SimpleAlign.pm & Seq.pm

BlastHSP.pm can provide the query or sbjct sequence as a Bio::Seq object via the seq() method. The BlastHSP.pm object can also create a two-sequence Bio::SimpleAlign alignment object using the the query and sbjct sequences via the get_aln() method. Creation of alignment objects is not automatic when constructing the BlastHSP.pm object since this level of functionality is not always required and would generate a lot of extra overhead when crunching many reports.

FEEDBACK

Mailing Lists

User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to one of the Bioperl mailing lists. Your participation is much appreciated.

bioperl-l@bioperl.org               - General discussion
http://bio.perl.org/MailList.html   - About the mailing lists

Reporting Bugs

Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their resolution. Bug reports can be submitted via email or the web:

bioperl-bugs@bio.perl.org                   
http://bugzilla.bioperl.org/

AUTHOR

Steve Chervitz <sac@bioperl.org>

See the FEEDBACK section for where to send bug reports and comments.

ACKNOWLEDGEMENTS

This software was originally developed in the Department of Genetics at Stanford University. I would also like to acknowledge my colleagues at Affymetrix for useful feedback.

COPYRIGHT

DISCLAIMER

This software is provided "as is" without warranty of any kind.

APPENDIX

The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _

new

Usage     : $hsp = Bio::Search::HSP::BlastHSP->new( %named_params );
          : Bio::Search::HSP::BlastHSP objects are constructed 
          : automatically by Bio::SearchIO::BlastHitFactory, 
          : so there is no need for direct instantiation.
Purpose   : Constructs a new BlastHSP object and Initializes key variables 
          : for the HSP.
Returns   : A Bio::Search::HSP::BlastHSP object
Argument  : Named parameters:
          : Parameter keys are case-insensitive.
          :      -RAW_DATA  => array ref containing raw BLAST report data for 
          :                    for a single HSP. This includes all lines 
          :                    of the HSP alignment from a traditional BLAST
                               or PSI-BLAST (non-XML) report,
          :      -RANK         => integer (1..n).
          :      -PROGRAM      => string ('TBLASTN', 'BLASTP', etc.).
          :      -QUERY_NAME   => string, id of query sequence
          :      -HIT_NAME     => string, id of hit sequence
          :
Comments  : Having the raw data allows this object to do lazy parsing of 
          : the raw HSP data (i.e., not parsed until needed).
          :
          : Note that there is a fair amount of basic parsing that is
          : currently performed in this module that would be more appropriate
          : to do within a separate factory object.
          : This parsing code will likely be relocated and more initialization
          : parameters will be added to new().
          :
See Also   : B<Bio::SeqFeature::SimilarityPair::new()>, B<Bio::SeqFeature::Similarity::new()>

algorithm

Title   : algorithm
Usage   : $alg = $hsp->algorithm();
Function: Gets the algorithm specification that was used to obtain the hsp
          For BLAST, the algorithm denotes what type of sequence was aligned 
          against what (BLASTN: dna-dna, BLASTP prt-prt, BLASTX translated 
          dna-prt, TBLASTN prt-translated dna, TBLASTX translated 
          dna-translated dna).
Returns : a scalar string 
Args    : none

signif()

Usage     : $hsp_obj->signif()
Purpose   : Get the P-value or Expect value for the HSP.
Returns   : Float (0.001 or 1.3e-43)
          : Returns P-value if it is defined, otherwise, Expect value.
Argument  : n/a
Throws    : n/a
Comments  : Provided for consistency with BlastHit::signif()
          : Support for returning the significance data in different
          : formats (e.g., exponent only), is not provided for HSP objects.
          : This is only available for the BlastHit or Blast object.

evalue

Usage     : $hsp_obj->evalue()
Purpose   : Get the Expect value for the HSP.
Returns   : Float (0.001 or 1.3e-43)
Argument  : n/a
Throws    : n/a
Comments  : Support for returning the expectation data in different
          : formats (e.g., exponent only), is not provided for HSP objects.
          : This is only available for the BlastHit or Blast object.

p

Usage     : $hsp_obj->p()
Purpose   : Get the P-value for the HSP.
Returns   : Float (0.001 or 1.3e-43) or undef if not defined.
Argument  : n/a
Throws    : n/a
Comments  : P-value is not defined with NCBI Blast2 reports.
          : Support for returning the expectation data in different
          : formats (e.g., exponent only) is not provided for HSP objects.
          : This is only available for the BlastHit or Blast object.

length

Usage     : $hsp->length( [seq_type] )
Purpose   : Get the length of the aligned portion of the query or sbjct.
Example   : $hsp->length('query')
Returns   : integer
Argument  : seq_type: 'query' | 'hit' or 'sbjct' | 'total'  (default = 'total')
            ('sbjct' is synonymous with 'hit')
Throws    : n/a
Comments  : 'total' length is the full length of the alignment
          : as reported in the denominators in the alignment section: 
          : "Identical = 34/120 Positives = 67/120".

gaps

Usage     : $hsp->gaps( [seq_type] )
Purpose   : Get the number of gaps in the query, sbjct, or total alignment.
          : Also can return query gaps and sbjct gaps as a two-element list
          : when in array context.
Example   : $total_gaps      = $hsp->gaps();
          : ($qgaps, $sgaps) = $hsp->gaps();
          : $qgaps           = $hsp->gaps('query');
Returns   : scalar context: integer
          : array context without args: (int, int) = ('queryGaps', 'sbjctGaps')
Argument  : seq_type: 'query' or 'hit' or 'sbjct' or 'total'  
          :  ('sbjct' is synonymous with 'hit')
          : (default = 'total', scalar context)
          : Array context can be "induced" by providing an argument of 'list' or 'array'.
Throws    : n/a

frac_identical

Usage     : $hsp_object->frac_identical( [seq_type] );
Purpose   : Get the fraction of identical positions within the given HSP.
Example   : $frac_iden = $hsp_object->frac_identical('query');
Returns   : Float (2-decimal precision, e.g., 0.75).
Argument  : seq_type: 'query' or 'hit' or 'sbjct' or 'total'
          :  ('sbjct' is synonymous with 'hit') 
          : default = 'total' (but see comments below).
Throws    : n/a
Comments  : Different versions of Blast report different values for the total
          : length of the alignment. This is the number reported in the
          : denominators in the stats section:
          : "Identical = 34/120 Positives = 67/120".
          : NCBI-BLAST uses the total length of the alignment (with gaps)
          : WU-BLAST uses the length of the query sequence (without gaps).
          : Therefore, when called without an argument or an argument of 'total',
          : this method will report different values depending on the
          : version of BLAST used.
          : 
          : To get the fraction identical among only the aligned residues,
          : ignoring the gaps, call this method with an argument of 'query'
          : or 'sbjct' ('sbjct' is synonymous with 'hit').

frac_conserved

 Usage     : $hsp_object->frac_conserved( [seq_type] );
 Purpose   : Get the fraction of conserved positions within the given HSP.
           : (Note: 'conservative' positions are called 'positives' in the
	   : Blast report.)
 Example   : $frac_cons = $hsp_object->frac_conserved('query');
 Returns   : Float (2-decimal precision, e.g., 0.75).
 Argument  : seq_type: 'query' or 'hit' or 'sbjct' or 'total'
           :  ('sbjct' is synonymous with 'hit') 
           : default = 'total' (but see comments below).
 Throws    : n/a
 Comments  : Different versions of Blast report different values for the total
           : length of the alignment. This is the number reported in the
           : denominators in the stats section:
           : "Identical = 34/120 Positives = 67/120".
           : NCBI-BLAST uses the total length of the alignment (with gaps)
           : WU-BLAST uses the length of the query sequence (without gaps).
           : Therefore, when called without an argument or an argument of 'total',
           : this method will report different values depending on the
           : version of BLAST used.
           :
           : To get the fraction conserved among only the aligned residues,
           : ignoring the gaps, call this method with an argument of 'query'
           : or 'sbjct'.

query_string

Title   : query_string
Usage   : my $qseq = $hsp->query_string;
Function: Retrieves the query sequence of this HSP as a string
Returns : string
Args    : none

hit_string

Title   : hit_string
Usage   : my $hseq = $hsp->hit_string;
Function: Retrieves the hit sequence of this HSP as a string
Returns : string
Args    : none

homology_string

Title   : homology_string
Usage   : my $homo_string = $hsp->homology_string;
Function: Retrieves the homology sequence for this HSP as a string.
        : The homology sequence is the string of symbols in between the 
        : query and hit sequences in the alignment indicating the degree
        : of conservation (e.g., identical, similar, not similar).
Returns : string
Args    : none

expect

See Bio::Search::HSP::HSPI::expect()

rank

Usage     : $hsp->rank( [string] );
Purpose   : Get the rank of the HSP within a given Blast hit.
Example   : $rank = $hsp->rank;
Returns   : Integer (1..n) corresponding to the order in which the HSP
            appears in the BLAST report.

to_string

Title   : to_string
Usage   : print $hsp->to_string;
Function: Returns a string representation for the Blast HSP.
          Primarily intended for debugging purposes.
Example : see usage
Returns : A string of the form:
          [BlastHSP] <rank>
          e.g.:
          [BlastHit] 1
Args    : None

n

Usage     : $hsp_obj->n()
Purpose   : Get the N value (num HSPs on which P/Expect is based).
          : This value is not defined with NCBI Blast2 with gapping.
Returns   : Integer or null string if not defined.
Argument  : n/a
Throws    : n/a
Comments  : The 'N' value is listed in parenthesis with P/Expect value:
          : e.g., P(3) = 1.2e-30  ---> (N = 3).
          : Not defined in NCBI Blast2 with gaps.
          : This typically is equal to the number of HSPs but not always.
          : To obtain the number of HSPs, use Bio::Search::Hit::BlastHit::num_hsps().

matches

 Usage     : $hsp->matches([seq_type], [start], [stop]);
 Purpose   : Get the total number of identical and conservative matches 
           : in the query or sbjct sequence for the given HSP. Optionally can
           : report data within a defined interval along the seq.
           : (Note: 'conservative' matches are called 'positives' in the
	   : Blast report.)
 Example   : ($id,$cons) = $hsp_object->matches('hit');
           : ($id,$cons) = $hsp_object->matches('query',300,400);
 Returns   : 2-element array of integers 
 Argument  : (1) seq_type = 'query' or 'hit' or 'sbjct' (default = query)
           :  ('sbjct' is synonymous with 'hit') 
           : (2) start = Starting coordinate (optional)
           : (3) stop  = Ending coordinate (optional)
 Throws    : Exception if the supplied coordinates are out of range.
 Comments  : Relies on seq_str('match') to get the string of alignment symbols
           : between the query and sbjct lines which are used for determining
           : the number of identical and conservative matches.

num_identical

Usage     : $hsp_object->num_identical();
Purpose   : Get the number of identical positions within the given HSP.
Example   : $num_iden = $hsp_object->num_identical();
Returns   : integer
Argument  : n/a
Throws    : n/a

num_conserved

Usage     : $hsp_object->num_conserved();
Purpose   : Get the number of conserved positions within the given HSP.
Example   : $num_iden = $hsp_object->num_conserved();
Returns   : integer
Argument  : n/a
Throws    : n/a

range

Usage     : $hsp->range( [seq_type] );
Purpose   : Gets the (start, end) coordinates for the query or sbjct sequence
          : in the HSP alignment.
Example   : ($query_beg, $query_end) = $hsp->range('query');
          : ($hit_beg, $hit_end) = $hsp->range('hit');
Returns   : Two-element array of integers 
Argument  : seq_type = string, 'query' or 'hit' or 'sbjct'  (default = 'query')
          :  ('sbjct' is synonymous with 'hit') 
Throws    : n/a

start

Usage     : $hsp->start( [seq_type] );
Purpose   : Gets the start coordinate for the query, sbjct, or both sequences
          : in the HSP alignment.
          : NOTE: Start will always be less than end. 
          : To determine strand, use $hsp->strand()
Example   : $query_beg = $hsp->start('query');
          : $hit_beg = $hsp->start('hit');
          : ($query_beg, $hit_beg) = $hsp->start();
Returns   : scalar context: integer
          : array context without args: list of two integers
Argument  : In scalar context: seq_type = 'query' or 'hit' or 'sbjct' (default= 'query')
          :  ('sbjct' is synonymous with 'hit') 
          : Array context can be "induced" by providing an argument of 'list' or 'array'.
Throws    : n/a

end

Usage     : $hsp->end( [seq_type] );
Purpose   : Gets the end coordinate for the query, sbjct, or both sequences
          : in the HSP alignment.
          : NOTE: Start will always be less than end. 
          : To determine strand, use $hsp->strand()
Example   : $query_end = $hsp->end('query');
          : $hit_end = $hsp->end('hit');
          : ($query_end, $hit_end) = $hsp->end();
Returns   : scalar context: integer
          : array context without args: list of two integers
Argument  : In scalar context: seq_type = 'query' or 'hit' or 'sbjct' (default= 'query')
          :  ('sbjct' is synonymous with 'hit') 
          : Array context can be "induced" by providing an argument of 'list' or 'array'.
Throws    : n/a

strand

Usage     : $hsp_object->strand( [seq_type] )
Purpose   : Get the strand of the query or sbjct sequence.
Example   : print $hsp->strand('query');
          : ($query_strand, $hit_strand) = $hsp->strand();
Returns   : -1, 0, or 1
          : -1 = Minus strand, +1 = Plus strand
          : Returns 0 if strand is not defined, which occurs
          : for BLASTP reports, and the query of TBLASTN
          : as well as the hit if BLASTX reports.
          : In scalar context without arguments, returns queryStrand value.
          : In array context without arguments, returns a two-element list 
          :    of strings (queryStrand, sbjctStrand).
          : Array context can be "induced" by providing an argument of 'list' or 'array'.
Argument  : seq_type: 'query' or 'hit' or 'sbjct' or undef
          :  ('sbjct' is synonymous with 'hit') 
Throws    : n/a

See Also : _set_seq(), _set_match_stats()

seq

Usage     : $hsp->seq( [seq_type] );
Purpose   : Get the query or sbjct sequence as a Bio::Seq.pm object.
Example   : $seqObj = $hsp->seq('query');
Returns   : Object reference for a Bio::Seq.pm object.
Argument  : seq_type = 'query' or 'hit' or 'sbjct' (default = 'query').
          :  ('sbjct' is synonymous with 'hit') 
Throws    : Propagates any exception that occurs during construction
          : of the Bio::Seq.pm object.
Comments  : The sequence is returned in an array of strings corresponding
          : to the strings in the original format of the Blast alignment.
          : (i.e., same spacing).

See Also : seq_str(), seq_inds(), Bio::Seq

seq_str

Usage     : $hsp->seq_str( seq_type );
Purpose   : Get the full query, sbjct, or 'match' sequence as a string.
          : The 'match' sequence is the string of symbols in between the 
          : query and sbjct sequences.
Example   : $str = $hsp->seq_str('query');
Returns   : String
Argument  : seq_Type = 'query' or 'hit' or 'sbjct' or 'match'
          :  ('sbjct' is synonymous with 'hit') 
Throws    : Exception if the argument does not match an accepted seq_type.
Comments  : Calls _set_seq_data() to set the 'match' sequence if it has
          : not been set already.

See Also : seq(), seq_inds(), _set_match_seq()

seq_inds

Usage     : $hsp->seq_inds( seq_type, class, collapse );
Purpose   : Get a list of residue positions (indices) for all identical 
          : or conserved residues in the query or sbjct sequence.
Example   : @s_ind = $hsp->seq_inds('query', 'identical');
          : @h_ind = $hsp->seq_inds('hit', 'conserved');
          : @h_ind = $hsp->seq_inds('hit', 'conserved', 1);
Returns   : List of integers 
          : May include ranges if collapse is true.
Argument  : seq_type  = 'query' or 'hit' or 'sbjct'  (default = query)
          :  ('sbjct' is synonymous with 'hit') 
          : class     = 'identical' or 'conserved' (default = identical)
          :              (can be shortened to 'id' or 'cons')
          :              (actually, anything not 'id' will evaluate to 'conserved').
          : collapse  = boolean, if true, consecutive positions are merged
          :             using a range notation, e.g., "1 2 3 4 5 7 9 10 11" 
          :             collapses to "1-5 7 9-11". This is useful for 
          :             consolidating long lists. Default = no collapse.
Throws    : n/a.
Comments  : Calls _set_residues() to set the 'match' sequence if it has
          : not been set already.

See Also : seq(), _set_residues(), Bio::Search::BlastUtils::collapse_nums(), Bio::Search::Hit::BlastHit::seq_inds()

get_aln

Usage     : $hsp->get_aln()
Purpose   : Get a Bio::SimpleAlign object constructed from the query + sbjct 
          : sequences of the present HSP object.
Example   : $aln_obj = $hsp->get_aln();
Returns   : Object reference for a Bio::SimpleAlign.pm object.
Argument  : n/a.
Throws    : Propagates any exception ocurring during the construction of
          : the Bio::SimpleAlign object.
Comments  : Requires Bio::SimpleAlign.
          : The Bio::SimpleAlign object is constructed from the query + sbjct 
          : sequence objects obtained by calling seq().
          : Gap residues are included (see $GAP_SYMBOL).

FOR DEVELOPERS ONLY

Data Members

Information about the various data members of this module is provided for those wishing to modify or understand the code. Two things to bear in mind:

1 Do NOT rely on these in any code outside of this module.: All data members are prefixed with an underscore to signify that they are private. Always use accessor methods. If the accessor doesn't exist or is inadequate, create or modify an accessor (and let me know, too!).
2 This documentation may be incomplete and out of date.: It is easy for these data member descriptions to become obsolete as this module is still evolving. Always double check this info and search for members not described here.

An instance of Bio::Search::HSP::BlastHSP.pm is a blessed reference to a hash containing all or some of the following fields:

FIELD           VALUE
--------------------------------------------------------------
(member names are mostly self-explanatory)

_score              :
_bits               :
_p                  :
_n                  : Integer. The 'N' value listed in parenthesis with P/Expect value:
                    : e.g., P(3) = 1.2e-30  ---> (N = 3).
                    : Not defined in NCBI Blast2 with gaps.
                    : To obtain the number of HSPs, use Bio::Search::Hit::BlastHit::num_hsps().
_expect             :
_queryLength        : 
_queryGaps          : 
_queryStart         :
_queryStop          :
_querySeq           :
_sbjctLength        :
_sbjctGaps          :
_sbjctStart         :
_sbjctStop          :
_sbjctSeq           :
_matchSeq           : String. Contains the symbols between the query and sbjct lines
                      which indicate identical (letter) and conserved ('+') matches
                      or a mismatch (' ').
_numIdentical       :
_numConserved       :
_identicalRes_query :
_identicalRes_sbjct :
_conservedRes_query :
_conservedRes_sbjct :
_match_indent       : The number of leading space characters on each line containing
                      the match symbols. _match_indent is 13 in this example:
                        Query:   285 QNSAPWGLARISHRERLNLGSFNKYLYDDDAG
                                     Q +APWGLARIS       G+ + Y YD+ AG
                        ^^^^^^^^^^^^^

To install Bio::Seq, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Bio::Seq

CPAN shell

perl -MCPAN -e shell
install Bio::Seq

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)