make.modifiers: make.modifiers

In treats: Trees and Traits Simulations

make.modifiers

Description

Making modifiers objects for treats based on an ancestor's (parent) trait.

Usage

make.modifiers(
  branch.length = NULL,
  selection = NULL,
  speciation = NULL,
  condition = NULL,
  modify = NULL,
  add = NULL,
  update = NULL,
  test = TRUE
)

Arguments

branch.length	A function for the waiting time generating branch length (can be left empty for the defeault branch length function; see details).
selection	A function for selecting the lineage(s) affected by speciation (can be left empty for the default selection function; see details).
speciation	A function for triggering the speciation events (can be left empty for the default speciation function; see details).
condition	A function giving the condition on which to modify the output of branch.length or speciation (see details). If NULL the condition is always met.
modify	A function giving the rule of how to modify the output of branch.length or speciation (see details). If NULL no modification is used.
add	Whether to add this modifier to a "treats" "modifier" object.
update	Optional, another previous "treats" modifiers object to update (see details).
test	Logical whether to test if the modifiers object will work (default is TRUE).

Details

branch.length, selection and speciation must be a functions that intakes the following arguments: bd.params, lineage, trait.values, modify.fun. If left empty, any of these arguments is considered as NULL.

The default branch.length function is drawing a random number from the exponantial distribution with a rate equal to the current number of taxa multiplied by the speciation and extinction (rexp(1, n_taxa * (speciation + extinction))).

The default selection function is randomly drawing a single lineage among the ones present at the time of the speciation (sample(n_taxa, 1)).

The default speciation function is drawing a random number from a uniform distribution (0,1) and starts a speciation event if this random number is lower than the ration of speciation on speciation and extinction (runif(1) < (speciation/(speciation + extinction))). If the random number is greater, the lineage goes extinct.

condition must be a function with unambiguous input (the inputs listed about for branch.length and speciation) and must output a single logical value.

For example a conditional on the number of taxa:

condition = function(lineage) return(lineage$n < 1)

or a conditional on the trait values:

condition = function(trait.values, lineage) { parent.traits(trait.values, lineage) < mean(trait.values) }

modify must be a function with at least one input named x (which will be the branch length or the speciation trigger to value depending on the modifier) and must return a numeric value. For example a constant modification of the input:

modify = function(x) return(x * 2)

or a modifier depending on the number of taxa:

modify = function(x, lineage) return(x/lineage$n)

When using update, the provided arguments (to make.modifiers) will be the ones updated in the "modifiers" object. If the "modifiers" object contains multiple modifiers (branch.length, selection or speciation), only the called arguments will be updated (e.g. make.modifiers(update = previous_modifiers, speciation = new_speciation) will only update the speciation process).

More details about the modifiers functions is explained in the treats manual: http://tguillerme.github.io/treats.

Value

This function outputs a treats object that is a named list of elements handled internally by the treats function.

Author(s)

Thomas Guillerme

See Also

treats modifiers

Examples

## These functions should be fed to the make.modifiers function to create
## modifiers for treats objects. For example, the following sets specifies that
## the branch length should be generated using the branch.length.trait function
## the selection using the selection function and the speciation using the
## speciation.trait function:
my_modifiers <- make.modifiers(branch.length = branch.length.trait,
                               selection     = selection,
                               speciation    = speciation.trait)

## Creating a treats simulation using these modifiers
treats(stop.rule = list(max.taxa = 20),
     traits = make.traits(),
     modifiers = my_modifiers)

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