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 Infectious-Disease-Modeling-Hubs/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 Infectious-Disease-Modeling-Hubs/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
We would like to have a
plot_step_ahead_forecasts()function as part of thehubUtilspackage. 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 Infectious-Disease-Modeling-Hubs/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_datarequired 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 Infectious-Disease-Modeling-Hubs/hubData#8). All forecasts inforecast_datawill 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 atarget_datecolumn of both of aorigin_dateandhorizoncolumn.truth_dataoptional data.frame from with required columns as follows:time_idxvalueArguments about plotting details
facetinterpretable 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_scalesargument for scales in [ggplot2::facet_wrap]. Default to"fixed".facet_nrownumber of rows for facetting; optional.facet_ncolnumber of columns for facetting; optional.intervalsvalues indicating which central prediction interval levels to plot.NULLmeans only plotting point forecasts. If not provided, it will default toc(.5, .8, .95). When plotting 6 models or more, the plot will be reduced to show .95 interval only.use_median_as_pointlogical for using median quantiles as point forecasts in plot. Default toFALSE.plot_truthlogical for showing truth data in plot. Default toTRUE. Data used in the plot is eithertruth_dataor data loaded fromtruth_source.plotlogical for showing the plot. Default toTRUE.fill_by_modellogical for specifying colors in plot. IfTRUE, separate colors will be used for each model. IfFALSE, only blues will be used for all models. Default toFALSE.fill_transparencynumeric value used to set transparency of intervals. 0 means fully transparent, 1 means opaque.top_layercharacter vector, where the first element indicates the top layer of the resulting plot. Possible options are"forecast"and"truth".titleoptional text for the title of the plot. If left as"default", the title will be automatically generated. If"none", no title will be plotted.subtitleoptional 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
is_step_aheadset to TRUE.target_dateor (b)origin_dateandhorizontime_idxvaluetarget_date,origin_date,horizonhub_mdl_out_dfformat