Rev Language Reference

• dnCDSSBDP
• dnCDFBDP
• dnBirthDeathMultiRate
• dnBirthDeathShift
• dnCDCladoBDP

dnCDBDP(RealPos rootAge/originAge, CladogeneticSpeciationRateMatrix speciationRates/lambda/cladoEventMap, RealPos[] extinctionRates/mu, RealPos[] psi/phi, RateGenerator Q, RealPos delta, Simplex pi, Probability rho, String condition, RealPos nTimeSlices, String simulateCondition, Natural minNumLineages, Natural maxNumLineages, Natural exactNumLineages, RealPos maxTime, Bool pruneExtinctLineages, Bool allowRateShiftsAtExtinctLineages)

rootAge/originAge :	RealPos (pass by const reference)
	The start time of the process.
speciationRates/lambda/cladoEventMap :	CladogeneticSpeciationRateMatrix (pass by const reference)
	The vector of speciation rates (for anagenetic-only models), or the map of speciation rates to cladogenetic event types.
extinctionRates/mu :	RealPos[] (pass by const reference)
	The vector of extinction rates.
psi/phi :	RealPos[] (pass by const reference)
	The vector of serial sampling rates.
	Default : NULL
Q :	RateGenerator (pass by const reference)
	The rate matrix of jumping between rate categories.
	Default : NULL
delta :	RealPos (pass by const reference)
	The rate-factor of jumping between rate categories.
	Default : 1
pi :	Simplex (pass by const reference)
	State frequencies at the root.
	Default : NULL
rho :	Probability (pass by const reference)
	The taxon sampling probability.
	Default : 1
condition :	String (pass by value)
	The condition of the birth-death process.
	Default : time
	Options : time|survival
nTimeSlices :	RealPos (pass by value)
	The number of time slices for the numeric ODE.
	Default : 500
simulateCondition :	String (pass by value)
	The conditions under which to simulate.
	Default : startTime
	Options : startTime|numTips|tipStates|tree
minNumLineages :	Natural (pass by value)
	The minimum number of lineages to simulate; applied under the startTime condition.
	Default : 0
maxNumLineages :	Natural (pass by value)
	The maximum number of lineages to simulate; applied under the startTime condition.
	Default : 500
exactNumLineages :	Natural (pass by value)
	The exact number of lineages to simulate; applied under the numTips condition.
	Default : 100
maxTime :	RealPos (pass by value)
	Maximum time for lineages to coalesce when simulating; applied under the numTips and tipStates condition.
	Default : 1000
pruneExtinctLineages :	Bool (pass by value)
	When simulating should extinct lineages be pruned off?
	Default : TRUE
allowRateShiftsAtExtinctLineages :	Bool (pass by value)
	Should we allow rate shifts to occur on extinct lineages?
	Default : TRUE

TimeTree

This distribution is a flexible simulator that can be used for several lineage-heterogeneous diversification models. Specifically, `dnCDBDP` allows the tree to be divided into multiple segments (also referred to as "regimes" or "types"; Barido-Sottani et al. 2020) separated by discrete shifts in birth and death rates, such that each segment draws its rate vector from a finite number of categories. These categories can (but need not) correspond to the states of an observed discrete character, in which case the shifts correspond to inferred state transitions: hence the characterization of `dnCDBDP` as a "character-dependent" model. Applications of this multi-type model include: 1. Multiple State-dependent Speciation Extinction (MuSSE) (Maddison et al. 2007; FitzJohn 2012) This model uses a state-dependent birth-death process to simulate a tree with only anagenetic state changes, i.e., changes taking place along the branches of the tree. When `dnCDBDP` is used to implement MuSSE, the `lambda` argument represents a vector of speciation rates for each state, and its length is therefore equal to the number of states. The rates at which the character transitions from one state to another are specified by the matrix `Q` (with as many rows and columns as there are states), and the extinction rates for each state are specified using the vector `mu` (with as many elements as there are states). A draw from the distribution needs to be fixed both to a previously inferred tree (using `.clamp()`), and to a matrix recording which state is observed at a given tip (using `.clampCharData()`). 2. Cladogenetic State-dependent Speciation Extinction (ClaSSE) (Goldberg & Igić 2012) This model additionally allows for cladogenetic state changes, i.e., changes that take place at nodes, corresponding to the assumption that state change either induces or immediately follows speciation. When `dnCDBDP` is used to implement ClaSSE, the `lambda` argument corresponds to a cladogenetic event map. A cladogenetic event map is a matrix specifying the speciation rates associated with the different character state triplets that can be observed for the parent and its two children at a given node (= cladogenetic event). As before, anagenetic state change is still allowed, with its rates described by the `Q` matrix, and each state is associated with a distinct extinction rate specified in the `mu` vector. A draw from the distribution again has to be clamped both to a tree and to a character matrix. See the example below for implementation. 3. Branch-specific Diversification Rate Estimation (Höhna et al. 2019) `dnCDBDP` can also be used to estimate the number and placement of events at which the rates of speciation and extinction shift from one category to another, without the assumption that such rate shifts correspond to state transitions in an observed character. While the number of shifts is inferred, the number of categories N has to be specified by the user, and relates to the length of the `lambda` and `mu` vectors. If only one of the two rates is allowed to shift, both vectors have to be of length N (with one containing N distinct and the other N identical elements); if both rates are allowed to shift independently of each other, the vectors have to be of length N^2. The `Q` matrix gives the rates of shifts between any two individual categories. In this case, a draw from the distribution is only fixed to a tree using `.clamp()`.

# setup for a two-state ClaSSE model
num_states = 2          # 0 and 1 are the only states

# set basic process parameters
root_age ~ dnUniform(0, 2)
rho <- Probability(1/2) # sampling one half of extant lineages

# specify extinction probabilities for each state
mu_vec <- rep(0.1, 2)

# Set up cladogenetic events and speciation rates. Each element
# in clado_events describes a state pattern at the cladogenetic
# event: for example, [0, 0, 1] denotes a parent having state 0
# and its two children having states 0 and 1.
clado_events = [[0, 0, 1], [0, 1, 0], [1, 0, 1], [1, 1, 0]]

# set speciation rates for each cladogenetic event described above
lambda ~ dnExponential( 10.0 )
speciation_rates := rep(lambda, 4)

# create cladogenetic rate matrix
clado_matrix = fnCladogeneticSpeciationRateMatrix(clado_events,
                                                  speciation_rates,
                                                  num_states)

# set up Q-matrix to specify rates of state changes along branches
ana_rate_matrix <- fnFreeK( [[0, .2], [.2, 0]], rescaled=FALSE )

# create vector of state frequencies at the root
pi <- simplex([1, 2])

# basic use of the function
timetree ~ dnCDBDP(rootAge   = root_age,
                   lambda    = clado_matrix,
                   mu        = mu_vec,
                   Q         = ana_rate_matrix,
                   pi        = pi,
                   rho       = rho,
                   condition = "time")

• dnCBDSP
• fnCladogeneticProbabilityMatrix
• fnCladogeneticSpeciationRateMatrix