# PCMBase v1.2.10

Monthly downloads

## Simulation and Likelihood Calculation of Phylogenetic Comparative Models

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. The PCMBase package is limited to
trait-simulation and likelihood calculation of (mixed) Gaussian phylogenetic
models. The PCMFit package provides functionality for ML and Bayesian fit of
these models to tree and trait data. The package web-site
<https://venelin.github.io/PCMBase/>
provides access to the documentation and other resources.

## Readme

# 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 Getting started guide
- The PCMBase parameterizations guide
- The Tracing the likelihood calculation of a Gaussian mode guide
- The Creating a Custom Model in the PCMBase Framework guide

The research article “Fast likelihood evaluation for multivariate phylogenetic comparative methods: the PCMBase R package” provides a general overview of PCMBase. The article is currently undergoing peer review for a publication and is available as a preprint from arxiv.

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. (2018, September 24). Fast likelihood evaluation for multivariate phylogenetic comparative methods: the PCMBase R package. arXiv.org. https://arxiv.org/abs/1809.09014.

# Used R-packages

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

- For tree processing in R: ape v5.3 (Paradis et al. 2018), data.table v1.12.2 (Dowle and Srinivasan 2019);
- For algebraic manipulation: expm v0.999.4 (Goulet et al. 2018), mvtnorm v1.0.11 (Genz et al. 2018);
- For plotting: ggtree v1.15.3 (Yu and Lam 2019), ggplot2 v3.2.0 (Wickham et al. 2018);
- For unit-testing: testthat v2.1.1 (Wickham 2018), covr v3.2.1 (Hester 2018);
- For documentation and web-site generation: roxygen2 v6.1.1 (Wickham, Danenberg, and Eugster 2018), pkgdown v1.3.0 (Wickham and Hesselberth 2018);

# Licence and copyright

Copyright 2016-2019 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

*Data.table: Extension of ‘Data.frame‘*. https://CRAN.R-project.org/package=data.table.

*Mvtnorm: Multivariate Normal and T Distributions*. https://CRAN.R-project.org/package=mvtnorm.

*Expm: Matrix Exponential, Log, ’Etc’*. https://CRAN.R-project.org/package=expm.

*Covr: Test Coverage for Packages*. https://CRAN.R-project.org/package=covr.

*Proceedings of the National Academy of Sciences of the United States of America*35 (August): 201813823.

*Ape: Analyses of Phylogenetics and Evolution*. https://CRAN.R-project.org/package=ape.

*Testthat: Unit Testing for R*. https://CRAN.R-project.org/package=testthat.

*Ggplot2: Create Elegant Data Visualisations Using the Grammar of Graphics*. https://CRAN.R-project.org/package=ggplot2.

*Roxygen2: In-Line Documentation for R*. https://CRAN.R-project.org/package=roxygen2.

*Pkgdown: Make Static Html Documentation for a Package*. https://CRAN.R-project.org/package=pkgdown.

*Ggtree: An R Package for Visualization and Annotation of Phylogenetic Trees with Their Covariates and Other Associated Data*. https://guangchuangyu.github.io/software/ggtree.

## Functions in PCMBase

Name | Description | |

PCM | Create a phylogenetic comparative model object | |

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

PCMDescribe | Human friendly description of a PCM | |

PCMGenerateParameterizations | Generate possible parameterizations for a given type of model | |

Args_MixedGaussian_MGPMSurfaceOUType | Arguments for the MixedGaussian constructor for SURFACE OU MGPM models. | |

PCMCond | Conditional distribution of a daughter node given its parent node | |

PCMGenerateModelTypes | Generate default model types for given PCM base-classes | |

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 | |

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

PCMBaseIsADevRelease | Check if the PCMBase version corresponds to a dev release | |

PCMApplyTransformation | Map a parametrization to its original form. | |

MGPMSurfaceOUType | Class name for the SURFACE OU MGPM model type | |

PCMLmr | Quadratic polynomial parameters L, m, r | |

MixedGaussian | Create a multi-regime Gaussian model (MixedGaussian) | |

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 | |

PCMMapModelTypesToRegimes | Integer vector giving the model type index for each regime | |

PCMNumRegimes | Number of regimes in a obj | |

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 classes associated with each regime. | |

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

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

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

PCMDescribeParameters | Describe the parameters of a PCM | |

MGPMScalarOUType | Class name for the scalar OU MGPM model type | |

PCMModelTypes | Get the model type(s) of a model | |

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. | |

PCMNumTraits | Number of traits modeled by a PCM | |

PCMParamType | Parameter types | |

PCMModels | Get a list of PCM models currently implemented | |

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

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

PCMCreateLikelihood | Create a likelihood function of a numerical vector parameter | |

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

PCMParamGetShortVector | Get a vector of the variable numeric parameters in a model | |

PCMPLambdaP_1 | Eigen-decomposition of a matrix H | |

PCMBaseTestObjects | Test objects for the PCMBase package | |

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

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

PCMPairSums | Sums of pairs of elements in a vector | |

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

PCMFixParameter | Fix a parameter in a PCM model | |

PCMListParameterizations | Specify the parameterizations for each parameter of a model | |

PCMParamUpperLimit | The upper limit for a given model or parameter type | |

