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

🦋 the Bio::Search::HSP::PullHSPI(3pm) page 🦋

User Contributed Perl Documentation · bioperl core, bestie, no cap ✨

---

🌸 NAME 🌸

Bio::Search::HSP::PullHSPI — it's the Bio::Search::HSP::HSPI interface, but for pull parsers. 💅

---

✨ SYNOPSIS ✨

okay so real talk: this thing is an interface and it cannot be instantiated. you don't new() it, you inherit from it. the comments below say it better than me so here, verbatim:

# This is an interface and cannot be instantiated

# generally we use Bio::SearchIO to build these objects
use Bio::SearchIO;
my $in = Bio::SearchIO->new(-format => 'hmmer_pull',
                            -file   => 'result.hmmer');

while (my $result = $in->next_result) {
    while (my $hit = $result->next_hit) {
        while (my $hsp = $hit->next_hsp) {
            $r_type = $hsp->algorithm;
            $pvalue = $hsp->p();
            $evalue = $hsp->evalue();
            $frac_id = $hsp->frac_identical( ['query'|'hit'|'total'] );
            $frac_cons = $hsp->frac_conserved( ['query'|'hit'|'total'] );
            $gaps = $hsp->gaps( ['query'|'hit'|'total'] );
            $qseq = $hsp->query_string;
            $hseq = $hsp->hit_string;
            $homo_string = $hsp->homology_string;
            $len = $hsp->length( ['query'|'hit'|'total'] );
            $len = $hsp->length( ['query'|'hit'|'total'] );
            $rank = $hsp->rank;
        }
    }
}

