Linux Certif

Toute la documentation sur la certification Linux LPI

Bio::Search::Tiling::MapTiling.3pm

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

Frequently, users want to use a set of high-scoring pairs (HSPs) obtained from a BLAST 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.

This module will execute a tiling algorithm on a given hit based on an interval decomposition I'm calling the ``coverage map''. 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.

STRAND/FRAME CONTEXTS

In BLASTX, TBLASTN, and TBLASTX reports, strand and frame information are reported for the query, subject, or query and subject, respectively, for each HSP. Tilings for these sequence types are only meaningful when they include HSPs in the same strand and frame, or ``context''. So, in these situations, the context must be specified in the method calls or the methods will throw.

Contexts are specified as strings: "[ 'all' | [m|p][_|0|1|2] ]", where "all" = all HSPs (will throw if context must be specified), "m" = minus strand, "p" = plus strand, and "_" = no frame info, "0,1,2" = respective (absolute) frame. The ``_make_context_key'' method will convert a (strand, frame) specification to a context string, e.g.:

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

returns "m2".

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 ``contexts'' method. If contexts don't apply for the given report, this returns "('all')".

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.

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. 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 of the bugs and their resolution. Bug reports can be submitted via the web:

   http://bugzilla.open-bio.org/
 
 

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'
 
 

STATISTICS

identities

  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 '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: Retrieve the calculated number of conserved sites for the invocant
  Example : 
  Returns : 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: Retrieve the total length of aligned residues for 
            the seq $type
  Example : 
  Returns : 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: 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 '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    : $denom == 'aligned', return desired_stat/num_aligned
            $denom == 'total', 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.
 
 

frac_identical

  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 'hit', 'subject', 'query'
            -denom => one of 'total', 'aligned'
            -action => one of 'exact', 'est', 'fast', 'max'
            -context => strand/frame context string
  Note    : $denom == 'aligned', return conserved/num_aligned
            $denom == 'total', 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()
 
 

frac_conserved

  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 'hit', 'subject', 'query'
            -denom => one of 'total', 'aligned'
            -action => one of 'exact', 'est', 'fast', 'max'
            -context => strand/frame context string
  Note    : $denom == 'aligned', return conserved/num_aligned
            $denom == 'total', 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()
 
 

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: Return the fraction of input sequence length
            that was aligned by the algorithm
  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: Return the number of residues of sequence $type
            that were aligned 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    : Since this is calculated from reported coordinates,
            not symbol string counts, it is already in terms of
            "logical length"
  Note    : Aliases length()
 
 

num_unaligned

  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 'hit', 'subject', 'query'
            -action => one of 'exact', 'est', 'fast', 'max'
            -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"
 
 

range

  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 'hit', 'subject', 'query'
            -context => strand/frame context string
 
 

ACCESSORS

coverage_map

  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 '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: Format a text-graphic representation of the
            coverage map
  Returns : an array of scalar strings, suitable for printing
  Args    : $type: one of 'query', 'hit', 'subject'
            $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('query',1);
 
 

hit

  Title   : hit
  Usage   : $tiling->hit
  Function: 
  Example : 
  Returns : The HitI object associated with the invocant
  Args    : none
  Note    : getter only
 
 

hsps

  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)
 
 

contexts

  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 'query', 'hit', 'subject'
            optional $context: context string
 
 

mapping

  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 'query', 'hit', 'subject'
  Note    : getter only (set in constructor)
 
 

default_context

  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 'query', 'hit', 'subject'
  Note    : getter only (set in constructor)
 
 

algorithm

  Title   : algorithm
  Usage   : $tiling->algorithm
  Function: Retrieve the algorithm name associated with the 
            invocant's hit object
  Returns : scalar string 
  Args    : none
  Note    : getter only (set in constructor)
 
 

PRIVATE METHODS

Calculators

See Bio::Search::Tiling::MapTileUtils for lower level calculation methods.

_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 : True on success
  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

See also 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".