Bio::S...lastHit(3pm)

📦
version 1.7.8 · 3 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

🌸 Bio::S...lastHit(3pm) — User Contributed Perl Documentation 🌸

okay bestie, buckle up, this is Bio::S...lastHit(3pm) from the User Contributed Perl Documentation and it's a whole personality 💖

✨ NAME ✨

Bio::Search::Hit::PsiBlastHit — the Bioperl BLAST Hit object 🧬👑

✨ SYNOPSIS ✨

go peek at Bio::Search::Result::BlastResult, that's where the real tea is 💅

✨ DESCRIPTION ✨

The Bio::Search::Hit::PsiBlastHit.pm module is literally the whole package for data and methods that let you mess with "hits" from a BLAST report. A BLAST hit is just a collection of HSPs plus some other metadata like the sequence name and score info. And how do you even get your hands on Hit objects? You access them through Bio::Search::Result::BlastResult objects after you've parsed a BLAST report using the Bio::SearchIO system. that's the pipeline, no cap ✨

In Blast lingo, the "sbjct" sequences are all the sequences in a target database that got compared against a "query" sequence. The terms "sbjct" and "hit" are used interchangeably in this module — they're the same thing, besties. And the way that every method taking 'sbjct' as an argument also supports 'hit' as a synonym? iconic 🫶

This module supports BLAST versions 1.x and 2.x, gapped and ungapped, and PSI-BLAST. versatility queen 👑

The construction of PsiBlastHit objects is performed by Bio::SearchIO::blast::PsiBlastHitFactory in a process that is orchestrated by the Blast parser (Bio::SearchIO::blast). The resulting PsiBlastHits are then accessed via Bio::Search::Result::BlastResult. So like... you do not need to use Bio::Search::Hit::PsiBlastHit directly, it just happens for you 💅 If you do need to construct PsiBlastHits directly, see the "new()" function for details.

For Bio::SearchIO BLAST parsing usage examples, go check the "examples/search-blast" directory of the Bioperl distribution 📂

🦋 HSP Tiling and Ambiguous Alignments 🦋

If a Blast hit has more than one HSP, the Bio::Search::Hit::PsiBlastHit.pm object has the ability to merge overlapping HSPs into contiguous blocks. This is lowkey genius because it lets the PsiBlastHit object sum data across all HSPs without counting data in the overlapping regions multiple times — which is what would happen if you just summed data from each overlapping HSP like a fool. HSP tiling is performed automatically when methods of the PsiBlastHit object that rely on tiled data are invoked. Those include frac_identical(), frac_conserved(), gaps(), frac_aligned_query(), frac_aligned_hit(), num_unaligned_query(), num_unaligned_hit(). all the tiled-data girlies 🎀

It also permits the assessment of an "ambiguous alignment" if the query (or sbjct) sequences from different HSPs overlap (see ambiguous_aln()). The existence of an overlap could indicate a biologically interesting region in the sequence, such as a repeated domain 👀 The PsiBlastHit object uses the -OVERLAP parameter to determine when two sequences overlap; if this is set to 2 — the default — then any two sbjct or query HSP sequences must overlap by more than two residues to get merged into the same contig and counted as an overlap. See the BUGS section below for "issues" with HSP tiling 💀

The results of the HSP tiling is reported with the following ambiguity codes:

'q' = Query sequence contains multiple sub-sequences matching
      a single region in the sbjct sequence.

's' = Subject (PsiBlastHit) sequence contains multiple sub-sequences matching
      a single region in the query sequence.

'qs' = Both query and sbjct sequences contain more than one
       sub-sequence with similarity to the other sequence.

For addition information about ambiguous BLAST alignments, see Bio::Search::BlastUtils::tile_hsps() 🔍

✨ DEPENDENCIES ✨

Bio::Search::Hit::PsiBlastHit.pm is a concrete class that inherits from Bio::Root::Root and Bio::Search::Hit::HitI, and relies on Bio::Search::HSP::BlastHSP. family tree moment 🌳

✨ BUGS ✨

One consequence of the HSP tiling is that methods that rely on HSP tiling such as frac_identical(), frac_conserved(), gaps() etc. may report misleading numbers when -OVERLAP is set to a large number. ⚠️

For example, say we have two HSPs and the query sequence tile as follows:

                1      8             22      30        40             60
 Full seq:  ------------------------------------------------------------
                        *  ** *   **
 HSP1:             ---------------                    (6 identical matches)
                                  **   **  **
 HSP2:                        -------------           (6 identical matches)

If -OVERLAP is set to some number over 4, HSP1 and HSP2 will not be tiled into a single contig and their numbers of identical matches will be added, giving a total of 12, not 10 if they had be combined into one contig. This can lead to number greater than 1.0 for methods frac_identical() and frac_conserved(). This is less of an issue with gapped Blast since it tends to combine HSPs that would be listed separately without gapping. (Fractions >1.0 can be viewed as a signal for an interesting alignment that warrants further inspection, thus turning this bug into a feature :-). 😭✨

Using large values for -OVERLAP can lead to incorrect numbers reported by methods that rely on HSP tiling but can be useful if you care more about detecting ambiguous alignments. Setting -OVERLAP to zero will lead to the most accurate numbers for the tiling-dependent methods but will be useless for detecting overlapping HSPs since all HSPs will appear to overlap. pick your struggle, bestie 💅

