Skip to contents

Attributable Fraction and Number from a DLNM Fit

Source: R/sus_mod_af.R
sus_mod_af.Rd

Computes population attributable fractions (AF) and attributable numbers (AN) from a climasus_dlnm object returned by sus_mod_dlnm(). Decomposes the total burden into heat and cold components, reports AF at user-defined exposure percentile ranges, and optionally breaks the burden down by month, year, or season.

Usage

sus_mod_af(
  fit,
  threshold = NULL,
  range = NULL,
  pred_at = c(0.75, 0.9, 0.95, 0.99),
  by = NULL,
  nsim = 1000L,
  alpha = 0.05,
  lang = c("pt", "en", "es"),
  verbose = TRUE
)

Arguments

fit

A climasus_dlnm object produced by sus_mod_dlnm().

threshold

Numeric or NULL. Exposure value splitting heat (above) and cold (below) components. NULL (default) uses fit$meta$ref_value.

range

Numeric vector c(low, high) or NULL. When provided, AF is also computed for this custom exposure range.

pred_at

Numeric vector (0-1). Quantiles defining the percentile-band table. For each q, the AF above the q-th quantile (hot) and below the (1-q)-th quantile (cold) is reported. Default c(0.75, 0.90, 0.95, 0.99).

by

Character or NULL. Temporal grouping for the period table: "month", "year", or "season". NULL (default) skips the breakdown.

nsim

Integer. Number of Monte Carlo simulations for CI. Default 1000L. Reduce to 200L for quick exploratory runs; increase to 5000L for publication-quality CI.

alpha

Numeric. Significance level for CI. Default 0.05 (95%).

lang

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

verbose

Logical. Print progress messages. Default TRUE.

Value

A climasus_af object (named list) with:

$total

One-row-per-component tibble (total/heat/cold) with AF, AN, and 95% CI.

$by_quantile

AF/AN at each percentile band in pred_at.

$by_period

Monthly/yearly/seasonal point estimates; NULL when by = NULL.

$daily

Per-day date + exposure + cases + AN + AF for mapping.

$custom

AF/AN for the custom range; NULL when not provided.

$meta

Named list of all parameters used.

Methodology

Point estimates are obtained by calling dlnm::crosspred() at the observed exposure values and computing \(AN_t = n_t \times (1 - 1/RR_t)\) for each day. Confidence intervals use Monte Carlo simulation: nsim coefficient vectors are drawn from \(N(\hat{\beta}_{cb}, \widehat{V}_{cb})\) via MASS::mvrnorm, crosspred is re-evaluated for each draw, and AF quantiles yield the CI. When MASS is unavailable the function falls back to delta-method bounds from the original crosspred object.

References

Gasparrini, A., & Armstrong, B. (2013). The impact of heat waves on mortality. Epidemiology, 24(1), 64-71. doi:10.1097/EDE.0b013e3182770cb4

Gasparrini, A., et al. (2017). Attributable causes of heat-related mortality across 739 locations. The Lancet Planetary Health, 1(9), e360-e367. doi:10.1016/S2542-5196(17)30156-0

See also

sus_mod_dlnm(), sus_mod_plot_dlnm()

Examples

if (FALSE) { # \dontrun{
fit <- sus_mod_dlnm(df_dl, outcome_col = "n_obitos", lang = "pt")

# Total burden with heat/cold split
af <- sus_mod_af(fit, lang = "pt")
print(af)
tidy(af)

# Monthly temporal breakdown
af_m <- sus_mod_af(fit, by = "month", nsim = 200L, lang = "en")
af_m$by_period

# Pool across multiple cities
dplyr::bind_rows(tidy(af_city1), tidy(af_city2))
} # }