Skip to contents

Tibble now (tbl.now)

tbl.now extends tibble() for storing, validating, and manipulating epidemiological nowcasting data. It standardizes event dates, report dates, strata, temporal covariates, and related metadata in a shape compatible with many frameworks, including diseasenowcasting, epinowcast, NobBS, surveillance, EpiNow2, and more. Finally, it also standardizes the prediction engines and their results for plotting, scoring, comparing, and ensembling models.

A tbl_now keeps track of the attributes needed for a nowcasting exercise, so dplyr transformations preserve 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.
revision revision_date An optional third date indicating when the report was resolved (see revision_type). Optional.
revision revision_type, revision_levels What the revision date resolved to. Only confirmed, retracted, pending or NA are ever stored; set revision_levels as a named dictionary mapping the data’s labels into those four ( e.g. c(positive = “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, revision_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,is_censored_revision Flags dates from either the report or the revision axis that are only an upper bound, i.e. the true report happened before the date given in the database. 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"),
         report_week <= as.Date("2005/10/01")) 

#And we specify as a tbl_now:
denguedat <- denguedat |> 
  tbl_now(
    report_date = report_week,
    event_date = onset_week,
    strata = gender
  ) 

#Which is just a tibble with extra attributes
denguedat
#> # A tibble:  1,652 × 6
#> # Data type: "linelist"
#> # Frequency: Event: `weeks` | Report: `weeks`
#>   onset_week   report_week   gender   .event_num .report_num .delay
#>   <date>       <date>        <chr>         <dbl>       <dbl>  <dbl>
#>   [event_date] [report_date] [strata]      [...]       [...]  [...]
#> 1 2005-01-03   2005-01-17    Male              0           2      2
#> 2 2005-01-03   2005-01-10    Female            0           1      1
#> 3 2005-01-03   2005-01-10    Female            0           1      1
#> 4 2005-01-03   2005-01-10    Male              0           1      1
#> 5 2005-01-03   2005-01-10    Male              0           1      1
#> # ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
#> # Now: 2005-09-26 | Event date: "onset_week" | Report date: "report_week"
#> # Strata: "gender"
#> # ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
#> # ℹ 1,647 more rows

Once transformed, it can help you diagnose data problems (see this article) 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 (see this article). 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 as you can see in this article:

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

If this seems as exciting to you as it is to us, install the development version from R universe:

install.packages("tbl.now", repos = c("https://rodrigozepeda.r-universe.dev", getOption("repos")))

and checkout our articles starting with the Get started guide:

If you have any questions or comments regarding the contents of this article please open an issue on Github.

Learning more