paleotree (version 3.1.3)

cladogeneticTraitCont: Simulate Cladogenetic Trait Evolution

Description

This function simulates trait evolution at each speciation/branching event in a matrix output from simFossilRecord, after transformation with fossilRecord2fossilTaxa.

Usage

cladogeneticTraitCont(taxa, rate = 1, meanChange = 0, rootTrait = 0)

Arguments

taxa

A five-column matrix of taxonomic data, as output by fossilRecord2fossilTaxa after simulation with simFossilRecord (or via the deprecated function simFossilTaxa)

rate

rate of trait change; variance of evolutionary change distribution per speciation event

meanChange

Mean change per speciation event. Default is 0; change to simulate 'active' speciational trends, where the expected change at each speciational event is non-zero.

rootTrait

The trait value of the first taxon in the dataset; set to 0 by default.

Value

Returns a vector of trait values for each taxon, with value names being the taxa IDs (column 1 of the input) with a 't' pasted (as with rtree in the ape library).

Details

This function simulates continuous trait evolution where change occurs under a Brownian model, but only at events that create new distinct morphotaxa (i.e. species as recognized in the fossil record), either branching events or anagenesis (pseudospeciation). These are the types of morphological differentiation which can be simulated in the function simFossilRecord. This is sometimes referred to as cladogenetic or speciation trait evolution and is related to Punctuated Equilibrium theory. Anagenetic shifts are not cladogenetic events per se (no branching!), so perhaps the best way to this of this function is it allows traits to change anytime simFossilRecord created a new 'morphotaxon' in a simulation.

Importantly, trait changes only occur at the base of 'new' species, thus allowing cladogenetic trait evolution to be asymmetrical at branching points: i.e. only one branch actually changes position in trait-space, as expected under a budding cladogenesis model. This distinction is important as converting the taxa matrix to a phylogeny and simulating the trait changes under a 'speciational' tree-transformation would assume that divergence occurred on both daughter lineages at each node. (This has been the standard approach for simulating cladogenetic trait change on trees).

Cryptic taxa generated with prop.cryptic in simFossilRecord will not differ at all in trait values. These species will all be identical.

See this link for additional details: http://nemagraptus.blogspot.com/2012/03/simulating-budding-cladogenetictrait.html

See Also

simFossilRecord,

This function is similar to Brownian motion simulation functions such as rTraitCont in ape, sim.char in geiger and fastBM in phytools.

See also unitLengthTree in this package and speciationalTree in the package geiger. These are tree transformation functions; together with BM simulation functions, they would be expected to have a similar effect as this function (when cladogenesis is 'bifurcating' and not 'budding'; see above).

Examples

# NOT RUN {
set.seed(444)
record <- simFossilRecord(p = 0.1, q = 0.1, nruns = 1,
nTotalTaxa = c(30,1000), plot = TRUE)
taxa <- fossilRecord2fossilTaxa(record)
trait <- cladogeneticTraitCont(taxa)
tree <- taxa2phylo(taxa)
plotTraitgram(trait,tree,conf.int = FALSE)

#with cryptic speciation
record <- simFossilRecord(p = 0.1, q = 0.1, prop.cryptic = 0.5, 
nruns = 1, nTotalTaxa = c(30,1000), plot = TRUE)
taxa <- fossilRecord2fossilTaxa(record)
trait <- cladogeneticTraitCont(taxa)
tree <- taxa2phylo(taxa)
plotTraitgram(trait,tree,conf.int = FALSE)

# }