| Title: | Quantifying Temporal Structure Across Landscapes |
| Version: | 0.1.0 |
| 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. |
| License: | MIT + file LICENSE |
| Encoding: | UTF-8 |
| Imports: | terra |
| Suggests: | knitr, rmarkdown, testthat (≥ 3.0.0) |
| VignetteBuilder: | knitr |
| Config/testthat/edition: | 3 |
| Config/roxygen2/version: | 8.1.1 |
| URL: | https://github.com/LoganHysen/timescapes |
| BugReports: | https://github.com/LoganHysen/timescapes/issues |
| NeedsCompilation: | no |
| Packaged: | 2026-10-29 20:02:10 UTC; Logan Hysen |
| Author: | Logan Hysen [aut, cre, cph], Ramcharan Reddy Mannam [aut, cph], Abhiram Moturi [aut, cph], Ho Yi Wan [aut, cph] |
| Maintainer: | Logan Hysen <hysenlog@msu.edu> |
| Repository: | CRAN |
| Date/Publication: | 2026-11-14 09:10:02 UTC |
Binary Timescape Metrics
Description
timescapes calculates mathematical summaries of binary conditions through
time, either for one vector or independently for every cell in a raster time
series.
Author(s)
Maintainer: Logan Hysen hysenlog@msu.edu [copyright holder]
Authors:
Logan Hysen hysenlog@msu.edu [copyright holder]
Ramcharan Reddy Mannam ramcharan.mannam@ufl.edu [copyright holder]
Abhiram Moturi ab.moturi@ufl.edu [copyright holder]
Ho Yi Wan wanhoyi@ufl.edu [copyright holder]
See Also
Useful links:
Report bugs at https://github.com/LoganHysen/timescapes/issues
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 |
metric |
One exact metric name returned by |
... |
Named metric-specific arguments. |
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 ton. -
n_periods: number of occupied periods; range 0 toceiling(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 byn - 1; returns 0 for a one-step series. -
autocorr: Pearson correlation between steps 1 throughn - 1and steps 2 throughn; returnsNAwhen 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 leastmin_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 |
metric |
One exact metric name returned by |
... |
Named metric-specific arguments passed to |
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")