Plot predictions generated by `simulate_scenarios()` while respecting both the scenario design created by `simulate_ranges()` (`"grid"` or `"paired"`) and the prediction output returned by `simulate_scenarios()` (`"samples"` or `"summary"`).
Usage
plot_scenarios(
data,
x,
scenario_type = c("grid", "paired"),
output = c("auto", "samples", "summary"),
mode = NULL,
y = "prediction",
facet = NULL,
sample = "sample",
lower = NULL,
upper = NULL,
scale_factor = 1,
facet_ncol = NULL,
facet_nrow = NULL,
color_scale = NULL,
color_label = "Sample",
line_color = "black",
ribbon_fill = "black",
ribbon_alpha = 1,
show_ribbon = TRUE,
smooth = TRUE,
smooth_method = NULL,
smooth_formula = NULL,
smooth_se = FALSE,
line_width = NULL,
line_alpha = 1,
paired_samples_geom = c("boxplot", "jitter"),
boxplot_color = "black",
boxplot_fill = "white",
boxplot_width = NULL,
jitter_color = "black",
jitter_width = 0.12,
jitter_alpha = 0.65,
jitter_size = NULL,
pointrange_color = "black",
point_size = NULL,
pointrange_linewidth = NULL,
paired_x_discrete = TRUE,
x_breaks = ggplot2::waiver(),
y_breaks = ggplot2::waiver(),
x_limits = NULL,
y_limits = NULL,
x_expand = NULL,
y_expand = ggplot2::waiver(),
x_label = "Exposure",
y_label = "Predicted",
title = NULL,
subtitle = NULL,
caption = NULL,
theme = NULL,
base_size = 10,
text_face = "bold",
axis_title_size = 12,
strip_background = ggplot2::element_rect(fill = "white", colour = "black"),
legend_position = "none",
line_args = list(),
ribbon_args = list(),
boxplot_args = list(),
jitter_args = list(),
pointrange_args = list(),
point_args = list(),
add = NULL,
...
)Arguments
- data
A non-empty data frame returned by `simulate_scenarios()`.
- x
Character scalar naming the scenario variable shown on the x-axis.
- scenario_type
Character. Scenario design used to generate the scenarios in `simulate_ranges()`. Must be `"grid"` or `"paired"`. Default is `"grid"`.
- output
Character. Prediction output represented by `data`: `"auto"`, `"samples"`, or `"summary"`.
With `"auto"` (default), the function identifies `"samples"` when the column named by `sample` is present; otherwise it uses `"summary"`. This mirrors the two output structures returned by `simulate_scenarios()`.
- mode
Deprecated compatibility alias for `output`. It is retained so calls written for earlier versions of `plot_scenarios()` do not break. New code should use `output`. Do not supply both `output` and `mode`.
- y
Character scalar naming the prediction column. Default is `"prediction"`.
- facet
Optional character vector naming variables used by `ggplot2::facet_wrap()`, for example `c("wetness", "tmean")`.
- sample
Character scalar naming the sample identifier in `output = "samples"`. Default is `"sample"`.
- lower, upper
Optional character scalars naming the lower and upper uncertainty-limit columns in `output = "summary"`.
When left as `NULL`, `plot_scenarios()` looks first for `"prediction_lower"` and `"prediction_upper"`, respectively, and then for `"lower"` and `"upper"`.
These arguments are not used for `output = "samples"` because sample-level output contains individual prediction draws rather than pre-computed lower/upper limits.
- scale_factor
Finite numeric multiplier applied to predictions and, when present, lower and upper limits. Use `100` to display proportions as percentages.
- facet_ncol, facet_nrow
Optional positive integers controlling the facet arrangement.
- color_scale
Optional ggplot2 color scale used for sample-specific grid trajectories. When `NULL`, `ggplot2::scale_color_viridis_c()` is used.
- color_label
Legend title used by the default grid color scale.
- line_color
Color of the central trajectory for grid-summary plots.
- ribbon_fill, ribbon_alpha
Legacy argument names retained for backward compatibility. In grid-summary plots, `ribbon_fill` now controls the color of the dashed lower/upper interval curves and `ribbon_alpha` controls their transparency. Defaults reproduce the black dashed interval curves used by `plot_losses()`.
- show_ribbon
Logical. Legacy argument name retained for backward compatibility. If `TRUE`, a grid-summary plot shows dashed lower/upper uncertainty curves when interval columns are available.
- smooth
Logical. For grid plots, use `ggplot2::geom_smooth()` when `TRUE` (default) or `ggplot2::geom_line()` when `FALSE`.
- smooth_method
Optional smoothing method passed to `ggplot2::geom_smooth()`. When `NULL`, ggplot2 chooses its default method.
- smooth_formula
Optional formula passed to `ggplot2::geom_smooth()`.
- smooth_se
Logical. Display the smoothing standard-error band produced by `geom_smooth()`. Default is `FALSE`. This is distinct from the prediction uncertainty represented by `lower` and `upper`.
- line_width
Optional positive line width for grid trajectories. When `NULL`, ggplot2 uses its default.
- line_alpha
Transparency of grid trajectories, between 0 and 1.
- paired_samples_geom
Character. Geometry used when `scenario_type = "paired"` and `output = "samples"`. `"boxplot"` (default) displays the distribution of the sample predictions for each paired scenario; `"jitter"` displays the individual sample predictions.
- boxplot_color, boxplot_fill
Color and fill used by the default paired sample boxplot.
- boxplot_width
Optional positive box width for paired sample boxplots. When `NULL`, ggplot2 uses its default.
- jitter_color
Color used for paired sample jittered points.
- jitter_width
Horizontal jitter width for paired sample points.
- jitter_alpha
Transparency of paired sample jittered points.
- jitter_size
Optional positive size of paired sample jittered points. When `NULL`, ggplot2 uses its default.
- pointrange_color
Color used by `ggplot2::geom_pointrange()` for paired summary plots.
- point_size
Optional positive point size for paired-summary plots. When `NULL`, ggplot2 uses its default.
- pointrange_linewidth
Optional positive line width for the uncertainty interval in paired-summary plots. When `NULL`, ggplot2 uses its default.
- paired_x_discrete
Logical. For paired scenarios, treat the x variable as discrete when `TRUE` (default), matching a manual mapping such as `aes(as.factor(rain), ...)`. If `FALSE`, `x` must be numeric and a continuous x-axis is used.
- x_breaks, y_breaks
Axis breaks. Defaults to `ggplot2::waiver()`, which lets ggplot2 choose breaks automatically and preserves axis tick labels and the `theme_bw()` panel grid. Use `NULL` only to intentionally remove the corresponding breaks and grid lines.
- x_limits, y_limits
Optional axis limits.
For grid plots and paired plots with `paired_x_discrete = FALSE`, `x_limits` must be a finite numeric vector of length two.
For paired plots with `paired_x_discrete = TRUE`, `x_limits` can instead be a vector of observed x levels used to subset and/or order the displayed categories.
- x_expand, y_expand
Axis expansion specifications.
When `x_expand = NULL`, continuous x-axes use `ggplot2::expansion(mult = c(0.01, 0.01))`, matching the original EpiExposure scenario figure, while discrete paired x-axes retain ggplot2's default discrete expansion.
- x_label, y_label
Axis titles. Defaults are `"Exposure"` and `"Predicted"`.
- title, subtitle, caption
Optional plot annotations.
- theme
Optional ggplot2 theme added after the default `theme_bw()` and EpiExposure text settings, allowing users to override them.
- base_size
Base text size. Default is 10.
- text_face
Common text face. Default is `"bold"`.
- axis_title_size
Axis-title size. Default is 12.
- strip_background
Facet-strip background element.
- legend_position
Legend position. Default is `"none"`.
- line_args
Optional named list of additional arguments passed to the active grid trajectory layer (`geom_smooth()` or `geom_line()`).
- ribbon_args
Optional named list of additional arguments passed to both lower and upper uncertainty-curve layers in grid-summary mode. The legacy argument name is retained for backward compatibility.
- boxplot_args
Optional named list of additional arguments passed to `ggplot2::geom_boxplot()` in paired-samples mode.
- jitter_args
Optional named list of additional arguments passed to `ggplot2::geom_jitter()` when `paired_samples_geom = "jitter"`.
- pointrange_args
Optional named list of additional arguments passed to `ggplot2::geom_pointrange()` in paired-summary mode.
- point_args
Optional named list of additional arguments passed to `ggplot2::geom_point()` when summary predictions do not contain lower/upper uncertainty limits.
- add
Optional ggplot2 component or list of components added last.
- ...
Additional named arguments passed to the principal geometry used for the selected combination of `scenario_type` and `output`.
Details
The default plotting behavior is:
* `scenario_type = "grid"` + `output = "samples"`: sample-specific trajectories using `geom_smooth()` (or `geom_line()`). * `scenario_type = "grid"` + `output = "summary"`: one central trajectory, optionally with dashed lower/upper uncertainty curves. * `scenario_type = "paired"` + `output = "samples"`: the distribution of sample predictions at each paired scenario using `geom_boxplot()` by default. * `scenario_type = "paired"` + `output = "summary"`: point estimates and lower/upper uncertainty intervals using `geom_pointrange()`.
`scenario_type` and `output` describe different aspects of the data and should not be conflated:
* `scenario_type` describes how exposure scenarios were constructed by `simulate_ranges()`. * `output` describes how predictions were returned by `simulate_scenarios()`.
Consequently, all four combinations are valid.
For sample-level output, `lower` and `upper` are intentionally ignored. The uncertainty is represented by the multiple sample predictions themselves.
For summary output, lower and upper limits are used when available:
* grid + summary: the limits define dashed lower/upper uncertainty curves; * paired + summary: the limits define the vertical point-range.
If summary output does not contain lower/upper limits, the function still plots the central prediction: a grid trajectory for grid scenarios or points for paired scenarios.
For paired sample output, `geom_boxplot()` is the default because several prediction samples correspond to the same paired scenario value. The user can instead request the individual sample predictions with `paired_samples_geom = "jitter"`.
Examples
# -----------------------------------------------------------------------
# 1. GRID + SAMPLES
# -----------------------------------------------------------------------
pred_grid_samples <- expand.grid(
rain = seq(0, 12, by = 3),
sample = 1:3
)
pred_grid_samples$prediction <- with(
pred_grid_samples,
0.05 + 0.015 * rain + 0.005 * sample
)
grid_samples_plot <- plot_scenarios(
data = pred_grid_samples,
x = "rain",
scenario_type = "grid",
output = "samples",
smooth = FALSE,
scale_factor = 100,
x_label = "Daily precipitation (mm)",
y_label = "Predicted (%)"
)
# The default output = "auto" identifies the sample column automatically.
grid_auto_plot <- plot_scenarios(
data = pred_grid_samples,
x = "rain",
scenario_type = "grid",
smooth = FALSE,
scale_factor = 100
)
# -----------------------------------------------------------------------
# 2. GRID + SUMMARY
# -----------------------------------------------------------------------
pred_grid_summary <- data.frame(
rain = seq(0, 12, by = 2)
)
pred_grid_summary$prediction <-
0.05 + 0.015 * pred_grid_summary$rain
pred_grid_summary$prediction_lower <-
pred_grid_summary$prediction - 0.02
pred_grid_summary$prediction_upper <-
pred_grid_summary$prediction + 0.02
grid_summary_plot <- plot_scenarios(
data = pred_grid_summary,
x = "rain",
scenario_type = "grid",
output = "summary",
smooth = FALSE,
scale_factor = 100,
x_label = "Daily precipitation (mm)",
y_label = "Predicted (%)"
)
# -----------------------------------------------------------------------
# 3. PAIRED + SAMPLES
# -----------------------------------------------------------------------
pred_paired_samples <- expand.grid(
rain = c(0, 4, 8, 12),
sample = 1:5
)
pred_paired_samples$prediction <- with(
pred_paired_samples,
0.05 + 0.015 * rain + 0.004 * sample
)
paired_samples_plot <- plot_scenarios(
data = pred_paired_samples,
x = "rain",
scenario_type = "paired",
output = "samples",
scale_factor = 100,
x_label = "Daily precipitation (mm)",
y_label = "Predicted (%)"
)
# -----------------------------------------------------------------------
# 4. PAIRED + SUMMARY
# -----------------------------------------------------------------------
pred_paired_summary <- data.frame(
rain = c(0, 4, 8, 12),
prediction = c(0.06, 0.12, 0.19, 0.25),
prediction_lower = c(0.04, 0.09, 0.15, 0.20),
prediction_upper = c(0.08, 0.15, 0.23, 0.30)
)
paired_summary_plot <- plot_scenarios(
data = pred_paired_summary,
x = "rain",
scenario_type = "paired",
output = "summary",
scale_factor = 100,
x_label = "Daily precipitation (mm)",
y_label = "Predicted (%)"
)
stopifnot(
inherits(grid_samples_plot, "ggplot"),
inherits(grid_auto_plot, "ggplot"),
inherits(grid_summary_plot, "ggplot"),
inherits(paired_samples_plot, "ggplot"),
inherits(paired_summary_plot, "ggplot")
)