Skip to contents

Engines for the built-in nowcasting packages

nowcast_engines.Rd

[Experimental]

One constructor per supported modelling package. Each is engine() with the arguments of that package's own entry point spelled out, so the ones that matter are visible in the signature and a typo is an error rather than a silently ignored extra.

The One dataset, many nowcasts article documents each package's own API; this page is about driving it through run_nowcast().

Usage

engine_diseasenowcasting(
  ...,
  model = NULL,
  type = NULL,
  n_draws = NULL,
  min_date = NULL,
  quantile_levels = nowcast_quantile_levels(),
  label = NULL
)

engine_baselinenowcast(
  ...,
  draws = 1000,
  delays_unit = NULL,
  max_delay = NULL,
  min_date = NULL,
  quantile_levels = nowcast_quantile_levels(),
  label = NULL
)

engine_epinowcast(
  ...,
  preprocess_args = list(),
  expectation = NULL,
  reference = NULL,
  report = NULL,
  fit = NULL,
  min_date = NULL,
  quantile_levels = nowcast_quantile_levels(),
  label = NULL
)

engine_nobbs(
  ...,
  max_D = NULL,
  moving_window = NULL,
  specs = NULL,
  min_date = NULL,
  quantile_levels = nowcast_quantile_levels(),
  label = NULL
)

engine_surveillance(
  ...,
  D = NULL,
  when = NULL,
  fit_method = NULL,
  control = NULL,
  min_date = NULL,
  quantile_levels = nowcast_quantile_levels(),
  label = NULL
)

engine_epinow2(
  ...,
  generation_time = NULL,
  delays = NULL,
  truncation = NULL,
  rt = NULL,
  stan = NULL,
  convert_args = list(),
  min_date = NULL,
  quantile_levels = nowcast_quantile_levels(),
  label = NULL
)

Arguments

...

Further arguments for the modelling function, passed through untouched. In engine() this is every argument; in the engine_*() functions it is whatever their named arguments do not already cover.

model, type, n_draws

(engine_diseasenowcasting()) Arguments of diseasenowcasting::nowcast(). model is where the epidemic and validation processes are chosen, e.g. diseasenowcasting::model(epidemic = diseasenowcasting::ar1_epidemic()). On count-cumulative data that revises downwards you also want a validation process, or the negative increments have nowhere to go.

min_date

How much history to fit on. One of

  • NULL (default) – the whole series;

  • a Date – keep event dates on or after it;

  • a single number – keep the last n periods before the object's now, counted in the object's event units.

The number is usually what you want in a nowcast_backtest(): now moves between fits, and a fixed calendar date would make the fitted window grow as the backtest walks forward, so the last fit would be trained on more data than the first. Trimming is per engine on purpose – baselinenowcast and diseasenowcasting take a long series in their stride, while epinowcast scales with the number of reference dates and is best given a window.

quantile_levels

Numeric vector of probabilities to report the nowcast at. Defaults to nowcast_quantile_levels().

It lives on the engine because for some backends it is a fit-time model argument, not a way of summarising afterwards. NobBS computes exactly the quantiles it is handed in specs$quantiles and keeps no draws, so a level it was never asked for cannot be recovered, and surveillance reports a fixed set and warns rather than interpolating. The draw-keeping backends – baselinenowcast, diseasenowcasting, epinowcast and EpiNow2 – answer any level after the fact.

label

Name for this engine in a nowcast_backtest() and in the ensemble weights derived from one. Defaults to the method name. Give one when the same package appears twice with different settings, which is the whole reason two diseasenowcasting models can be weighted separately.

draws, delays_unit, max_delay

(engine_baselinenowcast()) Number of nowcast samples, the unit of the reporting triangle's delay axis (inferred from the object's units when NULL), and how many delay periods to keep – max_delay = 10 keeps delays 0-9, as in tbl_now_to_baselinenowcast(). The last one is not only about speed: baselinenowcast needs more reference dates than delay columns, so a snapshot ("as of") series – which re-reports every past period in every snapshot, and therefore has a delay axis as long as the series itself – cannot be fitted at all until the axis is capped. The error says which number to use.

preprocess_args, expectation, reference, report, fit

(engine_epinowcast()) preprocess_args is a list for tbl_now_to_epinowcast(), e.g. list(max_delay = 30); the other four are epinowcast::epinowcast()'s module arguments. epinowcast is unseeded unless you say so: enw_fit_opts() passes ... to the sampler, so fit = epinowcast::enw_fit_opts(seed = 1) is what makes a fit reproducible.

max_D, moving_window, specs

(engine_nobbs()) Arguments of NobBS::NobBS() / NobBS::NobBS.strat(). moving_window counts event periods and must not exceed the history you hand it – ask for more and NobBS pads its grid backwards and returns zero for every date, with no error. specs$quantiles is filled from quantile_levels unless you set it.

D, when, fit_method, control

(engine_surveillance()) Arguments of surveillance::nowcast(). fit_method is that function's own method argument, renamed so it cannot collide with the engine's method. when defaults to get_surveillance_when(x, length = D + 1) and control$dRange to get_surveillance_range() – both built from the whole object, so every stratum is fitted on the same time axis.

generation_time, delays, truncation, rt, stan, convert_args

(engine_epinow2()) Arguments of EpiNow2::estimate_infections() / EpiNow2::regional_epinow(), plus convert_args for tbl_now_to_EpiNow2(). Read this before trusting the output: EpiNow2 defaults to delays = delay_opts(), which is Fixed(0) – no reporting delay at all – and a one-day generation time. Those defaults describe a process with nothing to nowcast, so supply the epidemiology yourself.

Value

A nowcast_engine, as engine() returns.

See also

engine(), run_nowcast(), nowcast_backtest()

Examples

engine_baselinenowcast(draws = 500)
#> ── <nowcast_engine: "baselinenowcast"> ─────────────────────────────────────────
#> • quantile levels: 0.025, 0.05, 0.1, 0.25, 0.5, 0.75, 0.9, 0.95, and 0.975
#> • arguments: draws
engine_nobbs(max_D = 10, moving_window = 64)
#> ── <nowcast_engine: "NobBS"> ───────────────────────────────────────────────────
#> • quantile levels: 0.025, 0.05, 0.1, 0.25, 0.5, 0.75, 0.9, 0.95, and 0.975
#> • arguments: max_D and moving_window

# Fit epinowcast on the last 180 periods only; it scales with the number of
# reference dates, while the two engines below take the whole series.
engine_epinowcast(preprocess_args = list(max_delay = 30), min_date = 180)
#> ── epinowcast model output ───────────────────────────────────────────────────── 
#> Groups:  | Timestep:  | Max delay:  
#> Observations:  timepoints x  snapshots 
#> Max date: NULL 
engine_baselinenowcast()
#> ── <nowcast_engine: "baselinenowcast"> ─────────────────────────────────────────
#> • quantile levels: 0.025, 0.05, 0.1, 0.25, 0.5, 0.75, 0.9, 0.95, and 0.975
#> • arguments: draws
engine_diseasenowcasting()
#> ── <nowcast_engine: "diseasenowcasting"> ───────────────────────────────────────
#> • quantile levels: 0.025, 0.05, 0.1, 0.25, 0.5, 0.75, 0.9, 0.95, and 0.975