The prediction_band geom/stat

stat_prediction_band(
  mapping = NULL,
  data = NULL,
  geom = "polygon",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  pb_type = c("delta_ball", "kde", "spherical_ball", "convex_hull"),
  grid_size = rep(100, 2),
  conf_level = 0.9,
  over_delta = 0.1,
  dist_params = list(dist_approach = "auto", num_steps = "auto", quantile_approach =
    "depth", quantile_approach_params = list()),
  ...
)

geom_prediction_band(
  mapping = NULL,
  data = NULL,
  stat = list("PredBandDeltaBall", "PredBandKDE", "PredBandSpherical",
    "PredBandConvexHull")[c("delta_ball", "kde", "spherical_ball", "convex_hull") ==
    pb_type][[1]],
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  pb_type = c("delta_ball", "kde", "spherical_ball", "convex_hull"),
  grid_size = rep(100, 2),
  conf_level = 0.9,
  over_delta = 0.1,
  dist_params = list(dist_approach = "auto", num_steps = "auto", quantile_approach =
    "depth", quantile_approach_params = list()),
  ...
)

Arguments

mapping	Set of aesthetic mappings created by `aes` or `aes_`. If specified and `inherit.aes = TRUE` (the default), it is combined with the default mapping at the top level of the plot. You must supply mapping if there is no plot mapping
data	The data to be displayed in this layer. There are three options: If `NULL`, the default, the data is inherited from the plot data as specified in the call to `ggplot`. A `data.frame`, or other object, will override the plot data. All objects will be fortified to produce a data frame. See `fortify` for which variables will be created. A `function` will be called with a single argument, the plot data. The return value must be a `data.frame`, and will be used as the layer data. A function can be created from a formula (e.g. `~ head(.x, 10)`).
geom	string associated with desired geom. `stat` is otherwise controlled by the `pb_type` parameter.
position	Position adjustment, either as a string, or the result of a call to a position adjustment function.
na.rm	If `FALSE`, the default, missing values are removed with a warning. If `TRUE`, missing values are silently removed.
show.legend	logical. Should this layer be included in the legends? `NA`, the default, includes if any aesthetics are mapped. `FALSE` never includes, and `TRUE` always includes. It can also be a named logical vector to finely select the aesthetics to display.
inherit.aes	If `FALSE`, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. `borders`.
pb_type	String indicating which prediction band type to use. Currently only `"kde"` and `"delta_ball"` inputs are expected. See details for more information.
grid_size	integer vector, length 2. Size of the grid which is going to be used to approximate prediction band (if needed). Can be reduced to speed-up computation.
conf_level	confidence level for prediction band. Aka, with `alpha = 1-conf_level`, it creates a `1 - alpha` level prediction band.
over_delta	defines small extension of box around actual points to define contour.
dist_params	list of parameters for distance based approaches (convex hull and delta ball). See details for more information
...	Other arguments passed on to `layer`. These are often aesthetics, used to set an aesthetic to a fixed value, like `colour = "red"` or `size = 3`. They may also be parameters to the paired `geom`/`stat`.
stat	string associated with desired stat `geom` is otherwise controlled by the `pb_type` parameter.

Details

Prediction Bands:

This stat/geom can create 1 of 4 prediction band structures. These approaches can be broken into 2 subgroups, "pointwise" and "uniform" prediction bands. The rational for these splits relate to containment properties and the 'original' ideas are discussed more here: Arvix: 1906.08832

Prediction Bands - Pointwise:

spherical_ball: This prediction band is defined relative to the time points that paths take. For each time point, we take a ellipsoid defined by the prediction region that would contain conf_level probability mass if the distribution of points were a multivariate gaussian. We then take a union of all these ellipsoids to create the full prediction band.
kde: This prediction band is defined as the kde level contour for conf_level relative to all points.

Prediction Bands - Uniform:

These approaches focus on containing the paths/curves/filaments in uniformity. This approach uses depth (specifically a distance-based depth developed by Geenens & Nieto-Reyes, 2017), to select to top conf_level curves and then creates a geometric representation of where the curves lie.

delta_ball: relative to all the points in the top conf_level curves, we find the minimum delta such all of these points are contained in at least 1 ball around another point with radius delta. This can be mathematically expressed as: \(\delta = \max_{i} \min_{j} d(x_i, x_j)\). Then we take the union of delta-balls surround all the points as the prediction band.
convex_hull: with to all the points in the top conf_level curves we just create a convex hull and define our prediction band as such.

Distance attributes

The dist_params list parameter informs us about what type of distance comparisons we do between simulations. The values in the list include:

