treats: Diversity and disparity simulator

In treats: Trees and Traits Simulations

Diversity and disparity simulator

Description

Simulating phylogenetic trees and traits. See full manual here: https://github.com/TGuillerme/treats

Usage

treats(
  stop.rule,
  bd.params,
  traits = NULL,
  modifiers = NULL,
  events = NULL,
  save.steps = NULL,
  null.error = FALSE,
  replicates,
  verbose = TRUE
)

Arguments

stop.rule	The rules on when to stop the simulation (see details).
bd.params	A "bd.params" object or a named list of parameters for the birth-death process (see details or make.bd.params).
traits	A "traits" object (see make.traits).
modifiers	A "modifiers" object (see make.modifiers).
events	A "events" object (see make.events).
save.steps	Optional, "numeric" value to save the simulations at specific internal points (this can slow down the algorithm significantly for large trees).
null.error	Logical, whether to return an error when the birth-death parameters fails to build a tree (FALSE; default and highly recommended) or whether to return NULL (TRUE). Can also be set to an integer value for the numbers of trials (see details).
replicates	Optional, the number of replicates for the simulation.
verbose	Logical, whether to be verbose (TRUE; default) or not (FALSE).

Details

stop.rule: The rule(s) for when to stop the simulation. When multiple rules are given, the simulation stops when any rule is broken. The allowed rules are:

• max.taxa The maximum number of taxa (including extinct ones).

• max.living The maximum number of living taxa (i.e. non extinct).

• max.time The maximum amount of phylogenetic (in arbitrary units).

bd.params: This can be either a "treats" "bd.params" object (see make.bd.params) or a list of named parameters. The allowed parameters are:

• speciation The speciation parameter value.

• extinction The extinction parameter value.

By default, this parameter is set to bd.params = list(speciation = 1)

If null.error is set to a numeric value, the function will run multiple times until a correct tree is generated. Using this option can greatly increase computational time!

Value

This function outputs either a "phylo" object if no traits where generated or a treats object that is a list of at least two elements: $tree, a "phylo" object and $data, a "matrix" of the trait values.

Author(s)

Thomas Guillerme

See Also

plot.treats make.traits make.modifiers make.events

Examples

## Setting pure birth tree (no extinction) parameters
my_bd_params <- list(speciation = 1)
## Setting a stopping rule: stop when reaching 10 taxa.
my_stop_rule <- list(max.taxa = 10) 

## Run a birth tree without traits
a_tree <- treats(bd.params = my_bd_params,
               stop.rule = my_stop_rule)
## Plot the results
plot(a_tree)

## Add an extinction parameter
my_bd_params$extinction <- 1/3

## Add a simple trait simulation (default Brownian motion)
my_trait <- make.traits()

## Run a birth-death tree with traits simulation
treats(bd.params = my_bd_params,
     stop.rule = my_stop_rule,
     traits    = my_trait)

## Simulating a tree using modifiers
## Making a modifier to make speciation trait dependent
my_modifiers <- make.modifiers(branch.length = branch.length.trait,
                               selection     = selection,
                               speciation    = speciation.trait)

## Simulating the tree
treats(stop.rule = list(max.taxa = 20),
     traits = make.traits(),
     modifiers = my_modifiers)

## Run a birth death tree with an event
## 80% mass extinction at time 4
mass_extinction <- make.events(
                      target       = "taxa",
                      condition    = age.condition(4),
                      modification = random.extinction(0.8))

## Set the simulation parameters
stop.rule <- list(max.time = 5)
bd.params <- list(extinction = 0, speciation = 1)

## Run the simulations
set.seed(123)
results <- treats(bd.params = bd.params,
                stop.rule = stop.rule,
                events    = mass_extinction)
## Plot the results
plot(results, show.tip.label = FALSE)
axisPhylo()

treats documentation built on June 8, 2025, 1:43 p.m.