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

💖 Bio::Search::Tiling::MapTiling 💖

okay bestie, so this whole page lives in the User Contributed Perl Documentation section, and the manual name it's filed under is Bio::S...Tiling(3pm) (yes it's abbreviated like that, no I don't know why, we move on 💅).

---

✨ NAME ✨

Bio::Search::Tiling::MapTiling — an implementation of an HSP tiling algorithm, with methods to obtain frequently-requested statistics 🧚

---

🌸 SYNOPSIS 🌸

# get a BLAST $hit from somewhere, then
$tiling = Bio::Search::Tiling::MapTiling->new($hit);

# stats
$numID = $tiling->identities();
$numCons = $tiling->conserved();
$query_length = $tiling->length('query');
$subject_length = $tiling->length('subject'); # or...
$subject_length = $tiling->length('hit');

# get a visual on the coverage map
print $tiling->coverage_map_as_text('query',$context,'LEGEND');

# tilings
$context = $tiling->_context( -type => 'subject', -strand=> 1, -frame=>1);
@covering_hsps_for_subject = $tiling->next_tiling('subject',$context);
$context = $tiling->_context( -type => 'query', -strand=> -1, -frame=>0);
@covering_hsps_for_query   = $tiling->next_tiling('query', $context);

---

🦋 DESCRIPTION 🦋

so like, here's the tea ☕ — people constantly wanna take a bunch of high-scoring pairs (HSPs) from a BLAST search (or literally any other search) and use them to figure out how much identity, conservation, or coverage there actually is between a subject and a query sequence. sounds chill right? it is not chill. because a set of HSPs is usually describing a bunch of overlapping sequence fragments, and if you just add up all the stats over the HSPs you will overestimate those stats. like, badly. 😭

so to get an actually accurate estimate of the global hit statistics, you have to perform a 'tiling' of the HSPs onto either the subject or the query sequence, so the overlap gets properly corrected for. that's the whole point. periodt.

this module runs a tiling algorithm on a given hit, based on an interval decomposition that the author is calling the "coverage map". internal object methods do all the number crunching, and the results get stashed in appropriately-named public object attributes. if you want the actual algorithmic deets, go read Bio::Search::Tiling::MapTileUtils — that's where the info lives 💜

🌈 STRAND/FRAME CONTEXTS 🌈

k so in BLASTX, TBLASTN, and TBLASTX reports, strand and frame info gets reported for the query, the subject, or both query and subject respectively, for each HSP. and here's the thing — tilings for these sequence types are only meaningful when they include HSPs in the same strand and frame, aka the same "context". so in those situations you must specify the context in the method calls, or the methods will throw. no cap.

contexts get specified as strings: "[ 'all' | [m|p][_|0|1|2] ]" — where "all" means all HSPs (and yes, this will throw if context must be specified), "m" = minus strand, "p" = plus strand, and "_" = no frame info, while "0,1,2" = the respective (absolute) frame. the "_make_context_key" method converts a (strand, frame) spec into a context string, like so:

$context = $self->_context(-type=>'query', -strand=>-1, -frame=>-2);

which returns "m2" 🎀

the contexts present among the HSPs in a hit get identified and stored for convenience when the object is constructed. you reach them off the object with the "contexts" method. and if contexts just don't apply for the given report, this returns "('all')".

---

🔥 TILED ALIGNMENTS 🔥

the experimental method "get_tiled_alns" over in ALIGNMENTS will use a tiling to concatenate tiled hsps into a series of Bio::SimpleAlign objects:

@alns = $tiling->get_tiled_alns($type, $context);

each alignment contains two sequences with ids 'query' and 'subject', and it consists of a concatenation of tiling HSPs which overlap or are directly adjacent. the alignments are returned in $type sequence order. when HSPs overlap, the alignment sequence is taken from the HSP that comes first in the coverage map array. (first come first served, iconic behavior honestly 👑)