✨ SEE ALSO ✨

  • Bio::Search::HSP::BlastHSP.pm — Blast HSP object.
  • Bio::Search::Result::BlastResult.pm — Blast Result object.
  • Bio::Search::Hit::HitI.pm — Interface implemented by PsiBlastHit.pm
  • Bio::Root::Root.pm — Base class for PsiBlastHit.pm

Links 🔗:

http://bio.perl.org/                       - Bioperl Project Homepage

✨ 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://bioperl.org/wiki/Mailing_lists  - About the mailing lists

🫂 Support 🫂

Please direct usage questions or support issues to the mailing list:

bioperl-l@bioperl.org

rather than to the module maintainer directly. Many experienced and reponsive experts will be able look at the problem and quickly address it. Please include a thorough description of the problem with code and data examples if at all possible 🙏

🐛 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 the web:

https://github.com/bioperl/bioperl-live/issues

✨ 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 (c) 1996-2001 Steve Chervitz. All Rights Reserved.

✨ 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     : $hit = Bio::Search::Hit::PsiBlastHit->new( %named_params );
          : Bio::Search::Hit::PsiBlastHit.pm objects are constructed
          : automatically by Bio::SearchIO::PsiBlastHitFactory.pm,
          : so there is no need for direct instantiation.
Purpose   : Constructs a new PsiBlastHit object and Initializes key variables
          : for the hit.
Returns   : A Bio::Search::Hit::PsiBlastHit object
Argument  : Named Parameters:
          : Parameter keys are case-insensitive.
          :     -RAW_DATA   => array reference holding raw BLAST report data
          :                    for a single hit. This includes all lines
          :                    within the HSP alignment listing section of a
          :                    traditional BLAST or PSI-BLAST (non-XML) report,
          :                    starting at (or just after) the leading '>'.
          :         -HOLD_RAW_DATA => boolean, should -RAW_DATA be saved within the object.
          :         -QUERY_LEN  => Length of the query sequence
          :         -ITERATION  => integer (PSI-BLAST iteration number in which hit was found)
          :         -OVERLAP    => integer (maximum overlap between adjacent
          :                    HSPs when tiling)
          :         -PROGRAM    => string (type of Blast: BLASTP, BLASTN, etc)
          :         -SIGNIF     => significance
          :         -IS_PVAL    => boolean, true if -SIGNIF contains a P-value
          :         -SCORE      => raw BLAST score
          :         -FOUND_AGAIN   => boolean, true if this was a hit from the
          :                       section of a PSI-BLAST with iteration > 1
          :                       containing sequences that were also found
          :                       in iteration 1.
Comments  : This object accepts raw Blast report data not because it
          : is required for parsing, but in order to retrieve it
          : (only available if -HOLD_RAW_DATA is set to true).

so real quick on those named params — here's the breakdown bestie, key by key, and yes the keys are case-insensitive 💅

  • -RAW_DATA — array reference holding raw BLAST report data for a single hit. This includes all lines within the HSP alignment listing section of a traditional BLAST or PSI-BLAST (non-XML) report, starting at (or just after) the leading '>'.
  • -HOLD_RAW_DATA — boolean, should -RAW_DATA be saved within the object.
  • -QUERY_LEN — Length of the query sequence
  • -ITERATION — integer (PSI-BLAST iteration number in which hit was found)
  • -OVERLAP — integer (maximum overlap between adjacent HSPs when tiling)
  • -PROGRAM — string (type of Blast: BLASTP, BLASTN, etc)
  • -SIGNIF — significance
  • -IS_PVAL — boolean, true if -SIGNIF contains a P-value
  • -SCORE — raw BLAST score
  • -FOUND_AGAIN — boolean, true if this was a hit from the section of a PSI-BLAST with iteration > 1 containing sequences that were also found in iteration 1.

Comments: This object accepts raw Blast report data not because it is required for parsing, but in order to retrieve it (only available if -HOLD_RAW_DATA is set to true). sneaky but useful 🍓

See Also: Bio::Search::BlastUtils::tile_hsps(), Bio::Root::Root::new()

🧚 algorithm 🧚

Title   : algorithm
Usage   : $alg = $hit->algorithm();
Function: Gets the algorithm specification that was used to obtain the hit
          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

tl;dr it tells you what kind of sequence got aligned against what — dna-dna, prt-prt, translated dna-prt, prt-translated dna, translated dna-translated dna 👑 Returns a scalar string, takes no args, zero drama.

🧚 name 🧚

Usage     : $hit->name([string]);
Purpose   : Set/Get a string to identify the hit.
Example   : $name = $hit->name;
          : $hit->name('M81707');
Returns   : String consisting of the hit's name or undef if not set.
Comments  : The name is parsed out of the "Query=" line as the first chunk of
            non-whitespace text. If you want the rest of the line, use
            $hit->description().

See Also: accession()

🧚 description 🧚

Usage     : $hit_object->description( [integer] );
Purpose   : Set/Get a description string for the hit.
            This is parsed out of the "Query=" line as everything after
            the first chunk of non-whitespace text. Use $hit->name()
            to get the first chunk (the ID of the sequence).
Example   : $description = $hit->description;
          : $desc_60char = $hit->description(60);
