RRphylo (version 2.8.0)

setBM: Producing simulated phenotypes with trends

Description

The function setBM is wrapper around phytools fastBM function, which generates BM simulated phenotypes with or without a trend.

Usage

setBM(tree, nY = 1, s2 = 1, a = 0, type = c("", "brown","trend",
  "drift"), trend.type = c("linear", "stepwise"),tr = 10, t.shift = 0.5,
  es=2, ds=1)

Value

Either an object of class 'array' containing a single phenotype or an object of class 'matrix' of n phenotypes as columns, where n is indicated as nY = n.

Arguments

tree

a phylogenetic tree.

nY

the number of phenotypes to simulate.

s2

value of the Brownian rate to use in the simulations.

a

the phenotype at the tree root.

type

the type of phenotype to simulate. With the option "brown" the phenotype will have no trend in the phenotypic mean or in the rate of evolution. A variation in the phenotypic mean over time (a phenotypic trend) is obtained by selecting the option "drift". A trend in the rate of evolution produces an increased variance in the residuals over time. This is obtained by specifying the option "trend".

trend.type

two kinds of heteroscedastic residuals are generated under the "trend" type. The option "linear" produces an exponential linear increase (or decrease) in heteroscedasticity, whereas the "stepwise" option produces an increase (or decrease) after a specified point in time.

tr

the intensity of the trend with the "stepwise" option is controlled by the tr argument. The scalar tr is the multiplier of the branches extending after the shift point as indicated by t.shift.

t.shift

the relative time distance from the tree root where the stepwise change in the rate of evolution is indicated to apply.

es

when trend.type="linear", es is a scalar representing the exponent at which the evolutionary time (i.e. distance from the root) scales to change to phenotypic variance. With es = 1 the phenotypic rate will be trendless, with es < 1 the variance of the phenotypes will decrease exponentially towards the present and the other way around with es > 1.

ds

a scalar indicating the change in phenotypic mean in the unit time, in type="drift" case. With ds = 0 the phenotype will be trendless, with ds < 0 the phenotypic mean will decrease exponentially towards the present and the other way around with ds > 0.

Author

Pasquale Raia, Silvia Castiglione, Carmela Serio, Alessandro Mondanaro, Marina Melchionna, Mirko Di Febbraro, Antonio Profico, Francesco Carotenuto

Details

Note that setBM differs from fastBM in that the produced phenotypes are checked for the existence of a temporal trend in the phenotype. The user may specify whether she wants trendless data (option "brown"), phenotypes trending in time (option "drift"), or phenotypes whose variance increases/decreases exponentially over time, consistently with the existence of a trend in the rate of evolution (option "trend"). In the latter case, the user may indicate the intensity of the trend (by applying different values of es), and whether it should occur after a given proportion of the tree height (hence a given point back in time, specified by the argument t.shift). Trees in setBM are treated as non ultrametric. If an ultrametric tree is fed to the function, setBM alters slightly the leaf lengths multiplying randomly half of the leaves by 1 * 10e-3,in order to make it non-ultrametric.

Examples

 # \donttest{
data("DataOrnithodirans")
DataOrnithodirans$treedino->treedino

setBM(tree=treedino, nY= 1, type="brown")
setBM(tree=treedino, nY= 1, type="drift", ds=2)
setBM(tree=treedino, nY= 1, type="trend", trend.type="linear", es=2)# }