Quantile Regression Flu Hospitalization Forecast (South Carolina)

Overview

This repository is built around a human-AI teaming workflow for forecast validation. The modeler contributes domain knowledge and a priori epidemiological assumptions, while an LLM agent translates those assumptions into concrete, runnable unit tests. The human owns the epidemiological judgment; the agent handles the repetitive work of encoding that judgment as test code, generating fixtures, and documenting the reasoning behind each assertion. The result is a forecast that is checked for both technical correctness and epidemiological plausibility before submission, with the human modeler always retaining final review and authority.

The test model is a quantile regression–based forecasting approach for weekly influenza hospital admissions in South Carolina (CDC location = 45).

The workflow integrates:

• CDC FluSight hospitalization targets
• Weekly EHR influenza indicators from Health System 1
• Log-scale multi-quantile regression
• A stability-aware recursive forecasting strategy with explicit safety valves

The primary output is a CDC-compliant quantile forecast submission file, along with a diagnostic visualization for internal review.

---

Dependencies

R Packages

• dplyr
• lubridate
• ggplot2
• purrr
• readr
• quantreg
• tidyr

---

Folder Contents

• QR.r
  Main quantile regression forecasting script. Handles data ingestion, feature engineering, model fitting, recursive forecasting, and submission file generation.

• target-hospital-admissions.csv
  CDC FluSight weekly influenza hospitalization target data.

• Health_System_1_Health_Weekly_Influenza_State_dx_cond_lab_Incident.csv
  State-level Health System 1 weekly influenza EHR indicators.

• test_forecast_metrics.R and test_model_output.R Agent-generated test scripts that encode the modeler's epidemiological rules as unit tests and run them against actual model output to validate the forecast.

---

Input Data

CDC Flu Hospitalization Target

• File: target-hospital-admissions.csv
• Source: CDC FluSight
• Filtering: location == "45" (South Carolina)
• Temporal unit: Weekly (CDC-defined epidemiological weeks, aligned to the CDC-provided week-ending date; operationally Sunday–Saturday)

Expected Format

Column	Type	Description
date	Date	CDC week-ending date of observation
location	Character	CDC location code (FIPS)
location_name	Character	Location name
value	Numeric	Total weekly influenza inpatient hospital admissions
weekly_rate	Numeric	Weekly influenza inpatient hospitalization rate

Processing Notes

• The value column is renamed at ingest to
  Total.Influenza.Admissions.
• Total.Influenza.Admissions is treated as the authoritative target outcome for model training and forecasting.
• All forecasts are generated on the same weekly index as the CDC target file to ensure FluSight compliance.

---

Health System 1 Data Sources

• File: Health_System_1_Health_Weekly_Influenza_State_dx_cond_lab_Incident.csv
• Temporal unit: Weekly (reindexed to align with CDC week-ending dates)

Expected Format

Column	Type	Description
State	Character	Spatial-scale indicator (SC)
Week	Date	Week-ending date of observation
Weekly_Inpatient_Hospitalizations	Numeric	Weekly influenza inpatient hospital admissions
Weekly_Tests	Numeric	Weekly influenza tests conducted
Weekly_Positive_Tests	Numeric	Weekly positive influenza tests

• Health System 1 data are treated as auxiliary predictors and are aligned to the CDC weekly calendar prior to model fitting.

---

Operational Data (Internal, derived during processing)

Column	Type	Description
week	Date	CDC week-ending date of observation
cdc_Total.Influenza.Admissions	Numeric	Total weekly influenza inpatient hospital admissions (CDC FluSight target outcome)
HS1_Weekly_Inpatient_Hospitalizations	Numeric	Weekly influenza inpatient hospital admissions (Health System 1)
HS1_Weekly_Tests	Numeric	Weekly influenza tests conducted (Health System 1)
HS1_Weekly_Positive_Tests	Numeric	Weekly positive influenza tests (Health System 1)

• CDC-derived fields are treated as the authoritative target outcome for model training and forecasting.
• Health System 1-derived fields are treated as authoritative auxiliary predictors and are aligned to the CDC weekly calendar prior to model fitting.

---

Feature Engineering

Features are constructed to capture:

• Magnitude (log-transformed levels)
• Momentum (first and second differences)
• Autoregression (lagged log target)
• Seasonality and calendar effects
  • Month
  • Week-of-month proxy
  • School break indicator
  • Christmas and New Year indicators

Original (non-log) EHR values are retained to support trend-based updates during forecasting.

---

Model Specification

• Model type: Linear Quantile Regression (quantreg::rq)
• Response variable:
  log(Total.Influenza.Admissions + 1)
• Quantiles:
  0.01, 0.025, 0.05, 0.1, 0.15, 0.2, 0.25, 0.3, 0.35, 0.4, 0.45, 0.5, 0.55, 0.6, 0.65, 0.7, 0.75, 0.8, 0.85, 0.9, 0.95, 0.975, 0.99 (23 quantiles)
• Training window:
  September 01, 2022 – most recent fully observed week available at run time

The model is fit once and reused for all forecast horizons.

---

EHR Trend Estimation

Short-term trends are estimated using:

• The four most recent observed weeks
• Exponentially decaying weights
• Weighted average week-to-week changes in:
  • Tests
  • Positive tests
  • Hospitalizations

These trends guide recursive updates rather than direct extrapolation.

---

Recursive Forecasting Logic

Forecasts are generated for:

• Nowcast (0-week)
• 1-week ahead
• 2-weeks ahead
• 3-weeks ahead

Stability Controls

Damping

• Progressive reduction in momentum across horizons to prevent runaway forecasts.

Safety Valve

• If recent EHR hospitalizations are increasing, damping is set to 1.0 (no damping)

Directional Thresholding

• Positive momentum is only allowed when weighted EHR trends are positive.
• Growth is clipped during declines to avoid artificial rebounds.

---

Uncertainty Management

To control excessive upper tails:

• Upper quantiles are progressively squeezed toward the median.
• Squeezing is disabled when EHR trends indicate active growth.
• Final predictions are:
  • Floored at zero
  • Maximum forecast value is capped at 120% of the observed maximum in the test period (Oct 2025+).

---

Post-Processing

Quantile Monotonicity

Quantile ordering is enforced using isotonic regression to ensure:

• Strictly increasing quantiles within each forecast horizon

---

Forecast Output (CDC Submission)

Each row represents a single quantile forecast.

Column	Type	Description
reference_date	Date	Forecast issue date
target	Character	wk inc flu hosp
horizon	Integer	0–3 weeks
location	Character	CDC location code ("45")
target_end_date	Date	End date of forecast week
output_type	Character	Always quantile
output_type_id	Numeric	Quantile level
value	Integer	Predicted weekly admissions

Constraints

• value ≥ 0
• Quantiles must be monotonic within horizon
• Must conform to CDC FluSight specifications