ailab · v0.3.0

One swallow does not make a summer.

ailab is an open-source time-series engine for infectious-disease surveillance. Every forecast has to beat a seasonal baseline in a rolling backtest; if it can’t, the quality gate tells you why it won’t forecast.

Run a forecast View on GitHub

Static showcase · nothing runs live

Service: checking…

One engine, three ways to use it

Python library

Series store, derived series, forecasts, quality gate and alert signals as plain functions. Missing is NULL, never 0.

CLI & offline batch

ailab demo / forecast / gate / alert / export: run it on a schedule in CI and publish static JSON and Parquet.

Docker API

FastAPI with embedded DuckDB, no Postgres or Redis. Non-root, read-only root filesystem; read-only until you set a key.

From a weekly series to a trustworthy signal

Every series goes through the same four steps. Each step leaves a conclusion and its reasons, so you can check them one by one.

Tidy the data

Lined up by week, one value per week. A missing week stays missing and is never filled with 0, so “not reported” is never read as “no cases”.
Quality gate

A check-up before any forecast: is the history long enough, how much is missing, is there a seasonal pattern, and would forecasts made in the past have been accurate? The answer is one of three — forecast, forecast with limits, or no forecast — always with the reasons.
Forecast

A few common methods are compared with a simple rule (copy the same week last year), and the one with the smallest error in the trial runs is used; if none beats the simple rule, there is no forecast. Besides the line, you get the range the real value will most likely fall in.
Unusual weeks

Flags weeks that are clearly higher than usual. It only means “statistically unusual”; whether it is an outbreak is for people to decide.

Methods: off-the-shelf vs custom

Mature libraries wherever they exist; custom code only for the decision logic no library covers.

Need	Off the shelf	Custom (and why)
Forecast models	statsforecast: SeasonalNaive, Naive, MSTL+ETS, AutoTheta, cross-validation	None.
Prediction intervals	numpy quantiles	About 30 lines of split-conformal-style code: reuses the existing backtest errors (no extra refits), per horizon, in transformed space, with leave-one-window-out coverage.
Quality gate	statsmodels (STL, ADF/KPSS, HAC), scipy (Levene)	Thresholds, the allowed / limited / refused decision logic, reason codes and en/zh/fr messages. No tool answers “should this series be forecast at all?”.
Alerts	statsmodels GLM	EARS C1–C3 and CUSUM are a few dozen lines of formulas; R’s surveillance package would need an R runtime, so the Farrington-style score is a small wrapper over the GLM.
Derived series	simpleeval, pandas	AST whitelist, kind inference (count / count → proportion), missing-value semantics (x/0 is missing) and lineage; no eval.
Storage, API, CLI	DuckDB, Parquet, FastAPI, pydantic, uvicorn, Typer	Thin middleware (request id, body-size limit); no default key: read-only unless you set one.

Basis and limits

Claim	Implementation / test evidence	Limits
A forecast must beat the seasonal-naive baseline in a rolling backtest	docs/MODEL_POLICY.md#decision-order-first-match-wins tests/test_forecast_policy.py tests/test_gate.py	A backtest describes past seasons only; re-evaluate after structural breaks.
Too little history or too many gaps → refused, with reason codes	docs/MODEL_POLICY.md#reason-codes tests/test_gate.py	Thresholds are configurable defaults; a refusal means “this data can’t support a forecast”, not that the series is useless.
Missing stays missing, never 0	docs/SERIES_KINDS.md tests/test_alignment.py tests/test_derive_kinds.py	Gaps of ≤ 2 weeks are interpolated for the model only, and disclosed in model_input.
“Limited” is separate from “refused”: shorter horizon, wider intervals	docs/MODEL_POLICY.md#limited-mode tests/test_gate.py	The widening factor is a heuristic, not a calibration guarantee.

Quick start

The image is published on GHCR; or install with pip / uv and use the CLI directly.

Docker (read-only, localhost)

docker run --rm -p 127.0.0.1:8000:8000 ghcr.io/cnalks/ailab:v0.3.0
# http://127.0.0.1:8000/docs  ·  /health

Python & CLI

pip install "git+https://github.com/CNalks/ailab@v0.3.0"   # Python 3.12
ailab demo --out out                  # offline batch: static JSON + Parquet
ailab gate us_ilinet_wili --lang en   # allowed / limited / refused + reasons
ailab forecast us_ilinet_wili --h 8

Call the API

curl -s http://127.0.0.1:8000/api/v1/series/us_ilinet_wili/gate
curl -s "http://127.0.0.1:8000/api/v1/series/us_ilinet_wili/forecast?horizon=8"

The container is read-only by default (writes answer 403 until AILAB_API_KEY is set). Put your own reverse proxy and rate limit in front before exposing it.

Documentation

Licences & data sources

Code

Data

Data are not covered by the code licence; each source’s own terms apply. Original values are unchanged; forecasts, verdicts and alerts are our own derivative analysis and are labelled as such.

CDC FluView / ILINet (national, weekly), via Delphi Epidata

US Centers for Disease Control and Prevention (CDC); API by Carnegie Mellon University Delphi Research Group

Licence: Public domain (US Government work); Delphi API documentation states 'Public Domain US Government'
Attribution (verbatim, as required by the provider): Source: US CDC FluView (ILINet), retrieved through the Delphi Epidata API (Carnegie Mellon University).
Notice: Forecasts and alerts shown here are our own statistical analysis of public data. They are not CDC/HHS products, are not endorsed by CDC/HHS, and are not public-health advice. The original data are available free of charge from CDC.
Series used: US national weighted ILI (wILI, %) · US national ILI outpatient visits

UKHSA data dashboard: influenza testing positivity by week (England)

UK Health Security Agency (UKHSA)

Licence: Open Government Licence v3.0 (dashboard footer: 'All content is available under the Open Government Licence v3.0, except where otherwise stated'; (c) Crown copyright)
Attribution (verbatim, as required by the provider): Contains public sector information published by the UK Health Security Agency (UKHSA) and licensed under the Open Government Licence v3.0.
Notice: Forecasts and alerts shown here are our own statistical analysis of public data. They are not UKHSA products, are not endorsed by UKHSA and are not public-health advice.
Series used: England: influenza test positivity (%)

ECDC ERVISS: primary-care sentinel respiratory virus data (weekly), Respiratory_viruses_weekly_data

European Centre for Disease Prevention and Control (ECDC), based on data from reporting countries and/or WHO

Licence: ECDC copyright page: ECDC-owned content is CC BY 4.0 (credit ECDC, link the licence, indicate modifications); third-party data from reporting countries may be reused if the dataset-provided-by-ECDC sentence is given
Attribution (verbatim, as required by the provider): Dataset provided by ECDC based on data provided by public health authorities, scientific institutes or health care providers in the relevant reporting countries and/or by WHO. Weekly values are unchanged; analysis added by us.
Notice: Forecasts, quality gates and alerts shown here are our own statistical analysis (modified/derived material). They are not ECDC products and are not endorsed by ECDC.
Series used: EU/EEA influenza positivity, sentinel (%) · Malta: influenza detections, sentinel