| 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 |
List available binary timescape metrics
ts_list_metrics()ts_list_metrics()
A character vector of exact metric names accepted by ts_metric()
and ts_raster_metric().
ts_list_metrics()ts_list_metrics()
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_.
ts_metric(x, metric, ...)ts_metric(x, metric, ...)
x |
A non-empty numeric vector containing only |
metric |
One exact metric name returned by |
... |
Named metric-specific arguments. |
One numeric value.
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.
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
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)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)
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.
ts_raster_metric(r, metric, ...)ts_raster_metric(r, metric, ...)
r |
A |
metric |
One exact metric name returned by |
... |
Named metric-specific arguments passed to |
A one-layer terra::SpatRaster containing the selected metric.
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")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")