Skip to contents

Compare arbitrary time windows

Source: R/cd_compare.R
cd_compare.Rd

Computes the mean value for two user-defined time windows, the difference between them, and (by default) a p-value testing whether the two windows differ.

Usage

cd_compare(
  x,
  window_a = 2015:2025,
  window_b = 1951:1980,
  method = "mean_diff",
  test = "t"
)

Arguments

x

A tibble from cd_extract() with columns variable, period, year, value.

window_a

Integer vector of years for the recent / impact window. Default 2015:2025.

window_b

Integer vector of years for the reference window. Default 1951:1980 (pre-warming reference, the GISS base period).

method

Character. Comparison method: "mean_diff" for mean_a - mean_b, or "pct_change" for percentage change relative to window_b. A percent change needs values with a real zero, so "pct_change" gives difference = NA, with one warning naming the rows, for a series whose pct_change resolves FALSE: temperatures in degrees C, the day of 50% melt, and variables already in percent (cd_variables()$pct_change; a series can carry its own, see the input contract in cd_anomaly()). A base mean of -0.57 degrees C would otherwise read as +343% warmer.

test

Character or NULL. Window-vs-window significance test: "t" for Welch's two-sample t-test (default) or "wilcox" for Mann-Whitney U. Set to NULL to skip — output then drops the p_value column. Rows where either window has fewer than 8 non-NA values get p_value = NA and a single batched warning.

Value

A tibble with columns variable, period, mean_a, mean_b, difference, method, (when test is non-NULL) p_value, and long_name when x carries one — resolved as in cd_trend() (see the input contract in cd_anomaly()) and read by cd_plot_comparison().

Details

Defaults compare the recent 11 years (2015:2025) to a pre-warming reference (1951:1980, the GISS base period) — the framing used in the package vignettes. This is a cumulative-impact comparison ("how much warmer are the recent years than the pre-warming reference?") rather than a rate-of-change comparison; for the latter use cd_trend().

The window-vs-window p-value (test = "t" Welch t-test or test = "wilcox" Mann-Whitney U) tests whether the means of the two windows differ — a different question than cd_trend()'s Mann-Kendall test, which checks for a monotonic trend across the full series. Two windows can differ significantly without a monotonic trend (step changes, U-shapes) and a non-significant trend doesn't always mean the windows are indistinguishable. The test treats annual values as independent; for series with strong autocorrelation the t-test p is mildly anti-conservative — the Wilcoxon alternative is more robust to non-Gaussian tails / outliers but shares the independence assumption.

Examples

catalog <- cd_catalog(
  system.file("extdata", "example_catalog.json", package = "cd")
)
aoi <- sf::st_read(
  system.file("extdata", "example_aoi.gpkg", package = "cd"),
  quiet = TRUE
)
ts <- cd_extract(catalog, aoi)

# The toy example catalog only spans 1951:1960, so the windows
# below override the defaults (2015:2025 vs 1951:1980) — those
# are the right choice on the live STAC catalog. test = NULL
# because the toy windows have < 8 years.
cd_compare(ts, window_a = 1956:1960, window_b = 1951:1955, test = NULL)
#> # A tibble: 1 × 6
#>   variable period mean_a mean_b difference method   
#>   <chr>    <chr>   <dbl>  <dbl>      <dbl> <chr>    
#> 1 tmean    annual  -1.33  -1.44      0.110 mean_diff

# Percentage change suits a variable with a real zero, such as
# precipitation. For temperature it returns NA with a warning: a base
# mean near 0 degrees C would make any percent meaningless.
prcp <- data.frame(
  variable = "prcp", period = "annual", year = 1951:1960,
  value = c(610, 580, 655, 600, 640, 690, 700, 640, 720, 705)
)
cd_compare(prcp, window_a = 1956:1960, window_b = 1951:1955,
           method = "pct_change", test = NULL)
#>   variable period mean_a mean_b difference     method
#> 1     prcp annual    691    617   11.99352 pct_change