1.3.1 CRAN Release

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.

New features

• Rewritten the interface for 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.
• Added support for region specific settings for all arguments that take an _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.
• Extended the functionality of the back calculation model so that Rt can be produced via calculation. These estimates are potentially less reliable than those produced using the generative model but the model can be estimated in a fraction of the time. In essence this is similar to using a back projection method and then estimating Rt using {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.
• Reduced the default maximum generation time and incubation period allowed in the truncated distribution (from 30 days to 15). This decreases the model run time substantially at a marginal accuracy cost. This new default is not suitable for longer generation times and should be modified by the user if these are used.
• Adds basic S3 plot and summary measures for epinow and estimate_infections.
• Updates the initialisation of the generative Rt model (the default) so that initial infections that occur in unobserved time (i.e before the first reported case) are generated using an exponential growth model with priors based on fitting the same model to the first week of data. This replaces the previous approach which was to use delay shifted reported cases multiplied by independent noise terms. It reduces degrees of freedom and fitting time at the cost of some model flexibility. Alternatives such as using the generative Rt model were considered but ultimately these approaches were not used as they introduced spurious variation to the gaussian process and result in unreliable Rt estimates due to the lack of historic infections.
• New 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.
• Updates the implementation of the Gaussian process to support the Matern 3/2 Kernel (and set this as the default) in addition to the squared exponential kernel. Updates the handling of Gaussian process arguments so that only overridden settings need to be passed by the user when making changes. Settings are now defined, and documented, in 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.
• Updates the over dispersion prior to be 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.
• Updates the interface for the observation model with arguments now passed using 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.
• Updates the interface to the Rt settings with all arguments passed via 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.
• Adds an adjustment for population susceptibility based on that used in {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).
• Adds 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.
• Adds estimate_delay as a user friendly wrapper around bootstrapped_dist_fit.

Other changes

• Recoded the core stan model to be functional with the aim of making the code modular and extendable.
• Added unit tests for the internal stan update_rt function.
• Reworked the package logging system to improve the reporting of issues both in epinow and in regional_epinow for large batch runs.
• Fix from @hsbadr to prevent overflow when overdispersion is larger (by switching to a Poisson approximation). Hitting this issue may indicate a bug in other model code that will need further work to explore.
• Moved default verbosity for all functions (excepting regional_epinow) to be based on whether or not usage is interactive.
• Removed the 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.
• Adds utility functions to map between mean and standard deviation and the log mean and log standard deviation for a log normal distribution (convert_to_logmean and convert_to_logsd).
• Optimised all discrete probability mass functions to be as vectorised as possible.
• Updated the Gaussian process to be internally on the unit scale.
• Added a new function, 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.
• Updates the default warmup to be 250 samples and the default adapt_delta to be 0.98.
• Adds a pooling parameter for the standard deviation of breakpoint effects.
• Updated all documentation and added {lifecycle} badges to all functions to indicate development stage.