README.md

In timescapes: Quantifying Temporal Structure Across Landscapes

timescapes

timescapes calculates interpretable metrics for binary conditions observed through time. A 1 means that a condition is present and a 0 means that it is absent. The same metrics can be applied to a single vector or independently to every cell in a raster time series.

Installation

Install the development version from GitHub:

remotes::install_github("LoganHysen/timescapes")

Vector metrics

Calculate one metric by supplying an exact name from ts_list_metrics():

library(timescapes)

x <- c(1, 1, 0, 0, 1, 1, 1, 0)

ts_list_metrics()
ts_metric(x, "n_periods")
ts_metric(x, "gap_mean")
ts_metric(x, "core_time_index", min_core_period = 3)

The available metrics are:

• total_time: number of time steps with presence
• n_periods: number of distinct presence periods
• gap_mean: mean length of absence periods
• gap_max: maximum length of an absence period
• duration_sd: variability in presence-period lengths
• edge_density: proportion of adjacent steps that change state
• autocorr: lag-1 Pearson autocorrelation
• aggregation: proportion of adjacent steps with the same state
• core_time_index: proportion of presence time in qualifying core periods
• n_core_periods: number of presence periods containing core time

Metric names must match exactly. Inputs must be non-empty numeric vectors containing only 0, 1, or NA. If any time step is missing, the metric is NA.

Raster metrics

For a terra::SpatRaster, layers are treated as ordered time steps and the metric is calculated independently for every cell:

library(terra)
library(timescapes)

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")
plot(periods)

Raster values must also be binary. A cell with one or more missing time steps receives an NA result.

Vignettes

• Getting Started

Development

Run the tests and CRAN checks with:

testthat::test_local()
devtools::check(args = "--as-cran")

License

This package is licensed under the MIT License (see the LICENSE file).

Citation

If you use timescapes in published work, please cite it as:

Hysen L, Mannam RR, Moturi, A, Wan HY (2026). timescapes: Quantifying temporal structure across landscapes (Version 0.1.0) [R package]. https://github.com/LoganHysen/timescapes

Authors

Logan Hysen: [e-mail] Ho Yi Wan: [e-mail] Ramcharan Reddy Mannam: [e-mail] Abhiram Moturi: [e-mail]

Metric options

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.

timescapes documentation built on Nov. 14, 2026, 5:10 p.m.