bpp-phyl  2.1.0
Public Member Functions | Static Public Member Functions
bpp::SubstitutionMappingTools Class Reference

Provide methods to compute substitution mappings. More...

#include <Bpp/Phyl/Mapping/SubstitutionMappingTools.h>

List of all members.

Public Member Functions

 SubstitutionMappingTools ()
virtual ~SubstitutionMappingTools ()

Static Public Member Functions

static
ProbabilisticSubstitutionMapping * 		computeSubstitutionVectors (const DRTreeLikelihood &drtl, SubstitutionCount &substitutionCount, bool verbose=true) throw (Exception)
 Compute the substitutions vectors for a particular dataset using the double-recursive likelihood computation.
static
ProbabilisticSubstitutionMapping * 		computeSubstitutionVectorsNoAveraging (const DRTreeLikelihood &drtl, SubstitutionCount &substitutionCount, bool verbose=true) throw (Exception)
 Compute the substitutions vectors for a particular dataset using the double-recursive likelihood computation.
static
ProbabilisticSubstitutionMapping * 		computeSubstitutionVectorsNoAveragingMarginal (const DRTreeLikelihood &drtl, SubstitutionCount &substitutionCount, bool verbose=true) throw (Exception)
 Compute the substitutions vectors for a particular dataset using the double-recursive likelihood computation.
static
ProbabilisticSubstitutionMapping * 		computeSubstitutionVectorsMarginal (const DRTreeLikelihood &drtl, SubstitutionCount &substitutionCount, bool verbose=true) throw (Exception)
 Compute the substitutions vectors for a particular dataset using the double-recursive likelihood computation.
static
ProbabilisticSubstitutionMapping * 		computeOneJumpProbabilityVectors (const DRTreeLikelihood &drtl, bool verbose=true) throw (Exception)
 This method computes for each site and for each branch the probability that at least one jump occurred.
static void writeToStream (const ProbabilisticSubstitutionMapping &substitutions, const SiteContainer &sites, size_t type, std::ostream &out) throw (IOException)
 Write the substitutions vectors to a stream.
static void readFromStream (std::istream &in, ProbabilisticSubstitutionMapping &substitutions, size_t type) throw (IOException)
 Read the substitutions vectors from a stream.
static std::vector< double > computeTotalSubstitutionVectorForSite (const SubstitutionMapping &smap, size_t siteIndex)
 Sum all type of substitutions for each branch of a given position (specified by its index).
static double computeNormForSite (const SubstitutionMapping &smap, size_t siteIndex)
 Compute the norm of a substitution vector for a given position (specified by its index).
static std::vector< double > computeSumForBranch (const SubstitutionMapping &smap, size_t branchIndex)
 Sum all substitutions for each type of a given branch (specified by its index).
static std::vector< double > computeSumForSite (const SubstitutionMapping &smap, size_t siteIndex)
 Sum all substitutions for each type of a given site (specified by its index).

Detailed Description

Provide methods to compute substitution mappings.

For now, only 4 methods are implemented, and provide probabilistic substitution mappings.

See: Dutheil J, Pupko T, Jean-Marie A, Galtier N. A model-based approach for detecting coevolving positions in a molecule. Mol Biol Evol. 2005 Sep;22(9):1919-28. Epub 2005 Jun 8.

Author:
Julien Dutheil

Definition at line 63 of file SubstitutionMappingTools.h.

Constructor & Destructor Documentation

bpp::SubstitutionMappingTools::SubstitutionMappingTools ( ) [inline]

Definition at line 66 of file SubstitutionMappingTools.h.

virtual bpp::SubstitutionMappingTools::~SubstitutionMappingTools ( ) [inline, virtual]

Definition at line 67 of file SubstitutionMappingTools.h.

Member Function Documentation

double SubstitutionMappingTools::computeNormForSite ( const SubstitutionMapping &  smap,
size_t  siteIndex 
) [static]

Compute the norm of a substitution vector for a given position (specified by its index).

