Add reference dates and relative horizons to a dataframe of forecasts

align_forecasts(
  forecasts,
  reference_dates = list(wk = NULL, day = NULL),
  reference_weekday = list(wk = "Saturday", day = "Monday"),
  reference_windows = list(wk = -4:2, day = -6:0),
  drop_nonpos_relative_horizons = TRUE
)

Arguments

forecasts: dataframe in format returned by load_forecasts
reference_dates: a named list of vectors of reference dates for forecasts, grouping forecasts that were made during the same week. The list should have two components: "wk" providing reference dates for forecasts at a weekly temporal resolution, and "day" providing reference dates for forecasts at a daily temporal resolution. Dates may be a character vector in the format "YYYY-MM-DD" or a vector of Dates. For example, if a forecast of daily hospitalizations is issued with a forecast date that is Saturday, 2021-09-04, and we want to align analyses around a Monday, the reference date would be Monday, 2021-09-06. This can be accomplished more easily by providing the reference_weekday argument below.
reference_weekday: a named list or named character vector of weekdays to use as reference dates. The list should contain entries named "wk" and "day". The default uses "Saturday" as the reference weekday for forecasts of weekly targets and "Monday" as the reference weekday for forecasts of daily targets.
reference_windows: a named list of integer vectors with offset values giving the set of forecast dates that should be assigned to a particular reference date, in units of number of days. The function defaults to using -4:2 for forecasts at a weekly temporal resolution so that a forecast issued on a Monday will have a reference date of the previous Saturday, and -6:0 for forecasts at a daily temporal resolution so that all forecasts with a forecast_date in the week leading up to a particular Monday will be assigned a reference date of that Monday.
drop_nonpos_relative_horizons: boolean indicating whether forecasts that have a non-positive horizon relative to the reference date should be dropped. Defaults to TRUE

Value

forecast dataframe augmented by columns reference_date and relative_horizon

Examples

if (FALSE) {
library(tidyverse)
library(covidHubUtils)
hub_repo_path <- "../covid19-forecast-hub"
dates <- seq.Date(as.Date("2021-05-01"), as.Date("2021-06-01"), by = 1)
forecasts <- load_forecasts(
  models = get_all_models(source = "local_hub_repo", hub_repo_path = hub_repo_path),
  dates = dates[!(weekdays(dates) %in% c("Monday", "Sunday"))],
  date_window_size = 0,
  locations = "US",
  types = "quantile",
  source = "local_hub_repo",
  hub_repo_path = hub_repo_path,
  verbose = FALSE,
  as_of = NULL,
  hub = c("US")
) %>% filter(quantile == .5)
forecasts
forecasts %>% distinct(model)
forecasts %>% align_forecasts()
forecasts %>% align_forecasts(drop_nonpos_relative_horizons = FALSE) %>% 
  filter(relative_horizon <= 0)
}