Argument  : Integer (optional) indicating the desired length of the
          : description string to be returned.
Returns   : String consisting of the hit's description or undef if not set.

accession

  • Title — accession
  • Usage — $acc = $hit->accession();
  • Function — grab the accession for the hit, if it's even there 💅
  • Returns — a scalar string (and yes bestie, an empty string if it's not set — not undef, an empty string)
  • Args — none
  • Comments — so here's the tea ☕ the accession numbers get extracted on the assumption that they're delimited by | characters (that's the NCBI-style vibe). If your data is not doing that, don't come for this method — use name() instead and parse it yourself however you need.
  • See Also — name()

raw_score

  • Usage — $hit_object->raw_score();
  • Purpose — gets the BLAST score of the best HSP for the current Blast hit 🔥
  • Example — $score = $hit_object->raw_score();
  • Returns — Integer
  • Argument — n/a
  • Throws — n/a
  • See Also — bits()

length

  • Usage — $hit_object->length();
  • Purpose — get the total length of the hit sequence 🦋
  • Example — $len = $hit_object->length();
  • Returns — Integer
  • Argument — n/a
  • Throws — n/a
  • Comments — dev note, bestie, listen up: when you're using the built-in length function inside this module, you gotta call it as CORE::length(). no cap.
  • See Also — logical_length(), length_aln()

significance

Equivalent to signif(). that's it, that's the whole method 🫶

next_hsp

  • Title — next_hsp
  • Usage — $hsp = $obj->next_hsp();
  • Function — returns the next available High Scoring Pair object ✨
  • Example — (none given, it's giving mystery 🙈)
  • Returns — Bio::Search::HSP::BlastHSP or undef if finished
  • Args — none

score

Equivalent to raw_score(). same energy, different name 💖

hit_length

Equivalent to length(). twins fr fr 👑

signif

  • Usage — $hit_object->signif( [format] );
  • Purpose — get the P or Expect value for the best HSP of the given BLAST hit. The value you get back is the one reported in the description section of the Blast report. For Blast1 and WU-Blast2 this is a P-value, and for Blast2 it's an Expect value.
  • Example —
$obj->signif()        # returns 1.3e-34
$obj->signif('exp')   # returns -34
$obj->signif('parts') # returns (1.3, -34)
  • Returns — Float or scientific notation number (the raw P/Expect value, DEFAULT). Integer if format == 'exp' (the magnitude of the base 10 exponent). 2-element list (float, int) if format == 'parts' and the P/Expect value is in scientific notation (see Comments).
  • Argument — format: string of 'raw' | 'exp' | 'parts'
    • 'raw' returns value given in report. Default. (1.2e-34)
    • 'exp' returns exponent value only (34)
    • 'parts' returns the decimal and exponent as a 2-element list (1.2, -34) (see Comments).
  • Throws — n/a
  • Comments — okay so the whole point of signif() is that Blast1 and Blast2 formats (and WU- vs. NCBI-BLAST) do not agree on what gets reported in the description lines of each hit in the Blast report 😭 and signif() saves any client code from having to know whether it's a P-value or an Expect value, which makes it way easier to write code that can process both Blast1 and Blast2 reports. That said, this is not necessarily a good thing, since one should always know when one is working with P-values or Expect values — hence the deprecated status 💀. Use of expect() is recommended since all hits will have an Expect value.

Also: using the 'parts' argument is not recommended, because it will not work as expected if the expect value is not in scientific notation. Like, floats are not converted into sci notation before splitting into parts. periodt.

  • See Also — p(), expect(), Bio::Search::BlastUtils::get_exponent()

to_string

  • Title — to_string
  • Usage — print $hit->to_string;
  • Function — returns a string representation for the Blast Hit. Primarily intended for debugging purposes 🐛
  • Example — see usage
  • Returns — a string of the form:
[PsiBlastHit] <name> <description>

e.g.:

[PsiBlastHit] emb|Z46660|SC9725 S.cerevisiae chromosome XIII cosmid
  • Args — None

ambiguous_aln

  • Usage — $ambig_code = $hit_object->ambiguous_aln();
  • Purpose — sets/gets the ambiguity code data member 🧚
  • Example — (see usage)
  • Returns — String = 'q', 's', 'qs', '-'
    • 'q' = query sequence contains overlapping sub-sequences while sbjct does not.
    • 's' = sbjct sequence contains overlapping sub-sequences while query does not.
    • 'qs' = query and sbjct sequence contains overlapping sub-sequences relative to each other.
    • '-' = query and sbjct sequence do not contains multiple domains relative to each other OR both contain the same distribution of similar domains.
  • Argument — n/a
  • Throws — n/a
  • Status — Experimental
  • See Also — Bio::Search::BlastUtils::tile_hsps, "HSP Tiling and Ambiguous Alignments"

overlap

  • Usage — $blast_object->overlap( [integer] );
  • Purpose — gets/sets the allowable amount of overlap between different HSP sequences 🌸
  • Example —
$blast_object->overlap(5);
$overlap = $blast_object->overlap;
  • Returns — Integer.
  • Argument — integer.
  • Throws — n/a
  • Status — Experimental
  • Comments — any two HSPs whose sequences overlap by less than or equal to the overlap() number of resides will be considered separate HSPs and will not get tiled by Bio::Search::BlastUtils::_adjust_contigs().
  • See Also — Bio::Search::BlastUtils::_adjust_contigs(), BUGS

bits

  • Usage — $hit_object->bits();
  • Purpose — gets the BLAST bit score of the best HSP for the current Blast hit ⭐
  • Example — $bits = $hit_object->bits();
  • Returns — Integer
  • Argument — n/a
  • Throws — Exception if bit score is not set. 🚨
  • Comments — for BLAST1, the non-bit score is listed in the summary line.
  • See Also — score()

n

  • Usage — $hit_object->n();
  • Purpose — gets the N number for the current Blast hit. This is the number of HSPs in the set which was ascribed the lowest P-value (listed on the description line). And no bestie, this number is not the same as the total number of HSPs — to get the total number of HSPs, use num_hsps() 💅
  • Example — $n = $hit_object->n();
  • Returns — Integer
  • Argument — n/a
  • Throws — Exception if HSPs have not been set (BLAST2 reports). 😭
  • Comments — heads up: the N parameter is not reported in gapped BLAST2. Calling n() on such reports will result in a call to num_hsps(). The num_hsps() method will count the actual number of HSPs in the alignment listing, which may exceed N in some cases. iykyk
  • See Also — num_hsps()

frame

  • Usage — $hit_object->frame();
  • Purpose — gets the reading frame for the best HSP after HSP tiling. This is only valid for BLASTX and TBLASTN/X reports 👑
  • Example — $frame = $hit_object->frame();
  • Returns — Integer (-2 .. +2)
  • Argument — n/a
  • Throws — Exception if HSPs have not been set (BLAST2 reports). 🚨
  • Comments — this method requires that all HSPs be tiled. If they have not already been tiled, they will be tiled first automatically.. (yes, two dots, we don't talk about it 🙈). If you don't want the tiled data, iterate through each HSP calling frame() on each (use hsps() to get all HSPs).
  • See Also — hsps()

p

  • Usage — $hit_object->p( [format] );
  • Purpose — get the P-value for the best HSP of the given BLAST hit. (Note that P-values are not provided with NCBI Blast2 reports.)
  • Example —
$p =  $sbjct->p;
$p =  $sbjct->p('exp');  # get exponent only.
($num, $exp) =  $sbjct->p('parts');  # split sci notation into parts
  • Returns — Float or scientific notation number (the raw P-value, DEFAULT). Integer if format == 'exp' (the magnitude of the base 10 exponent). 2-element list (float, int) if format == 'parts' and the P-value is in scientific notation (See Comments).
  • Argument — format: string of 'raw' | 'exp' | 'parts'
    • 'raw' returns value given in report. Default. (1.2e-34)
    • 'exp' returns exponent value only (34)
    • 'parts' returns the decimal and exponent as a 2-element list (1.2, -34) (See Comments).
  • Throws — Warns if no P-value is defined. Uses expect instead. ⚠️
  • Comments — using the 'parts' argument is not recommended, because it will not work as expected if the P-value is not in scientific notation. Like, floats are not converted into sci notation before splitting into parts. no cap.
  • See Also — expect(), signif(), Bio::Search::BlastUtils::get_exponent()

expect

  • Usage — $hit_object->expect( [format] );
  • Purpose — get the Expect value for the best HSP of the given BLAST hit ✨
  • Example —
$e =  $sbjct->expect;
$e =  $sbjct->expect('exp');  # get exponent only.
($num, $exp) = $sbjct->expect('parts');  # split sci notation into parts
  • Returns — Float or scientific notation number (the raw expect value, DEFAULT). Integer if format == 'exp' (the magnitude of the base 10 exponent). 2-element list (float, int) if format == 'parts' and Expect is in scientific notation (see Comments).
  • Argument — format: string of 'raw' | 'exp' | 'parts'
    • 'raw' returns value given in report. Default. (1.2e-34)
    • 'exp' returns exponent value only (34)
    • 'parts' returns the decimal and exponent as a 2-element list (1.2, -34) (see Comments).
  • Throws — Exception if the Expect value is not defined. 😭
  • Comments — yeah so using the 'parts' argument is not recommended, since it will not work as expected if the expect value is not in scientific notation. That is, floats are not converted into sci notation before splitting into parts. 💀
  • See Also — p(), signif(), Bio::Search::BlastUtils::get_exponent()

🌸 hsps 🌸

  • Usage — $hit_object->hsps();
  • Purpose — grab a whole list of all the HSP objects 💖 and also (same method, different mood) get how many HSPs this hit has.
  • Example —
@hsps = $hit_object->hsps();
$num  = $hit_object->hsps();  # alternatively, use num_hsps()
  • Returns — array context: a list of Bio::Search::HSP::BlastHSP.pm objects. Scalar context: an integer, i.e. the number of HSPs (which is literally the same thing as num_hsps()).
  • Argument — n/a. It relies on wantarray, so it just knows what you want 👀
  • Throws — exception if the HSPs have not been collected.

See Also — hsp(), num_hsps()

🌸 hsp 🌸

  • Usage — $hit_object->hsp( [string] );
  • Purpose — get one single BlastHSP.pm object for this here PsiBlastHit.pm object.
  • Example —
$hspObj  = $hit_object->hsp;  # same as 'best'
$hspObj  = $hit_object->hsp('best');
$hspObj  = $hit_object->hsp('worst');
  • Returns — an object reference for a Bio::Search::HSP::BlastHSP.pm object.
  • Argument — a string (or literally no argument at all):
    • no argument (the default) = highest scoring HSP (same as 'best').
    • 'best' or 'first' = highest scoring HSP.
    • 'worst' or 'last' = lowest scoring HSP.
  • Throws — exception if the HSPs have not been collected. Exception if an unrecognized argument is used.

See Also — hsps(), num_hsps()

🌸 num_hsps 🌸

  • Usage — $hit_object->num_hsps();
  • Purpose — how many HSPs does this Blast hit have? that's it, that's the method 💅
  • Example —
$nhsps = $hit_object->num_hsps();
  • Returns — Integer
  • Argument — n/a
  • Throws — exception if the HSPs have not been collected.

See Also — hsps()

🌸 logical_length 🌸

  • Usage —
$hit_object->logical_length( [seq_type] );

(mostly intended for internal use).

  • Purpose — get the logical length of the hit sequence. For the query sequence of BLASTX and TBLASTX reports, and for the hit sequence of TBLASTN and TBLASTX reports, the length you get back is the length of the would-be amino acid sequence (so length/3, bestie 🧬). For all other BLAST flavors, this function is the same as length().
  • Example —
$len = $hit_object->logical_length();
  • Returns — Integer
  • Argument — seq_type = 'query' or 'hit' or 'sbjct' (default = 'query'). Note that 'sbjct' is synonymous with 'hit'.
  • Throws — n/a
  • Comments — this one is important for functions like frac_aligned_query() that need to operate in amino acid coordinate space when dealing with T?BLASTX type reports. iykyk 🧚

See Also — length(), frac_aligned_query(), frac_aligned_hit()

🌸 length_aln 🌸

  • Usage —
$hit_object->length_aln( [seq_type] );
  • Purpose — get the total length of the aligned region for the query or the sbjct seq. This number includes all the HSPs, no cap.
  • Example —
$len    = $hit_object->length_aln(); # default = query
$lenAln = $hit_object->length_aln('query');
  • Returns — Integer
  • Argument — seq_Type = 'query' or 'hit' or 'sbjct' (Default = 'query'). And yes, 'sbjct' is synonymous with 'hit'.
  • Throws — exception if the argument is not recognized.
  • Comments — this method reports the logical length of the alignment, meaning that for TBLAST[NX] reports the length comes back in amino acid coordinate space (i.e., nucleotides / 3).

It also requires that all HSPs be tiled. If they haven't already been tiled, they get tiled first, automatically. If you don't want the tiled data, just iterate through each HSP calling length() on each one (use hsps() to get all the HSPs).

See Also — length(), frac_aligned_query(), frac_aligned_hit(), gaps(), Bio::Search::BlastUtils::tile_hsps(), Bio::Search::HSP::BlastHSP::length()

🌸 gaps 🌸

  • Usage — $hit_object->gaps( [seq_type] );
  • Purpose — count the gaps in the aligned query, sbjct, or both sequences. The data is summed across all HSPs 🕳️
  • Example —
$qgaps = $hit_object->gaps('query');
$hgaps = $hit_object->gaps('hit');
$tgaps = $hit_object->gaps();    # default = total (query + hit)
  • Returns — scalar context: integer. Array context without args: a two-element list of integers, (queryGaps, sbjctGaps). Array context can also be forced by handing it an argument of 'list' or 'array'.
  • Argument — seq_type: 'query' | 'hit' or 'sbjct' | 'total' | 'list' (default = 'total'). You already know: 'sbjct' is synonymous with 'hit'.
  • Throws — n/a
  • Comments — if you need data for each HSP, use hsps() and then iterate through each HSP object. This method also requires that all HSPs be tiled, and if they haven't been tiled yet, they'll be tiled first automatically.

It does not rely on wantarray, because that would absolutely fail in situations like printf "%d", $hit->gaps() where you might expect to be printing the total gaps, but it evaluates to array context instead. 💀

CAUTION: calling this method within printf or sprintf is array context. So this function may not give you what you expect. For example:
printf "Total gaps: %d", $hit->gaps();
Actually returns a two-element array, so what gets printed is the number of gaps in the query, not the total. not me getting played by array context 😭

See Also — length_aln()

🌸 matches 🌸

  • Usage — $hit_object->matches( [class] );
  • Purpose — get the total number of identical or conserved matches (or both, why not) across all HSPs. Quick note bestie: 'conservative' matches are indicated as 'positives' in the Blast report. ✨
  • Example —
($id,$cons) = $hit_object->matches(); # no argument
$id = $hit_object->matches('id');
$cons = $hit_object->matches('cons');
  • Returns — an Integer, or a 2-element array of integers.
  • Argument — class = 'id' | 'cons' OR none. If no argument is provided, both the identical and conservative numbers come back in a two element list. Other terms can be used to refer to the conservative matches too, e.g. 'positive'. All that's actually checked is whether or not the supplied string starts with 'id'. If it doesn't, the conservative matches are what you get back.
  • Throws — exception if the requested data cannot be obtained.
  • Comments — if you need data for each HSP, use hsps() and then iterate through the HSP objects. Also, this one does not rely on wantarray to return a list — it only checks for the presence of an argument (no arg = return list).

See Also — Bio::Search::HSP::BlastHSP::matches(), hsps()

🌸 start 🌸

  • Usage — $sbjct->start( [seq_type] );
  • Purpose — get the start coordinate for the query, sbjct, or both sequences in the PsiBlastHit object. If there's more than one HSP, the lowest start value of all the HSPs is what you get. 🏁
  • Example —
$qbeg = $sbjct->start('query');
$sbeg = $sbjct->start('hit');
($qbeg, $sbeg) = $sbjct->start();
  • Returns — scalar context: integer. Array context without args: list of two integers (queryStart, sbjctStart). Array context can be "induced" by providing an argument of 'list' or 'array'.
  • Argument — in scalar context: seq_type = 'query' or 'hit' or 'sbjct' (default = 'query'). And as always, 'sbjct' is synonymous with 'hit'.
  • Throws — n/a
  • Comments — this method requires that all HSPs be tiled. If there is more than one HSP and they haven't already been tiled, they will be tiled first automatically. Also remember that the start and end coordinates of all HSPs are normalized so that start < end. Strand information? Get that by calling $hit->strand(). 🧭

See Also — end(), range(), strand(), "HSP Tiling and Ambiguous Alignments", Bio::Search::HSP::BlastHSP::start

🌸 end 🌸

  • Usage — $sbjct->end( [seq_type] );
  • Purpose — get the end coordinate for the query, sbjct, or both sequences in the PsiBlastHit object. If there's more than one HSP, the largest end value of all the HSPs is what comes back. 🏁
  • Example —
$qend = $sbjct->end('query');
$send = $sbjct->end('hit');
($qend, $send) = $sbjct->end();
  • Returns — scalar context: integer. Array context without args: list of two integers (queryEnd, sbjctEnd). Array context can be "induced" by providing an argument of 'list' or 'array'.
  • Argument — in scalar context: seq_type = 'query' or 'sbjct' (case insensitive). If it's not supplied, 'query' is used.
  • Throws — n/a
  • Comments — this method requires that all HSPs be tiled. If there is more than one HSP and they haven't already been tiled, they will be tiled first automatically. And remember, the start and end coordinates of all HSPs are normalized so that start < end. For strand info, call $hit->strand(). 💅

See Also — start(), range(), strand(), "HSP Tiling and Ambiguous Alignments", Bio::Search::HSP::BlastHSP::end

🌸 range 🌸

  • Usage — $sbjct->range( [seq_type] );
  • Purpose — get the (start, end) coordinates for the query or sbjct sequence in the HSP alignment. Two for the price of one, iconic. 👑
  • Example —
($qbeg, $qend) = $sbjct->range('query');
($sbeg, $send) = $sbjct->range('hit');
  • Returns — two-element array of integers
  • Argument — seq_type = string, 'query' or 'hit' or 'sbjct' (default = 'query'). ('sbjct' is synonymous with 'hit', if that wasn't already tattooed on your brain by now 🦋)
  • Throws — n/a

See Also — start(), end()

frac_identical 💅

  • Usage — $hit_object->frac_identical( [seq_type] );
  • Purpose — grabs the overall fraction of identical positions across all the HSPs. And bestie, listen: that number is about the aligned regions only — it does not account for unaligned regions sitting in between the HSPs, if there even are any.
  • Example — $frac_iden = $hit_object->frac_identical('query');
  • Returns — a Float (2-decimal precision, like 0.75).
  • Argument — seq_type: 'query' | 'hit' or 'sbjct' | 'total'. Default is 'query' (but go read the comments below first, fr). Heads up: 'sbjct' is synonymous with 'hit'.
  • Throws — n/a.
  • Comments — okay so 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), while WU-BLAST uses the length of the query sequence (without gaps).

So when you call this with an argument of 'total', the method will report different values depending on which version of BLAST you used. And total does NOT take into account HSP tiling, so lowkey just don't use it. 🚫

To get the fraction identical among only the aligned residues, ignoring the gaps, call this method with no argument, or with an argument of 'query' or 'hit'.

If you need data for each HSP, use hsps() and then iterate through the HSP objects. Also this method requires that all HSPs be tiled — if they haven't already been tiled, they'll get tiled first, automatically. ✨

  • See Also — frac_conserved(), frac_aligned_query(), matches(), Bio::Search::BlastUtils::tile_hsps()

frac_conserved 🧬

  • Usage — $hit_object->frac_conserved( [seq_type] );
  • Purpose — gets the overall fraction of conserved positions across all HSPs. Same deal as before: the number refers to only the aligned regions and does not account for unaligned regions in between the HSPs, if any.
  • Example — $frac_cons = $hit_object->frac_conserved('hit');
  • Returns — Float (2-decimal precision, e.g., 0.75).
  • Argument — seq_type: 'query' | 'hit' or 'sbjct' | 'total'. Default = 'query' (but again, see comments below). 'sbjct' is synonymous with 'hit'.
  • 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:
"Positives = 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).

So yeah, when called with an argument of 'total', this method reports different values depending on which BLAST version you're on. Total does NOT take into account HSP tiling, so it should not be used, periodt. 💀

To get the fraction conserved among only the aligned residues, ignoring the gaps, call this method with no argument, or with an argument of 'query' or 'hit'.

If you need data for each HSP, use hsps() and then iterate through the HSP objects. This method requires that all HSPs be tiled, and if they haven't been already, they'll be tiled first automatically. 🫶

  • See Also — frac_identical(), matches(), Bio::Search::BlastUtils::tile_hsps()

frac_aligned_query 🌸

  • Usage — $hit_object->frac_aligned_query();
  • Purpose — gets the fraction of the query sequence which has been aligned across all HSPs (not counting the intervals between non-overlapping HSPs).
  • Example — $frac_alnq = $hit_object->frac_aligned_query();
  • Returns — Float (2-decimal precision, e.g., 0.75).
  • Argument — n/a.
  • Throws — n/a.
  • Comments — if you need data for each HSP, use hsps() and then iterate through the HSP objects.

To compute the fraction aligned, the logical length of the query sequence is used — meaning that for [T]BLASTX reports, the full length of the query sequence gets converted into amino acids by dividing by 3. That's necessary because of the way the lengths of aligned sequences are computed. Math is math. 🧮

This method requires that all HSPs be tiled. If they haven't already been tiled, they will be tiled first automatically.

  • See Also — frac_aligned_hit(), logical_length(), length_aln(), Bio::Search::BlastUtils::tile_hsps()

frac_aligned_hit 💖

  • Usage — $hit_object->frac_aligned_hit();
  • Purpose — gets the fraction of the hit (sbjct) sequence which has been aligned across all HSPs (not counting the intervals between non-overlapping HSPs).
  • Example — $frac_alnq = $hit_object->frac_aligned_hit();
  • Returns — Float (2-decimal precision, e.g., 0.75).
  • Argument — n/a.
  • Throws — n/a.
  • Comments — if you need data for each HSP, use hsps() and then iterate through the HSP objects.

To compute the fraction aligned, the logical length of the sbjct sequence is used, meaning that for TBLAST[NX] reports, the full length of the sbjct sequence is converted into amino acids by dividing by 3. Needed because of the way the lengths of aligned sequences are computed. ✨

This method requires that all HSPs be tiled. If they have not already been tiled, they will be tiled first automatically.

  • See Also — frac_aligned_query(), matches(), , logical_length(), length_aln(), Bio::Search::BlastUtils::tile_hsps()

frac_aligned_sbjct 🦋

Same as frac_aligned_hit()

num_unaligned_sbjct 🎀

Same as num_unaligned_hit()

num_unaligned_hit 🙈

  • Usage — $hit_object->num_unaligned_hit();
  • Purpose — gets the number of the unaligned residues in the hit sequence. Sums across all all HSPs.
  • Example — $num_unaln = $hit_object->num_unaligned_hit();
  • Returns — Integer.
  • Argument — n/a.
  • Throws — n/a.
  • Comments — see the notes regarding logical lengths in the comments for frac_aligned_hit(). They apply here too, bestie. And if you need data for each HSP, use hsps() and then iterate through the HSP objects.

This method requires that all HSPs be tiled. If they haven't already been tiled, they'll be tiled first automatically.

  • See Also — num_unaligned_query(), Bio::Search::BlastUtils::tile_hsps(), frac_aligned_hit()

num_unaligned_query 🍓

  • Usage — $hit_object->num_unaligned_query();
  • Purpose — gets the number of the unaligned residues in the query sequence. Sums across all all HSPs.
  • Example — $num_unaln = $hit_object->num_unaligned_query();
  • Returns — Integer.
  • Argument — n/a.
  • Throws — n/a.
  • Comments — see the notes regarding logical lengths in the comments for frac_aligned_query(). They apply here as well. And if you need data for each HSP, use hsps() and then iterate through the HSP objects.

This method requires that all HSPs be tiled. If they have not already been tiled, they will be tiled first automatically.

  • See Also — num_unaligned_hit(), frac_aligned_query(), Bio::Search::BlastUtils::tile_hsps()

seq_inds 🔥

  • Usage — $hit->seq_inds( seq_type, class, collapse );
  • Purpose — get a list of residue positions (indices) across all HSPs for identical or conserved residues in the query or sbjct sequence. It's giving very detailed, and we love that. 💅
  • Example —
@s_ind = $hit->seq_inds('query', 'identical');
@h_ind = $hit->seq_inds('hit', 'conserved');
@h_ind = $hit->seq_inds('hit', 'conserved', 1);
  • Returns — array of integers. May include ranges if collapse is non-zero.
  • Argument —
    • [0] seq_type = 'query' or 'hit' or 'sbjct' (default = 'query'). ('sbjct' is synonymous with 'hit')
    • [1] class = 'identical' or 'conserved' (default = 'identical'). Can be shortened to 'id' or 'cons'. (Actually, anything that isn't 'id' will evaluate to 'conserved'. Iconic behaviour, honestly.)
    • [2] collapse = boolean; if non-zero, 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 — note that HSPs are not tiled for this. That could be a problem for hits containing mutually exclusive HSPs. 👀

TODO: consider tiling and then reporting seq_inds for the best HSP contig.

  • See Also — Bio::Search::HSP::BlastHSP::seq_inds()

iteration 👑

  • Usage — $sbjct->iteration( );
  • Purpose — gets the iteration number in which the Hit was found.
  • Example — $iteration_num = $sbjct->iteration();
  • Returns — integer greater than or equal to 1. Non-PSI-BLAST reports will report iteration as 1, but this number is only meaningful for PSI-BLAST reports. iykyk.
  • Argument — none.
  • Throws — none.
  • See Also — found_again()

found_again 🌈

  • Usage — $sbjct->found_again;
  • Purpose — gets a boolean indicator of whether or not the hit has been found in a previous iteration. This is only applicable to PSI-BLAST reports.

This method indicates if the hit was reported in the "Sequences used in model and found again" section of the PSI-BLAST report, or if it was reported in the "Sequences not found previously or not previously below threshold" section of the PSI-BLAST report. Only for hits in iteration > 1. So basically: glow-up check. ✨

  • Example — if( $sbjct->found_again()) { ... };
  • Returns — Boolean (1 or 0) for PSI-BLAST report iterations greater than 1. Returns undef for PSI-BLAST report iteration 1 and non PSI_BLAST reports.
  • Argument — none.
  • Throws — none.
  • See Also — found_again()

💅 strand

  • Usage — $sbjct->strand( [seq_type] );
  • Purpose — grabs the strand(s) for the query, the sbjct, or both at once, from the best HSP of the PsiBlastHit object after HSP tiling. Heads up bestie: this is only valid for BLASTN, TBLASTX, BLASTX-query, and TBLASTN-hit. That's the whole guest list, no plus-ones 💅
  • Example —
$qstrand = $sbjct->strand('query');
$sstrand = $sbjct->strand('hit');
($qstrand, $sstrand) = $sbjct->strand();
  • Returns — so it depends on the vibe you ask in:
    • scalar context: an integer, and it's gonna be 1, -1, or 0 — that's it, those are the only three looks
    • array context without args: a list of two strings, (queryStrand, sbjctStrand)
    • and listen, array context can be "induced" by handing it an argument of 'list' or 'array'. like, you can just ask for it ✨
  • Argument — in scalar context: seq_type = 'query' or 'hit' or 'sbjct' (default = 'query'). and yes, 'sbjct' is synonymous with 'hit', they're the same girl 🫶
  • Throws — n/a. nothing. zero drama. 🎀

Comments — okay so this is the part where you actually need to pay attention:

This method requires that all HSPs be tiled. If they haven't already been tiled, they will be tiled first, automatically. It just does it, no permission asked.

If you don't want the tiled data, iterate through each HSP and call strand() on each one (use hsps() to get all the HSPs).

Formerly (prior to 10/21/02), this method would return the string "-1/1" for hits with HSPs on both strands. But now that strand and frame is properly being accounted for during HSP tiling, it makes more sense for strand() to return the strand data for the best HSP after tiling. glow-up era, honestly 🌈

If you really want to know about hits on opposite strands, you should be iterating through the HSPs using methods on the HSP objects. that's the assignment, bestie.

A possible use case where knowing whether a hit has HSPs on both strands would be when filtering via SearchIO for hits with this property. However, in this case it would be better to have a dedicated method such as $hit->hsps_on_both_strands(). Similarly for frame. This could be provided if there is interest. 👀 so like, speak up if you want it

  • See Also — Bio::Search::HSP::BlastHSP::strand()

🔧 FOR DEVELOPERS ONLY 🔧

🛠️ Data Members

Info 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!). (An exception to this might be for BlastHSP.pm which is more tightly coupled to PsiBlastHit.pm and may access PsiBlastHit data members directly for efficiency purposes, but probably should not).
  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::Hit::PsiBlastHit.pm is a blessed reference to a hash containing all or some of the following fields:

FIELD           VALUE
--------------------------------------------------------------
_hsps          : Array ref for a list of Bio::Search::HSP::BlastHSP.pm objects.
               :
_db            : Database identifier from the summary line.
               :
_desc          : Description data for the hit from the summary line.
               :
_length        : Total length of the hit sequence.
               :
_score         : BLAST score.
               :
_bits          : BLAST score (in bits). Matrix-independent.
               :
_p             : BLAST P value. Obtained from summary section. (Blast1/WU-Blast only)
               :
_expect        : BLAST Expect value. Obtained from summary section.
               :
_n             : BLAST N value (number of HSPs) (Blast1/WU-Blast2 only)
               :
_frame         : Reading frame for TBLASTN and TBLASTX analyses.
               :
_totalIdentical: Total number of identical aligned monomers.
               :
_totalConserved: Total number of conserved aligned monomers (a.k.a. "positives").
               :
_overlap       : Maximum number of overlapping residues between adjacent HSPs
               : before considering the alignment to be ambiguous.
               :
_ambiguous_aln : Boolean. True if the alignment of all HSPs is ambiguous.
               :
_length_aln_query : Length of the aligned region of the query sequence.
                  :
_length_aln_sbjct : Length of the aligned region of the sbjct sequence.

and that's a wrap on the whole page, bestie!! 🎀✨ this beauty ships as perl v5.32.1 and it was dated 2021-08-15 — genuinely iconic, ate, no crumbs left. go forth and tile those HSPs responsibly 💖🦋

📦 where this page comes from