The norm is computed as: $ N_i = \sqrt{\left(\sum_l {\left(\sum_t n_{l, i, t}\right)}^2\right)}$, where $n_{l, i, t}$ is the number of substitutions of type t on site i on branch l, obtained using the () operator for the SubstitutionMapping object.

Parameters:
smapThe substitution map to use.
siteIndexThe index of the substitution vector for which the norm should be computed.
Returns:
The norm of the substitution vector.

Definition at line 967 of file SubstitutionMappingTools.cpp.

References bpp::SubstitutionMapping::getNumberOfBranches(), and bpp::SubstitutionMapping::getNumberOfSubstitutionTypes().

static ProbabilisticSubstitutionMapping* bpp::SubstitutionMappingTools::computeOneJumpProbabilityVectors ( const DRTreeLikelihood &  drtl,
bool  verbose = true 
) throw (Exception) [inline, static]

This method computes for each site and for each branch the probability that at least one jump occurred.

Here 'jump' refer to a change in the model state. Depending on the model, this might not be the same as a substitution (an alphabet state change).

Definition at line 162 of file SubstitutionMappingTools.h.

References computeSubstitutionVectors().

ProbabilisticSubstitutionMapping * SubstitutionMappingTools::computeSubstitutionVectors ( const DRTreeLikelihood &  drtl,
SubstitutionCount &  substitutionCount,
bool  verbose = true 
) throw (Exception) [static]

Compute the substitutions vectors for a particular dataset using the double-recursive likelihood computation.

Parameters:
drtlA DRTreeLikelihood object.
substitutionCountThe SubstitutionCount to use.
verbosePrint info to screen.
Returns:
A vector of substitutions vectors (one for each site).
Exceptions:
ExceptionIf the likelihood object is not initialized.

Definition at line 58 of file SubstitutionMappingTools.cpp.

References bpp::ApplicationTools::displayGauge(), bpp::ApplicationTools::displayTask(), bpp::ApplicationTools::displayTaskDone(), bpp::DiscreteDistribution::getCategories(), bpp::Node::getDistanceToFather(), bpp::Node::getFather(), bpp::Node::getId(), bpp::TreeLikelihood::ConstBranchModelDescription::getModel(), bpp::TreeLikelihood::ConstBranchModelDescription::getNewSiteIterator(), bpp::DiscreteDistribution::getNumberOfCategories(), bpp::Node::getNumberOfSons(), bpp::DiscreteDistribution::getProbabilities(), bpp::DiscreteDistribution::getProbability(), bpp::Node::getSon(), bpp::Node::hasFather(), bpp::TreeLikelihood::ConstBranchModelIterator::hasNext(), bpp::ApplicationTools::message, bpp::TreeLikelihood::ConstBranchModelIterator::next(), and bpp::Matrix< Scalar >::resize().

Referenced by computeOneJumpProbabilityVectors().

ProbabilisticSubstitutionMapping * SubstitutionMappingTools::computeSubstitutionVectorsMarginal ( const DRTreeLikelihood &  drtl,
SubstitutionCount &  substitutionCount,
bool  verbose = true 
) throw (Exception) [static]

Compute the substitutions vectors for a particular dataset using the double-recursive likelihood computation.

The marginal probability is used for weighting, i.e. the product of probabilities for the pair.

This function is mainly for testing purpose (see Dutheil et al. 2005). For practical use, consider using the 'getSubstitutionVectors' method instead.

Parameters:
drtlA DRTreeLikelihood object.
substitutionCountThe substitutionsCount to use.
verbosePrint info to screen.
Returns:
A vector of substitutions vectors (one for each site).
Exceptions:
ExceptionIf the likelihood object is not initialized.

Definition at line 746 of file SubstitutionMappingTools.cpp.