"dist_approach": Options are c("auto", "equa_dist", "temporal"). Naturally we recommend "auto" - which is just "equa_dist". This parameter defines we calculate the distance between 2 curves using \(l_2\) distance. If "equa_dist" we re-define the curves relative to points spaced equa-distant apart.
num_steps: Options are either "auto" or a numerical value. If "dist_approach" parameter is "equa_dist" then this will define the number of points the curves are re-defined along. If "auto" then we use 20 equa-spaced points.
"quantile_approach": Options are c("depth", "local_depth", "pseudo-density"). Default is "depth" (but we recommend "pseudo-density"). This relates to the type of ordering approach to define.
"quantile_approach_params": this is a list of parameters values that are passed to the "quantile_approach", for "loal_depth" we expect a tau value, for "psuedo-density" it's sigma, both can either take associated values or associated quantile string percentages.

Debugging

If you get a

Error: Problem with `mutate()` input `piece_old`. x Column `piece` 
not found in `.data` ℹ Input `piece_old` is `.data$piece`.

Then that probably means you've input a parameter incorrectly (ggplot is slightly finicky.) We invite you to submit an issue if you're pretty sure all parameters are input correctly.

Aesthetics

stat_prediction_band/geom_prediction_band understands the following aesthetics (required aesthetics are in bold):

x
y
z
alpha
colour
group
linetype
size

For prediction band types = "kde", "delta_ball":

sim_group - note: this cannot be a factor

For prediction band type = "spherical_balls":

t - note: this cannot be a factor

Learn more about setting these aesthetics in vignette("ggplot2-specs").

Examples

library(ggplot2)
library(dplyr)
library(ggtern); EpiCompare:::update_approved_layers()
#                ^ this doesn't generally need to be done

# for speed purposes
smaller_pomp_df <- EpiCompare::pomp_df %>% filter(.id < 10)

vis_data <- smaller_pomp_df %>%
 rename(x = "S", y = "I", z = "R") %>%
 ggplot(aes(x = x, y =y, z = z, group = .id)) +
 geom_path(alpha = .3) +
 coord_tern() +
 labs(title = "Actually data paths")
#> Coordinate system already present. Adding new coordinate system, which will replace the existing one.

vis_spherical <- smaller_pomp_df %>%
 rename(x = "S", y = "I", z = "R", t = "time") %>%
 ggplot(aes(x = x, y = y, z = z, t = t)) +
 geom_prediction_band(pb_type = "spherical_ball",
                      grid_size = rep(100,2),
                      conf_level = .95) +
 coord_tern() +
 labs(title = "Spherical CB")
#> Coordinate system already present. Adding new coordinate system, which will replace the existing one.

vis_delta_ball <- smaller_pomp_df %>%
 rename(x = "S", y = "I", z = "R") %>%
 mutate(.id = as.numeric(.id)) %>%
 ggplot(aes(x = x, y = y, z = z, sim_group = .id)) +
 geom_prediction_band(pb_type = "delta_ball",
                      grid_size = rep(100,2),
                      conf_level = .95) +
 coord_tern() +
 labs(title = "Delta-ball CB")
#> Coordinate system already present. Adding new coordinate system, which will replace the existing one.

vis_kde <- smaller_pomp_df %>%
 rename(x = "S", y = "I", z = "R") %>%
 mutate(.id = as.numeric(.id)) %>%
 ggplot(aes(x = x, y = y, z = z, sim_group = .id)) +
 geom_prediction_band(pb_type = "kde",
                      grid_size = rep(100,2),
                      conf_level = .95) +
 coord_tern() +
 labs(title = "KDE CB")
#> Coordinate system already present. Adding new coordinate system, which will replace the existing one.

vis_convex_hull <- smaller_pomp_df %>%
 rename(x = "S", y = "I", z = "R") %>%
 mutate(.id = as.numeric(.id)) %>%
 ggplot(aes(x = x, y = y, z = z, sim_group = .id)) +
 geom_prediction_band(pb_type = "convex_hull",
                      conf_level = .95) +
 coord_tern() +
 labs(title = "Convex hull CB")
#> Coordinate system already present. Adding new coordinate system, which will replace the existing one.
# \donttest{
# run this if you want to see them all
grid.arrange(vis_data, vis_spherical,
            vis_delta_ball, vis_kde,
            vis_convex_hull, nrow = 2)
#> Due to dist_params$dist_approach = "equa_dist", this may take a little while - see `filament_compression` examples for a work-around if you're making this plot multiple times
#> Due to dist_params$dist_approach = "equa_dist", this may take a little while - see `filament_compression` examples for a work-around if you're making this plot multiple times
# }