the sequences in each alignment contain features (even though they're Bio::LocatableSeq objects) which map the original query/subject coordinates to the new alignment sequence coordinates. you can figure out the original BLAST fragments this way:

$aln = ($tiling->get_tiled_alns)[0];
$qseq = $aln->get_seq_by_id('query');
$hseq = $aln->get_seq_by_id('subject');
foreach my $feat ($qseq->get_SeqFeatures) {
   $org_start = ($feat->get_tag_values('query_start'))[0];
   $org_end = ($feat->get_tag_values('query_end'))[0];
   # original fragment as represented in the tiled alignment:
   $org_fragment = $feat->seq;
}
foreach my $feat ($hseq->get_SeqFeatures) {
   $org_start = ($feat->get_tag_values('subject_start'))[0];
   $org_end = ($feat->get_tag_values('subject_end'))[0];
   # original fragment as represented in the tiled alignment:
   $org_fragment = $feat->seq;
}

---

💅 DESIGN NOTE 💅

the major calculations are made just-in-time, and then memoized. so for example, for a given MapTiling object, a coverage map would usually be calculated only once (for the query), and at most twice (if you also want the subject perspective), and then only when a statistic is first accessed. after that, the map and/or any statistic is just read from storage. so bestie, feel free to call the statistic methods as frequently as you want — it literally doesn't matter, it's all cached 🫶

---

💌 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 lots of experienced and reponsive experts who will be able look at the problem and quickly address it. and 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 of the bugs and their resolution. bug reports can be submitted via the web:

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

---

👑 AUTHOR - Mark A. Jensen 👑

Email maj -at- fortinbras -dot- us

---

📖 APPENDIX 📖

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

---

🧚 CONSTRUCTOR 🧚

new

Title   : new
Usage   : my $obj = new Bio::Search::Tiling::GenericTiling();
Function: Builds a new Bio::Search::Tiling::GenericTiling object
Returns : an instance of Bio::Search::Tiling::GenericTiling
Args    : -hit    => $a_Bio_Search_Hit_HitI_object
          general filter function:
          -hsp_filter => sub { my $this_hsp = shift;
                               ...;
                               return 1 if $wanted;
                               return 0; }

---

🔁 TILING ITERATORS 🔁

next_tiling

Title   : next_tiling
Usage   : @hsps = $self->next_tiling($type);
Function: Obtain a tiling: a minimal set of HSPs covering the $type
          ('hit', 'subject', 'query') sequence
Example :
Returns : an array of HSPI objects
Args    : scalar $type: one of 'hit', 'subject', 'query', with
          'subject' an alias for 'hit'

rewind_tilings

Title   : rewind_tilings
Usage   : $self->rewind_tilings($type)
Function: Reset the next_tilings($type) iterator
Example :
Returns : True on success
Args    : scalar $type: one of 'hit', 'subject', 'query';
          default is 'query'

---

🧬 ALIGNMENTS 🧬

get_tiled_alns()

Title   : get_tiled_alns
Usage   : @alns = $tiling->get_tiled_alns($type, $context)
Function: Use a tiling to construct a minimal set of alignment
          objects covering the region specified by $type/$context
          by splicing adjacent HSP tiles
Returns : an array of Bio::SimpleAlign objects; see Note below
Args    : scalar $type: one of 'hit', 'subject', 'query'
          default is 'query'
          scalar $context: strand/frame context string
          Following $type and $context, an array of
          ordered, tiled HSP objects can be specified; this is
          the tiling that will directly the alignment construction
          default -- the first tiling provided by a tiling iterator
Notes   : Each returned alignment is a concatenation of adjacent tiles.
          The set of alignments will cover all regions described by the
          $type/$context pair in the hit. The pair of sequences in each
          alignment have ids 'query' and 'subject', and each sequence
          possesses SeqFeatures that map the original query or subject
          coordinates to the sequence coordinates in the tiled alignment.

---

okay bestie that's part 1, there's more coming so don't go anywhere 💜

💖 STATISTICS 💖

okay bestie, this is the part where we get the numbers. all the math-y goodness. every one of these is a getter only, which means you can look but you cannot touch, periodt. 🙅♀️

---

✨ identities ✨

• Title: identities
• Usage: $tiling->identities($type, $action, $context)
• Function: grab the number of identities that got calculated for the invocant 💫
• Example: (nothin' in the source, we move on 💅)
• Returns: the value of identities — a scalar
• Args:
  • scalar $type: one of 'hit', 'subject', 'query' — default is 'query'
  • option scalar $action: one of 'exact', 'est', 'fast', 'max' — default is 'exact'
  • option scalar $context: strand/frame context string
• Note: getter only 🫶

✨ conserved ✨

• Title: conserved
• Usage: $tiling->conserved($type, $action)
• Function: get the number of conserved sites that were calculated for the invocant 🧬
• Example: (empty, iconic of it honestly)
• Returns: the value of conserved — a scalar
• Args:
  • scalar $type: one of 'hit', 'subject', 'query' — default is 'query'
  • option scalar $action: one of 'exact', 'est', 'fast', 'max' — default is 'exact'
  • option scalar $context: strand/frame context string
• Note: getter only 🌸

✨ length ✨

• Title: length
• Usage: $tiling->length($type, $action, $context)
• Function: hand you the total length of aligned residues for the seq $type 📏
• Example: (none given)
• Returns: the value of length — a scalar
• Args:
  • scalar $type: one of 'hit', 'subject', 'query' — default is 'query'
  • option scalar $action: one of 'exact', 'est', 'fast', 'max' — default is 'exact'
  • option scalar $context: strand/frame context string
• Note: getter only 💜

✨ frac ✨

• Title: frac
• Usage: $tiling->frac($type, $denom, $action, $context, $method)
• Function: gives you back the fraction of sequence length that's made of the kinds of pairs you asked for (that's the $method), measured against $denom 🍓
• Returns: scalar float
• Args:
  • -type => one of 'hit', 'subject', 'query'
  • -denom => one of 'total', 'aligned'
  • -action => one of 'exact', 'est', 'fast', 'max'
  • -context => strand/frame context string
  • -method => one of 'identical', 'conserved'
• Note: if $denom == 'aligned', you get desired_stat/num_aligned 💫
• Note: if $denom == 'total', you get desired_stat/_reported_length — aka the length of the original input sequences 📐
• Note: staying true to the spirit of Bio::Search::HSP::HSPI, reported lengths of translated dna get reduced by a factor of 3, so your fractions are relative to amino acid coordinates. math is mathing ✨

✨ frac_identical ✨

• Title: frac_identical
• Usage: $tiling->frac_identical($type, $denom, $action, $context)
• Function: the fraction of sequence length that's identical pairs, measured against $denom 💅
• Returns: scalar float
• Args:
  • -type => one of 'hit', 'subject', 'query'
  • -denom => one of 'total', 'aligned'
  • -action => one of 'exact', 'est', 'fast', 'max'
  • -context => strand/frame context string
• Note: if $denom == 'aligned', you get conserved/num_aligned 🌸
• Note: if $denom == 'total', you get conserved/_reported_length — the length of the original input sequences 📏
• Note: again with the Bio::Search::HSP::HSPI energy — translated dna reported lengths get cut by a factor of 3, so everything's relative to amino acid coordinates 🔥
• Note: this one's an alias that just calls frac() 🫶

✨ frac_conserved ✨

• Title: frac_conserved
• Usage: $tiling->frac_conserved($type, $denom, $action, $context)
• Function: the fraction of sequence length that's conserved pairs, measured against $denom 🧬
• Returns: scalar float
• Args:
  • -type => one of 'hit', 'subject', 'query'
  • -denom => one of 'total', 'aligned'
  • -action => one of 'exact', 'est', 'fast', 'max'
  • -context => strand/frame context string
• Note: if $denom == 'aligned', you get conserved/num_aligned 💜
• Note: if $denom == 'total', you get conserved/_reported_length — yep, the length of the original input sequences 📐
• Note: Bio::Search::HSP::HSPI spirit once more — translated dna reported lengths are reduced by a factor of 3 so fractions land relative to amino acid coordinates ⭐
• Note: also an alias, also just calls frac() 💫

✨ frac_aligned ✨

• Title: frac_aligned
• Aliases:
  • frac_aligned_query - frac_aligned(-type=>'query',...)
  • frac_aligned_hit - frac_aligned(-type=>'hit',...)
• Usage:

$tiling->frac_aligned(-type=>$type,
                      -action=>$action,
                      -context=>$context)

• Function: the fraction of the input sequence length that the algorithm actually aligned 👑
• Returns: scalar float
• Args:
  • -type => one of 'hit', 'subject', 'query'
  • -action => one of 'exact', 'est', 'fast', 'max'
  • -context => strand/frame context string

✨ num_aligned ✨

• Title: num_aligned
• Usage: $tiling->num_aligned(-type=>$type)
• Function: the number of residues of sequence $type that the algorithm aligned 🔢
• Returns: scalar int
• Args:
  • -type => one of 'hit', 'subject', 'query'
  • -action => one of 'exact', 'est', 'fast', 'max'
  • -context => strand/frame context string
• Note: because this comes from reported coordinates, not from counting symbol strings, it's already in terms of "logical length" 🧠
• Note: it's an alias for length() 💅

✨ num_unaligned ✨

• Title: num_unaligned
• Usage: $tiling->num_unaligned(-type=>$type)
• Function: the number of residues of sequence $type that got left unaligned by the algorithm 🙈
• Returns: scalar int
• Args:
  • -type => one of 'hit', 'subject', 'query'
  • -action => one of 'exact', 'est', 'fast', 'max'
  • -context => strand/frame context string
• Note: same deal — calculated from reported coordinates, not symbol string counts, so it's already "logical length" ✨

✨ range ✨

• Title: range
• Usage: $tiling->range(-type=>$type)
• Function: returns how far the longest tiling stretches, as ($min_coord, $max_coord) 📏
• Returns: array of two scalar integers
• Args:
  • -type => one of 'hit', 'subject', 'query'
  • -context => strand/frame context string

---

💅 ACCESSORS 💅

the little doors you knock on to get at the internals. knock politely, bestie 🚪✨

🦋 coverage_map 🦋

• Title: coverage_map
• Usage: $map = $tiling->coverage_map($type)
• Function: the property holding the coverage map that _calc_coverage_map() built — go read that one for the deets 🗺️
• Example: (blank, as is tradition)
• Returns: the value of coverage_map_$type, as an array
• Args:
  • scalar $type: one of 'hit', 'subject', 'query' — default is 'query'
• Note: getter 💜

🦋 coverage_map_as_text 🦋

• Title: coverage_map_as_text
• Usage: $tiling->coverage_map_as_text($type, $legend_flag)
• Function: formats a whole text-graphic version of the coverage map 🎨
• Returns: an array of scalar strings, ready to print
• Args:
  • $type: one of 'query', 'hit', 'subject'
  • $context: strand/frame context string
  • $legend_flag: boolean — adds a legend showing the actual interval coordinates for every component interval and hsp (in the $type sequence context) 🏷️
• Example: print $tiling->coverage_map_as_text('query',1);

🦋 hit 🦋

• Title: hit
• Usage: $tiling->hit
• Function: (no description given, she's mysterious like that 💀)
• Example: (none)
• Returns: the HitI object that's tied to the invocant 💖
• Args: none
• Note: getter only 🫶

🦋 hsps 🦋

• Title: hsps
• Usage: $tiling->hsps()
• Function: the container holding the HSP objects attached to the invocant 📦
• Example: (empty)
• Returns: an array of the hsps hanging out with the hit
• Args: on set, the new value (an arrayref or undef, optional)

🦋 contexts 🦋

• Title: contexts
• Usage:

@contexts = $tiling->context($type) or
@indices  = $tiling->context($type, $context)

• Function: pulls the set of contexts available in the hit, or the indices of hsps that have the context you named (those are integer indices for the array that $self->hsps returns) 🔍
• Returns: an array of scalar context strings, or an array of scalar positive integers — and undef if there are no hsps in that given context 😭
• Args:
  • $type: one of 'query', 'hit', 'subject'
  • optional $context: context string

🦋 mapping 🦋

• Title: mapping
• Usage: $tiling->mapping($type)
• Function: gets the mapping coefficient for the sequence type, based on whatever algorithm is underneath 👑
• Returns: scalar integer (the mapping coefficient)
• Args:
  • $type: one of 'query', 'hit', 'subject'
• Note: getter only — it gets set in the constructor 🔒

🦋 default_context 🦋

• Title: default_context
• Usage: $tiling->default_context($type)
• Function: gets the default strand/frame context string for the sequence type, based on the underlying algorithm 🌈
• Returns: scalar string (the context string)
• Args:
  • $type: one of 'query', 'hit', 'subject'
• Note: getter only — set in the constructor 🔒

🦋 algorithm 🦋

• Title: algorithm
• Usage: $tiling->algorithm
• Function: gets the algorithm name tied to the invocant's hit object 🧠
• Returns: scalar string
• Args: none
• Note: getter only — set in the constructor 🔒

🔒 PRIVATE" METHODS 🔒

Okay bestie, listen — everything in this section is private. Like, behind-the-velvet-rope private. It's the backstage of the tiling show, and you're only here because you're cool. Don't go calling these in your own code unless you enjoy chaos. 💅

---

🧮 Calculators

Peep Bio::Search::Tiling::MapTileUtils if you want the lower-level calculation methods — that's where the actual math goblins live. ✨

_calc_coverage_map

• Title — _calc_coverage_map
• Usage — $tiling->_calc_coverage_map($type)
• Function — Calculates the coverage map for the object's associated hit from the perspective of the desired $type (see Args:) and sets the coverage_map() property 🌸
• Returns — True on success 💖
• Args — optional scalar $type: one of 'hit'|'subject'|'query'; default is 'query'
• Note — The "coverage map" is an array with the following format:

( [ $component_interval => [ @containing_hsps ] ], ... ),

where $component_interval is a closed interval (see DESCRIPTION) of the form [$a0, $a1] with $a0 <= $a1, and @containing_hsps is an array of all HspI objects in the hit which completely contain the $component_interval. The set of $component_interval's is a disjoint decomposition of the minimum set of minimal intervals that completely cover the hit's HSPs (from the perspective of the $type)

• Note — This calculates the map for all strand/frame contexts available in the hit 🌈

_calc_stats

• Title — _calc_stats
• Usage — $tiling->_calc_stats($type, $action, $context)
• Function — Calculates [estimated] tiling statistics (identities, conserved sites length) and sets the public accessors 📊
• Returns — True on success
• Args — scalar $type: one of 'hit', 'subject', 'query'; default is 'query'
  • optional scalar $action: requests calculation method — currently one of 'exact', 'est', 'fast', 'max'
  • option scalar $context: strand/frame context string
• Note — Action: The statistics are calculated by summing quantities over the disjoint component intervals, taking into account coverage of those intervals by multiple HSPs. The action tells the algorithm how to obtain those quantities —
  • 'exact' will use Bio::Search::HSP::HSPI::matches to count the appropriate segment of the homology string;
  • 'est' will estimate the statistics by multiplying the fraction of the HSP overlapped by the component interval (see MapTileUtils) by the BLAST-reported identities/postives (this may be convenient for BLAST summary report formats)
  • * Both exact and est take the average over the number of HSPs that overlap the component interval.
  • 'max' uses the exact method to calculate the statistics, and returns only the maximum identites/positives over overlapping HSP for the component interval. No averaging is involved here.
  • 'fast' doesn't involve tiling at all (hence the name), but it seems like a very good estimate, and uses only reported values, and so does not require sequence data. It calculates an average of reported identities, conserved sites, and lengths, over unmodified hsps in the hit, weighted by the length of the hsps.

---

🛠️ Tiling Helper Methods

_make_tiling_iterator

• Title — _make_tiling_iterator
• Usage — $self->_make_tiling_iterator($type)
• Function — Create an iterator code ref that will step through all minimal combinations of HSPs that produce complete coverage of the $type ('hit', 'subject', 'query') sequence, and set the correct iterator property of the invocant 🦋
• Example —
• Returns — The iterator
• Args — scalar $type, one of 'hit', 'subject', 'query'; default is 'query'

_tiling_iterator

• Title — _tiling_iterator
• Usage — $tiling->_tiling_iterator($type,$context)
• Function — Retrieve the tiling iterator coderef for the requested $type ('hit', 'subject', 'query') ✨
• Example —
• Returns — coderef to the desired iterator
• Args — scalar $type, one of 'hit', 'subject', 'query'; default is 'query'
  • option scalar $context: strand/frame context string
• Note — getter only 👑

---

🏗️ Construction Helper Methods

Also go say hi to Bio::Search::Tiling::MapTileUtils. 🫶

_make_context_key

• Title — _make_context_key
• Alias — _context
• Usage — $tiling->_make_context_key(-strand => $strand, -frame => $frame)
• Function — create a string indicating strand/frame context; serves as component of memoizing hash keys 🔑
• Returns — scalar string
• Args —
  • -type => one of ('query', 'hit', 'subject')
  • -strand => one of (1,0,-1)
  • -frame => one of (-2, 1, 0, 1, -2)
  • called w/o args: returns 'all'

_context

• Title — _context
• Alias — _make_context_key
• Usage — $tiling->_make_context_key(-strand => $strand, -frame => $frame)
• Function — create a string indicating strand/frame context; serves as component of memoizing hash keys 🔑
• Returns — scalar string
• Args —
  • -type => one of ('query', 'hit', 'subject')
  • -strand => one of (1,0,-1)
  • -frame => one of (-2, 1, 0, 1, -2)
  • called w/o args: returns 'all'

---

✅ Predicates

Most based on a reading of the algorithm name with a configuration lookup. ✨

• _has_sequence_data()
• _has_logical_length()
• _has_strand()
• _has_frame()

---

🔐 Private Accessors

_contig_intersection

• Title — _contig_intersection
• Usage — $tiling->_contig_intersection($type)
• Function — Return the minimal set of $type coordinate intervals covered by the invocant's HSPs 🌸
• Returns — array of intervals (2-member arrayrefs; see MapTileUtils)
• Args — scalar $type: one of 'query', 'hit', 'subject'

_reported_length

• Title — _reported_length
• Usage — $tiling->_reported_length($type)
• Function — Get the total length of the seq $type for the invocant's hit object, as reported by (not calculated from) the input data file 📏
• Returns — scalar int
• Args — scalar $type: one of 'query', 'hit', 'subject'
• Note — This is kludgy; the hit object does not currently maintain accessors for these values, but the hsps possess these attributes. This is a wrapper that allows a consistent access method in the MapTiling code. 💀
• Note — Since this number is based on a reported length, it is already a "logical length". 🧠

---

And that's a wrap on the whole page, bestie!! 🎀 This absolute icon of a manpage was shipped with perl v5.32.1 and stamped with the date 2021-08-15 — literally vintage in internet years and still serving main character energy. Go forth and tile those HSPs, no cap. 💖✨🦋