Learn R Programming

PCMBase : Simulation and likelihood calculation of phylogenetic comparative methods

Phylogenetic comparative methods represent models of continuous trait data associated with the tips of a phylogenetic tree. Examples of such models are Gaussian continuous time branching stochastic processes such as Brownian motion (BM) and Ornstein-Uhlenbeck (OU) processes, which regard the data at the tips of the tree as an observed (final) state of a Markov process starting from an initial state at the root and evolving along the branches of the tree. The PCMBase R package provides a general framework for manipulating such models. This framework consists of an application programming interface for specifying data and model parameters, and efficient algorithms for simulating trait evolution under a model and calculating the likelihood of model parameters for an assumed model and trait data. The package implements a growing collection of models, which currently includes BM, OU, BM/OU with jumps, two-speed OU as well as mixed Gaussian models, in which different types of the above models can be associated with different branches of the tree. Note that the PCMBase package does not implement model inference. Due to the enormous variety of models and possible model inference methods, this functionality is delegated to other packages that, taking advantage of PCMBase’s fast likelihood calculation, can implement maximum likelihood (ML) or Bayesian inference methods. For example, the PCMFit package provides heuristic-based ML fit of (mixed) Gaussian phylogenetic models (Mitov, Bartoszek, and Stadler 2019).

Installation

An optional but highly recommended dependency

The function PCMTreePlot in the package is implemented based on the R-package ggtree, which is not on CRAN. It is highly recommended to install this package in order to visualize trees with colored parts corresponding to different evolutionary regimes. If ggtree is not installed, the package will fail to run examples and generate the vignettes. At the time of writing this documentation, ggtree can be installed from bioconductor through the following code (if that does not work, check the ggtree home page):

if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("ggtree", version = "3.8")

Installing PCMBase from CRAN

A stable but possibly old version of PCMBase is available on CRAN and can be installed with this command:

install.packages("PCMBase")

Github

The newest but possibly less stable and tested version of the package can be installed using:

devtools::install_github("venelin/PCMBase")

Resources

The user guides and technical reference for the library are available from the PCMBase web-page.

The research article “Fast likelihood calculation for multivariate Gaussian phylogenetic models with shifts”, published in Theoretical Population Biology provides a thorough description of the likelihood calculation algorithm currently implemented in PCMBase. Appendix A of this article gives an overview of the modular structure and the features of the package.

The PCMBase source code is located in the PCMBase github repository.

Feature requests, bugs, etc can be reported in the PCMBase issues list.

Citing PCMBase

To give credit to the PCMBase package in a publication, please cite the following article:

Mitov, V., Bartoszek, K., Asimomitis, G., & Stadler, T. (2019). Fast likelihood calculation for multivariate Gaussian phylogenetic models with shifts. Theor. Popul. Biol. https://doi.org/10.1016/j.tpb.2019.11.005

Used R-packages

The PCMBase R-package uses the following 3rd party R-packages:

  • For tree processing in R: ape v5.5 (Paradis et al. 2018), data.table v1.14.2 (Dowle and Srinivasan 2019);
  • For algebraic manipulation: expm v0.999.6 (Goulet et al. 2018), mvtnorm v1.1.3 (Genz et al. 2018);
  • For plotting: ggtree v3.2.1 (Yu and Lam 2019), ggplot2 v3.3.5 (Wickham et al. 2018);
  • For unit-testing: testthat v3.1.1 (Wickham 2018), covr v3.5.1 (Hester 2018);
  • For documentation and web-site generation: roxygen2 v7.1.2 (Wickham, Danenberg, and Eugster 2018), pkgdown v2.0.1 (Wickham and Hesselberth 2018);

Licence and copyright

Copyright 2016-2021 Venelin Mitov

Source code to PCMBase is made available under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. PCMBase is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

References

Dowle, Matt, and Arun Srinivasan. 2019. Data.table: Extension of ‘Data.frame‘. https://CRAN.R-project.org/package=data.table.

Genz, Alan, Frank Bretz, Tetsuhisa Miwa, Xuefei Mi, and Torsten Hothorn. 2018. Mvtnorm: Multivariate Normal and t Distributions. https://CRAN.R-project.org/package=mvtnorm.

