Tapestry

influpaint v2, or maybe not too much like influpaint. Tapestry is a research project for multi-disease epidemic forecasting. In alpha, not ready, changing.

• Documenations (WIP)
• Data explorer with revisions

Environment

From the repository root:

uv sync --upgrade-package epibenchmark
uv run python -m tapestry.models --help
uv run pytest -q

uv manages the Python 3.11 .venv and Python dependencies, including EpiBenchmark from GitHub main, training, evaluation, explorer and tests. The sync command above checks for EpiBenchmark updates; uv.lock stays local. R is separate: scoring requires Rscript on PATH. After installing R, run Rscript scripts/setup_r.R to install missing scoringutils and purrr packages. See environment setup for fresh-machine R installation and lighter Python installs.

Start with the canonical training dataset

Run from the repository root:

uv sync --upgrade-package epibenchmark
# Needed only when acquiring or refreshing the two training sources:
uv run python -m tapestry.data --data-root data pull cdc_nhsn_final cdc_nssp_trajectories
uv run python -m tapestry.model_data build --data-root data \
  --output data/processed/build_b_finalized.npz
uv run python -m tapestry.model_data inspect
uv run python -m tapestry.models.season_cv --output data/experiments/my_b0_cv

The dataset contains weekly NHSN admissions and NSSP ED proportions for flu/COVID/RSV, with values and availability masks for 50 states, DC, and native US. Training reads the saved dataset; it does not need to download data or run the explorer. Use a new output directory for a new experiment. See the dataset contract and training/prediction guide.

This is finalized retrospective research: NSSP's latest saved values are assumed truth, and season CV does not recreate the observations available in real time. Raw snapshots and source hashes are retained so results can be traced to the exact inputs. Snapshots support reproducibility; publisher revision archives add historical release information where the source provides it.

B1: Wednesday snapshots and masked training

B1 uses finalized older history and recent Wednesday reports, supplying flagged reference finals where recent reports are absent. Visible known finals bypass nowcasting and its loss; hidden finals become nowcast targets again. Four future weeks are forecast from the resulting recent values. This is retrospective conditional forecasting; later finals are not claimed available on Wednesday. MLP, convolution, multiscale and spatial formulations have canonical scenario strings, with independently configurable masking rates. See the B1 implementation and commands.

Explore and compare

uv run python -m tapestry.explorer --data-root data serve

The explorer builds a disposable SQLite index and Parquet revision ledger. See explorer usage, selective acquisition, source catalog, selection policy, and storage/provenance. Broad --group all downloads are optional; they are not required to train the current six-channel model. Delphi requires an API key; Git is needed for Hubverse sources.

Saved CV forecasts can be evaluated without refitting. Hub scoring uses R scoringutils; configuration plots use the installed EpiBenchmark package. Follow hub comparison, then configuration comparison.

Where things live

Directory	Purpose
src/tapestry/data/	Acquisition, snapshots, source readers, geography, selection
src/tapestry/model_data/	Canonical dataset, windows, masks
src/tapestry/models/	Model and reusable training/CV code
src/tapestry/evaluation/	Shared scoring, hub comparison, exports and reports
src/tapestry/explorer/	index.py, server.py, cli.py, browser assets
analysis/wval/	Standalone wastewater analysis and evidence
scripts/	Small checkout launchers and CSV conversion utility
docs/workflows/	Current commands and behavior
docs/results/	Completed experiment findings
docs/design/	Research proposals
tests/	Checks that protect reported results: leakage, masks, scoring, export

Downloaded data, checkpoints, and generated results live in data/, output/, and tmp/. The experiment manager plans, runs, and scores named B0 experiments. See development and features and tests.

Tests

uv sync --upgrade-package epibenchmark
uv run pytest -q

The suite only keeps tests that protect reported results. GitHub Actions runs it on pushes and pull requests to main, with R scoringutils installed. Tests use fixtures and local temporary files; integration tests exercise R scoring and/or EpiBench and skip when Rscript is absent (run Rscript scripts/setup_r.R if Rscript exists but scoringutils does not). See what the tests do.

Files kept locally

Git excludes surveillance data, processed panels, checkpoints, generated output folders, downloaded analysis evidence, reference PDFs/extracted text, and credentials. The source catalog is src/tapestry/data/catalog.py. Download/build the data separately using the commands above. The supported dataset command is python -m tapestry.model_data build.