PCMParentClasses | Parent S3 classes for a model class | |

PCMParamLocateInShortVector | Locate a named parameter in the short vector representation of a model | |

PCMParamLowerLimit | The lower limit for a given model or parameter type | |

PCMParseErrorMessage | Extract error information from a formatted error message. | |

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

PCMParam | Module PCMParam | |

PCMTable | A data.table representation of a PCM object | |

PCMTableParameterizations | Cartesian product of possible parameterizations for the different parameters of a model | |

PCMSim | Simulation of a phylogenetic comparative model on a tree | |

PCMSpecify | Parameter specification of PCM model | |

PCMColorPalette | A fixed palette of n colors | |

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

PCMTreeListDescendants | A list of the descendants for each node in a tree | |

PCMTreeToString | A character representation of a phylo object. | |

PCMTreeVCV | Phylogenetic Variance-covariance matrix | |

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

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

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

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

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

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

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

PCMTreeGetTipsInPart | Get the tips belonging to a part in a tree | |

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

PCMTreeExtractClade | Extract a clade from phylogenetic tree | |

PCMTreeJumps | Jumps in modeled traits associated with branches in a tree | |

PCMTreeInsertSingletons | Insert singleton nodes on chosen edges | |

PCMTreeEvalNestedEDxOnTree | Perfrorm nested extractions or drops of clades from a tree | |

PCMTreeGetTipsInRegime | Get the tips belonging to a regime in a tree | |

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

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

PCMTreeNumTips | Wrapper for length(tree$tip.label) | |

PCMTreeNodeTimes | Calculate the time from the root to each node of the tree | |

PCMTreePlot | Plot a tree with parts and regimes assigned to these parts | |

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

PCMTreeGetLabels | Get a vector of the tip and node labels in a tree | |

PCMTreeGetParent | The parent node id of a daughter node in a tree | |

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

PCMOptions | Global options for the PCMBase package | |

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

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

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. | |

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

PCMTreeSetPartition | Set a partition of a tree by specifying the partition nodes | |

PCMTreeSetRegimesForEdges | Set the regime for each individual edge in a tree explicitly | |

PCMTreeLocateMidpointsOnBranches | Find the middle point of each branch longer than a threshold | |

PCMTreeSetPartRegimes | Set regimes for the parts in a tree | |

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

PCMTreeSetLabels | Set tip and internal node labels in a tree | |

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

PCMUnfixParameter | Unfix a parameter in a PCM model | |

dataFig3 | Data for Fig3 in the TPB manuscript | |

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

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

PCMParamSetByName | Set model parameters from a named list | |

PCMPlotGaussianSample2D | A 2D sample from Gaussian distribution | |

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

PCMTrajectory | Generate a trajectory for the mean in one regime of a PCM | |

PCMTree | Create a PCMTree object from a phylo object | |

PCMPlotTraitData2D | Scatter plot of 2-dimensional data | |

PCMPlotMath | Beautiful model description based on plotmath | |

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

PCMTreeDropClade | Drop a clade from a phylogenetic tree | |

PCMTreeGetBranchLength | The length of the branch leading to a node | |

UpperChol | Upper triangular factor of a symmetric positive definite matrix | |

PCMTreeNumParts | Number of unique parts on a tree | |

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

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

PCMTreeNumNodes | Number of all nodes in a tree | |

White | White Gaussian PCM ignoring phylogenetic history | |

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

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

is.PCMTree | Check that a tree is a PCMTree | |

PCMTreePreorder | Pre-order tree traversal | |

PCMTreePostorder | Post-order tree traversal | |

is.PCM | Check if an object is a PCM. | |

TruePositiveRate | True positive rate of a set of binary predictions against their trues | |

PCMTreeGetPartRegimes | Regime mapping for the parts in a tree | |

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

No Results! |

## Vignettes of PCMBase

Name | ||

Fig1.pdf | ||

PCMBase.Rmd | ||

PCMCreateModel.Rmd | ||

PCMParam.Rmd | ||

PCMTracePruning.Rmd | ||

REFERENCES-R.bib | ||

REFERENCES.bib | ||

No Results! |

## Last month downloads

## Details

Type | Package |

Encoding | UTF-8 |

License | GPL (>= 3.0) |

LazyData | true |

RoxygenNote | 6.1.1 |

ByteCompile | yes |

VignetteBuilder | knitr, rmarkdown |

URL | https://venelin.github.io/PCMBase/, https://github.com/venelin/PCMBase |

BugReports | https://github.com/venelin/PCMBase/issues |

NeedsCompilation | no |

Repository | CRAN |

Packaged | 2019-09-11 16:00:01 UTC; vmitov |

Date/Publication | 2019-09-11 16:30:02 UTC |

suggests | abind , BiocManager , covr , cowplot , ggtree , knitr , mvSLOUCH , rmarkdown , testthat |

imports | ape , data.table , expm , ggplot2 , mvtnorm , xtable |

depends | R (>= 3.1.0) |

Contributors | Tanja Stadler, Krzysztof Bartoszek, Georgios Asimomitis |

#### Include our badge in your README

```
[![Rdoc](http://www.rdocumentation.org/badges/version/PCMBase)](http://www.rdocumentation.org/packages/PCMBase)
```