---
title: "Estimating extinction dates from sighting records"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Estimating extinction dates from sighting records}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.width = 7, fig.height = 5)
```

## Overview

EDE implements eleven procedures for inference about extinction from sighting
records. Some estimate an endpoint directly; others test whether a species
could plausibly have persisted to a candidate time. The latter return
frequentist p-values, not posterior probabilities that the species is extant.

The column containing these p-values is currently named `chance` for
compatibility with EDE 0.1.0.

## Input and observation origin

```{r}
library(EDE)

years <- c(1900, 1902, 1903, 1905, 1907, 1908, 1910, 1912,
           1915, 1918, 1920, 1923, 1925, 1928, 1930, 1933, 1936)
counts <- c(4, 3, 5, 2, 3, 4, 2, 1, 2, 1, 1, 2, 1, 1, 1, 1, 1)
sd <- sighting_data(data.frame(year = years, sightings = counts))
```

The earliest supplied time defines the observation origin. Include an initial
zero-count row if observation began before the first sighting. Methods differ
in their treatment of counts: OLE treats counts as independent events,
constant-rate Solow uses occupied times, and Burgman uses full frequencies.

## Endpoint estimators

`robson1964()` uses the final gap for a jackknife point estimate and a
one-sided confidence interval. `strauss1989()` supplies an unbiased endpoint
estimate and one-sided interval under uniform occurrence. `ole()` fits the
Weibull extreme-value model to the `k` most recent sighting events.

```{r}
robson1964(sd)
strauss1989(sd)
ole(sd)
ole(sd, k = 10)
```

## Persistence tests

```{r}
solow1993(sd, test_year = 2000)
solow1993b(sd, test_year = 2000)
solow2005(sd, test_year = 2000)
mcinerny2006(sd, test_year = 2000)
burgman1995(sd, test_year = 2000)
solow_roberts2003(sd, test_year = 2000)
jaric2010(sd, test_year = 2000)
```

- `solow1993()` assumes a stationary Poisson process.
- `solow1993b()` allows an exponentially declining sighting rate.
- `solow2005()` uses the Weibull extreme-value p-value associated with OLE.
- `mcinerny2006()` conditions on the previous binary sighting rate.
- `burgman1995()` tests the longest run of empty discrete periods.
- `solow_roberts2003()` uses only the two most recent distinct sightings.
- `jaric2010()` uses the average interval and can adjust it for a trend in
  consecutive interval lengths.

The full p-value curve is available with `data_out = TRUE`:

```{r}
curve <- jaric2010(sd, test_year = 2000, data_out = TRUE)
plot(curve$time, curve$chance, type = "l",
     xlab = "candidate time", ylab = "p-value")
abline(h = 0.05, lty = 2)
```

## Records of variable reliability

`jaric_roberts2014()` assigns a probability of validity to every occupied
time. The current implementation requires binary counts because reliability
belongs to individual observations.

```{r}
uncertain <- sighting_data(data.frame(
  year = c(1900, 1910, 1920, 1930),
  sightings = 1
))

jaric_roberts2014(
  uncertain,
  reliability = c(1.0, 0.9, 0.6, 0.3)
)
```

The result includes the effective number of sightings and the
reliability-adjusted endpoint as additional components. Reliabilities should
be elicited independently of the extinction analysis.

## Choosing a method

- Use OLE when the recent record is sufficiently long and an extreme-value
  model is defensible.
- Use `solow1993()` only when a constant sighting rate is plausible.
- Use `solow1993b()` for an approximately exponential decline.
- Use `jaric2010()` when the intervals themselves show a gradual trend.
- Use `burgman1995()` for discrete frequency data and longest-run questions.
- Use `jaric_roberts2014()` when observations have explicit reliability
  assessments.

Running several scientifically defensible methods is useful, but p-values from
models whose assumptions are violated should not be combined or interpreted as
extinction probabilities.

## References

Burgman, M. A., Grimson, R. C., & Ferson, S. (1995). Inferring threat from
scientific collections. *Conservation Biology*, 9(4), 923-928.

Jarić, I., & Ebenhard, T. (2010). A method for inferring extinction based on
sighting records that change in frequency over time. *Wildlife Biology*,
16(3), 267-275.

Jarić, I., & Roberts, D. L. (2014). Accounting for observation reliability
when inferring extinction based on sighting records. *Biodiversity and
Conservation*, 23(11), 2801-2815.

McInerny, G. J., Roberts, D. L., Davy, A. J., & Cribb, P. J. (2006).
Significance of sighting rate in inferring extinction and threat.
*Conservation Biology*, 20(2), 562-567.

Roberts, D. L., & Solow, A. R. (2003). When did the dodo become extinct?
*Nature*, 426, 245.

Robson, D. S., & Whitlock, J. H. (1964). Estimation of a truncation point.
*Biometrika*, 51, 33-39.

Solow, A. R. (1993). Inferring extinction from sighting data. *Ecology*, 74,
962-964.

Solow, A. R. (1993). Inferring extinction in a declining population.
*Journal of Mathematical Biology*, 32, 79-82.

Solow, A. R. (2005). Inferring extinction from a sighting record.
*Mathematical Biosciences*, 195, 47-55.

Solow, A. R., & Roberts, D. L. (2003). A nonparametric test for extinction
based on a sighting record. *Ecology*, 84, 1329-1332.

Strauss, D., & Sadler, P. M. (1989). Classical confidence intervals and
Bayesian probability estimates for ends of local taxon ranges.
*Mathematical Geology*, 21, 411-427.