Scientific Plots and Tables from a DLNM Fit

Produces publication-quality visualisations and statistical summary tables from a climasus_dlnm object returned by sus_mod_dlnm(). Implements all visualisation types standard in distributed lag non-linear model (DLNM) epidemiology: overall exposure-response, lag-response, bidimensional surface, contour map, lag-stratified slices, exposure distribution, and time series.

Usage

sus_mod_plot_dlnm(
  fit,
  type = c("overall", "lag", "surface", "contour", "slice", "distribution", "series"),
  output_type = c("plot", "table", "all"),
  exposure_at = NULL,
  lags_at = c(0L, 3L, 7L, 14L, 21L),
  pred_at = c(0.05, 0.1, 0.25, 0.5, 0.75, 0.9, 0.95, 0.99),
  interactive = FALSE,
  color_palette = "npg",
  base_size = 12L,
  save_plot = NULL,
  lang = c("pt", "en", "es"),
  verbose = FALSE
)

Arguments

fit: A climasus_dlnm object produced by sus_mod_dlnm().
type: Character. Plot type (see Plot types section). Default "overall".
output_type: Character. What to return: "plot" (default), "table", or "all" (named list $plot, $table, $data).
exposure_at: Numeric or NULL. Exposure value used as the focal point for the "lag" plot. NULL (default) uses the 75th percentile of lag-0 exposure.
lags_at: Integer vector. Lag times shown in the "slice" plot. Default c(0L, 3L, 7L, 14L, 21L) – automatically clipped to lag_max.
pred_at: Numeric vector (0-1). Quantile probabilities at which to report cumulative RR in the statistical table. Default: c(0.05, 0.10, 0.25, 0.50, 0.75, 0.90, 0.95, 0.99).
interactive: Logical. TRUE -> plotly::ggplotly() / plotly 3-D for "surface"; FALSE (default) -> static ggplot2.
color_palette: Character. Name of a ggsci palette. Default "npg". Other useful options: "lancet", "jama", "nejm", "aaas".
base_size: Numeric. ggplot2 base font size. Default 12.
save_plot: Character or NULL. File path to save the output. PNG/PDF for static; HTML for interactive.
lang: Character. Language for labels: "pt" (default), "en", "es".
verbose: Logical. Print progress messages. Default FALSE.

Value

Depending on output_type:

"plot" -> a ggplot or plotly object.
"table" -> a gt_tbl (or tibble when gt is unavailable).
"all" -> a named list: $plot, $table, $data.

Plot types (`type`)

`type`	Description	Key reference
`"overall"`	Cumulative exposure-response curve with CI + exposure histogram	Gasparrini et al. (2010)
`"lag"`	Lag-specific and cumulative lag-response at a given exposure	Gasparrini et al. (2010)
`"surface"`	3-D bidimensional exposure x lag response surface	Gasparrini (2011)
`"contour"`	2-D contour heat map of exposure x lag (publication-friendly)	Gasparrini et al. (2014)
`"slice"`	Exposure-response curves at specific lag times (multilag)	Armstrong (2006)
`"distribution"`	Exposure variable histogram/density with quartile markers	Bhaskaran et al. (2013)
`"series"`	Daily outcome count + exposure time series	Bhaskaran et al. (2013)

Statistical table (`output_type = "table"` or `"all"`)

When a table is requested, returns a gt object (or tibble fallback) with four sections: (1) model specification, (2) cumulative RR at exposure percentiles, (3) lag peak summary, and (4) model diagnostics following reporting standards in Gasparrini et al. (2014) and Bhaskaran et al. (2013).

References

Gasparrini, A., Armstrong, B., & Kenward, M.G. (2010). Distributed lag non-linear models. Statistics in Medicine, 29(21), 2224-2234. doi:10.1002/sim.3940

Gasparrini, A. (2011). Distributed lag linear and non-linear models in R: the package dlnm. Journal of Statistical Software, 43(8), 1-20. doi:10.18637/jss.v043.i08

Gasparrini, A., Armstrong, B., & Kenward, M.G. (2014). Reducing and meta-analysing estimates from distributed lag non-linear models. BMC Medical Research Methodology, 14, 70. doi:10.1186/1471-2288-14-70

Armstrong, B. (2006). Models for the relationship between ambient temperature and daily mortality. Epidemiology, 17(6), 624-631.

Bhaskaran, K., Gasparrini, A., Hajat, S., Smeeth, L., & Armstrong, B. (2013). Time series regression studies in environmental epidemiology. International Journal of Epidemiology, 42(4), 1187-1195. doi:10.1093/ije/dyt092

Examples

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

# Overall exposure-response curve (static)
sus_mod_plot_dlnm(fit, type = "overall", lang = "pt")

# Interactive lag-response
sus_mod_plot_dlnm(fit, type = "lag", interactive = TRUE, lang = "en")

# 3-D surface (interactive only)
sus_mod_plot_dlnm(fit, type = "surface", interactive = TRUE)

# Full output with table
out <- sus_mod_plot_dlnm(fit, type = "overall", output_type = "all", lang = "pt")
out$plot
out$table
} # }