Skip to contents

Tibble now (tbl.now)

tbl.now provides an extension of the tibble() for storing, validating, and manipulating epidemiological nowcasting data. It standardizes the representation of event dates, report dates, strata, temporal covariates, etc and in a way that is compatible with many frameworks including diseasenowcasting, epinowcast, NobBS, surveillance, EpiNow2, and more.

Specifically a tbl_now is a data structure that keeps track of the following attributes relevant for a nowcasting excercise so that all dplyr transformations (i.e. the ones from tidyverse) keep track of the relevant nowcasting variables:

  Argument What it records
event_date event_date The column storing event dates; i.e. when the epidemiological phenomenon of interest happened (symptom onset, hospitalisation, death, …). Required.
report_date report_date The column storing report dates; i.e. when that event became known to the surveillance system. Required, unless it is reconstructed from delay.
validation validation_date An optional third date indicating when the report was resolved (see validation_type). Optional.
validation validation_type What the validation date resolved to. Only confirmed, retracted, pending or NA are ever stored; use validation_levels for data recorded in other words. Optional.
validation_levels validation_levels A named dictionary translating the labels in validation_type into those four, e.g. c(confirmado = “confirmed”). Optional.
now now The date the nowcast is anchored to — “today” from the model’s point of view. Optional; defaults to the latest date.
strata strata Columns you want a separate nowcast for (e.g. gender, region). Optional.
covariates covariates Columns that inform the nowcast but that you do not want it broken down by (e.g. temperature or precipitation). Optional.
case_count case_count The column holding the counts when the data is given as aggregated (rather than line-list). Optional.
data_type data_type Whether the data represents a linelist (each row is a case), count-incidence(each row is a collection of cases per event-report date) or count-cumulative(each row is the cummulative number cases for that event accumulating in the report axis). Optional; inferred by default.
units event_units, report_units, validation_units The time grid each date lives on: days, weeks, months, years or numeric. Optional; inferred (“auto”) by default.
is_censored_report is_censored_report Flags report dates that are only an upper bound, e.g. a batch or back-fill dump. Optional.
is_censored_validation is_censored_validation The same on the validation axis: flags rows whose validation delay is a bound rather than a measurement. Optional.
temporal_effects t_effects Columns holding temporal effects (day of week, holidays, …) that some models can use. Optional.

You can specify an object as a tbl.now with the tbl_now command:

library(dplyr)
library(tbl.now)
data(denguedat)

#Here we use just a few dates for the example
denguedat <- denguedat |> 
  filter(onset_week >= as.Date("2005/01/01")) |> 
  filter(onset_week <= as.Date("2005/10/01")  & report_week <= as.Date("2005/10/01")) |> 
  tbl_now(
    report_date = report_week,
    event_date = onset_week,
    strata = gender
  )

Once transformed, it can help you diagnose data problems or modeling requirements with your database:

autoplot(denguedat)

And it can be used to run any of multiple nowcast libraries through the engine() and run_nowcast specifications. For example, baselinenowcast:

dengue_nowcast_1 <- denguedat |> 
  run_nowcast(engine = engine_baselinenowcast())
autoplot(dengue_nowcast_1)

or diseasenowcasting:

dengue_nowcast_2 <- denguedat |> 
  run_nowcast(engine = engine_diseasenowcasting())
autoplot(dengue_nowcast_2)

It can also generate ensemble nowcasts combining multiple engines or multiple realizations from the same engine:

dengue_ensemble <- nowcast_ensemble(
  baselinenowcast  = dengue_nowcast_1,
  diseasenowcasting = dengue_nowcast_2
)
autoplot(dengue_ensemble)

If this seems exciting to you, install the development version from GitHub:

# install.packages("pak") # <- uncomment if you do not have `pak`
pak::pkg_install("RodrigoZepeda/tbl.now")

and checkout our articles starting with the Introduction:

Learning more