Title: | Forecast Case and Sequence Notifications using Variant of Concern Strain Dynamics |
---|---|
Description: | Contains models and tools to produce short-term forecasts for both case and sequence notifications assuming circulation of either one or two variants. Tools are also provided to allow the evaluation of the use of sequence data for short-term forecasts in both real-world settings and in user generated scenarios. |
Authors: | Sam Abbott [aut, cre] |
Maintainer: | Sam Abbott <[email protected]> |
License: | MIT + file LICENSE |
Version: | 0.9.0 |
Built: | 2024-08-13 13:02:58 UTC |
Source: | https://github.com/epiforecasts/forecast.vocs |
Add the forecast dates to a plot
add_forecast_dates(plot, forecast_dates = NULL)
add_forecast_dates(plot, forecast_dates = NULL)
plot |
|
forecast_dates |
A data.frame in the format produced by
|
A ggplot2
plot with dates of data unavailability added.
Plotting functions
plot.fv_forecast()
,
plot.fv_posterior()
,
plot_cases()
,
plot_default()
,
plot_growth()
,
plot_pairs()
,
plot_posterior()
,
plot_rt()
,
plot_theme()
,
plot_voc_advantage()
,
plot_voc_frac()
,
save_plots()
Launch shinystan an interactive tool for stan model evaluation
bp_launch_shinystan(fit)
bp_launch_shinystan(fit)
fit |
List of output as returned by |
Functions to explore and validate models
fv_score_forecast()
,
plot_pairs()
obs <- filter_by_availability( germany_covid19_delta_obs, date = as.Date("2021-06-12") ) dt <- fv_as_data_list(obs) inits <- fv_inits(dt) fit <- fv_sample(dt, init = inits, adapt_delta = 0.99, max_treedepth = 15) bp_launch_shinystan(fit)
obs <- filter_by_availability( germany_covid19_delta_obs, date = as.Date("2021-06-12") ) dt <- fv_as_data_list(obs) inits <- fv_inits(dt) fit <- fv_sample(dt, init = inits, adapt_delta = 0.99, max_treedepth = 15) bp_launch_shinystan(fit)
Check a data.frame
check_dataframe(dataframe, req_vars, req_types, rows)
check_dataframe(dataframe, req_vars, req_types, rows)
dataframe |
A data.frame to check. |
req_vars |
A character vector of variables that are required. |
req_types |
A character vector of types for each required variable. |
rows |
Integer specifying the number of rows the data.frame should have. |
Functions used for checking inputs
check_observations()
,
check_param()
,
check_quantiles()
Check observations are in the correct format
check_observations(obs)
check_observations(obs)
obs |
A |
Functions used for checking inputs
check_dataframe()
,
check_param()
,
check_quantiles()
obs <- latest_obs(germany_covid19_delta_obs) check_observations(obs)
obs <- latest_obs(germany_covid19_delta_obs) check_observations(obs)
Check a parameter is the correct type and length
check_param(param, name = "param", type = "numeric", length)
check_param(param, name = "param", type = "numeric", length)
param |
A parameter to check the format of. |
name |
A character string naming the variable to check. |
type |
A character string identifying the allowed parameter type (must be a type with a is.type function except for a Date). |
length |
Numeric, allowed length of the variable. Defaults to any allowed length. |
Functions used for checking inputs
check_dataframe()
,
check_observations()
,
check_quantiles()
Check Quantiles Required are Present
check_quantiles(posterior, req_probs = c(0.5, 0.95, 0.2, 0.8))
check_quantiles(posterior, req_probs = c(0.5, 0.95, 0.2, 0.8))
posterior |
A dataframe containing quantiles identified using
the |
req_probs |
A numeric vector of required probabilities. |
Functions used for checking inputs
check_dataframe()
,
check_observations()
,
check_param()
Convert to stanfit object
convert_to_stanfit(fit)
convert_to_stanfit(fit)
fit |
List of output as returned by |
The model fit as a stanfit
object
Functions used for postprocessing of model fits
extract_draws()
,
extract_forecast_dates()
,
fv_extract_forecast()
,
fv_posterior()
,
fv_tidy_posterior()
,
link_dates_with_posterior()
,
link_obs_with_posterior()
,
plot.fv_posterior()
,
print.fv_posterior()
,
quantiles_to_long()
,
summary.fv_posterior()
,
update_voc_label()
obs <- filter_by_availability( germany_covid19_delta_obs, date = as.Date("2021-06-12"), ) dt <- fv_as_data_list(obs) inits <- fv_inits(dt) fit <- fv_sample(dt, init = inits, adapt_delta = 0.99, max_treedepth = 15) convert_to_stanfit(fit)
obs <- filter_by_availability( germany_covid19_delta_obs, date = as.Date("2021-06-12"), ) dt <- fv_as_data_list(obs) inits <- fv_inits(dt) fit <- fv_sample(dt, init = inits, adapt_delta = 0.99, max_treedepth = 15) convert_to_stanfit(fit)
Define data availability scenarios
define_scenarios( seq_lag = 0:3, seq_samples = seq(1, by = -0.25, length.out = 4), voc_scale = list(c(0, 0.5)) )
define_scenarios( seq_lag = 0:3, seq_samples = seq(1, by = -0.25, length.out = 4), voc_scale = list(c(0, 0.5)) )
seq_lag |
The number of weeks that sequences lag the date. Default is to test 0 to 3 weeks of lag. |
seq_samples |
Fraction of samples to include (deterministic scaling). The default is to test all samples down to 25% of samples by 25% increments. |
voc_scale |
A list of mean and standard deviations to use to inform the prior for additional transmissibility of the VOC variant. The default a uninformed no prior knowledge prior (0, 0.5). adjusted growth (0.74, 0.1). |
A data frame of scenario definitions with ids
Functions to define and create data scenarios
generate_obs_scenario()
,
update_obs_availability()
define_scenarios()
define_scenarios()
Extract posterior draws
extract_draws(fit, ...)
extract_draws(fit, ...)
fit |
A list as produced by |
... |
Additional parameters passed to |
A cmdstanr::draws()
object from the posterior
package.
Functions used for postprocessing of model fits
convert_to_stanfit()
,
extract_forecast_dates()
,
fv_extract_forecast()
,
fv_posterior()
,
fv_tidy_posterior()
,
link_dates_with_posterior()
,
link_obs_with_posterior()
,
plot.fv_posterior()
,
print.fv_posterior()
,
quantiles_to_long()
,
summary.fv_posterior()
,
update_voc_label()
obs <- filter_by_availability( germany_covid19_delta_obs, date = as.Date("2021-06-12"), ) dt <- fv_as_data_list(obs) inits <- fv_inits(dt) fit <- fv_sample(dt, init = inits, adapt_delta = 0.99, max_treedepth = 15) extract_draws(fit)
obs <- filter_by_availability( germany_covid19_delta_obs, date = as.Date("2021-06-12"), ) dt <- fv_as_data_list(obs) inits <- fv_inits(dt) fit <- fv_sample(dt, init = inits, adapt_delta = 0.99, max_treedepth = 15) extract_draws(fit)
Extract forecast dates based on the availability of both case and sequence data.
extract_forecast_dates(posterior)
extract_forecast_dates(posterior)
posterior |
A dataframe of posterior output as produced by
|
A data.frame containing at least two vectors: Data unavailable indicating the type of data that is missing, and date giving the date data was last available for.
Functions used for postprocessing of model fits
convert_to_stanfit()
,
extract_draws()
,
fv_extract_forecast()
,
fv_posterior()
,
fv_tidy_posterior()
,
link_dates_with_posterior()
,
link_obs_with_posterior()
,
plot.fv_posterior()
,
print.fv_posterior()
,
quantiles_to_long()
,
summary.fv_posterior()
,
update_voc_label()
p <- fv_example(strains = 2, type = "posterior") extract_forecast_dates(p)
p <- fv_example(strains = 2, type = "posterior") extract_forecast_dates(p)
Filter data based on availability and forecast date
filter_by_availability( obs, date = max(obs$date), seq_date = date, case_date = date )
filter_by_availability( obs, date = max(obs$date), seq_date = date, case_date = date )
obs |
A |
date |
Date at which to filter. Defaults to the
maximum date in |
seq_date |
Date from which to use available sequence data. Defaults to
the |
case_date |
Date from which to use available case data. Defaults to
the |
A data.frame
of observations filter for the latest available
data for the specified dates of interest.
Preprocessing functions
fv_dow_period()
,
latest_obs()
,
piecewise_steps()
options(mc.cores = 4) obs <- filter_by_availability( germany_covid19_delta_obs, date = as.Date("2021-06-12"), ) dt <- rbind( update_obs_availability(obs, seq_lag = 3), update_obs_availability(obs, seq_lag = 1) ) # filter out duplicates and up to the present date filter_by_availability(dt) # filter to only use sequence data up the the 12th of June filter_by_availability(dt, seq_date = "2021-06-12") # as above but only use filter_by_availability(dt, seq_date = "2021-06-12", case_date = "2021-07-01" )
options(mc.cores = 4) obs <- filter_by_availability( germany_covid19_delta_obs, date = as.Date("2021-06-12"), ) dt <- rbind( update_obs_availability(obs, seq_lag = 3), update_obs_availability(obs, seq_lag = 1) ) # filter out duplicates and up to the present date filter_by_availability(dt) # filter to only use sequence data up the the 12th of June filter_by_availability(dt, seq_date = "2021-06-12") # as above but only use filter_by_availability(dt, seq_date = "2021-06-12", case_date = "2021-07-01" )
Forecast using branching processes at a target date
forecast( obs, forecast_date = max(obs$date), seq_date = forecast_date, case_date = forecast_date, data_list = forecast.vocs::fv_as_data_list, inits = forecast.vocs::fv_inits, fit = forecast.vocs::fv_sample, posterior = forecast.vocs::fv_tidy_posterior, extract_forecast = forecast.vocs::fv_extract_forecast, horizon = 4, r_init = c(0, 0.25), r_step = 1, r_forecast = TRUE, beta = c(0, 0.1), lkj = 0.5, period = NULL, special_periods = c(), voc_scale = c(0, 0.2), voc_label = "VOC", strains = 2, variant_relationship = "correlated", overdispersion = TRUE, models = NULL, likelihood = TRUE, output_loglik = FALSE, debug = FALSE, keep_fit = TRUE, scale_r = 1, digits = 3, timespan = 7, probs = c(0.05, 0.2, 0.8, 0.95), id = 0, ... )
forecast( obs, forecast_date = max(obs$date), seq_date = forecast_date, case_date = forecast_date, data_list = forecast.vocs::fv_as_data_list, inits = forecast.vocs::fv_inits, fit = forecast.vocs::fv_sample, posterior = forecast.vocs::fv_tidy_posterior, extract_forecast = forecast.vocs::fv_extract_forecast, horizon = 4, r_init = c(0, 0.25), r_step = 1, r_forecast = TRUE, beta = c(0, 0.1), lkj = 0.5, period = NULL, special_periods = c(), voc_scale = c(0, 0.2), voc_label = "VOC", strains = 2, variant_relationship = "correlated", overdispersion = TRUE, models = NULL, likelihood = TRUE, output_loglik = FALSE, debug = FALSE, keep_fit = TRUE, scale_r = 1, digits = 3, timespan = 7, probs = c(0.05, 0.2, 0.8, 0.95), id = 0, ... )
obs |
A |
forecast_date |
Date at which to forecast. Defaults to the
maximum date in |
seq_date |
Date from which to use available sequence data. Defaults to
the |
case_date |
Date from which to use available case data. Defaults to
the |
data_list |
A function that returns a list of data as ingested by the
|
inits |
A function that returns a function to samples initial
conditions with the same arguments as |
fit |
A function that fits the supplied model with the same arguments
and return values as |
posterior |
A function that summarises the output from the supplied
fitting function with the same arguments and return values (depending on
the requirement for downstream package functionality to function) as
|
extract_forecast |
A function that extracts the forecast from
the summarised |
horizon |
Integer forecast horizon. Defaults to 4. |
r_init |
Numeric vector of length 2. Mean and standard deviation for the normal prior on the initial log growth rate. |
r_step |
Integer, defaults to 1. The number of observations between each change in the growth rate. |
r_forecast |
Logical, defaults |
beta |
Numeric vector, defaults to c(0, 0.5). Represents the mean and standard deviation of the normal prior (truncated at 1 and -1) on the weighting in the differenced AR process of the previous difference. Placing a tight prior around zero effectively reduces the AR process to a random walk on the growth rate. |
lkj |
Numeric defaults to 0.5. The assumed prior covariance between variants growth rates when using the "correlated" model. This sets the shape parameter for the Lewandowski-Kurowicka-Joe (LKJ) prior distribution. If set to 1 assigns a uniform prior for all correlations, values less than 1 indicate increased belief in strong correlations and values greater than 1 indicate increased belief weaker correlations. Our default setting places increased weight on some correlation between strains. |
period |
Logical defaults to |
special_periods |
A vector of dates to pass to the |
voc_scale |
Numeric vector of length 2. Prior mean and standard deviation for the initial growth rate modifier due to the variant of concern. |
voc_label |
A character string, default to "VOC". Defines the label to assign to variant of concern specific parameters. Example usage is to rename parameters to use variant specific terminology. |
strains |
Integer number of strains to use. Defaults to 2. Current maximum is 2. A numeric vector can be passed if forecasts from multiple strain models are desired. |
variant_relationship |
Character string, defaulting to "correlated". Controls the relationship of strains with options being "correlated" (strains growth rates are correlated over time), "scaled" (a fixed scaling between strains), and "independent" (fully independent strains after initial scaling). |
overdispersion |
Logical, defaults to |
models |
A model as supplied by |
likelihood |
Logical, defaults to |
output_loglik |
Logical, defaults to |
debug |
Logical, defaults to |
keep_fit |
Logical, defaults to |
scale_r |
Numeric, defaults to 1. Rescale the timespan over which the growth rate and reproduction number is calculated. An example use case is rescaling the growth rate from weekly to be scaled by the mean of the generation time (for COVID-19 for example this would be 5.5 / 7. |
digits |
Numeric, defaults to 3. Number of digits to round summary statistics to. |
timespan |
Integer, defaults to 7. Indicates the number of days between each observation. Defaults to a week. |
probs |
A vector of numeric probabilities to produce
quantile summaries for. By default these are the 5%, 20%, 80%,
and 95% quantiles which are also the minimum set required for
plotting functions to work (such as |
id |
ID to assign to this forecast. Defaults to 0. |
... |
Additional parameters passed to |
A data.frame
containing the output of fv_sample()
in each row as
well as the summarised posterior, forecast and information about the
parameters specified.
Functions used for forecasting across models, dates, and scenarios
forecast_across_dates()
,
forecast_across_scenarios()
,
forecast_n_strain()
,
plot.fv_forecast()
,
summary.fv_forecast()
,
unnest_posterior()
options(mc.cores = 4) forecasts <- forecast( germany_covid19_delta_obs, forecast_date = as.Date("2021-06-12"), horizon = 4, strains = c(1, 2), adapt_delta = 0.99, max_treedepth = 15, variant_relationship = "scaled" ) # inspect forecasts forecasts # extract the model summary summary(forecasts, type = "model") # plot case posterior predictions plot(forecasts, log = TRUE) # plot voc posterior predictions plot(forecasts, type = "voc_frac") # extract the case forecast summary(forecasts, type = "cases", forecast = TRUE)
options(mc.cores = 4) forecasts <- forecast( germany_covid19_delta_obs, forecast_date = as.Date("2021-06-12"), horizon = 4, strains = c(1, 2), adapt_delta = 0.99, max_treedepth = 15, variant_relationship = "scaled" ) # inspect forecasts forecasts # extract the model summary summary(forecasts, type = "model") # plot case posterior predictions plot(forecasts, log = TRUE) # plot voc posterior predictions plot(forecasts, type = "voc_frac") # extract the case forecast summary(forecasts, type = "cases", forecast = TRUE)
Forecast across multiple dates
forecast_across_dates( obs, forecast_dates = unique(obs[!is.na(seq_available)])$date[-c(1:3)], ... )
forecast_across_dates( obs, forecast_dates = unique(obs[!is.na(seq_available)])$date[-c(1:3)], ... )
obs |
A |
forecast_dates |
A list of dates to forecast at. |
... |
Additional parameters passed to |
A data.table
each row containing the output from running
forecast()
on a single forecast date.
Functions used for forecasting across models, dates, and scenarios
forecast_across_scenarios()
,
forecast_n_strain()
,
forecast()
,
plot.fv_forecast()
,
summary.fv_forecast()
,
unnest_posterior()
library(ggplot2) options(mc.cores = 4) forecasts <- forecast_across_dates( germany_covid19_delta_obs, forecast_dates = c(as.Date("2021-05-01"), as.Date("2021-06-12")), horizon = 4, strains = 2, adapt_delta = 0.99, max_treedepth = 15, variant_relationship = "scaled" ) # inspect forecasts forecasts # unnest posteriors posteriors <- unnest_posterior(forecasts) # plot case posterior predictions plot_cases(posteriors, log = TRUE) + facet_grid(vars(forecast_date), vars(voc_scale))
library(ggplot2) options(mc.cores = 4) forecasts <- forecast_across_dates( germany_covid19_delta_obs, forecast_dates = c(as.Date("2021-05-01"), as.Date("2021-06-12")), horizon = 4, strains = 2, adapt_delta = 0.99, max_treedepth = 15, variant_relationship = "scaled" ) # inspect forecasts forecasts # unnest posteriors posteriors <- unnest_posterior(forecasts) # plot case posterior predictions plot_cases(posteriors, log = TRUE) + facet_grid(vars(forecast_date), vars(voc_scale))
Forecast across multiple scenarios and dates
forecast_across_scenarios(obs, scenarios, ...)
forecast_across_scenarios(obs, scenarios, ...)
obs |
A |
scenarios |
A |
... |
Additional parameters passed to |
A data table each rows containing the output from running
forecast()
on a single scenario for a single forecast date.
Functions used for forecasting across models, dates, and scenarios
forecast_across_dates()
,
forecast_n_strain()
,
forecast()
,
plot.fv_forecast()
,
summary.fv_forecast()
,
unnest_posterior()
library(ggplot2) options(mc.cores = 4) scenarios <- define_scenarios( voc_scale = list(c(0, 0.5), c(0.5, 0.25)), seq_lag = 1, seq_samples = 1 ) scenarios forecasts <- forecast_across_scenarios( germany_covid19_delta_obs, scenarios, forecast_dates = c(as.Date("2021-05-01"), as.Date("2021-06-12")), horizon = 4, strains = 2, adapt_delta = 0.99, max_treedepth = 15, variant_relationship = "scaled" ) # inspect forecasts forecasts # unnest posteriors posteriors <- unnest_posterior(forecasts) # plot case posterior predictions plot_cases(posteriors, log = TRUE) + facet_grid(vars(forecast_date))
library(ggplot2) options(mc.cores = 4) scenarios <- define_scenarios( voc_scale = list(c(0, 0.5), c(0.5, 0.25)), seq_lag = 1, seq_samples = 1 ) scenarios forecasts <- forecast_across_scenarios( germany_covid19_delta_obs, scenarios, forecast_dates = c(as.Date("2021-05-01"), as.Date("2021-06-12")), horizon = 4, strains = 2, adapt_delta = 0.99, max_treedepth = 15, variant_relationship = "scaled" ) # inspect forecasts forecasts # unnest posteriors posteriors <- unnest_posterior(forecasts) # plot case posterior predictions plot_cases(posteriors, log = TRUE) + facet_grid(vars(forecast_date))
Forecast for a single model and summarise
forecast_n_strain( data, model = NULL, inits = forecast.vocs::fv_inits, fit = forecast.vocs::fv_sample, posterior = forecast.vocs::fv_tidy_posterior, extract_forecast = forecast.vocs::fv_extract_forecast, strains = 2, voc_label = "VOC", probs = c(0.05, 0.2, 0.8, 0.95), digits = 3, scale_r = 1, timespan = 7, ... )
forecast_n_strain( data, model = NULL, inits = forecast.vocs::fv_inits, fit = forecast.vocs::fv_sample, posterior = forecast.vocs::fv_tidy_posterior, extract_forecast = forecast.vocs::fv_extract_forecast, strains = 2, voc_label = "VOC", probs = c(0.05, 0.2, 0.8, 0.95), digits = 3, scale_r = 1, timespan = 7, ... )
data |
A list of data as produced by |
model |
A |
inits |
A function that returns a function to samples initial
conditions with the same arguments as |
fit |
A function that fits the supplied model with the same arguments
and return values as |
posterior |
A function that summarises the output from the supplied
fitting function with the same arguments and return values (depending on
the requirement for downstream package functionality to function) as
|
extract_forecast |
A function that extracts the forecast from
the summarised |
strains |
Integer number of strains. Defaults to 2. Current maximum is 2. |
voc_label |
A character string, default to "VOC". Defines the label to assign to variant of concern specific parameters. Example usage is to rename parameters to use variant specific terminology. |
probs |
A vector of numeric probabilities to produce
quantile summaries for. By default these are the 5%, 20%, 80%,
and 95% quantiles which are also the minimum set required for
plotting functions to work (such as |
digits |
Numeric, defaults to 3. Number of digits to round summary statistics to. |
scale_r |
Numeric, defaults to 1. Rescale the timespan over which the growth rate and reproduction number is calculated. An example use case is rescaling the growth rate from weekly to be scaled by the mean of the generation time (for COVID-19 for example this would be 5.5 / 7. |
timespan |
Integer, defaults to 7. Indicates the number of days between each observation. Defaults to a week. |
... |
Additional parameters passed to |
Functions used for forecasting across models, dates, and scenarios
forecast_across_dates()
,
forecast_across_scenarios()
,
forecast()
,
plot.fv_forecast()
,
summary.fv_forecast()
,
unnest_posterior()
Format data for use with stan
fv_as_data_list( obs, horizon = 4, r_init = c(0, 0.25), r_step = 1, r_forecast = TRUE, beta = c(0, 0.5), lkj = 0.5, voc_scale = c(0, 0.2), period = NULL, special_periods = c(), variant_relationship = "correlated", overdispersion = TRUE, likelihood = TRUE, output_loglik = TRUE, debug = FALSE )
fv_as_data_list( obs, horizon = 4, r_init = c(0, 0.25), r_step = 1, r_forecast = TRUE, beta = c(0, 0.5), lkj = 0.5, voc_scale = c(0, 0.2), period = NULL, special_periods = c(), variant_relationship = "correlated", overdispersion = TRUE, likelihood = TRUE, output_loglik = TRUE, debug = FALSE )
obs |
A data frame with the following variables:
|
horizon |
Integer forecast horizon. Defaults to 4. |
r_init |
Numeric vector of length 2. Mean and standard deviation for the normal prior on the initial log growth rate. |
r_step |
Integer, defaults to 1. The number of observations between each change in the growth rate. |
r_forecast |
Logical, defaults |
beta |
Numeric vector, defaults to c(0, 0.5). Represents the mean and standard deviation of the normal prior (truncated at 1 and -1) on the weighting in the differenced AR process of the previous difference. Placing a tight prior around zero effectively reduces the AR process to a random walk on the growth rate. |
lkj |
Numeric defaults to 0.5. The assumed prior covariance between variants growth rates when using the "correlated" model. This sets the shape parameter for the Lewandowski-Kurowicka-Joe (LKJ) prior distribution. If set to 1 assigns a uniform prior for all correlations, values less than 1 indicate increased belief in strong correlations and values greater than 1 indicate increased belief weaker correlations. Our default setting places increased weight on some correlation between strains. |
voc_scale |
Numeric vector of length 2. Prior mean and standard deviation for the initial growth rate modifier due to the variant of concern. |
period |
Logical defaults to |
special_periods |
A vector of dates to pass to the |
variant_relationship |
Character string, defaulting to "correlated". Controls the relationship of strains with options being "correlated" (strains growth rates are correlated over time), "scaled" (a fixed scaling between strains), and "independent" (fully independent strains after initial scaling). |
overdispersion |
Logical, defaults to |
likelihood |
Logical, defaults to |
output_loglik |
Logical, defaults to |
debug |
Logical, defaults to |
A list as required by stan.
Functions used for modelling
fv_inits()
,
fv_model()
,
fv_sample()
fv_as_data_list(latest_obs(germany_covid19_delta_obs))
fv_as_data_list(latest_obs(germany_covid19_delta_obs))
This helper function allows the user to generate a vector of day of the the week periods.
fv_dow_period(t, start_date, specials = c(), special_to = "Sunday")
fv_dow_period(t, start_date, specials = c(), special_to = "Sunday")
t |
An integer indicating the number of dates |
start_date |
A date indicating the start date |
specials |
A vector of special dates to modify the day of the week for. |
special_to |
A character string indicating which day of the week or other label to assign holidays. By default this is set to "Sunday" |
A vector indicating the period of the dates.
Preprocessing functions
filter_by_availability()
,
latest_obs()
,
piecewise_steps()
fv_dow_period(t = 10, start_date = as.Date("2021-12-01"))
fv_dow_period(t = 10, start_date = as.Date("2021-12-01"))
Loads examples of posterior and forecast summaries produced
using example scripts. Used to streamline examples,
in package tests and to enable users to explore package functionality
without needing to install cmdstanr
.
fv_example(strains = 1, type = "posterior")
fv_example(strains = 1, type = "posterior")
strains |
Integer number of strains. Defaults to 2. Current maximum is 2. |
type |
A character string indicating the example to load.
Supported options are "posterior", "forecast", "observations",
and "script" which are the
output of |
A data.table
of summarised output
Package data sets
germany_covid19_delta_obs
# Load the summarised posterior from an example fit of the one strain model fv_example(strains = 1, type = "posterior") # Load the summarised forecast from this posterior fv_example(strains = 1, type = "forecast") # Load the script used to generate these examples # Optionally source this script to regenerate the example readLines(fv_example(strains = 1, type = "script"))
# Load the summarised posterior from an example fit of the one strain model fv_example(strains = 1, type = "posterior") # Load the summarised forecast from this posterior fv_example(strains = 1, type = "forecast") # Load the script used to generate these examples # Optionally source this script to regenerate the example readLines(fv_example(strains = 1, type = "script"))
Uses the observed
variable returned by
fv_tidy_posterior()
to return posterior predictions
for forecast dates only.
fv_extract_forecast(posterior)
fv_extract_forecast(posterior)
posterior |
A dataframe of posterior output as produced by
|
A data.frame
of forecasts in the format returned
by fv_tidy_posterior()
but with fitting variables dropped.
Functions used for postprocessing of model fits
convert_to_stanfit()
,
extract_draws()
,
extract_forecast_dates()
,
fv_posterior()
,
fv_tidy_posterior()
,
link_dates_with_posterior()
,
link_obs_with_posterior()
,
plot.fv_posterior()
,
print.fv_posterior()
,
quantiles_to_long()
,
summary.fv_posterior()
,
update_voc_label()
p <- fv_example(strains = 2, type = "posterior") fv_extract_forecast(p)
p <- fv_example(strains = 2, type = "posterior") fv_extract_forecast(p)
Set up initial conditions for model
fv_inits(data, strains = 2)
fv_inits(data, strains = 2)
data |
A list of data as produced by |
strains |
Integer number of strains. Defaults to 2. Current maximum is 2. |
A function that when called returns a list of initial conditions for the package stan models.
Functions used for modelling
fv_as_data_list()
,
fv_model()
,
fv_sample()
dt <- fv_as_data_list(latest_obs(germany_covid19_delta_obs)) inits <- fv_inits(dt) inits inits()
dt <- fv_as_data_list(latest_obs(germany_covid19_delta_obs)) inits <- fv_inits(dt) inits inits()
Load and compile a strain model
fv_model(model, include, strains = 2, compile = TRUE, verbose = FALSE, ...)
fv_model(model, include, strains = 2, compile = TRUE, verbose = FALSE, ...)
model |
A character string indicating the path to the model. If not supplied the package default model is used. |
include |
A character string specifying the path to any stan files to include in the model. If missing the package default is used. |
strains |
Integer number of strains. Defaults to 2. Current maximum is 2. |
compile |
Logical, defaults to |
verbose |
Logical, defaults to |
... |
Additional arguments passed to |
A cmdstanr
model.
Functions used for modelling
fv_as_data_list()
,
fv_inits()
,
fv_sample()
# one strain model mod <- fv_model(strains = 1) # two strain model two_strain_mod <- fv_model(strains = 2)
# one strain model mod <- fv_model(strains = 1) # two strain model two_strain_mod <- fv_model(strains = 2)
A generic wrapper around posterior::summarise_draws()
with
opinionated defaults. See fv_tidy_posterior()
for a more
opinionated wrapper with further cleaning and tidying
including linking to observed data, tidying parameter names,
and transforming parameters for interpretability.
fv_posterior(fit, probs = c(0.05, 0.2, 0.8, 0.95), digits = 3, ...)
fv_posterior(fit, probs = c(0.05, 0.2, 0.8, 0.95), digits = 3, ...)
fit |
List of output as returned by |
probs |
A vector of numeric probabilities to produce
quantile summaries for. By default these are the 5%, 20%, 80%,
and 95% quantiles which are also the minimum set required for
plotting functions to work (such as |
digits |
Numeric, defaults to 3. Number of digits to round summary statistics to. |
... |
Additional arguments that may be passed but will not be used. |
A dataframe summarising the model posterior.
Functions used for postprocessing of model fits
convert_to_stanfit()
,
extract_draws()
,
extract_forecast_dates()
,
fv_extract_forecast()
,
fv_tidy_posterior()
,
link_dates_with_posterior()
,
link_obs_with_posterior()
,
plot.fv_posterior()
,
print.fv_posterior()
,
quantiles_to_long()
,
summary.fv_posterior()
,
update_voc_label()
options(mc.cores = 4) obs <- filter_by_availability( germany_covid19_delta_obs, date = as.Date("2021-06-12"), ) dt <- fv_as_data_list(obs) inits <- fv_inits(dt) fit <- fv_sample(dt, init = inits, adapt_delta = 0.99, max_treedepth = 15) fv_posterior(fit)
options(mc.cores = 4) obs <- filter_by_availability( germany_covid19_delta_obs, date = as.Date("2021-06-12"), ) dt <- fv_as_data_list(obs) inits <- fv_inits(dt) fit <- fv_sample(dt, init = inits, adapt_delta = 0.99, max_treedepth = 15) fv_posterior(fit)
Fit a brancing process strain model
fv_sample( data, model = forecast.vocs::fv_model(strains = 2), diagnostics = TRUE, ... )
fv_sample( data, model = forecast.vocs::fv_model(strains = 2), diagnostics = TRUE, ... )
data |
A list of data as produced by |
model |
A |
diagnostics |
Logical, defaults to |
... |
Additional parameters passed to the |
A data.frame
containing the cmdstanr
fit, the input data, the
fitting arguments, and optionally summary diagnostics.
Functions used for modelling
fv_as_data_list()
,
fv_inits()
,
fv_model()
options(mc.cores = 4) # format example data obs <- filter_by_availability( germany_covid19_delta_obs, date = as.Date("2021-06-12"), ) dt <- fv_as_data_list(obs) # single strain model inits <- fv_inits(dt, strains = 1) mod <- fv_model(strains = 1) fit <- fv_sample( dt, model = mod, init = inits, adapt_delta = 0.99, max_treedepth = 15 ) fit # two strain model inits <- fv_inits(dt, strains = 2) mod <- fv_model(strains = 2) two_strain_fit <- fv_sample(dt, model = mod, init = inits, adapt_delta = 0.99, max_treedepth = 15 ) two_strain_fit
options(mc.cores = 4) # format example data obs <- filter_by_availability( germany_covid19_delta_obs, date = as.Date("2021-06-12"), ) dt <- fv_as_data_list(obs) # single strain model inits <- fv_inits(dt, strains = 1) mod <- fv_model(strains = 1) fit <- fv_sample( dt, model = mod, init = inits, adapt_delta = 0.99, max_treedepth = 15 ) fit # two strain model inits <- fv_inits(dt, strains = 2) mod <- fv_model(strains = 2) two_strain_fit <- fv_sample(dt, model = mod, init = inits, adapt_delta = 0.99, max_treedepth = 15 ) two_strain_fit
Acts as a wrapper to scoringutils::score()
. In particular,
handling filtering the output for various forecast.vocs functions and
linking this output to observed data. See the documentation for the
scoringutils
package for more on forecast scoring and the documentation
and examples below for simple examples in the context of forecast.vocs
.
Internally name clashes between scoringutils
variables and forecast.vocs
variables are handled.
fv_score_forecast(forecast, obs, log = FALSE, check = TRUE, round_to = 3, ...)
fv_score_forecast(forecast, obs, log = FALSE, check = TRUE, round_to = 3, ...)
forecast |
A posterior forecast or posterior prediction as returned by
|
obs |
A data frame of observed data as produced by |
log |
Logical, defaults to FALSE. Should scores be calculated on the log scale (with a 0.01 shift) for both observations and forecasts. Scoring in this way can be thought of as a relative score vs the more usual absolute measure. It may be useful when targets are on very different scales or when the forecaster is more interested in good all round performance versus good performance for targets with large values. |
check |
Logical, defaults to FALSE. Should
|
round_to |
Integer defaults to 3. Number of digits to round scoring output to. |
... |
Additional arguments passed to |
A data.table
as returned by scoringutils::score()
.
Functions to explore and validate models
bp_launch_shinystan()
,
plot_pairs()
options(mc.cores = 4) library(data.table) library(scoringutils) # Fit and forecast using both the one and two strain models forecasts <- forecast( germany_covid19_delta_obs, forecast_date = as.Date("2021-06-12"), horizon = 4, strains = c(1, 2), adapt_delta = 0.99, max_treedepth = 15, variant_relationship = "scaled" ) # Extract forecasts forecasts <- summary(forecasts, target = "forecast", type = "cases") # Filter for the latest available observations obs <- latest_obs(germany_covid19_delta_obs) # score on the absolute scale scores <- fv_score_forecast(forecasts, obs) summarise_scores(scores, by = "strains") # score overall on a log scale log_scores <- fv_score_forecast(forecasts, obs, log = TRUE) summarise_scores(log_scores, by = "strains") # score by horizon summarise_scores(scores, by = c("strains", "horizon")) # score by horizon on a log scale summarise_scores(log_scores, by = c("strains", "horizon"))
options(mc.cores = 4) library(data.table) library(scoringutils) # Fit and forecast using both the one and two strain models forecasts <- forecast( germany_covid19_delta_obs, forecast_date = as.Date("2021-06-12"), horizon = 4, strains = c(1, 2), adapt_delta = 0.99, max_treedepth = 15, variant_relationship = "scaled" ) # Extract forecasts forecasts <- summary(forecasts, target = "forecast", type = "cases") # Filter for the latest available observations obs <- latest_obs(germany_covid19_delta_obs) # score on the absolute scale scores <- fv_score_forecast(forecasts, obs) summarise_scores(scores, by = "strains") # score overall on a log scale log_scores <- fv_score_forecast(forecasts, obs, log = TRUE) summarise_scores(log_scores, by = "strains") # score by horizon summarise_scores(scores, by = c("strains", "horizon")) # score by horizon on a log scale summarise_scores(log_scores, by = c("strains", "horizon"))
A very opinionated wrapper around
posterior::summarise_draws()
with cleaning and tidying including linking
to observed data, tidying parameter names, and transforming parameters for
interpretability. See fv_posterior()
for a more generic solution.
fv_tidy_posterior( fit, probs = c(0.05, 0.2, 0.8, 0.95), digits = 3, voc_label = "VOC", scale_r = 1, timespan = 7 )
fv_tidy_posterior( fit, probs = c(0.05, 0.2, 0.8, 0.95), digits = 3, voc_label = "VOC", scale_r = 1, timespan = 7 )
fit |
List of output as returned by |
probs |
A vector of numeric probabilities to produce
quantile summaries for. By default these are the 5%, 20%, 80%,
and 95% quantiles which are also the minimum set required for
plotting functions to work (such as |
digits |
Numeric, defaults to 3. Number of digits to round summary statistics to. |
voc_label |
A character string, default to "VOC". Defines the label to assign to variant of concern specific parameters. Example usage is to rename parameters to use variant specific terminology. |
scale_r |
Numeric, defaults to 1. Rescale the timespan over which the growth rate and reproduction number is calculated. An example use case is rescaling the growth rate from weekly to be scaled by the mean of the generation time (for COVID-19 for example this would be 5.5 / 7. |
timespan |
Integer, defaults to 7. Indicates the number of days between each observation. Defaults to a week. |
A dataframe summarising the model posterior. Output is stratified
by value_type
with posterior summaries by case, voc, voc advantage vs
non-voc over time, rt, growth, model, and the raw posterior summary.
Functions used for postprocessing of model fits
convert_to_stanfit()
,
extract_draws()
,
extract_forecast_dates()
,
fv_extract_forecast()
,
fv_posterior()
,
link_dates_with_posterior()
,
link_obs_with_posterior()
,
plot.fv_posterior()
,
print.fv_posterior()
,
quantiles_to_long()
,
summary.fv_posterior()
,
update_voc_label()
options(mc.cores = 4) obs <- filter_by_availability( germany_covid19_delta_obs, date = as.Date("2021-06-12"), ) dt <- fv_as_data_list(obs) inits <- fv_inits(dt) fit <- fv_sample(dt, init = inits, adapt_delta = 0.99, max_treedepth = 15) fv_tidy_posterior(fit)
options(mc.cores = 4) obs <- filter_by_availability( germany_covid19_delta_obs, date = as.Date("2021-06-12"), ) dt <- fv_as_data_list(obs) inits <- fv_inits(dt) fit <- fv_sample(dt, init = inits, adapt_delta = 0.99, max_treedepth = 15) fv_tidy_posterior(fit)
Generate simulated observations from the prior or posterior
distributions of a forecast.vocs
model. When a single strain model is used
only case data is simulated but when a multiple strain model is used sequence
data is also simulated.
generate_obs( obs, strains = 2, model = forecast.vocs::fv_model(strains = strains), data_list = forecast.vocs::fv_as_data_list, inits = forecast.vocs::fv_inits, fit = forecast.vocs::fv_sample, type = "prior", datasets = 10, ... )
generate_obs( obs, strains = 2, model = forecast.vocs::fv_model(strains = strains), data_list = forecast.vocs::fv_as_data_list, inits = forecast.vocs::fv_inits, fit = forecast.vocs::fv_sample, type = "prior", datasets = 10, ... )
obs |
Observed data to use to parameterise the model and used for fitting when the posterior is required. |
strains |
Integer number of strains to use. Defaults to 2. Current maximum is 2. A numeric vector can be passed if forecasts from multiple strain models are desired. |
model |
A |
data_list |
A function that returns a list of data as ingested by the
|
inits |
A function that returns a function to samples initial
conditions with the same arguments as |
fit |
A function that fits the supplied model with the same arguments
and return values as |
type |
A character string indicating the type of data to generate. Supported options are data based on the "prior" or data based on the "posterior" with the default being the prior. |
datasets |
Numeric, defaults to 10. Number of datasets to generate. |
... |
Additional arguments to pass |
A dataframe with a sampled dataset on each row with the following
variables: parameters (prior/posterior parameters used to generate the data),
obs (simulated observed data), data, (the simulated data formatted
using the supplied data_list
function (by default fv_as_data_list()
)
with the same arguments as specified for simulation).
Functions to generate simulated data
sample_sequences()
options(mc.cores = 4) obs <- latest_obs(germany_covid19_delta_obs) sim_obs <- generate_obs(obs, voc_scale = c(0.8, 0.1), r_init = c(-0.1, 0.05)) # fit a simulated dataset sim_dt <- sim_obs$data[[1]] inits <- fv_inits(sim_dt) fit <- fv_sample( sim_dt, init = inits, adapt_delta = 0.95, max_treedepth = 15 ) # summarise and plot simualated fit posterior <- fv_tidy_posterior(fit) plot_cases(posterior, log = TRUE) plot_voc(posterior) plot_rt(posterior)
options(mc.cores = 4) obs <- latest_obs(germany_covid19_delta_obs) sim_obs <- generate_obs(obs, voc_scale = c(0.8, 0.1), r_init = c(-0.1, 0.05)) # fit a simulated dataset sim_dt <- sim_obs$data[[1]] inits <- fv_inits(sim_dt) fit <- fv_sample( sim_dt, init = inits, adapt_delta = 0.95, max_treedepth = 15 ) # summarise and plot simualated fit posterior <- fv_tidy_posterior(fit) plot_cases(posterior, log = TRUE) plot_voc(posterior) plot_rt(posterior)
Define observed data for a scenario
generate_obs_scenario(obs, seq_lag, seq_samples)
generate_obs_scenario(obs, seq_lag, seq_samples)
obs |
A dataframe of observations as returned by |
seq_lag |
Number, number of weeks to lag sequence data behind date of observation. |
seq_samples |
Fraction of sequence samples to include. |
A data.frame
of scenario definitions with ids
Functions to define and create data scenarios
define_scenarios()
,
update_obs_availability()
generate_obs_scenario(latest_obs(germany_covid19_delta_obs), 4, 0.1)
generate_obs_scenario(latest_obs(germany_covid19_delta_obs), 4, 0.1)
Test positive COVID-19 cases and sequences stratified by voc variant status summarised by week for Germany. Data is sourced from the RKI via the Germany/Poland forecasting hub.
germany_covid19_delta_obs
germany_covid19_delta_obs
An object of class data.table
(inherits from data.frame
) with 114 rows and 9 columns.
A data.table
with the following variables: date, location_name,
location, cases, seq_total, seq_voc, share_voc, cases_available,
and seq_available.
Package data sets
fv_example()
Filter for latest observations of all types
latest_obs(obs)
latest_obs(obs)
obs |
A |
A data.frame
of observations filtered for the
latest available data.
Preprocessing functions
filter_by_availability()
,
fv_dow_period()
,
piecewise_steps()
dt <- rbind( update_obs_availability(germany_covid19_delta_obs, seq_lag = 3), update_obs_availability(germany_covid19_delta_obs, seq_lag = 1) ) latest_obs(dt)
dt <- rbind( update_obs_availability(germany_covid19_delta_obs, seq_lag = 3), update_obs_availability(germany_covid19_delta_obs, seq_lag = 1) ) latest_obs(dt)
Link dates by time for posterior parameter estimates
link_dates_with_posterior(posterior, data, timespan = 7, mod_end = 0)
link_dates_with_posterior(posterior, data, timespan = 7, mod_end = 0)
posterior |
A data frame of summarised posterior estimates
as returned by |
data |
A list of data as returned in the "data" entry of the output
returned by |
timespan |
Integer, defaults to 7. Indicates the number of days between each observation. Defaults to a week. |
mod_end |
Integer, defaults to 0. Amount to shift the end date of estimates. |
A posterior data.frame
with an additional data column.
Functions used for postprocessing of model fits
convert_to_stanfit()
,
extract_draws()
,
extract_forecast_dates()
,
fv_extract_forecast()
,
fv_posterior()
,
fv_tidy_posterior()
,
link_obs_with_posterior()
,
plot.fv_posterior()
,
print.fv_posterior()
,
quantiles_to_long()
,
summary.fv_posterior()
,
update_voc_label()
Link posterior estimates with observed data and flag if values are observed or not.
link_obs_with_posterior(posterior, obs, horizon, target_types)
link_obs_with_posterior(posterior, obs, horizon, target_types)
posterior |
A data frame of summarised posterior estimates
as returned by |
obs |
Numeric vector of observed data to link to posterior estimates. |
horizon |
Integer indicating the horizon of unobserved forecasts. If not
specified will be inferred from |
target_types |
A character vector of types (as specified in the |
The input data.frame
combined with obs
and observed
variables.
Functions used for postprocessing of model fits
convert_to_stanfit()
,
extract_draws()
,
extract_forecast_dates()
,
fv_extract_forecast()
,
fv_posterior()
,
fv_tidy_posterior()
,
link_dates_with_posterior()
,
plot.fv_posterior()
,
print.fv_posterior()
,
quantiles_to_long()
,
summary.fv_posterior()
,
update_voc_label()
This helper function streamlines the calculation of piecewise steps. This may be useful when specifying random walks, AR processes, etc.
piecewise_steps(t, step, offset = 0, steps_post_offset = TRUE)
piecewise_steps(t, step, offset = 0, steps_post_offset = TRUE)
t |
Integer, the timespan over which to calculate steps |
step |
Integer, the frequency at which to step. |
offset |
Integer, the amount to offset steps. This can be used to index steps from this index. |
steps_post_offset |
Logical, defaults to |
A list containing two elements: n
(the number of steps) and steps
the location of steps as a binary variable.
Preprocessing functions
filter_by_availability()
,
fv_dow_period()
,
latest_obs()
Plot the posterior prediction for cases
plot_cases( posterior, obs = NULL, forecast_dates = NULL, all_obs = FALSE, central = FALSE, col = NULL, log = TRUE )
plot_cases( posterior, obs = NULL, forecast_dates = NULL, all_obs = FALSE, central = FALSE, col = NULL, log = TRUE )
posterior |
A dataframe of posterior output as produced by
|
obs |
A data frame of observed data as produced by |
forecast_dates |
A data.frame in the format produced by
|
all_obs |
Logical, defaults to |
central |
Logical, defaults to FALSE. Should the mean and median
central estimates be plot as dashed and solid lines respectively. Requires
|
col |
A character string denoting the variable to use to stratify the ribbon plot. Defaults to "type" which indicates the data stream. |
log |
Logical, defaults to |
A ggplot2
plot.
Plotting functions
add_forecast_dates()
,
plot.fv_forecast()
,
plot.fv_posterior()
,
plot_default()
,
plot_growth()
,
plot_pairs()
,
plot_posterior()
,
plot_rt()
,
plot_theme()
,
plot_voc_advantage()
,
plot_voc_frac()
,
save_plots()
posterior <- fv_example(strains = 2, type = "posterior") # default with log transform plot_cases(posterior) # without log transform plot_cases(posterior, log = FALSE)
posterior <- fv_example(strains = 2, type = "posterior") # default with log transform plot_cases(posterior) # without log transform plot_cases(posterior, log = FALSE)
Default posterior plot
plot_default( posterior, target, obs = NULL, forecast_dates = NULL, central = FALSE, all_obs = FALSE, ... )
plot_default( posterior, target, obs = NULL, forecast_dates = NULL, central = FALSE, all_obs = FALSE, ... )
posterior |
A dataframe of posterior output as produced by
|
target |
A character string indicating which variable to extract from the posterior list. |
obs |
A data frame of observed data as produced by |
forecast_dates |
A data.frame in the format produced by
|
central |
Logical, defaults to FALSE. Should the mean and median
central estimates be plot as dashed and solid lines respectively. Requires
|
all_obs |
Logical, defaults to |
... |
Additional arguments passed to |
A ggplot2
plot.
Plotting functions
add_forecast_dates()
,
plot.fv_forecast()
,
plot.fv_posterior()
,
plot_cases()
,
plot_growth()
,
plot_pairs()
,
plot_posterior()
,
plot_rt()
,
plot_theme()
,
plot_voc_advantage()
,
plot_voc_frac()
,
save_plots()
Plot the posterior prediction for the growth rate
plot_growth(posterior, forecast_dates = NULL, central = FALSE, col = NULL)
plot_growth(posterior, forecast_dates = NULL, central = FALSE, col = NULL)
posterior |
A dataframe of posterior output as produced by
|
forecast_dates |
A data.frame in the format produced by
|
central |
Logical, defaults to FALSE. Should the mean and median
central estimates be plot as dashed and solid lines respectively. Requires
|
col |
A character string denoting the variable to use to stratify the ribbon plot. Defaults to "type" which indicates the data stream. |
A ggplot2
plot.
Plotting functions
add_forecast_dates()
,
plot.fv_forecast()
,
plot.fv_posterior()
,
plot_cases()
,
plot_default()
,
plot_pairs()
,
plot_posterior()
,
plot_rt()
,
plot_theme()
,
plot_voc_advantage()
,
plot_voc_frac()
,
save_plots()
posterior <- fv_example(strains = 2, type = "posterior") plot_growth(posterior)
posterior <- fv_example(strains = 2, type = "posterior") plot_growth(posterior)
Pairs plot of parameters of interest and fitting diagnostics
plot_pairs( fit, pars = c("r_init", "r_scale", "beta", "voc_beta", "voc_scale[1]", "init_cases[1]", "init_cases[2]", "eta[1]", "voc_eta[1]", "sqrt_phi[1]", "sqrt_phi[2]", "sqrt_phi"), diagnostics = TRUE, ... )
plot_pairs( fit, pars = c("r_init", "r_scale", "beta", "voc_beta", "voc_scale[1]", "init_cases[1]", "init_cases[2]", "eta[1]", "voc_eta[1]", "sqrt_phi[1]", "sqrt_phi[2]", "sqrt_phi"), diagnostics = TRUE, ... )
fit |
List of output as returned by |
pars |
Character vector of parameters to try and include in the plot. Will only be included if present in the fitted model. |
diagnostics |
Logical, defaults to |
... |
Additional parameters passed to |
A ggplot2
based pairs plot of parameters of interest
Plotting functions
add_forecast_dates()
,
plot.fv_forecast()
,
plot.fv_posterior()
,
plot_cases()
,
plot_default()
,
plot_growth()
,
plot_posterior()
,
plot_rt()
,
plot_theme()
,
plot_voc_advantage()
,
plot_voc_frac()
,
save_plots()
Functions to explore and validate models
bp_launch_shinystan()
,
fv_score_forecast()
obs <- filter_by_availability( germany_covid19_delta_obs, date = as.Date("2021-06-12"), ) dt <- fv_as_data_list(obs) inits <- fv_inits(dt) fit <- fv_sample(dt, init = inits, adapt_voc = 0.99, max_treedepth = 15) plot_pairs(fit)
obs <- filter_by_availability( germany_covid19_delta_obs, date = as.Date("2021-06-12"), ) dt <- fv_as_data_list(obs) inits <- fv_inits(dt) fit <- fv_sample(dt, init = inits, adapt_voc = 0.99, max_treedepth = 15) plot_pairs(fit)
Plot posterior predictions
plot_posterior( posterior, obs = NULL, forecast_dates = NULL, central = FALSE, all_obs = FALSE, voc_label = "variant of concern" )
plot_posterior( posterior, obs = NULL, forecast_dates = NULL, central = FALSE, all_obs = FALSE, voc_label = "variant of concern" )
posterior |
A dataframe of posterior output as produced by
|
obs |
A data frame of observed data as produced by |
forecast_dates |
A data.frame in the format produced by
|
central |
Logical, defaults to FALSE. Should the mean and median
central estimates be plot as dashed and solid lines respectively. Requires
|
all_obs |
Logical, defaults to |
voc_label |
Character string giving the name to assign to the variant of concern. Defaults to "variant of concern". |
A named list of all supported package plots with sensible defaults.
Plotting functions
add_forecast_dates()
,
plot.fv_forecast()
,
plot.fv_posterior()
,
plot_cases()
,
plot_default()
,
plot_growth()
,
plot_pairs()
,
plot_rt()
,
plot_theme()
,
plot_voc_advantage()
,
plot_voc_frac()
,
save_plots()
posterior <- fv_example(strains = 2, type = "posterior") plot_posterior(posterior)
posterior <- fv_example(strains = 2, type = "posterior") plot_posterior(posterior)
Plot the posterior prediction for the reproduction number
plot_rt(posterior, forecast_dates = NULL, central = FALSE, col = NULL)
plot_rt(posterior, forecast_dates = NULL, central = FALSE, col = NULL)
posterior |
A dataframe of posterior output as produced by
|
forecast_dates |
A data.frame in the format produced by
|
central |
Logical, defaults to FALSE. Should the mean and median
central estimates be plot as dashed and solid lines respectively. Requires
|
col |
A character string denoting the variable to use to stratify the ribbon plot. Defaults to "type" which indicates the data stream. |
A ggplot2
plot.
Plotting functions
add_forecast_dates()
,
plot.fv_forecast()
,
plot.fv_posterior()
,
plot_cases()
,
plot_default()
,
plot_growth()
,
plot_pairs()
,
plot_posterior()
,
plot_theme()
,
plot_voc_advantage()
,
plot_voc_frac()
,
save_plots()
posterior <- fv_example(strains = 2, type = "posterior") plot_rt(posterior)
posterior <- fv_example(strains = 2, type = "posterior") plot_rt(posterior)
Add the default plot theme
plot_theme(plot)
plot_theme(plot)
plot |
|
A ggplot2
plot with the package theme applied.
Plotting functions
add_forecast_dates()
,
plot.fv_forecast()
,
plot.fv_posterior()
,
plot_cases()
,
plot_default()
,
plot_growth()
,
plot_pairs()
,
plot_posterior()
,
plot_rt()
,
plot_voc_advantage()
,
plot_voc_frac()
,
save_plots()
Plot the posterior prediction for the transmission advantage for the variant of concern
plot_voc_advantage( posterior, forecast_dates = NULL, central = FALSE, voc_label = "variant of concern", ... )
plot_voc_advantage( posterior, forecast_dates = NULL, central = FALSE, voc_label = "variant of concern", ... )
posterior |
A dataframe of posterior output as produced by
|
forecast_dates |
A data.frame in the format produced by
|
central |
Logical, defaults to FALSE. Should the mean and median
central estimates be plot as dashed and solid lines respectively. Requires
|
voc_label |
Character string giving the name to assign to the variant of concern. Defaults to "variant of concern". |
... |
Additional parameters passed to |
A ggplot2
plot.
Plotting functions
add_forecast_dates()
,
plot.fv_forecast()
,
plot.fv_posterior()
,
plot_cases()
,
plot_default()
,
plot_growth()
,
plot_pairs()
,
plot_posterior()
,
plot_rt()
,
plot_theme()
,
plot_voc_frac()
,
save_plots()
posterior <- fv_example(strains = 2, type = "posterior") plot_voc_advantage(posterior)
posterior <- fv_example(strains = 2, type = "posterior") plot_voc_advantage(posterior)
Plot the population posterior prediction for the fraction of samples with the variant of concern
plot_voc_frac( posterior, obs = NULL, forecast_dates = NULL, all_obs = FALSE, central = FALSE, voc_label = "variant of concern", logit = TRUE, ... )
plot_voc_frac( posterior, obs = NULL, forecast_dates = NULL, all_obs = FALSE, central = FALSE, voc_label = "variant of concern", logit = TRUE, ... )
posterior |
A dataframe of posterior output as produced by
|
obs |
A data frame of observed data as produced by |
forecast_dates |
A data.frame in the format produced by
|
all_obs |
Logical, defaults to |
central |
Logical, defaults to FALSE. Should the mean and median
central estimates be plot as dashed and solid lines respectively. Requires
|
voc_label |
Character string giving the name to assign to the variant of concern. Defaults to "variant of concern". |
logit |
Logical, defaults to |
... |
Additional parameters passed to |
A ggplot2
plot.
Plotting functions
add_forecast_dates()
,
plot.fv_forecast()
,
plot.fv_posterior()
,
plot_cases()
,
plot_default()
,
plot_growth()
,
plot_pairs()
,
plot_posterior()
,
plot_rt()
,
plot_theme()
,
plot_voc_advantage()
,
save_plots()
posterior <- fv_example(strains = 2, type = "posterior") plot_voc_frac(posterior)
posterior <- fv_example(strains = 2, type = "posterior") plot_voc_frac(posterior)
plot
method for class "fv_forecast". The type of plot
produced can be controlled using the target
and type
arguments with the
latter only being functional when target
is set to "posterior" or
"forecast".
## S3 method for class 'fv_forecast' plot(x, obs = NULL, target = "posterior", type = "cases", ...)
## S3 method for class 'fv_forecast' plot(x, obs = NULL, target = "posterior", type = "cases", ...)
x |
A |
obs |
A data frame of observed data as produced by |
target |
A character string indicating the target object within the
|
type |
A character string indicating the type of plot required,
defaulting to "cases". Current options are: "cases" which calls
|
... |
Pass additional arguments to lower level plot functions. |
ggplot2
object
plot.fv_posterior
Functions used for forecasting across models, dates, and scenarios
forecast_across_dates()
,
forecast_across_scenarios()
,
forecast_n_strain()
,
forecast()
,
summary.fv_forecast()
,
unnest_posterior()
Plotting functions
add_forecast_dates()
,
plot.fv_posterior()
,
plot_cases()
,
plot_default()
,
plot_growth()
,
plot_pairs()
,
plot_posterior()
,
plot_rt()
,
plot_theme()
,
plot_voc_advantage()
,
plot_voc_frac()
,
save_plots()
options(mc.cores = 4) forecasts <- forecast( germany_covid19_delta_obs, forecast_date = as.Date("2021-06-12"), horizon = 4, strains = c(1, 2), adapt_delta = 0.99, max_treedepth = 15, variant_relationship = "scaled" ) # inspect forecasts forecasts # plot case posterior predictions plot(forecasts, log = TRUE) # plot case posterior predictions with central estimates plot(forecasts, log = TRUE, central = TRUE) # plot voc posterior predictions plot(forecasts, type = "voc_frac")
options(mc.cores = 4) forecasts <- forecast( germany_covid19_delta_obs, forecast_date = as.Date("2021-06-12"), horizon = 4, strains = c(1, 2), adapt_delta = 0.99, max_treedepth = 15, variant_relationship = "scaled" ) # inspect forecasts forecasts # plot case posterior predictions plot(forecasts, log = TRUE) # plot case posterior predictions with central estimates plot(forecasts, log = TRUE, central = TRUE) # plot voc posterior predictions plot(forecasts, type = "voc_frac")
plot
method for class "fv_posterior". This function wraps all
lower level plot functions.
## S3 method for class 'fv_posterior' plot( x, obs = NULL, type = "cases", forecast_dates = NULL, central = FALSE, all_obs = FALSE, voc_label = "variant of concern", ... )
## S3 method for class 'fv_posterior' plot( x, obs = NULL, type = "cases", forecast_dates = NULL, central = FALSE, all_obs = FALSE, voc_label = "variant of concern", ... )
x |
A |
obs |
A data frame of observed data as produced by |
type |
A character string indicating the type of plot required,
defaulting to "cases". Current options are: "cases" which calls
|
forecast_dates |
A data.frame in the format produced by
|
central |
Logical, defaults to FALSE. Should the mean and median
central estimates be plot as dashed and solid lines respectively. Requires
|
all_obs |
Logical, defaults to |
voc_label |
Character string giving the name to assign to the variant of concern. Defaults to "variant of concern". |
... |
Pass additional arguments to lower level plot functions. |
ggplot2
object
Functions used for postprocessing of model fits
convert_to_stanfit()
,
extract_draws()
,
extract_forecast_dates()
,
fv_extract_forecast()
,
fv_posterior()
,
fv_tidy_posterior()
,
link_dates_with_posterior()
,
link_obs_with_posterior()
,
print.fv_posterior()
,
quantiles_to_long()
,
summary.fv_posterior()
,
update_voc_label()
Plotting functions
add_forecast_dates()
,
plot.fv_forecast()
,
plot_cases()
,
plot_default()
,
plot_growth()
,
plot_pairs()
,
plot_posterior()
,
plot_rt()
,
plot_theme()
,
plot_voc_advantage()
,
plot_voc_frac()
,
save_plots()
posterior <- fv_example(strains = 2, type = "posterior") # plot cases on the log scale plot(posterior, type = "cases", log = TRUE) # plot cases with central estimates plot(posterior, type = "cases", log = FALSE, central = TRUE) # plot fraction that have the variant of concern plot(posterior, type = "voc_frac") # plot the transmission advantage for the the variant of concern plot(posterior, type = "voc_advantage") # plot the growth rates for both voc and non-voc cases plot(posterior, type = "growth") # plot the reproduction number estimates plot(posterior, type = "rt")
posterior <- fv_example(strains = 2, type = "posterior") # plot cases on the log scale plot(posterior, type = "cases", log = TRUE) # plot cases with central estimates plot(posterior, type = "cases", log = FALSE, central = TRUE) # plot fraction that have the variant of concern plot(posterior, type = "voc_frac") # plot the transmission advantage for the the variant of concern plot(posterior, type = "voc_advantage") # plot the growth rates for both voc and non-voc cases plot(posterior, type = "growth") # plot the reproduction number estimates plot(posterior, type = "rt")
print
method for class "fv_posterior". Prints the available
value types and then falls back to the data.table
print method.
## S3 method for class 'fv_posterior' print(x, ...)
## S3 method for class 'fv_posterior' print(x, ...)
x |
An output from output from |
... |
Pass additional arguments to |
A summary data.frame
fv_tidy_posterior
Functions used for postprocessing of model fits
convert_to_stanfit()
,
extract_draws()
,
extract_forecast_dates()
,
fv_extract_forecast()
,
fv_posterior()
,
fv_tidy_posterior()
,
link_dates_with_posterior()
,
link_obs_with_posterior()
,
plot.fv_posterior()
,
quantiles_to_long()
,
summary.fv_posterior()
,
update_voc_label()
posterior <- fv_example(strains = 2, type = "posterior") # case summary posterior
posterior <- fv_example(strains = 2, type = "posterior") # case summary posterior
Convert summarised quantiles from wide to long format
quantiles_to_long(posterior)
quantiles_to_long(posterior)
posterior |
A dataframe as output by |
A data frame of quantiles in long format.
Functions used for postprocessing of model fits
convert_to_stanfit()
,
extract_draws()
,
extract_forecast_dates()
,
fv_extract_forecast()
,
fv_posterior()
,
fv_tidy_posterior()
,
link_dates_with_posterior()
,
link_obs_with_posterior()
,
plot.fv_posterior()
,
print.fv_posterior()
,
summary.fv_posterior()
,
update_voc_label()
posterior <- fv_example(strains = 2, type = "posterior") long_posterior <- quantiles_to_long(posterior) long_posterior
posterior <- fv_example(strains = 2, type = "posterior") long_posterior <- quantiles_to_long(posterior) long_posterior
Sample Sequence Observation Model
sample_sequences(frac_voc, seq_total, phi)
sample_sequences(frac_voc, seq_total, phi)
frac_voc |
A numeric vector of expected proportions positive for the variant of concern. |
seq_total |
An integer vector of total sequences available. |
phi |
The overdispersion of the sampling process. If not supplied then no overdispersion is used (i.e a binomial observation model vs a beta binomial observation model). |
A vector of observed sequences positive for the variant of concern.
Functions to generate simulated data
generate_obs()
# dummy sequence data frac_voc <- seq(0, 1, by = 0.1) seq_total <- seq(10, length.out = length(frac_voc), by = 100) # binomial observation model sample_sequences(frac_voc, seq_total) # beta binomial observation model sample_sequences(frac_voc, seq_total, 0.5)
# dummy sequence data frac_voc <- seq(0, 1, by = 0.1) seq_total <- seq(10, length.out = length(frac_voc), by = 100) # binomial observation model sample_sequences(frac_voc, seq_total) # beta binomial observation model sample_sequences(frac_voc, seq_total, 0.5)
Save plots by name
save_plots(plots, save_path = NULL, type = "png", ...)
save_plots(plots, save_path = NULL, type = "png", ...)
plots |
A named list of |
save_path |
A character string indicating where to save plots if required. |
type |
A character string indicating the format to use to save plots. |
... |
Additional arguments passed to |
Plotting functions
add_forecast_dates()
,
plot.fv_forecast()
,
plot.fv_posterior()
,
plot_cases()
,
plot_default()
,
plot_growth()
,
plot_pairs()
,
plot_posterior()
,
plot_rt()
,
plot_theme()
,
plot_voc_advantage()
,
plot_voc_frac()
posterior <- fv_example(strains = 2, type = "posterior") p <- plot(posterior, type = "all") save_plots(p, save_path = tempdir())
posterior <- fv_example(strains = 2, type = "posterior") p <- plot(posterior, type = "all") save_plots(p, save_path = tempdir())
summary
method for class "fv_forecast".
## S3 method for class 'fv_forecast' summary( object, target = "posterior", type = "model", as_dt = FALSE, forecast = FALSE, ... )
## S3 method for class 'fv_forecast' summary( object, target = "posterior", type = "model", as_dt = FALSE, forecast = FALSE, ... )
object |
A |
target |
A character string indicating the target object within the
|
type |
A character string used to filter the summarised output and defaulting to "model". Current options are: "model" which returns a summary of key model parameters, "cases" which returns summarised cases, "voc_frac" which returns summarised estimates of the fraction of cases that have the variant of concern, "voc_advantage" that returns summarised estimates of the the transmission advantage of the variant of concern, "growth" which returns summarised variant specific and overall growth rates, "rt" which returns summarised variant specific and overall reproduction number estimates, "raw" which returns a raw posterior summary, and "all" which returns all tidied posterior estimates. |
as_dt |
Logical defaults to |
forecast |
Logical defaults to |
... |
Additional summary arguments. |
A summary data.table
.
summary.fv_posterior forecast unnest_posterior
Functions used for forecasting across models, dates, and scenarios
forecast_across_dates()
,
forecast_across_scenarios()
,
forecast_n_strain()
,
forecast()
,
plot.fv_forecast()
,
unnest_posterior()
options(mc.cores = 4) forecasts <- forecast( germany_covid19_delta_obs, forecast_date = as.Date("2021-06-12"), horizon = 4, strains = c(1, 2), adapt_delta = 0.99, max_treedepth = 15, variant_relationship = "scaled" ) # inspect forecasts forecasts # extract the model summary summary(forecasts, type = "model") # extract the fit object summary(forecasts, target = "fit") # extract the case forecast summary(forecasts, type = "cases", forecast = TRUE)
options(mc.cores = 4) forecasts <- forecast( germany_covid19_delta_obs, forecast_date = as.Date("2021-06-12"), horizon = 4, strains = c(1, 2), adapt_delta = 0.99, max_treedepth = 15, variant_relationship = "scaled" ) # inspect forecasts forecasts # extract the model summary summary(forecasts, type = "model") # extract the fit object summary(forecasts, target = "fit") # extract the case forecast summary(forecasts, type = "cases", forecast = TRUE)
summary
method for class "fv_tidy_posterior". Can be used to
filter the posterior for variables of interest, to return forecasts only, and
to summarise using the data.table
method
## S3 method for class 'fv_posterior' summary(object, type = "model", forecast = FALSE, as_dt = FALSE, ...)
## S3 method for class 'fv_posterior' summary(object, type = "model", forecast = FALSE, as_dt = FALSE, ...)
object |
An object of the class |
type |
A character string used to filter the summarised output and defaulting to "model". Current options are: "model" which returns a summary of key model parameters, "cases" which returns summarised cases, "voc_frac" which returns summarised estimates of the fraction of cases that have the variant of concern, "voc_advantage" that returns summarised estimates of the the transmission advantage of the variant of concern, "growth" which returns summarised variant specific and overall growth rates, "rt" which returns summarised variant specific and overall reproduction number estimates, "raw" which returns a raw posterior summary, and "all" which returns all tidied posterior estimates. |
forecast |
Logical defaults to |
as_dt |
Logical defaults to |
... |
Additional summary arguments. |
A summary data.table table unless type "all" is used in which case the output is still of type "fv_posterior".
Functions used for postprocessing of model fits
convert_to_stanfit()
,
extract_draws()
,
extract_forecast_dates()
,
fv_extract_forecast()
,
fv_posterior()
,
fv_tidy_posterior()
,
link_dates_with_posterior()
,
link_obs_with_posterior()
,
plot.fv_posterior()
,
print.fv_posterior()
,
quantiles_to_long()
,
update_voc_label()
posterior <- fv_example(strains = 2, type = "posterior") # case summary summary(posterior, type = "cases") # summary of the case summary summary(posterior, type = "cases", as_dt = TRUE) # case forecast only summary(posterior, type = "cases", forecast = TRUE) # voc fraction summary summary(posterior, type = "voc_frac") # voc advantage summary summary(posterior, type = "voc_advantage") # growth summary summary(posterior, type = "growth") # Rt summary summary(posterior, type = "rt") # model parameter summary summary(posterior, type = "model") # raw posterior values summary(posterior, type = "raw")
posterior <- fv_example(strains = 2, type = "posterior") # case summary summary(posterior, type = "cases") # summary of the case summary summary(posterior, type = "cases", as_dt = TRUE) # case forecast only summary(posterior, type = "cases", forecast = TRUE) # voc fraction summary summary(posterior, type = "voc_frac") # voc advantage summary summary(posterior, type = "voc_advantage") # growth summary summary(posterior, type = "growth") # Rt summary summary(posterior, type = "rt") # model parameter summary summary(posterior, type = "model") # raw posterior values summary(posterior, type = "raw")
Unnest posterior predictions and forecasts from output
produced by forecast()
(or multiple combined calls) dropping diagnostic
and fitting variables in the process.
unnest_posterior(forecasts, target = "posterior")
unnest_posterior(forecasts, target = "posterior")
forecasts |
A data frame of forecasts as produced by |
target |
A character string indicating the list of outputs to unnest. |
An unnested data.frame
of posterior estimates and other variables
produced by forecast()
.
Functions used for forecasting across models, dates, and scenarios
forecast_across_dates()
,
forecast_across_scenarios()
,
forecast_n_strain()
,
forecast()
,
plot.fv_forecast()
,
summary.fv_forecast()
library(data.table) options(mc.cores = 4) dt <- forecast( germany_covid19_delta_obs, forecast_date = as.Date("2021-06-12"), max_treedepth = 15, adapt_delta = 0.99 ) # unnest posterior predictions posterior <- unnest_posterior(dt) posterior # unnest forecasts forecasts <- unnest_posterior(dt, target = "forecast") forecasts
library(data.table) options(mc.cores = 4) dt <- forecast( germany_covid19_delta_obs, forecast_date = as.Date("2021-06-12"), max_treedepth = 15, adapt_delta = 0.99 ) # unnest posterior predictions posterior <- unnest_posterior(dt) posterior # unnest forecasts forecasts <- unnest_posterior(dt, target = "forecast") forecasts
Update observations based on availability
update_obs_availability(obs, cases_lag, seq_lag)
update_obs_availability(obs, cases_lag, seq_lag)
obs |
A |
cases_lag |
Number of weeks that case data takes to be reported. Defaults to not alter the input data. |
seq_lag |
Number of weeks that sequence data takes to be reported. Defaults to not alter the input data. |
A data.frame
of observations with updated case and
sequence availability dates.
Functions to define and create data scenarios
define_scenarios()
,
generate_obs_scenario()
update_obs_availability( germany_covid19_delta_obs, cases_lag = 2, seq_lag = 3 )
update_obs_availability( germany_covid19_delta_obs, cases_lag = 2, seq_lag = 3 )
Assign a custom label to the variant of concern in the
output from fv_tidy_posterior()
.
update_voc_label(posterior, label, target_label = "VOC")
update_voc_label(posterior, label, target_label = "VOC")
posterior |
A dataframe of posterior output as produced by
|
label |
Character string indicating the new label to use for the variant of concern. |
target_label |
A character string defaulting to "VOC". Indicates the current label for the variant of concern. |
A list of data frames as returned by 'fv_tidy_posterior()
but
with updated labels.
Functions used for postprocessing of model fits
convert_to_stanfit()
,
extract_draws()
,
extract_forecast_dates()
,
fv_extract_forecast()
,
fv_posterior()
,
fv_tidy_posterior()
,
link_dates_with_posterior()
,
link_obs_with_posterior()
,
plot.fv_posterior()
,
print.fv_posterior()
,
quantiles_to_long()
,
summary.fv_posterior()
p <- fv_example(strains = 2, type = "posterior") p <- update_voc_label(p, "Delta") summary(p, type = "cases") summary(p, type = "model")
p <- fv_example(strains = 2, type = "posterior") p <- update_voc_label(p, "Delta") summary(p, type = "cases") summary(p, type = "model")