Fit a nowcast model to censored reporting data

The main entry point. Takes a tbl_now (from the tbl.now package) and a model(), fits the latent-epidemic + reporting-delay model as of a given date, and returns the common tbl.now::tbl_nowcast result. Predictive draws and quantiles are materialised in that result; the untouched native fit is retained in @fit for predict(), mean()/median()/quantile(), coef(), and model-specific diagnostics.

Usage

nowcast(
  data,
  model = diseasenowcasting::model(),
  type = c("two_stage", "one_stage", "auto"),
  now = NULL,
  K = 25L,
  n_draws = 2000L,
  delay_window = 120L,
  np_spread = 1,
  floor_mu = 0.08,
  floor_sig_frac = 0.08,
  temporal_effects = "auto",
  prior_only = FALSE,
  quantile_levels = tbl.now::nowcast_quantile_levels(),
  seed = sample.int(.Machine$integer.max, 1),
  ...
)

Arguments

data: A tbl_now object (tbl.now::tbl_now()).
model: A model() object. Default: model() (NB + HSGP + Dirichlet).
type: "two_stage" (default; reporting-delay imputation pooling), "one_stage" (a single joint fit), or "auto" (per reporting-delay family: Dirichlet one-stage, all other delays two-stage – the better choice for each in our experiments).
now: As-of date; only events/reports up to now are used. Default: tbl.now::get_now(data), falling back to the latest report date.
K: Number of delay imputations for the two-stage path.
n_draws: Default number of posterior draws used by predict() and the latent-incidence summaries.
delay_window: Recent window length for the parametric Stage-1 delay fit.
np_spread: Dirichlet simplex imputation covariance inflation (default 1).
floor_mu, floor_sig_frac: Imputation-spread floors (parametric families).
temporal_effects: Controls automatic seasonal / day-of-week covariates. "auto" (default) adds sensible effects based on the data's time unit (weekly -> 52-period seasonality; daily -> day-of-week + 52-period seasonality; monthly -> 12-period seasonality) only if the tbl_now does not already carry computed temporal effects. Use "none" (or "None") to disable, or pre-attach your own effects to the tbl_now with tbl.now::add_temporal_effects() + tbl.now::compute_temporal_effects().
prior_only: If TRUE, ignore the likelihood and draw the epidemic parameters from their priors only, returning the prior-predictive latent incidence. Useful for understanding what a prior implies before seeing data (e.g. how the SIR R0 prior or the AR(1) phi prior reshapes the epidemic). The result uses the same common grammar as an ordinary fit, so predict() / autoplot() / median() / quantile() all work; data only supplies the time grid. Default FALSE.
quantile_levels: Probabilities at which to summarise the predictive draws in the returned tbl.now::tbl_nowcast.
seed: Optional RNG seed (imputation draws).
...: Passed to prepare_data() (e.g. gp_boundary_frac).

Value

A diseasenowcasting subclass of tbl.now::tbl_nowcast. The native fitted model is retained in @fit; diseasenowcasting operations unwrap it automatically. The @fit_diagnostics property (also available at @metadata$diseasenowcasting$fit_diagnostics) records the resolved fitting stage, imputation retention, optimizer adequacy, curvature, and any Laplace-precision regularization used for prediction.

Revision processes

A revision process – reports that are later confirmed or retracted – is a row-level mechanism for linelist and count-incidence data. It is detected from the data, not requested by an argument. nowcast() attaches one when the tbl_now carries revision_date / revision_type (see tbl.now::add_revision_date()). The mode (confirmation_only / retraction_only / both) is read from unique(revision_type) over the full data, so it is stable across as-of dates. Configure p and the lag with model(revision = revision_process(...)), which always wins over the detected default; assert the mode with revision_process(mode = ). Revision-date censoring is likewise data metadata: set is_censored_revision when constructing the tbl_now. There is no nowcast() column-name argument for it. Count-cumulative revisions instead use cumulative_process() and do not estimate a separate revision probability p.

One-stage and two-stage revision

With type = "one_stage", the epidemic process, event-to-report delay, report-to-revision delay, and revision probability p are estimated in one joint objective. With type = "two_stage", Stage 1 estimates the event-to-report delay and draws K imputations from its Laplace approximation. Each Stage-2 fit conditions on one imputed reporting-delay distribution and jointly estimates the epidemic process, revision delay, and p. Posterior draws within a Stage-2 fit propagate revision uncertainty; pooling across the fits additionally propagates reporting-delay uncertainty. This is the same stepwise boundary used by the original event-to-report model: two_stage separates the reporting process from the downstream model, while the revision block remains downstream of a report.

Overdispersion (`phi`)

The negative-binomial overdispersion prior is not an argument of nowcast(). Set it on the likelihood instead, e.g. model(nb_likelihood(phi = lognormal_prior(log(5), 0.5)), ...). The default nb_likelihood() already uses lognormal_prior(log(20), 0.5).

Examples

if (requireNamespace("tbl.now", quietly = TRUE)) {
  # data <- tbl.now::tbl_now(my_linelist, event_date = onset, report_date = reported)
  # nc <- nowcast(data, model(nb_likelihood(), hsgp_epidemic(), lognormal_delay()))
  # predict(nc); median(nc); coef(nc)
}
#> NULL