Skip to contents

Excess Mortality and Morbidity from Climate-Health Time Series

Source: R/sus_mod_excess.R
sus_mod_excess.Rd

Estimates excess counts (observed minus expected baseline) for daily health outcome series in the context of climate-health research. Supports three baseline methods: counterfactual extraction from a fitted DLNM ("from_dlnm"), quasi-Poisson GLM with natural splines ("spline"), and Serfling sinusoidal regression ("serfling"). Confidence intervals are derived from the baseline model's prediction standard errors. A z-score flag identifies statistically significant excess events.

Usage

sus_mod_excess(
  data,
  outcome_col = NULL,
  date_col = "date",
  control_period = NULL,
  study_period = NULL,
  method = NULL,
  dof_per_year = 8L,
  harmonics = 2L,
  family = "quasipoisson",
  threshold_z = 1.96,
  by = NULL,
  alpha = 0.05,
  lang = "pt",
  verbose = TRUE
)

Arguments

data

A climasus_dlnm object (for method = "from_dlnm"), a climasus_df at stage "aggregate" or later, or any data.frame with a date column and an integer count column.

outcome_col

Character. Name of the outcome count column. Required when data is a data frame; inferred from fit$meta$outcome_col when data is a climasus_dlnm.

date_col

Character. Name of the date column. Default "date".

control_period

Date vector of length 2 specifying the reference period used to fit the baseline model, e.g. c(as.Date("2018-01-01"), as.Date("2019-12-31")). Default NULL uses all available data before study_period, or all data when both are NULL.

study_period

Date vector of length 2 specifying the period for which excess is reported. Default NULL uses the full data range.

method

Character. Baseline estimation method:

  • "from_dlnm" — counterfactual from DLNM (requires climasus_dlnm).

  • "spline" (default for data frames) — quasi-Poisson with ns().

  • "serfling" — Serfling harmonic regression.

dof_per_year

Integer. Degrees of freedom per year for the spline baseline. Default 8L.

harmonics

Integer. Number of sinusoidal harmonics in the Serfling model. Default 2L.

family

Character. GLM family: "quasipoisson" (default) or "poisson". Ignored for method = "from_dlnm".

threshold_z

Numeric. Z-score threshold for flagging excess events. Default 1.96 (95th percentile).

by

Character or NULL. Temporal breakdown variable for the period summary: "year", "month", or "season". Default NULL.

alpha

Numeric. Significance level for confidence intervals. Default 0.05.

lang

Character. Language for messages: "pt" (default), "en", "es".

verbose

Logical. Print progress messages. Default TRUE.

Value

A climasus_excess list with:

$daily

Tibble with one row per day: date, observed, expected, expected_lo, expected_hi, excess, excess_lo, excess_hi, z_score, is_excess.

$total

One-row tibble: total observed, expected, excess, excess percentage, and their confidence bounds.

$by_period

Temporal breakdown tibble (when by is not NULL).

$model

The fitted baseline GLM object (NULL for method = "from_dlnm").

$meta

Metadata list: method, outcome_col, date_col, control_period, study_period, family, dof_per_year, harmonics, threshold_z, n_obs, call_time.

Statistical framework

"spline" and "serfling" methods: A quasi-Poisson GLM is fitted on the control_period:

$$\log(\mu_t) = \alpha + f(t)$$

where \(f(t)\) is either a natural spline over calendar date ("spline") or a Serfling harmonic: \(\beta_1 t + \beta_2 t^2 + \sum_{k=1}^{H}[\gamma_k \sin(2\pi k t/365.25) + \delta_k \cos(2\pi k t/365.25)]\) ("serfling"). Expected counts for the study period are predicted from this model.

"from_dlnm" method: Given a climasus_dlnm object, the counterfactual expected mortality without the climate-exposure effect is:

$$\hat\mu_t^{(0)} = \hat\mu_t / \widehat{RR}(x_t)$$

where \(\hat\mu_t\) are fitted values and \(\widehat{RR}(x_t)\) is the cumulative relative risk at the observed exposure \(x_t\) from dlnm::crosspred(). This yields the Gasparrini & Armstrong (2013) temperature-attributable excess.

See also

sus_mod_dlnm(), sus_mod_af(), sus_mod_plot_dlnm()

Examples

if (FALSE) { # \dontrun{
# From a fitted DLNM
exc <- sus_mod_excess(fit_dlnm, method = "from_dlnm", lang = "en")

# Standalone spline baseline for a heat wave period
exc <- sus_mod_excess(
  df_daily,
  outcome_col    = "n_obitos",
  control_period = c(as.Date("2018-01-01"), as.Date("2021-12-31")),
  study_period   = c(as.Date("2022-01-01"), as.Date("2022-12-31")),
  method         = "spline",
  lang           = "pt"
)
print(exc)
tidy(exc)
} # }