Package 'timescapes'

Title: Quantifying Temporal Structure Across Landscapes
Description: Calculates interpretable mathematical summaries of binary conditions observed through time, based on metrics presented in Wan, Ho Yi (2025) <doi:10.1007/s10980-025-02252-4>. Metrics can be calculated for a single binary vector or independently for every cell in a raster time series.
Authors: Logan Hysen [aut, cre, cph], Ramcharan Reddy Mannam [aut, cph], Abhiram Moturi [aut, cph], Ho Yi Wan [aut, cph]
Maintainer: Logan Hysen <[email protected]>
License: MIT + file LICENSE
Version: 0.1.0
Built: 2026-11-14 12:05:02 UTC
Source: https://github.com/loganhysen/timescapes

Help Index


List available binary timescape metrics

Description

List available binary timescape metrics

Usage

ts_list_metrics()

Value

A character vector of exact metric names accepted by ts_metric() and ts_raster_metric().

Examples

ts_list_metrics()

Calculate a binary timescape metric

Description

Calculates one named metric for a numeric vector in which 1 means that a condition is present and 0 means that it is absent. Metric names must match ts_list_metrics() exactly. If x contains any missing value, the result is NA_real_.

Usage

ts_metric(x, metric, ...)

Arguments

x

A non-empty numeric vector containing only 0, 1, or NA.

metric

One exact metric name returned by ts_list_metrics().

...

Named metric-specific arguments. core_time_index and n_core_periods accept min_core_period, a positive whole number of time steps. If omitted, 15 is used with a warning once per call. gap_mean and gap_max accept include_boundary_gaps (default TRUE); set it to FALSE to count only absence runs between presence periods.

Value

One numeric value.

Metrics

Let n be the number of time steps, let an occupied period be a maximal run of ones, and let a gap be any maximal run of zeros, including leading and trailing runs by default. With include_boundary_gaps = FALSE, only gaps between presence periods count. No qualifying gaps (including an all-zero series with boundary gaps excluded) returns 0.

  • total_time: sum of the series; range 0 to n.

  • n_periods: number of occupied periods; range 0 to ceiling(n / 2).

  • gap_mean: arithmetic mean of gap lengths, or 0 when no gaps occur.

  • gap_max: maximum gap length, or 0 when no gaps occur.

  • duration_sd: sample standard deviation of occupied-period lengths, or 0 when fewer than two occupied periods occur.

  • edge_density: number of changes between adjacent time steps divided by n - 1; returns 0 for a one-step series.

  • autocorr: Pearson correlation between steps 1 through n - 1 and steps 2 through n; returns NA when the correlation is undefined.

  • aggregation: proportion of adjacent time-step pairs that are equal; returns 0 for a one-step series.

  • core_time_index: proportion of occupied time in presence runs whose full length is at least min_core_period; returns 0 when no presence occurs.

  • n_core_periods: number of such qualifying presence runs.

Time steps are unitless ordered observations; their duration is user-defined.

References

Wan, H. Y. (2025). It's about time: Temporal fragmentation and metrics for habitat change. Landscape Ecology, 40, 226. doi:10.1007/s10980-025-02252-4

Examples

x <- c(1, 1, 0, 0, 1, 1, 1, 0)
ts_metric(x, "n_periods")
ts_metric(x, "gap_mean")
ts_metric(x, "core_time_index", min_core_period = 3)

Calculate a binary timescape metric for each raster cell

Description

Applies one named timescape metric independently to every cell of a terra::SpatRaster, treating its layers as ordered time steps. Raster cells must contain only 0, 1, or NA through time. A cell containing any NA receives an NA result.

Usage

ts_raster_metric(r, metric, ...)

Arguments

r

A terra::SpatRaster whose layers are ordered time steps.

metric

One exact metric name returned by ts_list_metrics().

...

Named metric-specific arguments passed to ts_metric(), including include_boundary_gaps = TRUE for gap metrics and a positive whole number min_core_period for core metrics. Omitting min_core_period uses 15 time steps and warns once per raster call, rather than once per cell.

Value

A one-layer terra::SpatRaster containing the selected metric.

Examples

r <- terra::rast(nrows = 2, ncols = 2, nlyrs = 4)
terra::values(r) <- matrix(
  c(
    1, 1, 0, 1,
    0, 0, 0, 0,
    1, 0, 1, 0,
    1, 1, 1, 1
  ),
  nrow = terra::ncell(r),
  byrow = TRUE
)
ts_raster_metric(r, "n_periods")