## ----setup, include=FALSE-----------------------------------------------------
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", warning = FALSE, message = FALSE)
library(mudnester)

## ----data---------------------------------------------------------------------
set.seed(42)
n <- 120
df <- data.frame(
  onset_date = as.Date("2024-01-01") + sample(0:364, n, replace = TRUE),
  age        = sample(0:90, n, replace = TRUE),
  pathogen   = sample(c("COVID-19","Influenza A","RSV"), n, TRUE,
                       prob = c(0.45, 0.35, 0.20)),
  icu_flag   = sample(0:1, n, TRUE, prob = c(0.9, 0.1)),
  stringsAsFactors = FALSE
)
df <- preening(df, age_col = "age", scheme = "flucan_sentinel")

## ----time-units-table, echo=FALSE---------------------------------------------
knitr::kable(
  data.frame(
    `time_unit` = c("day","isoweek","fortnight","month","biannual",
                     "quarter","year","epiweek","season","season_year"),
    `Output column type` = c("Date","Date (Monday of week)","Date (first day of fortnight)",
                              "Date (1st of month)","Date (Jan 1 or Jul 1)",
                              "Date (1st of quarter)","Date (Jan 1)","Integer (1–53)",
                              "Character","Character"),
    `Notes` = c("One row per calendar day","ISO 8601 week","14-day intervals from first date",
                 "","H1 = Jan–Jun, H2 = Jul–Dec",
                 "","","Also produces epiyear column",
                 "Hemisphere-aware","Hemisphere-aware; e.g. 'Winter 2024'")
  ),
  col.names = c("time_unit", "Output type", "Notes")
)

## ----monthly------------------------------------------------------------------
monthly <- roost(
  df,
  date_col   = "onset_date",
  time_unit  = "month",
  group_cols = "pathogen"
)
monthly

## ----epiweek------------------------------------------------------------------
epi <- roost(df, date_col = "onset_date", time_unit = "epiweek")
head(epi, 6)

## ----season-------------------------------------------------------------------
seasonal <- roost(df, date_col = "onset_date", time_unit = "season_year")
seasonal

## ----biannual-----------------------------------------------------------------
bi <- roost(df, date_col = "onset_date", time_unit = "biannual")
bi

## ----events-------------------------------------------------------------------
hosp_counts <- roost(
  df,
  date_col   = "onset_date",
  time_unit  = "month",
  event_cols = "icu_flag",
  group_cols = "pathogen"
)
head(hosp_counts)

## ----preening-roost-----------------------------------------------------------
age_monthly <- roost(
  df,
  date_col   = "onset_date",
  time_unit  = "month",
  group_cols = c("age_group", "pathogen")
)
head(age_monthly)

## ----roost-tbl----------------------------------------------------------------
monthly_simple <- roost(df, date_col = "onset_date", time_unit = "month")
monthly_simple   # print.roost_tbl shows the roost_meta footer

## ----roost-meta---------------------------------------------------------------
sub <- monthly_simple[monthly_simple$n > 5, ]
attr(sub, "roost_meta")$time_unit

## ----zero-fill-demo-----------------------------------------------------------
# Even for a sparse dataset with genuine zero-count periods, every period appears
sparse <- data.frame(onset_date = as.Date(c("2024-01-15","2024-04-20","2024-11-01")))
roost(sparse, date_col = "onset_date", time_unit = "month")