---
title: "Getting started with toeclim"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with toeclim}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.width = 6,
                      fig.height = 4)
library(toeclim)
```

## What is time of emergence?

Climate records combine a slowly evolving *forced signal* (for example
greenhouse-gas driven warming) with *internal variability* (weather, ENSO,
decadal oscillations). The **time of emergence** (ToE) is the moment the signal
becomes large relative to that variability, so that a change can be told apart
from natural fluctuations (Hawkins and Sutton, 2012).

`toeclim` implements a transparent, configurable version of this idea and
attaches uncertainty to it:

1. estimate a smooth signal relative to a baseline mean;
2. estimate noise from a baseline period;
3. declare emergence when the signal-to-noise ratio exceeds `k` for at least
   `persist` consecutive years (optionally through to the end of the record);
4. bootstrap the residuals to see how much of the answer is just noise.

## A single series

```{r simulate}
d <- toe_simulate(n_years = 150, slope = 0.03, onset = 1970,
                  sigma = 0.3, phi = 0.5, seed = 10)
head(d, 3)
```

The forced response is flat until 1970 and then warms at 0.03 units per year,
so the true signal is known.

```{r trend}
toe_trend(d$member_01, d$year)
```

```{r emerge}
fit <- toe_emerge(d$member_01, d$year, baseline = c(1900, 1950),
                  n_boot = 200, seed = 1)
fit
```

```{r plot-emerge}
plot(fit)
```

The shaded orange band is the bootstrap interval for the emergence year. The
grey band shows the baseline mean plus or minus `k` noise standard deviations.

## How likely is emergence by a given date?

```{r prob}
toe_prob(fit, times = c(1990, 2000, 2010, 2020))
```

## Sensitivity to subjective choices

The threshold `k` and the persistence requirement are choices, not physics.
`toe_sensitivity()` shows how much they matter.

```{r sens}
toe_sensitivity(d$member_01, d$year, baseline = c(1900, 1950),
                k = c(1, 2, 3), persist = c(1, 5, 10))
```

## Ensembles

For large ensembles, apply the method to every member and inspect the spread.
The bundled `toe_example` data set has ten synthetic members.

```{r ensemble}
members <- toe_example[, grep("^member", names(toe_example))]
ens <- toe_ensemble(members, toe_example$year, baseline = c(1900, 1960))
ens
```

```{r plot-ensemble}
plot(ens)
```

The *pooled* estimate uses the ensemble-mean signal, which has little noise of
its own, against the typical single-realisation noise. It is usually earlier
than most members: the ensemble mean reveals the forced response before any
single realisation can.

## Preparing real data

Monthly data can be converted to seasonal-cycle-free anomalies and then to
annual means:

```{r prepare}
dates <- seq(as.Date("1950-01-01"), as.Date("2019-12-01"), by = "month")
mon <- as.integer(format(dates, "%m"))
yr  <- as.integer(format(dates, "%Y"))
x <- 12 + 8 * sin(2 * pi * mon / 12) + 0.02 * pmax(0, yr - 1980) +
  rnorm(length(dates), sd = 0.8)

anom   <- toe_anomaly(x, dates, baseline = c(1950, 1979), by = "month")
annual <- toe_annual(anom$anomaly, dates)
head(annual, 3)
```

```{r real-emerge}
toe_emerge(annual$value, annual$year, baseline = c(1950, 1979))
```

## Notes and limitations

* The signal is a statistical smoother, not a physical attribution. A `"loess"`
  signal will follow low-frequency internal variability if the span is small.
* Noise from a short baseline is uncertain; `toe_noise()` reports the
  effective sample size.
* Persistence is counted in observations, so use regularly spaced data.
* Bootstrap intervals describe sampling uncertainty given the chosen
  definition, not structural uncertainty about the definition itself.

## References

Hawkins, E. and Sutton, R. (2012). Time of emergence of climate signals.
*Geophysical Research Letters*, 39, L01702. doi:10.1029/2011GL050087

Yue, S., Pilon, P., Phinney, B. and Cavadias, G. (2002). The influence of
autocorrelation on the ability to detect trend in hydrological series.
*Hydrological Processes*, 16, 1807-1829. doi:10.1002/hyp.1095