PaFAR

Code and reproducibility materials for PaFAR: Finite-Sample Patient-Level False-Alarm Calibration for Repeated Risk Monitoring by Zhuowei Gao and Weipeng Sun, School of Mathematics, Jilin University.

Overview

PaFAR calibrates repeated risk monitoring at the level of a complete monitoring episode. Each eligible non-event calibration trajectory contributes one maximum score, and a finite-sample corrected order statistic determines the alert threshold.

PaFAR is a calibration layer applied to frozen score trajectories. The F rule uses established conformal/order-statistic calibration; the HC rule uses a one-sided tolerance-limit/NP binomial-tail construction. The code evaluates episode-level false-alert risk together with timely first detection and repeated-alert workload.

Installation

PaFAR requires Python 3.12 or later.

git clone https://github.com/gaozw23/PaFAR.git
cd PaFAR
git checkout manuscript-code-v2
python -m venv .venv

Activate the environment with source .venv/bin/activate (Linux/macOS) or .venv\Scripts\Activate.ps1 (PowerShell), then install:

python -m pip install --upgrade pip
python -m pip install -e ".[test]"

Data

The retrospective analysis uses version 1.0.0 of the public training data from the PhysioNet/Computing in Cardiology Challenge 2019 (DOI: 10.13026/v64v-d857). Raw clinical records are not distributed with this repository. See data/README.md for the expected local layout.

Reproducing the paper

See docs/REPRODUCIBILITY.md for configuration details, data layout, computational requirements, and the calibration rules used in the analyses.

Simulations

The primary simulations use the configurations under configs/:

python paper_repro/run_simulation.py --experiment exp1 --resume --confirm RUN_PAFAR_PRIMARY_SIMULATION
python paper_repro/run_simulation.py --experiment exp2 --resume --confirm RUN_PAFAR_PRIMARY_SIMULATION

Retrospective analysis

After placing the PhysioNet files in the documented locations, check the inputs and run the analysis with:

python paper_repro/run_realdata.py --check-only
python paper_repro/run_realdata.py --stage all --n-jobs 4 --resume --confirm RUN_PAFAR_REALDATA_PRIMARY

Tables and figures

Saved simulation and retrospective-analysis summaries are required to generate the manuscript tables and figures:

python paper_repro/build_paper_outputs.py --component all --check-only
python paper_repro/build_paper_outputs.py --component all --confirm BUILD_PAFAR_PAPER_OUTPUTS

The saved summaries and generated artifacts are not distributed with the repository. Additional entry-point information is available in paper_repro/README.md.

Code version

Use the manuscript-code-v2 tag for the revised manuscript. This version includes the corrected temporal availability rules, first-observation support and real-data reproduction workflow, while retaining the primary synthetic calibration algorithms.

Commit c4a50d8b303a3d9994d8c9355724e5388f6ef613 identifies the historical implementation cited in the original submission. Its real-data outputs precede these corrections and must not be combined with the revised estimates. See the reproducibility guide for the current commands and evidence definitions.

Tests

python -m pytest -q

The tests use synthetic fixtures to check calibration, strict alerting, patient-level splitting, causal feature construction and output formatting. They do not require raw clinical records, trained models, production simulation checkpoints or manuscript PDFs.

Citation

If you use this software, please cite the accompanying manuscript:

Gao, Z. and Sun, W. PaFAR: Finite-Sample Patient-Level False-Alarm Calibration for Repeated Risk Monitoring. Publication details will be updated after publication.

License

The source code in this repository is released under the MIT License.