events.modifications {treats}

Events modifications

Description

Inbuilt modifications functions for helping designing events

Usage

events.modification(x, ...)

Arguments

x

a numerical value to update.

...

any specific argument for the modification (see details).

Details

The following functions allow to design specific modifications for events:

• modifications for the target "taxa"

  • random.extinction: this function removes (makes extinct) a proportion of living taxa when the event is triggered. The proportion of taxa to remove can be changed with the argument x.

  • trait.extinction: this function removes (makes extinct) a number of living taxa based on their trait(s) values when the event is triggered. The trait value is specified with the argument x.This function has one optional argument:

    • condition to specify the condition in relation to that trait value (the default is condition = `<` meaning taxa with a trait value lower that x will go extinct).

    • trait to specify which trait will be affected (the default is trait = 1, meaning it will only consider the first trait).

• modifications for the target "bd.params"

  • bd.params.update: this function updates a "bd.params" object within the birth death process. It takes any unambiguous named argument to be passed to make.bd.params. For example, to update the speciation from any current rate to a new rate of 42, you can use bd.params.update(speciation = 42).

• modifications for the target "traits"

  • traits.update: this function updates a "traits" object within the birth death process. It takes any unambiguous named argument to be passed to make.traits. For example, to update the trait process from the current one to an OU process, you can use traits.update(process = OU.process).

• modifications for the target "modifiers"

  • modifiers.update: this function updates a "modifiers" object within the birth death process. It takes any unambiguous named argument to be passed to make.modifiers. For example, to update the speciation from the current process to be dependent to trait values, you can use modifiers.update(speciation = speciation.trait).

• modifications for the target "founding"

  • founding.event: this function runs an independent birth-death process when the condition is met. This function takes any of the arguments normally passed to treats ("bd.params", "traits", "modifiers" and "events"). The stop.rule and other arguments are handled internally: namely the stop.rule argument is updated to match the time and number of taxa when the founding event is triggered. Note that this can lead to the simulation stopping just before reaching the max.taxa or max.living stop rule.

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

Value

This function outputs a "function" to be passed to make.events.

Author(s)

Thomas Guillerme

See Also

treats make.events events.conditions

Examples

## Generating a mass extinction
## 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()

## Changing the trait process
## The 95% upper quantile value of a distribution
upper.95 <- function(x) {
    return(quantile(x, prob = 0.95))
} 
## Create an event to change the trait process
change_process <- make.events(
                  target       = "traits",
                  ## condition is triggered if(upper.95(x) > 3)
                  condition    = trait.condition(3, condition = `>`, what = upper.95),
                  modification = traits.update(process = OU.process))

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

## Run the simulations
set.seed(1)
no_change <- treats(bd.params = bd.params,
                  stop.rule = stop.rule,
                  traits    = traits)
set.seed(1)
process_change <- treats(bd.params = bd.params,
                       stop.rule = stop.rule,
                       traits    = traits,
                       events    = change_process)
## Plot the results
oldpar <- par(mfrow = c(1,2))
plot(no_change, ylim = c(-7, 7))
plot(process_change, ylim = c(-7, 7))
par(oldpar)