---
title: "Getting Started with timescapes"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with timescapes}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

`timescapes` summarizes a binary condition through time. A value of `1`
indicates presence and `0` indicates absence. Metric names must match a value
returned by `ts_list_metrics()` exactly.

## A binary vector

Here is a small example with two periods of the presence of some condition separated by
the absence of that condition. Each time step in this case represents a year, so the first two years 
have the condition, then two years of absence, followed by three 
more years of presence and one year of absence.

```{r vector}
library(timescapes)

x <- c(1, 1, 0, 0, 1, 1, 1, 0)

```

The values can be visualized as a simple timeline.

```{r plot-example-series}
plot(
  seq_along(x), x,
  type = "s",
  ylim = c(-0.1, 1.1),
  xlab = "Time step",
  ylab = "Habitat available",
  yaxt = "n",
  main = "Binary habitat availability through time"
)
axis(2, at = c(0, 1), labels = c("No", "Yes"), las = 1)
```

Now, calculate a few metrics using ts_metric(), selecting from the available
list of metrics found by using ts_list_metrics().

``` {r metrics}
ts_list_metrics()
ts_metric(x, "total_time")
ts_metric(x, "n_periods")
ts_metric(x, "gap_mean")
```


Time steps are unitless ordered observations with a duration defined by the user.
Gap metrics include leading and trailing absence runs by default. Set
`include_boundary_gaps = FALSE` to count only gaps between presence periods;
no qualifying gaps returns 0, including for an all-absence series.

For core metrics, supply `min_core_period`, a positive whole number of time
steps. A presence run qualifies when its full length is at least this threshold.
`core_time_index` divides the total length of qualifying runs by total presence
time (0 if there is no presence); `n_core_periods` counts qualifying runs.
Omitting the threshold uses 15 time steps and issues one warning per vector or
raster call. The former `core_buffer` argument is no longer accepted.

For example:

```{r core}
ts_metric(x, "core_time_index", min_core_period = 3)
ts_metric(x, "n_core_periods", min_core_period = 3)
```

Every observed value must be `0` or `1`. A series containing a missing time
step produces `NA`, because removing or reinterpreting that step could change
the temporal pattern.

```{r missing}
ts_metric(c(1, 1, NA, 0), "n_periods")
```

## A raster time series

A `terra::SpatRaster` can represent the same type of series at many locations.
Layers are treated as ordered time steps.

```{r raster}
library(terra)

r <- rast(nrows = 2, ncols = 2, nlyrs = 4)
values(r) <- matrix(
  c(
    1, 1, 0, 1,
    0, 0, 0, 0,
    1, 0, 1, 0,
    1, 1, 1, 1
  ),
  nrow = ncell(r),
  byrow = TRUE
)

periods <- ts_raster_metric(r, "n_periods")
values(periods)
```

The result is a one-layer raster with the same geometry as the input. Raster
cells containing missing or non-binary values follow the same validation rules
as vector inputs.

## Citation

Wan, H. Y. (2025). It’s about time: Temporal fragmentation and metrics for habitat change. *Landscape Ecology*, 40, 226. <https://doi.org/10.1007/s10980-025-02252-4>