References bpp::ApplicationTools::displayGauge(), bpp::ApplicationTools::displayTask(), bpp::ApplicationTools::displayTaskDone(), bpp::DiscreteDistribution::getCategories(), bpp::Node::getDistanceToFather(), bpp::Node::getFather(), bpp::Node::getId(), bpp::TreeLikelihood::ConstBranchModelDescription::getModel(), bpp::TreeLikelihood::ConstBranchModelDescription::getNewSiteIterator(), bpp::DiscreteDistribution::getNumberOfCategories(), bpp::DRTreeLikelihoodTools::getPosteriorProbabilitiesForEachStateForEachRate(), bpp::DiscreteDistribution::getProbabilities(), bpp::ApplicationTools::message, and bpp::Matrix< Scalar >::resize().

ProbabilisticSubstitutionMapping * SubstitutionMappingTools::computeSubstitutionVectorsNoAveraging ( const DRTreeLikelihood &  drtl,
SubstitutionCount &  substitutionCount,
bool  verbose = true 
) throw (Exception) [static]

Compute the substitutions vectors for a particular dataset using the double-recursive likelihood computation.

In this method, substitution counts are computed using the pair of ancestral states with maximum likelihood. This is a kind of joint-pair ancestral reconstruction, as in Galtier and Boursot (1998). This reconstruction possibly takes into account several rate classes, and substitution counts are averaged over all rate classes, weighted by their conditional likelihood.

This function is mainly for testing purpose (see Dutheil et al. 2005). For practical use, consider using the 'getSubstitutionVectors' method instead.

Parameters:
drtlA DRTreeLikelihood object.
substitutionCountThe substitutionsCount to use.
verbosePrint info to screen.
Returns:
A vector of substitutions vectors (one for each site).
Exceptions:
ExceptionIf the likelihood object is not initialized.

Definition at line 350 of file SubstitutionMappingTools.cpp.

References bpp::ApplicationTools::displayGauge(), bpp::ApplicationTools::displayTask(), bpp::ApplicationTools::displayTaskDone(), bpp::MatrixTools::fill(), bpp::DiscreteDistribution::getCategories(), bpp::Node::getDistanceToFather(), bpp::Node::getFather(), bpp::Node::getId(), bpp::TreeLikelihood::ConstBranchModelDescription::getModel(), bpp::TreeLikelihood::ConstBranchModelDescription::getNewSiteIterator(), bpp::DiscreteDistribution::getNumberOfCategories(), bpp::Node::getNumberOfSons(), bpp::DiscreteDistribution::getProbability(), bpp::Node::getSon(), bpp::Node::hasFather(), bpp::TreeLikelihood::ConstBranchModelIterator::hasNext(), bpp::ApplicationTools::message, bpp::TreeLikelihood::ConstBranchModelIterator::next(), bpp::Matrix< Scalar >::resize(), and bpp::MatrixTools::whichMax().

ProbabilisticSubstitutionMapping * SubstitutionMappingTools::computeSubstitutionVectorsNoAveragingMarginal ( const DRTreeLikelihood &  drtl,
SubstitutionCount &  substitutionCount,
bool  verbose = true 
) throw (Exception) [static]

Compute the substitutions vectors for a particular dataset using the double-recursive likelihood computation.

In this method, all ancestral states are estimated using marginal likelihoods, putatively intregated over several rate classes. For each branch, the number of substitution given marginal states is used. This method, used with a SimpleSubstitutionCount objet is equivalent to Tufféry and Darlu's (2000) computation of substitution vectors.

Use with another substitution count objet is in most cases irrelevent.

Parameters:
drtlA DRTreeLikelihood object.
substitutionCountThe substitutionsCount to use.
verbosePrint info to screen.
Returns:
A vector of substitutions vectors (one for each site).
Exceptions:
ExceptionIf the likelihood object is not initialized.

Definition at line 633 of file SubstitutionMappingTools.cpp.

