--- 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.