Goulet, Vincent, Christophe Dutang, Martin Maechler, David Firth, Marina Shapira, and Michael Stadelmann. 2018. Expm: Matrix Exponential, Log, ’Etc’. https://CRAN.R-project.org/package=expm.

Hester, Jim. 2018. Covr: Test Coverage for Packages. https://CRAN.R-project.org/package=covr.

Mitov, Venelin, Krzysztof Bartoszek, and Tanja Stadler. 2019. “Automatic generation of evolutionary hypotheses using mixed Gaussian phylogenetic models.” Proceedings of the National Academy of Sciences of the United States of America 35 (August): 201813823.

Paradis, Emmanuel, Simon Blomberg, Ben Bolker, Joseph Brown, Julien Claude, Hoa Sien Cuong, Richard Desper, et al. 2018. Ape: Analyses of Phylogenetics and Evolution. https://CRAN.R-project.org/package=ape.

Wickham, Hadley. 2018. Testthat: Unit Testing for r. https://CRAN.R-project.org/package=testthat.

Wickham, Hadley, Winston Chang, Lionel Henry, Thomas Lin Pedersen, Kohske Takahashi, Claus Wilke, and Kara Woo. 2018. Ggplot2: Create Elegant Data Visualisations Using the Grammar of Graphics. https://CRAN.R-project.org/package=ggplot2.

Wickham, Hadley, Peter Danenberg, and Manuel Eugster. 2018. Roxygen2: In-Line Documentation for r. https://CRAN.R-project.org/package=roxygen2.

Wickham, Hadley, and Jay Hesselberth. 2018. Pkgdown: Make Static HTML Documentation for a Package. https://CRAN.R-project.org/package=pkgdown.

Yu, Guangchuang, and Tommy Tsan-Yuk Lam. 2019. Ggtree: An r Package for Visualization and Annotation of Phylogenetic Trees with Their Covariates and Other Associated Data. https://guangchuangyu.github.io/software/ggtree/.

Copy Link

Version

Install

install.packages('PCMBase')

Monthly Downloads

376

Version

1.2.14

License

GPL (>= 3.0)

Maintainer

Venelin Mitov

Last Published

March 15th, 2024

Functions in PCMBase (1.2.14)

PCMColorPalette

A fixed palette of n colors
PCMCombineListAttribute

Combine all member attributes of a given name into a list
PCMApplyTransformation

Map a parametrization to its original form.
PCMAbCdEf

Quadratic polynomial parameters A, b, C, d, E, f for each node
PCMCond

Conditional distribution of a daughter node given its parent node
PCMDefaultModelTypes

Class names for the the default PCM and MGPM model types
PCMDefaultObject

Generate a default object of a given PCM model type or parameter type
PCMCreateLikelihood

Create a likelihood function of a numerical vector parameter
PCMCondVOU

Variance-covariance matrix of an OU process with optional measurement error and jump at the start
PCMGetVecParamsRegimesAndModels

Get a vector of all parameters (real and discrete) describing a model on a tree including the numerical parameters of each model regime, the integer ids of the splitting nodes defining the regimes on the tree and the integer ids of the model types associated with each regime.
PCMExtractDimensions

Given a PCM or a parameter object, extract an analogical object for a subset of the dimensions (traits) in the original object.
PCMGetAttribute

Value of an attribute of an object or values for an attribute found in its members
PCMInfo

Meta-information about a tree and trait data associated with a PCM
PCMExtractRegimes

Given a PCM or a parameter object, extract an analogical object for a subset of the regimes in the original object.
PCMLikDmvNorm

Calculate the likelihood of a model using the standard formula for multivariate pdf
PCMLikTrace

Tracing the log-likelihood calculation of a model over each node of the tree
PCMLik

Likelihood of a multivariate Gaussian phylogenetic comparative model with non-interacting lineages
PCMFixParameter

Fix a parameter in a PCM model
PCMFindMethod

Find the S3 method for a given PCM object or class-name and an S3 generic
PCMLmr

Quadratic polynomial parameters L, m, r
PCMDescribeParameters

Describe the parameters of a PCM
PCMMeanAtTime

Calculate the mean at time t, given X0, under a PCM model
PCMGenerateModelTypes

Generate default model types for given PCM base-classes
PCMMapModelTypesToRegimes

Integer vector giving the model type index for each regime
PCMParamLowerLimit

The lower limit for a given model or parameter type
PCMParamRandomVecParams

