mvSLOUCH (version 2.7.7)

simulBMProcPhylTree: Simulate data on a phylogeny under a (multivariate) Brownian motion model

Description

Simulate data on a phylogeny under a (multivariate) Brownian motion model

Usage

simulBMProcPhylTree(phyltree, X0, Sigma, dropInternal = TRUE, M.error=NULL, 
fullTrajectory=FALSE, jumpsetup=NULL, keep_tree = FALSE, step=NULL)

Value

If fullTrajectory is FALSE then returns a matrix with each row corresponding to a tree node and each column to a trait. Otherwise returns a more complex object describing the full realization of the process on the tree. If dropInternal is TRUE, then the entries for the internal nodes are changed to NAs. The ordering of the rows corresponds to the order of the nodes (their indices) in the phylo object. Hence, the first n rows will be the tip rows (by common phylo convention).

Arguments

phyltree

The phylogeny in phylo format. The tree can be obtained from e.g. a nexus file by the read.nexus() function from the ape package. The "standard" ape node indexing is assumed: for a tree with \(n\) tips, the tips should have indices 1:n and the root index n+1. The root.edge field is ignored.

X0

The ancestral, root state.

Sigma

The diffusion matrix of the Brownian motion.

dropInternal

Logical whether the simulated values at the internal nodes should be dropped.

M.error

An optional measurement error covariance structure. The measurement errors between species are assumed independent. The program tries to recognize the structure of the passed matrix and accepts the following possibilities :

• a single number that is a common measurement error for all tips and species,

• a m element vector with each value corresponding to a variable, measurement errors are independent between variables and each species is assumed to have the same measurement errors,

• a m x m ((number of variables) x (number of variables)) matrix, all species will have the same measurement error,

• a list of length n (number of species), each list element is the covariance structure for the appropriate (numbering according to tree) species, either a single number (each variable has same variance), vector (of length m for each variable), or m x m matrix, the order of the list has to correspond to the order of the nodes in the phyltree object,

• NULL no measurement error.

From version 2.0.0 of mvSLOUCH it is impossible to pass a single joint measurement error matrix for all the species and traits.

fullTrajectory

Should the full realization of the process or only node and tip values be returned

jumpsetup

Either NULL or list describing the jump at speciation. In the second case:

jumptype

In what way does the jump take place. Possible values are
"ForBoth" the jump occurs at speciation and is common to both daughter lineages, "RandomLineage" the jump occurs just after speciation affecting exactly one daughter lineage, both descending branches have the same chance of being affected, "JumpWithProb" the jump occurs with probability jumpprob just after speciation independently on each daughter lineage independently.

jumpprob

A value in \([0,1]\) indicating the probability of a jump taking place, only matters if jumptype is "JumpWithProb" or "JumpWithProb".

jumpdistrib

The distribution of the jump, currently only can take value "Normal".

vMean

The expected value of the jump, a vector of appropriate length if the trait is multivariate.

mCov

The variance of the jump, a matrix of appropriate dimensions if the trait is multivariate.

keep_tree

Logical whether the used tree should be saved inside the output object. Useful for any future reference, but as the tree is enhanced for mvSLOUCH's needs the resulting output object may be very large (it the number of tips is large).

step

The step size of the simulation.

Author

Krzysztof Bartoszek

References

Bartoszek, K. (2014) Quantifying the effects of anagenetic and cladogenetic evolution. Mathematical Biosciences 254:42-57.

Bartoszek, K. (2016) A Central Limit Theorem for punctuated equilibrium. arXiv:1602.05189.

Bartoszek, K. and Fuentes-Gonzalez, J. and Mitov, V. and Pienaar, J. and Piwczynski, M. and Puchalka, R. and Spalik, K. and Voje, K. L. (2023) Model Selection Performance in Phylogenetic Comparative Methods Under Multivariate Ornstein-Uhlenbeck Models of Trait Evolution, Systematic Biology 72(2):275-293.

Bartoszek, K. and Fuentes-Gonzalez, J. and Mitov, V. and Pienaar, J. and Piwczynski, M. and Puchalka, R. and Spalik, K. and Voje, K. L. (2024) Analytical advances alleviate model misspecification in non-Brownian multivariate comparative methods, Evolution 78(3):389-400.

Bartoszek, K. and Pienaar, J. and Mostad. P. and Andersson, S. and Hansen, T. F. (2012) A phylogenetic comparative method for studying multivariate adaptation. Journal of Theoretical Biology 314:204-215.

Bartoszek, K. and Tredgett Clarke J. and Fuentes-Gonzalez, J. and Mitov, V. and Pienaar, J. and Piwczynski, M. and Puchalka, R. and Spalik, K. and Voje, K. L. (2024) Fast mvSLOUCH: Multivariate Ornstein-Uhlenbeck-based models of trait evolution on large phylogenies, Methods in Ecology and Evolution 15(9):1507-1515.

Butler, M.A. and A.A. King (2004) Phylogenetic comparative analysis: a modeling approach for adaptive evolution. American Naturalist 164:683-695.

Felsenstein, J. (1985) Phylogenies and the comparative method. American Naturalist 125:1-15.

Hansen, T.F. and Bartoszek, K. (2012) Interpreting the evolutionary regression: the interplay between observational and biological errors in phylogenetic comparative studies. Systematic Biology 61(3):413-425.

Pienaar et al (in prep) An overview of comparative methods for testing adaptation to external environments.

See Also

BrownianMotionModel, SummarizeBM

Examples

RNGversion(min(as.character(getRversion()),"3.6.1"))
set.seed(12345, kind = "Mersenne-Twister", normal.kind = "Inversion")
### We will first simulate a small phylogenetic tree using functions from ape.
### For simulating the tree one could also use alternative functions, e.g. sim.bd.taxa 
### from the TreeSim package
phyltree<-ape::rtree(5)

## The line below is not necessary but advisable for speed
phyltree<-phyltree_paths(phyltree)

### Define Brownian motion parameters to be able to simulate data 
### under the Brownian motion model.
BMparameters<-list(vX0=matrix(0,nrow=3,ncol=1),
Sxx=rbind(c(1,0,0),c(0.2,1,0),c(0.3,0.25,1)))

### Now simulate the data.
jumpobj<-list(jumptype="RandomLineage",jumpprob=0.5,jumpdistrib="Normal",
vMean=rep(0,3),mCov=diag(1,3,3))
BMdata<-simulBMProcPhylTree(phyltree,X0=BMparameters$vX0,Sigma=BMparameters$Sxx,
jumpsetup=jumpobj)
RNGversion(as.character(getRversion()))