NEWS.md
This release is under development and the features outlined below may change before release.
simulate_infections
so that a data.frame
of R samples can be passed in instead of a vector of R values.estimate_infections
.zero_threshold
to users allowing for control over when zeros or NAs in count data are treated as true zeros versus as reporting errors that require some smoothing.obs_opts
). This allows, for example, fitting to data with cases only reported every 3 days.contributing.md
to guide contributors and added pre-commit
support to check new contributions styling.In this release model run times have been reduced using a combination of code optimisation and testing to reduce the likelihood of long running edge cases. Model flexibility has also been increased, particularly for the back calculation approach which now supports an increased range of prior choices. A significant development in this release is the edition of the experimental estimate_secondary
model (and supporting forecast
and plot
functions). This allows a downstream target to be forecast from an observation. Example use cases include forecasting deaths from test positive cases and hospital bed usage from hospital admissions. This approach is intended to provide an alternative to models in which multiple targets are estimated jointly.
prior
, to backcalc_opts
. This allows the use of different priors for the underlying latent infections when estimating using deconvolution/back-calculation rather than the package default of using a generated Rt model (enable this option by setting rt = NULL
). The default prior remains smoothed mean delay shifted reported cases but optionally no prior can now also be used (for scenarios when the data is very untrustworthy but likely to perform extremely poorly in real time).In addition, the previously estimated infections can be used (i.e infections[t] = infections[t-1] * exp(GP)) with this being an approximate version of the generative Rt model that does not weight previous infections using the generation time.prior = "reports"
to be a partial centred moving average rather than a right aligned moving average. This choice means that increasing the prior
window does not alter the location of epidemic peaks as when using a right alighted moving average.init_fit
to stan_opts()
that enables the user to pass in a stanfit
to use to initialise a model fit in estimate_infections()
. Optionally init_fit = "cumulative"
can also be passed which first fits to cumulative data and then uses the result to initialise the full fit on incidence data. This approach is based on the approach used in epidemia authored by James Scott. Currently stan
warnings from this initial fit are broadcast to the user and may cause concern as the short run time and approximate settings often lead to poor convergence.estimate_secondary
and forecast_secondary
along with a plot
method and a new option function (secondary_opts
). These functions implement a generic model for forecasting a secondary observation (such as hospital bed usage, deaths in hospital) that entirely depends on a primary observation (such as hospital admissions) via a combination of convolving over a delay and adding/subtracting current observations. They share the same observation model and optional features used by estimate_infections
and so support data truncation, scaling (between primary and secondary observations), multiple log normal delays, a day of the week effect, and various error models. stationary_opts
allows for easy specification of the most common use cases (incidence and prevalence variables). See the documentation and examples for model details.discretised_gamma_pmf
(discretised truncated Gamma PMF) and discretised_lognormal_pmf
(discretised truncated lognormal PMF) to limit/clip the values of the parameters by prespecified lower and upper bounds.estimate_infections
by reducing all standard deviations used by a scaling factor of 0.1 in create_initial_conditions
.gt_mean
(the mean of the generation time) to reject samples with a mean greater than gt_max
(the maximum allowed generation time). Adds boundary checking to reject standard deviations that are negative. Adds a boundary check on R values to reject them if 10 times greater than the mean of the initial prior. In some scenarios this will require users to supply a prior not is not completely misspecified (i.e if the prior has a mean of 1 and the posterior has a mean of 50).update_rt
(an internal stan
function found in inst/stan/functions/rt.stan
) to be vectorised. This change reduces run times by approximately 1- ~ 20% (though only tested on a small subset of examples) and opens the way for future model extensions (such as additive rather than multiplicative random walks, and introducing covariates).This release focusses on model stability, with a functional rewrite of the model implementation, finalising the interface across the package, and introducing additional tooling. The additional tooling includes: support for adjusting for and estimating data truncation, multiple approaches for estimating Rt (including the default generative Rt approach, de-convolution coupled with Rt calculation, and EpiEstim
like estimation on observed cases but with a robust observation model), optional scaling of observed data, and optional adjustment of future forecasts based on population susceptibility. The examples have also been expanded with links out to Covid-19 specific work flows that may be of interest to users. The implementation and model options are now considered to be maturing with the next release planned to contain documentation on the underlying approach, case studies, validation, evaluation the various supported options, and tools for dealing with secondary reports that are dependent on a primary report (i.e hospital admissions and hospital bed usage). If interested in contributing to any of these features please contact the package authors or submit a PR. User contributions are warmly welcomed.
estimate_infections
to be divided into calls to _opts
functions. Options are now divided by type for delays (delay_opts
), Rt (rt_opts
), backcalculation (backcalc_opts
), the Gaussian process (gp_opts
), and stan arguments (stan_opts
). This has resulted in a larger number of the arguments from estimate_infections
being folded into the related _opts
function. Please see the function documentation and examples for details._opts
function in regional_epinow
using the helper functions opts_list
and update_list
or alternatively by constructing a named list with an entry for each region to be estimated.{EpiEstim}
(here with a default window of 1 but this can be updated using backcalc_opts(rt_window))
but this approaches incorporates uncertainty from all inputs in a single estimate.epinow
and estimate_infections
.simulate_infections
function from @sbfnk which allows the simulation of different Rt traces when combined with estimates as produced by estimate_infections
. This function is likely to form the basis for moving all forecasting out of estimate_infections
which may improve model stability.gp_opts
. The length scale is now defined using a log normal truncated prior with a mean of 21 days and a standard deviation of 7 days truncated at 3 days and the length of the data by default. This prior is an area of active research and so may change in future releases.1 / sqrt(half_normal(0, rho_prior))
based on this advice and as the over dispersion being measured is in reports and not infections and hence a priori there is not strong evidence for over dispersion (which may be the case for infections) so the previous prior was overly weighted towards this.obs_opts
. This removes week_effect
and family
from the main argument list which will allow for future extensions. Also adds a new argument scale
which controls the uncertain fraction of cases that are eventually observed (defined as normally distributed). Setting this parameter will not impact Rt estimates.rt
, using rt_opts
, this includes the initial prior,use_breakpoints
, and future
. Adds a new helper argument rw
which enables easy parameterisation of a fixed length random walk. These changes also help make it clear that these arguments only impact the Rt generative model and not the back calculation model.{epidemia}
when Rt is fixed into the future (set by passing a population to rt_opts(pop = initial susceptible population)
. Note this only impacts case forecasts and not output Rt estimates and only impacts estimates at all beyond the forecast horizon as those based on data already account for population susceptibility by definition. The impact of this assumption can be explored using simulate_infections
(by updating est$arg$pop
in the example).truncation
as a new argument to estimate_infections
and higher level functions. This takes output from trunc_opts
and allows for internally adjusting observed cases for truncation. A new method estimate_truncation
has also been added to support estimating a log normal truncation distribution from archived versions of the same data set though this method is currently experimental.estimate_delay
as a user friendly wrapper around bootstrapped_dist_fit
.epinow
and in regional_epinow
for large batch runs.regional_epinow
) to be based on whether or not usage is interactive.burn_in
argument of estimate_infections
as updates to model initialisation mean that this feature is likely no longer needed. Please contact the developers if you feel you have a use case for this argument.convert_to_logmean
and convert_to_logsd
).expose_stan_fns
that exposes the internal stan functions into R. The enables unit testing, exploration of the stan functionality and potentially within R use cases for these functions.warmup
to be 250 samples and the default adapt_delta
to be 0.98.This release introduces multiple breaking interface changes. Please see the README for examples of the new interface. It adds a range of quality of life improvements including updating the stan
interface to support fitting each chain independently and offering variational inference as an alternative, experimental, fitting option. Notably it also adds support for nesting logging and a parallel enabled progress bar via the progressr
package. Minor bugs have been fixed in the core model implementation focussing on stability and several already implemented features have been extended. Major model developments are planned for the next release of EpiNow2
.
method = "exact"
) or Variational inference (method = "approximate"
).get_dist
, get_generation_time
, get_incubation_period
based on ideas from @pearsonca. (This leads to breaking changes with the removal of covid_generation_times
and covid_incubation_periods
).setup_logging
to enable users to specify the level and location of logging (wrapping functionality from futile.logger
). Also added setup_default_logging
to give users sensible defaults and embedded this function in regional_epinow
and epinow
.setup_future
to making using nested futures easier (required when using future = TRUE
).progressr
.regional_epinow
regional_epinow
regional_runtimes
that summarises the run time across regions.estimate_infections
interface and expanded the range of options for the future_rt
argument. Users can now choose to set Rt from any time point referenced to the forecast date.plot_summary
.discretised_gamma_pmf
(discretised truncated Gamma PMF) to constrain gamma shape and (inverse) scale parameters to be positive and finite (alpha > 0
and beta > 0
).readLines
incomplete final line warnings.fit_chain
function where an interaction between rstan
and timing out may have introduced an exception that caused whole regions to fail. This did not show on current unit tests or exploration using examples indicating a gap in testing.create_stan_args
with the option to override using stan_args
. This leads to breaking changes - see the examples for details of the new interface.samples
argument to get_regional_results
to make loading in samples optional. This also allows samples to be dropped when using regional_epinow
which reduces RAM usage.global_map
and country_map
expanded by @ellispglobal_map
from @ellispregional_summary
now saves input reported cases data reported_cases.csv
.