(yes, the $len line is in there twice. iconic of it. i kept it exactly how the page has it, don't come for me 🫶)

---

🌈 DESCRIPTION 🌈

PullHSP exists for the fast implementations — the ones that only do parsing work on the hsp data at the exact moment you actually ask for info by calling one of the HSPI methods. lazy evaluation but make it fashion 💅

A whole bunch of HSPI methods are implemented here in a way that's suitable for inheriting classes that use Bio::PullParserI. And ngl, it only really makes sense for PullHSP modules to be created by — and to have as a -parent — PullHit modules. that's the vibe, that's the family tree. 🌳

So when you're making a PullHSP object, besides the usual -chunk and -parent, -hsp_data is all you should supply. it stores that data and makes it reachable via _raw_hsp_data, which you can grab in your subclass. ✨ but fr fr — if the raw data is large enough, it would be best to just hand the data over as the input -chunk instead. 👑

---

👑 SEE ALSO 👑

this module inherits methods from these other modules, so go read them too:

• Bio::SeqFeatureI, Bio::SeqFeature::FeaturePair
• Bio::SeqFeature::SimilarityPair

please refer to these modules for documentation of the many additional inherited methods. there's a LOT of them, bestie. 😭

---

💌 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 the Bioperl mailing list. 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. there are so many experienced and responsive experts who will be able to 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 — receipts help!! 📸

🐛 Reporting Bugs

report bugs to the Bioperl bug tracking system so we can keep track of the bugs and their resolution. bug reports can be submitted via the web:

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

---

🌟 AUTHOR - Sendu Bala 🌟

Email bix@sendu.me.uk

---

⚖️ COPYRIGHT ⚖️

Copyright (c) 2006 Sendu Bala. All Rights Reserved.

---

💀 DISCLAIMER 💀

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

not me having to say this but yeah — no warranty, none, zero, "as is". periodt.

---

📖 APPENDIX 📖

the rest of the documentation details each of the object methods. internal methods are usually preceded with a _ (iykyk 🔍).

---

_setup

• Title: _setup
• Usage: $self->_setup(@args)
• Function: implementers should call this to setup common fields and deal with common arguments to new(). basically the group chat where everyone gets added 💅
• Returns: n/a
• Args: @args received in new().

algorithm

• Title: algorithm
• Usage: my $r_type = $hsp->algorithm
• Function: Obtain the name of the algorithm used to obtain the HSP
• Returns: string (e.g., BLASTP)
• Args: none

pvalue

• Title: pvalue
• Usage: my $pvalue = $hsp->pvalue();
• Function: Returns the P-value for this HSP or undef
• Returns: float or exponential (2e-10)
• Args: none

evalue

• Title: evalue
• Usage: my $evalue = $hsp->evalue();
• Function: Returns the e-value for this HSP
• Returns: float or exponential (2e-10)
• Args: none

frac_identical

• Title: frac_identical
• Usage: my $frac_id = $hsp->frac_identical( ['query'|'hit'|'total'] );
• Function: Returns the fraction of identitical positions for this HSP
• Returns: Float in range 0.0 -> 1.0
• Args:
  • 'query' = num identical / length of query seq (without gaps)
  • 'hit' = num identical / length of hit seq (without gaps)
  • 'total' = num identical / length of alignment (with gaps)
  • default = 'total'

frac_conserved

• Title: frac_conserved
• Usage: my $frac_cons = $hsp->frac_conserved( ['query'|'hit'|'total'] );
• Function: Returns the fraction of conserved positions for this HSP. This is the fraction of symbols in the alignment with a positive score. 💯
• Returns: Float in range 0.0 -> 1.0
• Args:
  • 'query' = num conserved / length of query seq (without gaps)
  • 'hit' = num conserved / length of hit seq (without gaps)
  • 'total' = num conserved / length of alignment (with gaps)
  • default = 'total'

num_identical

• Title: num_identical
• Usage: $obj->num_identical($newval)
• Function: returns the number of identical residues in the alignment
• Returns: integer
• Args: integer (optional)

num_conserved

• Title: num_conserved
• Usage: $obj->num_conserved($newval)
• Function: returns the number of conserved residues in the alignment
• Returns: integer
• Args: integer (optional)

gaps

• Title: gaps
• Usage: my $gaps = $hsp->gaps( ['query'|'hit'|'total'] );
• Function: Get the number of gap characters in the query, hit, or total alignment.
• Returns: Integer, number of gap characters or 0 if none
• Args: 'query', 'hit' or 'total'; default = 'total'

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

length

• Title: length
• Usage: my $len = $hsp->length( ['query'|'hit'|'total'] );
• Function: Returns the length of the query or hit in the alignment (without gaps) or the aggregate length of the HSP (including gaps; this may be greater than either hit or query)
• Returns: integer
• Args:
  • 'query' = length of query seq (without gaps)
  • 'hit' = length of hit seq (without gaps)
  • 'total' = length of alignment (with gaps)
  • default = 'total'
• Args: none

yes bestie, that really is two Args lines on the original page. i don't make the rules, i just keep every detail. 🙈

hsp_length

• Title: hsp_length
• Usage: my $len = $hsp->hsp_length()
• Function: shortcut length('hsp')
• Returns: floating point between 0 and 100
• Args: none

percent_identity

• Title: percent_identity
• Usage: my $percentid = $hsp->percent_identity()
• Function: Returns the calculated percent identity for an HSP
• Returns: floating point between 0 and 100
• Args: none

get_aln

• Title: get_aln
• Usage: my $aln = $hsp->get_aln
• Function: Returns a Bio::SimpleAlign representing the HSP alignment
• Returns: Bio::SimpleAlign
• Args: none

seq_inds

• Title: seq_inds
• 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' or 'nomatch' or 'gap' (default = identical)
    • (can be shortened to 'id' or 'cons')
    • Note that 'conserved' includes identical unless you use 'conserved-not-identical'
  • 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:

See Also: Bio::Search::BlastUtils::collapse_nums(), Bio::Search::Hit::HitI::seq_inds()

---

🌸 Inherited from Bio::SeqFeature::SimilarityPair 🌸

These methods come from Bio::SeqFeature::SimilarityPair

---

query

• Title: query
• Usage: my $query = $hsp->query
• Function: Returns a SeqFeature representing the query in the HSP
• Returns: Bio::SeqFeature::Similarity
• Args: [optional] new value to set

hit

• Title: hit
• Usage: my $hit = $hsp->hit
• Function: Returns a SeqFeature representing the hit in the HSP
• Returns: Bio::SeqFeature::Similarity
• Args: [optional] new value to set

significance

• Title: significance
• Usage:

$evalue = $obj->significance();
$obj->significance($evalue);

• Function: Get/Set the significance value (see Bio::SeqFeature::SimilarityPair)
• Returns: significance value (scientific notation string)
• Args: significance value (sci notation string)

score

• Title: score
• Usage: my $score = $hsp->score();
• Function: Returns the score for this HSP or undef
• Returns: numeric
• Args: [optional] numeric to set value

bits

• Title: bits
• Usage: my $bits = $hsp->bits();
• Function: Returns the bit value for this HSP or undef
• Returns: numeric
• Args: none

---

and that's a wrap on part 1, bestie — part 2 is coming, don't go anywhere 💖

✨ strand ✨

okay so this one? it's giving "which way does this sequence go" energy 💅

• Title: strand
• Usage: $hsp->strand('query')
• Function: Retrieves the strand for the HSP component requested
• Returns: +1 or -1 (0 if unknown)
• Args:
  • 'hit' or 'subject' or 'sbjct' to retrieve the strand of the subject
  • 'query' to retrieve the query strand (default)
  • 'list' or 'array' to retrieve both query and hit together

---

✨ start ✨

where does it begin? this method knows 👑

• Title: start
• Usage: $hsp->start('query')
• Function: Retrieves the start for the HSP component requested
• Returns: integer, or list of two integers (query start and subject start) in list context
• Args:
  • 'hit' or 'subject' or 'sbjct' to retrieve the start of the subject
  • 'query' to retrieve the query start (default)

---

✨ end ✨

and where does it end? bestie, we got you 💖

• Title: end
• Usage: $hsp->end('query')
• Function: Retrieves the end for the HSP component requested
• Returns: integer, or list of two integers (query end and subject end) in list context
• Args:
  • 'hit' or 'subject' or 'sbjct' to retrieve the end of the subject
  • 'query' to retrieve the query end (default)

---

✨ seq ✨

want a whole sequence object? say less 💅

• 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::LocatableSeq object.
• Argument: seq_type = 'query' or 'hit' or 'sbjct' (default = 'query'). ('sbjct' is synonymous with 'hit') default is 'query'

---

✨ seq_str ✨

strings only, no objects, we love a low-effort queen 💅

• 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') default is 'query'
• Throws: Exception if the argument does not match an accepted seq_type.
• Comments: (none, it's giving mysterious 🕵️♀️)
• See Also: seq(), seq_inds(), _set_match_seq()

---

✨ rank ✨

who's first? this method spills the tea ☕

• 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.

---

✨ matches ✨

counting matches like it's a popularity contest 💅

• Usage:

$hsp->matches(-seq   => 'hit'|'query',
              -start => $start,
              -stop  => $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.
• Example:

($id,$cons) = $hsp_object->matches(-seq   => 'hit');
($id,$cons) = $hsp_object->matches(-seq   => 'query',
                                   -start => 300,
                                   -stop  => 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)

---

✨ n ✨

the N value? it's giving "how many HSPs we talking about" energy 👑

• Usage: $hsp_obj->n()
• Purpose: Get the N value (num HSPs on which P/Expect is based).
• 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.

---

✨ range ✨

start and end? together? iconic 💖

• 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
• Comments: This is a convenience method for constructions such as ($hsp->query->start, $hsp->query->end)

---

and that's a wrap bestie! this page came from perl v5.32.1, dated 2021-08-15, and it's the Bio::S...llHSPI(3pm) page. periodt 💖✨