References bpp::ApplicationTools::displayGauge(), bpp::ApplicationTools::displayTask(), bpp::ApplicationTools::displayTaskDone(), bpp::MarginalAncestralStateReconstruction::getAllAncestralStates(), bpp::DiscreteDistribution::getCategories(), bpp::Node::getDistanceToFather(), bpp::Node::getFather(), bpp::Node::getId(), bpp::TreeLikelihood::ConstBranchModelDescription::getModel(), bpp::TreeLikelihood::ConstBranchModelDescription::getNewSiteIterator(), bpp::Alphabet::getSize(), bpp::TreeLikelihood::ConstBranchModelIterator::hasNext(), bpp::ApplicationTools::message, bpp::TreeLikelihood::ConstBranchModelIterator::next(), and bpp::Matrix< Scalar >::resize().

vector< double > SubstitutionMappingTools::computeSumForBranch ( const SubstitutionMapping &  smap,
size_t  branchIndex 
) [static]

Sum all substitutions for each type of a given branch (specified by its index).

Parameters:
smapThe substitution map to use.
branchIndexThe index of the substitution vector for which the counts should be computed.
Returns:
A vector will all counts summed for each types of substitutions.

Definition at line 982 of file SubstitutionMappingTools.cpp.

References bpp::SubstitutionMapping::getNumberOfSites(), and bpp::SubstitutionMapping::getNumberOfSubstitutionTypes().

vector< double > SubstitutionMappingTools::computeSumForSite ( const SubstitutionMapping &  smap,
size_t  siteIndex 
) [static]

Sum all substitutions for each type of a given site (specified by its index).

Parameters:
smapThe substitution map to use.
siteIndexThe index of the substitution vector for which the counts should be computed.
Returns:
A vector will all counts summed for each types of substitutions.

Definition at line 997 of file SubstitutionMappingTools.cpp.

References bpp::SubstitutionMapping::getNumberOfBranches(), and bpp::SubstitutionMapping::getNumberOfSubstitutionTypes().

vector< double > SubstitutionMappingTools::computeTotalSubstitutionVectorForSite ( const SubstitutionMapping &  smap,
size_t  siteIndex 
) [static]

Sum all type of substitutions for each branch of a given position (specified by its index).

Parameters:
smapThe substitution map to use.
siteIndexThe index of the substitution vector for which the counts should be computed.
Returns:
A vector will all counts for all types of substitutions summed.

Definition at line 951 of file SubstitutionMappingTools.cpp.

References bpp::SubstitutionMapping::getNumberOfBranches(), and bpp::SubstitutionMapping::getNumberOfSubstitutionTypes().

void SubstitutionMappingTools::readFromStream ( std::istream &  in,
ProbabilisticSubstitutionMapping &  substitutions,
size_t  type 
) throw (IOException) [static]

Read the substitutions vectors from a stream.

Parameters:
inThe input stream where to read the vectors.
substitutionsThe mapping object to fill.
typeThe type of substitutions that are read. Should be in supported by the substittuion count obect assiciated to the mapping, if any.
Exceptions:
IOExceptionIf an input error happens.

Definition at line 909 of file SubstitutionMappingTools.cpp.

References bpp::DataTable::deleteColumn(), bpp::DataTable::getColumn(), bpp::DataTable::getColumnName(), bpp::DataTable::getNumberOfColumns(), bpp::DataTable::getNumberOfRows(), bpp::DataTable::read(), bpp::TextTools::toDouble(), bpp::TextTools::toInt(), and bpp::Exception::what().

void SubstitutionMappingTools::writeToStream ( const ProbabilisticSubstitutionMapping &  substitutions,
const SiteContainer &  sites,
size_t  type,
std::ostream &  out 
) throw (IOException) [static]

Write the substitutions vectors to a stream.

Parameters:
substitutionsThe substitutions vectors to write.
sitesThe dataset associated to the vectors (needed to know the position of each site in the dataset).
typeThe type of substitutions to be output. See SubstitutionCount class. Only one type of substitution can be output at a time.
outThe output stream where to write the vectors.
Exceptions:
IOExceptionIf an output error happens.

Definition at line 880 of file SubstitutionMappingTools.cpp.

The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Friends