Generate a random parameter vector for a model using uniform distribution between its lower and upper bounds.
PCMParamBindRegimeParams

Bind named vectors or matrices into an array so that the names form the names of the last dimension.
PCMParam

Module PCMParam
PCMMean

Expected mean vector at each tip conditioned on a trait-value vector at the root
PCMModels

Get a list of PCM models currently implemented
PCMDescribe

Human friendly description of a PCM
PCMModelTypes

Get the model type(s) of a model
PCMGenerateParameterizations

Generate possible parameterizations for a given type of model
PCMNumTraits

Number of traits modeled by a PCM
PCMNumRegimes

Number of regimes in a obj
PCMParamCount

Count the number of free parameters associated with a PCM or a PCM-parameter
PCMParseErrorMessage

Extract error information from a formatted error message.
PCMListMembers

A vector of access-code strings to all members of a named list
PCMListParameterizations

Specify the parameterizations for each parameter of a model
PCMPlotTraitData2D

Scatter plot of 2-dimensional data
PCMPresentCoordinates

Determine which traits are present (active) on each node of the tree
PCMOptions

Global options for the PCMBase package
PCMPExpxMeanExp

Create a function of time that calculates \((1-exp(-lambda_ij*time))/lambda_ij\) for every element \(lambda_ij\) of the input matrix \(Lambda_ij\).
PCMPlotGaussianDensityGrid2D

A 2D Gaussian distribution density grid in the form of a ggplot object
PCMRegimes

Get the regimes (aka colors) of a PCM or of a PCMTree object
PCMParamLoadOrStore

Load (or store) a PCM parameter from (or to) a vector of the variable parameters in a model.
PCMParamType

Parameter types
PCMParamSetByName

Set model parameters from a named list
PCMParamLocateInShortVector

Locate a named parameter in the short vector representation of a model
PCMSpecify

Parameter specification of PCM model
PCMSim

Simulation of a phylogenetic comparative model on a tree
PCMTree

Create a PCMTree object from a phylo object
PCMTrajectory

Generate a trajectory for the mean in one regime of a PCM
PCMSetAttribute

Set an attribute of a named member in a PCM or other named list object
PCMTreeDropClade

Drop a clade from a phylogenetic tree
PCMTreeDtNodes

A data.table with time, part and regime information for the nodes in a tree
PCMPlotGaussianSample2D

A 2D sample from Gaussian distribution
PCMParamGetShortVector

Get a vector of the variable numeric parameters in a model
PCMPLambdaP_1

Eigen-decomposition of a matrix H
PCMTreeGetPartNames

Unique parts on a tree in the order of occurrence from the root to the tips (preorder)
PCMTreeGetPartRegimes

Regime mapping for the parts in a tree
PCMTreeGetLabels

Node labels of a tree
PCMTreeBackbonePartition

Prune the tree leaving one tip for each or some of its parts
PCMTreeEdgeTimes

A matrix with the begin and end time from the root for each edge in tree
PCMPlotMath

Beautiful model description based on plotmath
PCMTreeGetBranchLength

The length of the branch leading to a node
PCMTable

A data.table representation of a PCM object
PCMTreeMatrixNodesInSamePart

Which couples from a given set of nodes in a tree belong to the same part?
PCMTreeGetDaughters

A vector of the daughter nodes for a given parent node id in a tree
PCMTreeGetPartsForNodes

Get the parts of the branches leading to a set of nodes or tips
PCMTreeMatchLabels

Get the node numbers associated with tip- or node-labels in a tree
PCMTreeGetPartition

Get the starting branch' nodes for each part on a tree
PCMTreeGetTipsInPart

Get the tips belonging to a part in a tree
PCMTreeGetTipsInRegime

Get the tips belonging to a regime in a tree
PCMTreeGetParent

The parent node id of a daughter node in a tree
PCMTreeLocateMidpointsOnBranches

Find the middle point of each branch longer than a threshold
PCMTableParameterizations

Cartesian product of possible parameterizations for the different parameters of a model
PCMTreeListAllPartitions

A list of all possible (including recursive) partitions of a tree
PCMTreeLocateEpochOnBranches

Find the crossing points of an epoch-time with each lineage of a tree
PCMPairSums

Sums of pairs of elements in a vector
PCMTreeNumNodes

Number of all nodes in a tree
PCMTreeTableAncestors

