This function calculates various metrics from occurrence datasets in the form of time series.

## Usage

```
divDyn(
x,
tax,
bin = NULL,
age = NULL,
revtime = FALSE,
breaks = NULL,
coll = NULL,
ref = NULL,
om = NULL,
noNAStart = FALSE,
data.frame = TRUE,
filterNA = FALSE
)
```

## Arguments

- x
`(data.frame)`

Fossil occurrence table.- tax
`(character)`

Variable name of the occurring taxa (variable type:`factor`

or`character`

- such as`"genus"`

- bin
`(character)`

Variable name of the discrete bin numbers of the occurrences. This variable should be`numeric`

. Time flows from lower to higher values by default. Use`revtime`

to reverse this order.- age
`(character)`

Variable name of the ages of the occurrences that will be sliced with the`slice`

function using the intervals provided in`breaks`

. This variable should be`numeric`

. Time flows from higher to lower values by default. Use`revtime`

to reverse this order.- revtime
`(logical)`

Argument for reversing the default direction of time. Setting this argument to`TRUE`

will make time flow from higher to lower values when`bin`

is used, and from lower to higher values, when`age`

is given. CAUTION: Failing to set this argument properly can make originations become extinctions and vice versa!- breaks
`(numeric)`

If`NULL`

(default) the used values in the`bin`

variable will designate independent time slices that follow each other in succession. If a vector is provided, than the numeric entries in`bin`

will be binned similarly to the`hist`

or`cut`

function. The order of elements in this vector is arbitrary.- coll
`(character)`

The variable name of the collection identifiers. (optional, only for use with the internal`omit`

function)- ref
`(character)`

The variable name of the reference identifiers. (optional, only for use with the internal`omit`

function)- om
`(character)`

The`om`

argument of the`omit()`

function. If set to`NULL`

(default), then no occurrences will be omitted before the execution of the function.- noNAStart
(logical) Useful when the entries in the

`bin`

variable do not start from bin no. 1, but positive integer bin numbers are provided. Then`noNAStart=TRUE`

will cut the first part of the resulting table, so the first row will contain the estimates for the lowest bin number. In case of positive integer bin identifiers, and if`noNAStart=FALSE`

, the index of the row will be the bin number.- data.frame
`(logical)`

Should the output be a`data.frame`

or a`matrix`

?- filterNA
`(logical)`

The`filterNA`

parameter of the`omit`

function.

## Details

The following variables are produced:

`bin`

: Bin number, or the numeric identifier of the bin.

`tThrough`

: Number of through-ranging taxa, taxa that have first occurrences before, and last occurrences after the focal bin.

`tOri`

: Number of originating taxa, taxa that have first occurrences in the focal bin, and last occurrences after it.

`tExt`

: Number of taxa getting extinct. These are taxa that have first occurrences before the focal bin, and last occurrences in it.

`tSing`

: Number of stratigraphic singleton (single-interval) taxa, taxa that only occur in the focal bin.

`t2d`

: Number of lower two timers (Alroy, 2008; 2014), taxa that are present in the *i*-1th and the ith bin (focal bin).

`t2u`

: Number of upper two timers (Alroy, 2008; 2014), taxa that are present in the *i*th (focal) and the *i*+1th bin. (Alroy, 2008; 2014)

`tGFu`

: Number of upper gap-fillers (Alroy, 2014), taxa that occurr in bin *i*+2 and *i*-1, but were not found in *i*+1. (Alroy, 2014)

`tGFd`

: Number of lower gap-fillers (Alroy, 2014), taxa that occurr in bin *i*-2 and *i*+1, but were not found in *i*-1. (Alroy, 2014)

`t3`

: Number of three timer taxa (Alroy, 2008; 2014), present in bin *i*-1, *i*, and *i*+1. (Alroy, 2008; 2014)

`tPart`

: Part timer taxa (Alroy, 2008; 2014), present in bin *i*-1,and *i*+1, but not in bin *i*.

`extProp`

: Proportional extinctions including single-interval taxa: *(tExt + tSing) / (tThrough + tOri + tExt + tSing)*.

`oriProp`

: Proportional originations including single-interval taxa: *(tOri + tSing) / (tThrough + tOri + tExt + tSing)*.

`extPC`

: Per capita extinction rates of Foote (1999). *-log(tExt/(tExt + tThrough))*. Values are not normalized with bin lengths. Similar equations were used by Alroy (1996) but without taking the logarithm.

`oriPC`

: Per capita origination rates of Foote (1999). *-log(tOri/(tOri + tThrough))*. Values are not normalized with bin lengths. Similar equations were used by Alroy (1996) but without taking the logarithm.

`ext3t`

: Three-timer extinction rates of Alroy (2008). *log(t2d/t3)*.

`ori3t`

: Three-timer origination rates of Alroy (2008). *log(t2u/t3)*.

`extC3t`

: Corrected three-timer extinction rates of Alroy (2008). *ext3t[i] + log(samp3t[i+1])*.

`oriC3t`

: Corrected three-timer origination rates of Alroy (2008). *ori3t[i] + log(samp3t[i-1])*.

`divSIB`

: Sampled-in-bin diversity (richness), the number of genera sampled in the focal bin.

`divCSIB`

: Corrected sampled-in-bin diversity (richness). *divSIB/samp3t*totSamp3t*, where *totSamp3t* is total three-timer sampling completeness of the dataset (Alroy, 2008).

`divBC`

: Boundary-crosser diversity (richness), the number of taxa with ranges crossing the boundaries of the interval. *tExt + tOri + tThrough*.

`divRT`

: Range-through diversity (richness), all taxa in the interval, based on the range-through assumption. *(tSing + tOri + tExt + tThrough)*.

`sampRange`

: Range-based sampling probability, without observed range end-points (Foote), *(divSIB - tExt - tOri- t-Sing)/tThrough*

`samp3t`

: Three-timer sampling completeness of Alroy (2008). *t3/(t3+tPart)*

`extGF`

: Gap-filler extinction rates of Alroy(2014). *log((t2d + tPart)/(t3+tPart+tGFd))*

`oriGF`

: Gap-filler origination rates of Alroy(2014). *log((t2u + tPart)/(t3+tPart+tGFd))*

`E2f3`

: Second-for-third extinction propotions of Alroy (2015). As these metrics are based on an algorithmic approach, for the equations please refer to the Alroy (2015, p. 634, right column and Eq. 4)). See source code (https://github.com/divDyn/divDyn) for the exact implementation, found in the `Metrics`

function in the diversityDynamics.R file.

`O2f3`

: Second-for-third origination propotions of Alroy (2015). Please see `E2f3`

.

`ext2f3`

: Second-for-third extinction rates (based on Alroy, 2015). Transformed to the usual rate form with *log(1/(1-E2f3))*.

`ori2f3`

: Second-for-third origination rates (based on Alroy, 2015). Transformed to the usual rate form with *log(1/(1-O2f3))*.

**References:**

Foote, M. (1999) Morphological Diversity In The Evolutionary Radiation Of Paleozoic and Post-Paleozoic Crinoids. Paleobiology 25, 1–115. doi:10.1017/S0094837300020236.

Alroy, J. (2008) Dynamics of origination and extinction in the marine fossil record. Proceedings of the National Academy of Science 105, 11536-11542. doi: 10.1073/pnas.0802597105

Alroy, J. (2014) Accurate and precise estimates of origination and extinction rates. Paleobiology 40, 374-397. doi: 10.1666/13036

Alroy, J. (2015) A more precise speciation and extinction rate estimator. Paleobiology 41, 633-639. doi: 10.1017/pab.2015.26

## Examples

```
# import data
data(corals)
data(stages)
# calculate metrics of diversity dynamics
dd <- divDyn(corals, tax="genus", bin="stg")
# plotting
tsplot(stages, shading="series", boxes="sys", xlim=c(260,0),
ylab="range-through diversity (genera)", ylim=c(0,230))
lines(stages$mid, dd$divRT, lwd=2)
# with omission of single reference taxa
ddNoSing <- divDyn(corals, tax="genus", bin="stg", om="ref", ref="reference_no")
lines(stages$mid, ddNoSing$divRT, lwd=2, col="red")
# using the estimated ages (less robust) - 10 million years
# mean ages
corals$me_ma <- apply(corals[, c("max_ma", "min_ma")], 1, mean)
# ages reverse the direction of time! set ages to TRUE in this case
ddRadio10 <- divDyn(corals, tax="genus", age="me_ma",
breaks=seq(250,0,-10))
lines(ddRadio10$me_ma, ddRadio10$divRT, lwd=2, col="green")
# legend
legend("topleft", legend=c("all", "no single-ref. taxa", "all, estimated ages"),
col=c("black", "red", "green"), lwd=c(2,2,2), bg="white")
```