.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::Search::Tiling::MapTiling 3pm"
.TH Bio::Search::Tiling::MapTiling 3pm "2021-08-15" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::Search::Tiling::MapTiling \- An implementation of an HSP tiling
algorithm, with methods to obtain frequently\-requested statistics
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& # 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(\*(Aqquery\*(Aq);
\& $subject_length = $tiling\->length(\*(Aqsubject\*(Aq); # or...
\& $subject_length = $tiling\->length(\*(Aqhit\*(Aq);
\&
\& # get a visual on the coverage map
\& print $tiling\->coverage_map_as_text(\*(Aqquery\*(Aq,$context,\*(AqLEGEND\*(Aq);
\&
\& # tilings
\& $context = $tiling\->_context( \-type => \*(Aqsubject\*(Aq, \-strand=> 1, \-frame=>1);
\& @covering_hsps_for_subject = $tiling\->next_tiling(\*(Aqsubject\*(Aq,$context);
\& $context = $tiling\->_context( \-type => \*(Aqquery\*(Aq, \-strand=> \-1, \-frame=>0);
\& @covering_hsps_for_query   = $tiling\->next_tiling(\*(Aqquery\*(Aq, $context);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Frequently, users want to use a set of high-scoring pairs (HSPs)
obtained from a \s-1BLAST\s0 or other search to assess the overall level of
identity, conservation, or coverage represented by matches between a
subject and a query sequence. Because a set of HSPs frequently
describes multiple overlapping sequence fragments, a simple summation of
statistics over the HSPs will generally overestimate those
statistics. To obtain an accurate estimate of global hit statistics, a
\&'tiling' of HSPs onto either the subject or the query sequence must be
performed, in order to properly correct for this.
.PP
This module will execute a tiling algorithm on a given hit based on an
interval decomposition I'm calling the \*(L"coverage map\*(R". Internal object
methods compute the various statistics, which are then stored in
appropriately-named public object attributes. See
Bio::Search::Tiling::MapTileUtils for more info on the algorithm.
.SS "\s-1STRAND/FRAME CONTEXTS\s0"
.IX Subsection "STRAND/FRAME CONTEXTS"
In \s-1BLASTX, TBLASTN,\s0 and \s-1TBLASTX\s0 reports, strand and frame information
are reported for the query, subject, or query and subject,
respectively, for each \s-1HSP.\s0 Tilings for these sequence types are only
meaningful when they include HSPs in the same strand and frame, or 
\&\*(L"context\*(R". So, in these situations, the context must be specified
in the method calls or the methods will throw.
.PP
Contexts are specified as strings: \f(CW\*(C`[ \*(Aqall\*(Aq | [m|p][_|0|1|2] ]\*(C'\fR, where
\&\f(CW\*(C`all\*(C'\fR = all HSPs (will throw if context must be specified), \f(CW\*(C`m\*(C'\fR = minus
strand, \f(CW\*(C`p\*(C'\fR = plus strand, and \f(CW\*(C`_\*(C'\fR = no frame info, \f(CW\*(C`0,1,2\*(C'\fR = respective
(absolute) frame. The \*(L"_make_context_key\*(R" method will convert a (strand,
frame) specification to a context string, e.g.:
.PP
.Vb 1
\&    $context = $self\->_context(\-type=>\*(Aqquery\*(Aq, \-strand=>\-1, \-frame=>\-2);
.Ve
.PP
returns \f(CW\*(C`m2\*(C'\fR.
.PP
The contexts present among the HSPs in a hit are identified and stored
for convenience upon object construction. These are accessed off the
object with the \*(L"contexts\*(R" method. If contexts don't apply for the
given report, this returns \f(CW\*(C`(\*(Aqall\*(Aq)\*(C'\fR.
.SH "TILED ALIGNMENTS"
.IX Header "TILED ALIGNMENTS"
The experimental method \*(L"get_tiled_alns\*(R" in \s-1ALIGNMENTS\s0 will use a tiling
to concatenate tiled hsps into a series of Bio::SimpleAlign
objects:
.PP
.Vb 1
\& @alns = $tiling\->get_tiled_alns($type, $context);
.Ve
.PP
Each alignment contains two sequences with ids 'query' and 'subject',
and consists of a concatenation of tiling HSPs which overlap or are
directly adjacent. The alignment are returned in \f(CW$type\fR sequence
order. When HSPs overlap, the alignment sequence is taken from the \s-1HSP\s0
which comes first in the coverage map array.
.PP
The sequences in each alignment contain features (even though they are
Bio::LocatableSeq objects) which map the original query/subject
coordinates to the new alignment sequence coordinates. You can
determine the original \s-1BLAST\s0 fragments this way:
.PP
.Vb 10
\& $aln = ($tiling\->get_tiled_alns)[0];
\& $qseq = $aln\->get_seq_by_id(\*(Aqquery\*(Aq);
\& $hseq = $aln\->get_seq_by_id(\*(Aqsubject\*(Aq);
\& foreach my $feat ($qseq\->get_SeqFeatures) {
\&    $org_start = ($feat\->get_tag_values(\*(Aqquery_start\*(Aq))[0];
\&    $org_end = ($feat\->get_tag_values(\*(Aqquery_end\*(Aq))[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(\*(Aqsubject_start\*(Aq))[0];
\&    $org_end = ($feat\->get_tag_values(\*(Aqsubject_end\*(Aq))[0];
\&    # original fragment as represented in the tiled alignment:
\&    $org_fragment = $feat\->seq;
\& }
.Ve
.SH "DESIGN NOTE"
.IX Header "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
the subject perspective is also desired), and then only when a
statistic is first accessed. Afterward, the map and/or any statistic
is read from storage. So feel free to call the statistic methods
frequently if it suits you.
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "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.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
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.
.SS "Reporting Bugs"
.IX Subsection "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:
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR \- Mark A. Jensen"
.IX Header "AUTHOR - Mark A. Jensen"
Email maj \-at\- fortinbras \-dot\- us
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.SS "new"
.IX Subsection "new"
.Vb 10
\& 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; }
.Ve
.SH "TILING ITERATORS"
.IX Header "TILING ITERATORS"
.SS "next_tiling"
.IX Subsection "next_tiling"
.Vb 8
\& Title   : next_tiling
\& Usage   : @hsps = $self\->next_tiling($type);
\& Function: Obtain a tiling: a minimal set of HSPs covering the $type
\&           (\*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq) sequence
\& Example :
\& Returns : an array of HSPI objects
\& Args    : scalar $type: one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq, with
\&           \*(Aqsubject\*(Aq an alias for \*(Aqhit\*(Aq
.Ve
.SS "rewind_tilings"
.IX Subsection "rewind_tilings"
.Vb 7
\& 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 \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq;
\&           default is \*(Aqquery\*(Aq
.Ve
.SH "ALIGNMENTS"
.IX Header "ALIGNMENTS"
.SS "\fBget_tiled_alns()\fP"
.IX Subsection "get_tiled_alns()"
.Vb 10
\& 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 \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
\&           default is \*(Aqquery\*(Aq
\&           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 \*(Aqquery\*(Aq and \*(Aqsubject\*(Aq, and each sequence 
\&           possesses SeqFeatures that map the original query or subject 
\&           coordinates to the sequence coordinates in the tiled alignment.
.Ve
.SH "STATISTICS"
.IX Header "STATISTICS"
.SS "identities"
.IX Subsection "identities"
.Vb 11
\& Title   : identities
\& Usage   : $tiling\->identities($type, $action, $context)
\& Function: Retrieve the calculated number of identities for the invocant
\& Example : 
\& Returns : value of identities (a scalar)
\& Args    : scalar $type: one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
\&           default is \*(Aqquery\*(Aq
\&           option scalar $action: one of \*(Aqexact\*(Aq, \*(Aqest\*(Aq, \*(Aqfast\*(Aq, \*(Aqmax\*(Aq
\&           default is \*(Aqexact\*(Aq
\&           option scalar $context: strand/frame context string
\& Note    : getter only
.Ve
.SS "conserved"
.IX Subsection "conserved"
.Vb 11
\& Title   : conserved
\& Usage   : $tiling\->conserved($type, $action)
\& Function: Retrieve the calculated number of conserved sites for the invocant
\& Example : 
\& Returns : value of conserved (a scalar)
\& Args    : scalar $type: one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
\&           default is \*(Aqquery\*(Aq
\&           option scalar $action: one of \*(Aqexact\*(Aq, \*(Aqest\*(Aq, \*(Aqfast\*(Aq, \*(Aqmax\*(Aq
\&           default is \*(Aqexact\*(Aq
\&           option scalar $context: strand/frame context string
\& Note    : getter only
.Ve
.SS "length"
.IX Subsection "length"
.Vb 12
\& Title   : length
\& Usage   : $tiling\->length($type, $action, $context)
\& Function: Retrieve the total length of aligned residues for 
\&           the seq $type
\& Example : 
\& Returns : value of length (a scalar)
\& Args    : scalar $type: one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
\&           default is \*(Aqquery\*(Aq
\&           option scalar $action: one of \*(Aqexact\*(Aq, \*(Aqest\*(Aq, \*(Aqfast\*(Aq, \*(Aqmax\*(Aq
\&           default is \*(Aqexact\*(Aq
\&           option scalar $context: strand/frame context string
\& Note    : getter only
.Ve
.SS "frac"
.IX Subsection "frac"
.Vb 10
\& Title   : frac
\& Usage   : $tiling\->frac($type, $denom, $action, $context, $method)
\& Function: Return the fraction of sequence length consisting
\&           of desired kinds of pairs (given by $method), 
\&           with respect to $denom
\& Returns : scalar float
\& Args    : \-type => one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
\&           \-denom => one of \*(Aqtotal\*(Aq, \*(Aqaligned\*(Aq
\&           \-action => one of \*(Aqexact\*(Aq, \*(Aqest\*(Aq, \*(Aqfast\*(Aq, \*(Aqmax\*(Aq
\&           \-context => strand/frame context string
\&           \-method => one of \*(Aqidentical\*(Aq, \*(Aqconserved\*(Aq
\& Note    : $denom == \*(Aqaligned\*(Aq, return desired_stat/num_aligned
\&           $denom == \*(Aqtotal\*(Aq, return desired_stat/_reported_length
\&             (i.e., length of the original input sequences)
\& Note    : In keeping with the spirit of Bio::Search::HSP::HSPI, 
\&           reported lengths of translated dna are reduced by 
\&           a factor of 3, to provide fractions relative to 
\&           amino acid coordinates.
.Ve
.SS "frac_identical"
.IX Subsection "frac_identical"
.Vb 10
\& Title   : frac_identical
\& Usage   : $tiling\->frac_identical($type, $denom, $action, $context)
\& Function: Return the fraction of sequence length consisting
\&           of identical pairs, with respect to $denom
\& Returns : scalar float
\& Args    : \-type => one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
\&           \-denom => one of \*(Aqtotal\*(Aq, \*(Aqaligned\*(Aq
\&           \-action => one of \*(Aqexact\*(Aq, \*(Aqest\*(Aq, \*(Aqfast\*(Aq, \*(Aqmax\*(Aq
\&           \-context => strand/frame context string
\& Note    : $denom == \*(Aqaligned\*(Aq, return conserved/num_aligned
\&           $denom == \*(Aqtotal\*(Aq, return conserved/_reported_length
\&             (i.e., length of the original input sequences)
\& Note    : In keeping with the spirit of Bio::Search::HSP::HSPI, 
\&           reported lengths of translated dna are reduced by 
\&           a factor of 3, to provide fractions relative to 
\&           amino acid coordinates. 
\& Note    : This an alias that calls frac()
.Ve
.SS "frac_conserved"
.IX Subsection "frac_conserved"
.Vb 10
\& Title   : frac_conserved
\& Usage   : $tiling\->frac_conserved($type, $denom, $action, $context)
\& Function: Return the fraction of sequence length consisting
\&           of conserved pairs, with respect to $denom
\& Returns : scalar float
\& Args    : \-type => one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
\&           \-denom => one of \*(Aqtotal\*(Aq, \*(Aqaligned\*(Aq
\&           \-action => one of \*(Aqexact\*(Aq, \*(Aqest\*(Aq, \*(Aqfast\*(Aq, \*(Aqmax\*(Aq
\&           \-context => strand/frame context string
\& Note    : $denom == \*(Aqaligned\*(Aq, return conserved/num_aligned
\&           $denom == \*(Aqtotal\*(Aq, return conserved/_reported_length
\&             (i.e., length of the original input sequences)
\& Note    : In keeping with the spirit of Bio::Search::HSP::HSPI, 
\&           reported lengths of translated dna are reduced by 
\&           a factor of 3, to provide fractions relative to 
\&           amino acid coordinates. 
\& Note    : This an alias that calls frac()
.Ve
.SS "frac_aligned"
.IX Subsection "frac_aligned"
.Vb 12
\& Title   : frac_aligned
\& Aliases : frac_aligned_query \- frac_aligned(\-type=>\*(Aqquery\*(Aq,...)
\&           frac_aligned_hit   \- frac_aligned(\-type=>\*(Aqhit\*(Aq,...)
\& Usage   : $tiling\->frac_aligned(\-type=>$type,
\&                                 \-action=>$action,
\&                                 \-context=>$context)
\& Function: Return the fraction of input sequence length
\&           that was aligned by the algorithm
\& Returns : scalar float
\& Args    : \-type => one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
\&           \-action => one of \*(Aqexact\*(Aq, \*(Aqest\*(Aq, \*(Aqfast\*(Aq, \*(Aqmax\*(Aq
\&           \-context => strand/frame context string
.Ve
.SS "num_aligned"
.IX Subsection "num_aligned"
.Vb 12
\& Title   : num_aligned
\& Usage   : $tiling\->num_aligned(\-type=>$type)
\& Function: Return the number of residues of sequence $type
\&           that were aligned by the algorithm
\& Returns : scalar int
\& Args    : \-type => one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
\&           \-action => one of \*(Aqexact\*(Aq, \*(Aqest\*(Aq, \*(Aqfast\*(Aq, \*(Aqmax\*(Aq
\&           \-context => strand/frame context string
\& Note    : Since this is calculated from reported coordinates,
\&           not symbol string counts, it is already in terms of
\&           "logical length"
\& Note    : Aliases length()
.Ve
.SS "num_unaligned"
.IX Subsection "num_unaligned"
.Vb 11
\& Title   : num_unaligned
\& Usage   : $tiling\->num_unaligned(\-type=>$type)
\& Function: Return the number of residues of sequence $type
\&           that were left unaligned by the algorithm
\& Returns : scalar int
\& Args    : \-type => one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
\&           \-action => one of \*(Aqexact\*(Aq, \*(Aqest\*(Aq, \*(Aqfast\*(Aq, \*(Aqmax\*(Aq
\&           \-context => strand/frame context string
\& Note    : Since this is calculated from reported coordinates,
\&           not symbol string counts, it is already in terms of
\&           "logical length"
.Ve
.SS "range"
.IX Subsection "range"
.Vb 7
\& Title   : range
\& Usage   : $tiling\->range(\-type=>$type)
\& Function: Returns the extent of the longest tiling
\&           as ($min_coord, $max_coord)
\& Returns : array of two scalar integers
\& Args    : \-type => one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
\&           \-context => strand/frame context string
.Ve
.SH "ACCESSORS"
.IX Header "ACCESSORS"
.SS "coverage_map"
.IX Subsection "coverage_map"
.Vb 10
\& Title   : coverage_map
\& Usage   : $map = $tiling\->coverage_map($type)
\& Function: Property to contain the coverage map calculated
\&           by _calc_coverage_map() \- see that for 
\&           details
\& Example : 
\& Returns : value of coverage_map_$type as an array
\& Args    : scalar $type: one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
\&           default is \*(Aqquery\*(Aq
\& Note    : getter
.Ve
.SS "coverage_map_as_text"
.IX Subsection "coverage_map_as_text"
.Vb 11
\& Title   : coverage_map_as_text
\& Usage   : $tiling\->coverage_map_as_text($type, $legend_flag)
\& Function: Format a text\-graphic representation of the
\&           coverage map
\& Returns : an array of scalar strings, suitable for printing
\& Args    : $type: one of \*(Aqquery\*(Aq, \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq
\&           $context: strand/frame context string
\&           $legend_flag: boolean; add a legend indicating
\&            the actual interval coordinates for each component
\&            interval and hsp (in the $type sequence context)
\& Example : print $tiling\->coverage_map_as_text(\*(Aqquery\*(Aq,1);
.Ve
.SS "hit"
.IX Subsection "hit"
.Vb 7
\& Title   : hit
\& Usage   : $tiling\->hit
\& Function: 
\& Example : 
\& Returns : The HitI object associated with the invocant
\& Args    : none
\& Note    : getter only
.Ve
.SS "hsps"
.IX Subsection "hsps"
.Vb 6
\& Title   : hsps
\& Usage   : $tiling\->hsps()
\& Function: Container for the HSP objects associated with invocant
\& Example : 
\& Returns : an array of hsps associated with the hit
\& Args    : on set, new value (an arrayref or undef, optional)
.Ve
.SS "contexts"
.IX Subsection "contexts"
.Vb 11
\& Title   : contexts
\& Usage   : @contexts = $tiling\->context($type) or
\&           @indices = $tiling\->context($type, $context)
\& Function: Retrieve the set of available contexts in the hit,
\&           or the indices of hsps having the given context
\&           (integer indices for the array returned by $self\->hsps)
\& Returns : array of scalar context strings or 
\&           array of scalar positive integers
\&           undef if no hsps in given context
\& Args    : $type: one of \*(Aqquery\*(Aq, \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq
\&           optional $context: context string
.Ve
.SS "mapping"
.IX Subsection "mapping"
.Vb 7
\& Title   : mapping
\& Usage   : $tiling\->mapping($type)
\& Function: Retrieve the mapping coefficient for the sequence type
\&           based on the underlying algorithm
\& Returns : scalar integer (mapping coefficient)
\& Args    : $type: one of \*(Aqquery\*(Aq, \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq
\& Note    : getter only (set in constructor)
.Ve
.SS "default_context"
.IX Subsection "default_context"
.Vb 7
\& Title   : default_context
\& Usage   : $tiling\->default_context($type)
\& Function: Retrieve the default strand/frame context string
\&           for the sequence type based on the underlying algorithm
\& Returns : scalar string (context string)
\& Args    : $type: one of \*(Aqquery\*(Aq, \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq
\& Note    : getter only (set in constructor)
.Ve
.SS "algorithm"
.IX Subsection "algorithm"
.Vb 7
\& Title   : algorithm
\& Usage   : $tiling\->algorithm
\& Function: Retrieve the algorithm name associated with the 
\&           invocant\*(Aqs hit object
\& Returns : scalar string 
\& Args    : none
\& Note    : getter only (set in constructor)
.Ve
.ie n .SH """PRIVATE"" METHODS"
.el .SH "``PRIVATE'' METHODS"
.IX Header "PRIVATE METHODS"
.SS "Calculators"
.IX Subsection "Calculators"
See Bio::Search::Tiling::MapTileUtils for lower level
calculation methods.
.SS "_calc_coverage_map"
.IX Subsection "_calc_coverage_map"
.Vb 10
\& Title   : _calc_coverage_map
\& Usage   : $tiling\->_calc_coverage_map($type)
\& Function: Calculates the coverage map for the object\*(Aqs 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 \*(Aqhit\*(Aq|\*(Aqsubject\*(Aq|\*(Aqquery\*(Aq
\&           default is \*(Aqquery\*(Aq
\& 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\*(Aqs is a disjoint decomposition
\&           of the minimum set of minimal intervals that completely
\&           cover the hit\*(Aqs HSPs (from the perspective of the $type)
\& Note    : This calculates the map for all strand/frame contexts available
\&           in the hit
.Ve
.SS "_calc_stats"
.IX Subsection "_calc_stats"
.Vb 10
\& 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 \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
\&           default is \*(Aqquery\*(Aq
\&           optional scalar $action: requests calculation method
\&            currently one of \*(Aqexact\*(Aq, \*(Aqest\*(Aq, \*(Aqfast\*(Aq, \*(Aqmax\*(Aq
\&           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\-\-
\&           \*(Aqexact\*(Aq will use Bio::Search::HSP::HSPI::matches
\&            to count the appropriate segment of the homology string;
\&           \*(Aqest\*(Aq 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.
\&           \*(Aqmax\*(Aq 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.
\&           \*(Aqfast\*(Aq doesn\*(Aqt 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.
.Ve
.SS "Tiling Helper Methods"
.IX Subsection "Tiling Helper Methods"
.SS "_make_tiling_iterator"
.IX Subsection "_make_tiling_iterator"
.Vb 10
\& 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 (\*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq) sequence, 
\&           and set the correct iterator property of the invocant
\& Example :
\& Returns : The iterator
\& Args    : scalar $type, one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq;
\&           default is \*(Aqquery\*(Aq
.Ve
.SS "_tiling_iterator"
.IX Subsection "_tiling_iterator"
.Vb 10
\& Title   : _tiling_iterator
\& Usage   : $tiling\->_tiling_iterator($type,$context)
\& Function: Retrieve the tiling iterator coderef for the requested 
\&           $type (\*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq)
\& Example : 
\& Returns : coderef to the desired iterator
\& Args    : scalar $type, one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
\&           default is \*(Aqquery\*(Aq
\&           option scalar $context: strand/frame context string
\& Note    : getter only
.Ve
.SS "Construction Helper Methods"
.IX Subsection "Construction Helper Methods"
See also Bio::Search::Tiling::MapTileUtils.
.SS "_make_context_key"
.IX Subsection "_make_context_key"
.Vb 10
\& 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 (\*(Aqquery\*(Aq, \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq)
\&           \-strand => one of (1,0,\-1)
\&           \-frame  => one of (\-2, 1, 0, 1, \-2)
\&           called w/o args: returns \*(Aqall\*(Aq
.Ve
.SS "_context"
.IX Subsection "_context"
.Vb 10
\& 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 (\*(Aqquery\*(Aq, \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq)
\&           \-strand => one of (1,0,\-1)
\&           \-frame  => one of (\-2, 1, 0, 1, \-2)
\&           called w/o args: returns \*(Aqall\*(Aq
.Ve
.SS "Predicates"
.IX Subsection "Predicates"
Most based on a reading of the algorithm name with a configuration lookup.
.IP "\fB_has_sequence_data()\fR" 4
.IX Item "_has_sequence_data()"
.PD 0
.IP "\fB_has_logical_length()\fR" 4
.IX Item "_has_logical_length()"
.IP "\fB_has_strand()\fR" 4
.IX Item "_has_strand()"
.IP "\fB_has_frame()\fR" 4
.IX Item "_has_frame()"
.PD
.SH "Private Accessors"
.IX Header "Private Accessors"
.SS "_contig_intersection"
.IX Subsection "_contig_intersection"
.Vb 6
\& Title   : _contig_intersection
\& Usage   : $tiling\->_contig_intersection($type)
\& Function: Return the minimal set of $type coordinate intervals
\&           covered by the invocant\*(Aqs HSPs
\& Returns : array of intervals (2\-member arrayrefs; see MapTileUtils)
\& Args    : scalar $type: one of \*(Aqquery\*(Aq, \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq
.Ve
.SS "_reported_length"
.IX Subsection "_reported_length"
.Vb 10
\& Title   : _reported_length
\& Usage   : $tiling\->_reported_length($type)
\& Function: Get the total length of the seq $type
\&           for the invocant\*(Aqs hit object, as reported
\&           by (not calculated from) the input data file
\& Returns : scalar int
\& Args    : scalar $type: one of \*(Aqquery\*(Aq, \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq
\& 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".
.Ve