Origination/extinction response table for statistical modelling.

This function takes an occurrence dataset and reformats it to a table that can be used as input for logistic models.

Usage

modeltab(
  x,
  tax,
  bin,
  taxvars = NULL,
  rt = FALSE,
  singletons = FALSE,
  probs = NULL
)

Arguments

x

(data.frame) Fossil occurrence data.frame.

tax

(character) Variable name of the occurring taxa (variable type: factor or character - such as "genus")

bin

(character) Variable name of the bin numbers of the occurrences. This variable should be numeric and should increase as time passes by (use negative values for age estimates). The current version only supports discreet, non-negative integer interval numbers.

taxvars

(character) Taxon-specific column names of the variables that should be included in the output table. Only one entry/taxon is used, make sure that the data are clean.

rt

(logical) Should the range-through assumption be applied within the function? If set to TRUE then missing occurrences will be interpolated with FALSE values in both the ext and ori variables. .

singletons

(logical) Should single-interval taxa be included from the final table? This is not recommended, as it is impossible to get a FALSE response for these taxa.

probs

(logical) When set to NULL, the response variable will be binary. When set to "samp3t" or "sampRange" the response results will be probabilities, based on the three-timer sampling completeness, or the range-based sampling completeness, respectively.

Value

A data.frame with binary response variables.

Details

Every entry in the output table corresponds to one cell in the bin/tax matrix. This function omits duplicates and concatenates two logical vectors (response variables) to the occurrence dataset: The ori vector is TRUE in the interval when the taxon first appeared, and FALSE in all others. The ext vector is TRUE in the interval the taxon appeared for the last time, and FALSE in the rest.

The true date of extinction and origination is unknown, therefore these events can only be expressed as probabilities. The argument probs allows the replacement of a binary response with two probability values, which are based on the apparent sampling patterns. For extinctions, when probs is set to "samp3t", the response parameter for extinctions in the last bin of appearance is set to the three-timer sampling compelteness of the following bin. Assuming that the taxon'as range offset is not larger than a whole bin, if the taxon did not go extinct in the bin in which it appeared the last time, it is assumed to be going extinct in the following bin, and the remainder (1 - sampling completeness) is assigned to that bin. The pattern is reversed for originations. For probs="sampRange", the range-based completeness measures are applied in a similar fashion. For Phanerozoic-scale analyses, a whole bin difference between apparent event and the actual event is reasonable. See more in Reddin et al. 2021. Note that the response probabilities are set to missing values (NAs) when the probabilities cannot be calculated. The variable ext is also set to NaN for the early virtual extension of the range, and ori is treated the same for the late-extension.

References:

Reddin, C. J., Kocsis, Á. T., Aberhan, M., & Kiessling, W. (2021). Victims of ancient hyperthermal events herald the fates of marine clades and traits under global warming. Global Change Biology, 27(4), 868–878. https://doi.org/10.1111/gcb.15434

Examples

# load necessary data
data(corals)
# simple table
modTab<-modeltab(corals, bin="stg", tax="genus", taxvars=c("ecology", "family"))
# probabilities for extinction modeling
modTab2 <- modeltab(corals, bin="stg", tax="genus", probs="samp3t")
# only extinction response (omit virtual origination extensions)
extTab <- modTab2[!is.nan(modTab2$ext), ]
# only extinction response (omit virtual extinction extensions)
oriTab <- modTab2[!is.nan(modTab2$ori), ]