A matrix (table) of ancestors/descendants for each node in a tree
PCMTreeSplitAtNode

Slit a tree at a given internal node into a clade rooted at this node and the remaining tree after dropping this clade
PCMTreeJumps

Jumps in modeled traits associated with branches in a tree
PCMTreeInsertSingletons

Insert tips or singleton nodes on chosen edges
PCMTreePostorder

Post-order tree traversal
PCMTreePlot

Plot a tree with parts and regimes assigned to these parts
PCMTreeListRootPaths

A list of the path to the root from each node in a tree
PCMTreeListDescendants

A list of the descendants for each node in a tree
PCMTreeListCladePartitions

A list of all possible clade partitions of a tree with a number of splitting nodes
PCMTreePreorder

Pre-order tree traversal
PCMTreeNumTips

Wrapper for length(tree$tip.label)
TruePositiveRate

True positive rate of a set of binary predictions against their trues
UpperTriFactor

Upper triangular factor of a symmetric positive definite matrix
is.MixedGaussian

Check if an object is a `MixedGaussian` PCM
as.MixedGaussian

Convert a GaussianPCM model object to a MixedGaussian model object
is.PCMTree

Check that a tree is a PCMTree
White

White Gaussian PCM ignoring phylogenetic history
PCMTreeNumParts

Number of unique parts on a tree
PCMTreeSetRegimesForEdges

Set the regime for each individual edge in a tree explicitly
PCMUnfixParameter

Unfix a parameter in a PCM model
PCMTreeSetPartition

Set a partition of a tree by specifying the partition nodes
dataFig3

Data for Fig3 in the TPB manuscript
PCMVar

Expected variance-covariance matrix for each couple of tips (i,j)
PCMTreeToString

A character representation of a phylo object.
is.GaussianPCM

Check if an object is a `GaussianPCM`
PCMTreeVCV

Phylogenetic Variance-covariance matrix
PCMParamUpperLimit

The upper limit for a given model or parameter type
is.PCM

Check if an object is a PCM.
PCMParentClasses

Parent S3 classes for a model class
PCMTreeEvalNestedEDxOnTree

Perfrorm nested extractions or drops of clades from a tree
PCMTreeSetPartRegimes

Set regimes for the parts in a tree
PCMVarAtTime

Calculate the variance covariance k x k matrix at time t, under a PCM model
PCMTreeGetRegimesForEdges

Model regimes (i.e. colors) associated with the branches in a tree
PCMTreeNearestNodesToEpoch

Find the nearest node to a given time from the root (epoch) on each lineage crossing this epoch
RequireSuggestedPackages

Check if all packages listed in Suggests are available
PCMTreeSetLabels

Set tip and internal node labels in a tree
PCMTreeNodeTimes

Calculate the time from the root to each node of the tree
PCMTreeGetRegimesForNodes

Get the regimes of the branches leading to a set of nodes or tips
PCMTreeExtractClade

Extract a clade from phylogenetic tree
MGPMSurfaceOUType

Class name for the SURFACE OU MGPM model type
MixedGaussian

Create a multi-regime Gaussian model (MixedGaussian)
FormatTableAsLatex

Latex representation of a data.table with matrix and vectors in its cells
Args_MixedGaussian_MGPMScalarOUType

Arguments for the MixedGaussian constructor for scalar OU MGPM models.
Args_MixedGaussian_MGPMDefaultModelTypes

Arguments to be passed to the constructor MixedGaussian when constructing a MGPM model with some of the default MGPM model types.
Args_MixedGaussian_MGPMSurfaceOUType

Arguments for the MixedGaussian constructor for SURFACE OU MGPM models.
MatchListMembers

Find the members in a list matching a member expression
MGPMScalarOUType

Class name for the scalar OU MGPM model type
FormatCellAsLatex

Latex representation of a model parameter or other found in a data.table object
PCMCond.GaussianPCM

Conditional distribution of a daughter node given its parent node
MixedGaussianTemplate

Create a template MixedGaussian object containing a regime for each model type
PCM

Create a phylogenetic comparative model object
PCMBaseIsADevRelease

Check if the PCMBase version corresponds to a dev release
PCMBaseTestObjects

Test objects for the PCMBase package
PCMAddToListAttribute

Add a value to a list-valued attribute of a member or members matching a pattern