Skip to contents

Ranked Disease Burden Table Across Cities or Strata

Source: R/sus_mod_burden.R
sus_mod_burden.Rd

Aggregates city-level attributable fraction or excess mortality/morbidity results into a ranked burden table showing each city's contribution to the total population burden. Accepts climasus_af, climasus_excess, or climasus_dlnm objects (DLNM fits are automatically converted to AF via sus_mod_af()). Produces a concentration curve suitable for Lorenz-style inequality analysis: how unevenly burden is distributed across cities.

Usage

sus_mod_burden(
  fits,
  component = "total",
  rank_by = NULL,
  top_n = NULL,
  nsim = 0L,
  alpha = 0.05,
  lang = "pt",
  verbose = TRUE
)

Arguments

fits

Named list of climasus_af, climasus_excess, or climasus_dlnm objects. Names become city/stratum labels in the output. All elements must be the same class; mixing types is not allowed.

component

Character. For climasus_af inputs: which heat/cold component to display and rank. One of "total" (default), "heat", "cold", or "all" (all three components; ranking is always derived from the "total" component). Ignored for climasus_excess inputs.

rank_by

Character or NULL. Metric for ranking cities. For AF inputs: "an" (attributable number, default) or "af_pct" (attributable fraction percent). For excess inputs: "excess" (default) or "excess_pct". NULL selects the default for the detected input type.

top_n

Integer or NULL. Keep only the top-N cities after ranking. NULL (default) retains all cities.

nsim

Integer. Monte Carlo simulations used when auto-computing AF from climasus_dlnm inputs. 0L (default) uses the faster delta-method CI.

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_burden object (named list) with:

$burden_table

Tibble with one row per city (three rows per city when component = "all"). For AF inputs: city, component, n_cases, an, an_lo, an_hi, af_pct, af_pct_lo, af_pct_hi, rank, pct_of_total. For excess inputs: city, n_days, observed, expected, excess, excess_lo, excess_hi, excess_pct, rank, pct_of_total.

$concentration

City-level tibble with city, rank, pct_of_total, and cumulative_pct for Lorenz-style concentration analysis. Always one row per city, based on the total component.

$total_burden

Named list with aggregate statistics: an_total and af_pct_avg for AF inputs; excess_total and excess_pct_avg for excess inputs. Also contains top_city and the top city's metric.

$meta

Named list of all parameters used in this call.

See also

sus_mod_af(), sus_mod_excess(), sus_mod_pool(), sus_mod_metaregression(), sus_mod_dlnm()

Examples

if (FALSE) { # \dontrun{
# Rank cities by attributable number (AN)
af_list <- list(
  fortaleza = sus_mod_af(fit_fortaleza, verbose = FALSE),
  recife    = sus_mod_af(fit_recife,    verbose = FALSE),
  salvador  = sus_mod_af(fit_salvador,  verbose = FALSE)
)
burden <- sus_mod_burden(af_list, lang = "pt")
print(burden)
tidy(burden)

# Show heat/cold split, keep top 5 cities
sus_mod_burden(af_list, component = "all", top_n = 5L)

# From DLNM fits directly (AF auto-computed via delta method)
burden2 <- sus_mod_burden(dlnm_list, nsim = 0L, lang = "en")

# Excess-based ranking
exc_list <- list(
  sp  = sus_mod_excess(fit_sp,  method = "from_dlnm", verbose = FALSE),
  rj  = sus_mod_excess(fit_rj,  method = "from_dlnm", verbose = FALSE)
)
sus_mod_burden(exc_list, rank_by = "excess_pct")
} # }