create plot_step_ahead_forecasts()

[nickreich]

We would like to have a plot_step_ahead_forecasts() function as part of the hubUtils package. Ideally, this would have similar functionality to the "original" covidHubUtils::plot_forecasts() function which can be found here. The scope of this function is limited to plotting what we are calling step-ahead forecasts, that is forecasts for a single "target variable" at different horizons in the future.

Based on the original function, and integrating knowledge of the new hubverse toolkit, here is a proposal for what the new function would do and look like. This depends in some ways on hubverse-org/hubUtils#33 which relates to standardized structures for collections of predictions

General functionality

This function will plot forecasts and optional truth data for only one selected step-ahead target variable (which might be represented by one or more task_id variables). Optionally, faceted plots could be created for multiple models, locations and forecast dates are supported with specified facet formula.

Input parameters

(I've copied some text from the original plot_forecasts() function)

Arguments specifying input data

• forecast_data required data.frame with forecasts in the hub_mdl_out_df format. Noting that maybe we want to start by supporting only certain output types (e.g. quantiles, means, medians, maybe samples once we implement add function to transform sample output_type data to quantile hubData#8). All forecasts in forecast_data will be plotted, i.e. all filtering needs to happen outside this function. We note per validation specified below that this data.frame must have either a target_date column of both of a origin_date and horizon column.
• truth_data optional data.frame from with required columns as follows:
  • time_idx
  • value
  • [collection of columns that are task_id variables, but not the ones that define the target date]

Arguments about plotting details

• facet interpretable facet option for ggplot. Function will error if multiple values of some task_id variables are passed in without the corresponding column in the facet formula.
• facet_scales argument for scales in [ggplot2::facet_wrap]. Default to "fixed".
• facet_nrow number of rows for facetting; optional.
• facet_ncol number of columns for facetting; optional.
• intervals values indicating which central prediction interval levels to plot. NULL means only plotting point forecasts. If not provided, it will default to c(.5, .8, .95). When plotting 6 models or more, the plot will be reduced to show .95 interval only.
• use_median_as_point logical for using median quantiles as point forecasts in plot. Default to FALSE.
• plot_truth logical for showing truth data in plot. Default to TRUE. Data used in the plot is either truth_data or data loaded from truth_source.
• plot logical for showing the plot. Default to TRUE.
• fill_by_model logical for specifying colors in plot. If TRUE, separate colors will be used for each model. If FALSE, only blues will be used for all models. Default to FALSE.
• fill_transparency numeric value used to set transparency of intervals. 0 means fully transparent, 1 means opaque.
• top_layer character vector, where the first element indicates the top layer of the resulting plot. Possible options are "forecast" and "truth".
• title optional text for the title of the plot. If left as "default", the title will be automatically generated. If "none", no title will be plotted.
• subtitle optional text for the subtitle of the plot. If left as "default", the subtitle will be automatically generated. If "none", no subtitle will be plotted.

Input validations

• at least one of target_metadata entry for the hub must have is_step_ahead set to TRUE.
• hub target ids include "temporal ID variables" which are either (a) target_date or (b) origin_date and horizon
• truth data has
  • time_idx
  • value
  • if specified by hub, columns for all task_id variables that are not target_date, origin_date, horizon
• forecast data is in the hub_mdl_out_df format