.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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::TilingI 3pm"
.TH Bio::Search::Tiling::TilingI 3pm "2020-10-28" "perl v5.30.3" "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::TilingI \- Abstract interface for an HSP tiling module
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Not used directly. Useful \s-1POD\s0 here for developers, however.
.PP
The interface is designed to make the following code conversion as
simple as possible:
.PP
From:
.PP
.Vb 5
\& # Bio::Search::SearchUtils\-based
\& while ( local $_ = $result\->next_hit ) {
\&    printf( "E\-value: %g; Fraction aligned: %f; Number identical: %d\en",
\&      $hit\->significance, $hit\->frac_aligned_query, $hit\->num_identical);
\& }
.Ve
.PP
To:
.PP
.Vb 6
\& # TilingI\-based
\& while ( local $_ = $result\->next_hit ) {
\&    my $tiling = Bio::Search::Tiling::MyTiling($_);
\&    printf( "E\-value: %g; Fraction aligned: %f; Number identical: %d\en",
\&      $hit\->significance, $tiling\->frac_aligned_query, $tiling\->num_identical);
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides strong suggestions for any intended \s-1HSP\s0 tiling
object implementation. An object subclassing TilingI should override
the methods defined here according to their descriptions below.
.PP
See the section \s-1STATISTICS METHODS\s0 for hints on implementing methods
that are valid across different algorithms and report types.
.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@fortinbras.us
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _
.SS "\s-1STATISTICS METHODS\s0"
.IX Subsection "STATISTICS METHODS"
The tiling statistics can be thought of as global counterparts to
similar statistics defined for the individual HSPs. We therefore
prescribe definitions for many of the synonymous methods defined in
Bio::Search::HSP::HSPI.
.PP
The tiling statistics must be able to keep track of the coordinate
systems in which both the query and subject sequences exist; i.e.,
either nucleotide or amino acid. This information is typically
inferred from the name of the algorithm used to perform the original
search (contained in \f(CW\*(C`$hit_object\->algorithm\*(C'\fR). Here is a table
of algorithm information that may be useful (if you trust us).
.PP
.Vb 10
\& algorithm   query on hit   coordinates(q/h)
\& \-\-\-\-\-\-\-\-\-   \-\-\-\-\-\-\-\-\-\-\-\-   \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&  blastn      dna on dna         dna/dna
\&  blastp      aa  on aa           aa/aa
\&  blastx      xna on aa          dna/aa
\& tblastn      aa  on xna          aa/dna
\& tblastx      xna on xna         dna/dna
\&   fasta      dna on dna         dna/dna
\&   fasta      aa  on aa           aa/aa
\&   fastx      xna on aa          dna/aa
\&   fasty      xna on aa          dna/aa
\&  tfasta      aa  on xna          aa/dna
\&  tfasty      aa  on xna          aa/dna
\& megablast    dna on dna         dna/dna
\&
\&  xna: translated nucleotide data
.Ve
.PP
Statistics methods must also be aware of differences in reporting
among the algorithms. Hit attributes are not necessarily normalized
over all algorithms. Devs, please feel free to add examples to the
list below.
.IP "\s-1NCBI BLAST\s0 vs WU-BLAST (AB-BLAST) lengths" 4
.IX Item "NCBI BLAST vs WU-BLAST (AB-BLAST) lengths"
The total length of the alignment is reported differently between these two flavors. \f(CW\*(C`$hit_object\->length()\*(C'\fR will contain the number in the denominator of the stats line; i.e., 120 in
.Sp
.Vb 1
\& Identical = 34/120 Positives = 67/120
.Ve
.Sp
\&\s-1NCBI BLAST\s0 uses the total length of the query sequence as input by the user (a.k.a. \*(L"with gaps\*(R"). WU-BLAST uses the length of the query sequence actually aligned by the algorithm (a.k.a. \*(L"without gaps\*(R").
.PP
Finally, developers should remember that sequence data may or may not
be associated with the HSPs contained in the hit object. This will
typically depend on whether a full report (e.g, \f(CW\*(C`blastall \-m0\*(C'\fR) or a
summary (e.g., \f(CW\*(C`blastall \-m8\*(C'\fR) was parsed. Statistics methods that
depend directly on the sequence data will need to check that
that data is present.
.SS "identities"
.IX Subsection "identities"
.Vb 8
\& Title   : identities
\& Alias   : num_identical
\& Usage   : $num_identities = $tiling\->identities()
\& Function: Return the estimated or exact number of identities in the
\&           tiling, accounting for overlapping HSPs
\& Example : 
\& Returns : number of identical residue pairs
\& Args    :
.Ve
.SS "conserved"
.IX Subsection "conserved"
.Vb 8
\& Title   : conserved
\& Alias   : num_conserved
\& Usage   : $num_conserved = $tiling\->conserved()
\& Function: Return the estimated or exact number of conserved sites in the 
\&           tiling, accounting for overlapping HSPs
\& Example : 
\& Returns : number of conserved residue pairs
\& Args    :
.Ve
.SS "length"
.IX Subsection "length"
.Vb 6
\& Title   : length
\& Usage   : $max_length = $tiling\->length($type)
\& Function: Return the total number of residues of the subject or query
\&           sequence covered by the tiling
\& Returns : number of "logical" residues covered
\& Args    : scalar $type, one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
.Ve
.SS "frac_identical"
.IX Subsection "frac_identical"
.Vb 9
\& Title   : frac_identical
\& Usage   : $tiling\->frac_identical($type)
\& Function: Return the fraction of sequence length consisting
\&           of identical pairs
\& Returns : scalar float
\& Args    : scalar $type, one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
\& Note    : This method must take account of the $type coordinate
\&           system and the length reporting method (see STATISTICS
\&           METHODS above)
.Ve
.SS "percent_identity"
.IX Subsection "percent_identity"
.Vb 6
\& Title   : percent_identity
\& Usage   : $tiling\->percent_identity($type)
\& Function: Return the fraction of sequence length consisting
\&           of identical pairs as a percentage
\& Returns : scalar float
\& Args    : scalar $type, one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
.Ve
.SS "frac_conserved"
.IX Subsection "frac_conserved"
.Vb 9
\& Title   : frac_conserved
\& Usage   : $tiling\->frac_conserved($type)
\& Function: Return the fraction of sequence length consisting
\&           of conserved pairs
\& Returns : scalar float
\& Args    : scalar $type, one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
\& Note    : This method must take account of the $type coordinate
\&           system and the length reporting method (see STATISTICS
\&           METHODS above)
.Ve
.SS "percent_conserved"
.IX Subsection "percent_conserved"
.Vb 6
\& Title   : percent_conserved
\& Usage   : $tiling\->percent_conserved($type)
\& Function: Return the fraction of sequence length consisting
\&           of conserved pairs as a percentage
\& Returns : scalar float
\& Args    : scalar $type, one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
.Ve
.SS "frac_aligned"
.IX Subsection "frac_aligned"
.Vb 9
\& Title   : frac_aligned
\& Usage   : $tiling\->frac_aligned($type)
\& Function: Return the fraction of B<input> sequence length consisting
\&           that was aligned by the algorithm
\& Returns : scalar float
\& Args    : scalar $type, one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
\& Note    : This method must take account of the $type coordinate
\&           system and the length reporting method (see STATISTICS
\&           METHODS above)
.Ve
.SS "range"
.IX Subsection "range"
.Vb 6
\& Title   : range
\& Usage   : $tiling\->range($type)
\& Function: Returns the extent of the longest tiling
\&           as ($min_coord, $max_coord)
\& Returns : array of two scalar integers
\& Args    : scalar $type, one of \*(Aqhit\*(Aq, \*(Aqsubject\*(Aq, \*(Aqquery\*(Aq
.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 of HSPs over 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, with
\&           \*(Aqsubject\*(Aq an alias for \*(Aqhit\*(Aq
.Ve
.SH "INFORMATIONAL ACCESSORS"
.IX Header "INFORMATIONAL ACCESSORS"
.SS "algorithm"
.IX Subsection "algorithm"
.Vb 6
\& Title   : algorithm
\& Usage   : $tiling\->algorithm
\& Function: Retrieve the algorithm name associated with the 
\&           invocant\*(Aqs hit object
\& Returns : scalar string 
\& Args    :
.Ve