Reference implementation plus a fixed-seed evaluation script that let a reader re-derive the paper's central safety property: under the monotonic-escalation rule, a deteriorating patient is never silently down-classified.
Bedside risk monitoring still leans on stateless early-warning scores. Each new measurement is judged on its own, so a brief dip after a critical reading can quietly reset the patient to a lower acuity. When the next deterioration falls between observations, the earlier crisis has already been forgotten. Probabilistic models raise sensitivity but inherit the same blind spot: they emit a fresh estimate per step without any memory of how the patient's state has moved.
DRAS-5 sits between an upstream risk source and the clinical workflow as a five-state supervisor. It does not try to be a better classifier; it constrains the output sequence of whatever score feeds it. Five invariants are checked on every transition — monotonic escalation (C1), timeout-driven auto-escalation (C2), an append-only audit trail (C3), a human approval gate for the highest tier (C4), and a decay-gated, dual-approval de-escalation protocol (C5). Each runs in constant time per update.
This repository is the artifact behind those claims. It holds the package source, a deterministic driver pinned to seed 42, the committed metric tables it writes, and the figure generators. The point is verifiability: a reader can install the package, run one script, and confirm the headline number for themselves rather than take it on trust.
All figures below come from python scripts/run_all.py at seed 42 on the synthetic cohort (5,000 trajectories, 100 steps each, 500,000 evaluations). They are properties of this generated cohort and its observation model, not clinical validation.
- Reach form of the missed-escalation rate (MER_reach) is 0% for DRAS-5 on every trajectory family, relative to the scores it receives. This is a structural consequence of C1, not a statistical estimate, and a running maximum shares it. It does not repair an upstream model that under-reports risk (see
results/revision_biased_upstream.csv), and the end-of-episode form (MER_end) is 20.5% for full DRAS-5 because C5 lowers a state after a verified recovery (results/revision_like_for_like.csv). - Stateless baselines miss a large share of escalations under intermittent sampling. In this run the modelled NEWS2 scorer records 74.2% overall and MEWS 75.6%; graded under-recognition is 64.8% and 67.0% respectively. These seed-42 values are the values reported in the current manuscript.
- C5 grants 1,250 safe single-step de-escalations on the released parameter regime. Of 115,757 requests, 67,100 are denied for an incomplete cooling window and 47,407 for unsustained decay; zero grants are premature.
- Over-escalation is 69.7% with and without C5. The valid grants remain above the instantaneous recovered true level, so they do not change the binary over-escalation indicator on this cohort.
- Per-update cost stays well under the 1 ms target. The committed run records 0.0701 ms mean latency (14,267 updates/s) over 50,000 operations. Timing is wall-clock and machine-dependent; reruns should be interpreted against the sub-millisecond target rather than as exact portable timing.
- Recoverable filters that need no state machine (hysteresis, timed-release max-hold, decayed max) end episodes with less excess (1.40-1.65 vs 2.06 levels) and less over-escalation (42.9-58.0% vs 69.7%) than DRAS-5, with no premature step-down on this cohort (
scripts/recoverable_baselines.py). - Without the C2 timeout, DRAS-5's over-escalation is 58.69%, equal to max-hold: the timeout causes the whole gap. The same timeout is what reduces unreported true peaks under hourly charting (8.56% -> 2.44%,
scripts/ward_timing.py) and behind an under-reporting vital-sign predictor (23.9% -> 2.0%,scripts/ml_wrapper_v2.py). - All 1,250 C5 grants are S4 -> S3 steps, one per spike-to-critical trajectory.
python scripts/run_tlc.pyregenerates the TLC outputs; eight mutants are rejected.- Result keys follow the paper:
mer_reach_*(never reached the sustained peak) andmer_end_*(final level below it).under_recognition_overall_pctinsummary.jsonis the fraction of the post-peak window a stateless score sits below the sustained peak; it is a diagnostic and is not reported in the paper.
- Install from the clone. If another copy of
dras5is installed (for example an editable install of a different working tree), the scripts may import it instead of this clone. Runpip install -e .inside the clone, or prefix every command withPYTHONPATH=src(PowerShell:$env:PYTHONPATH="src"). scripts/tradeoff_frontier.py(about 5 min) sweeps a threshold shift for every baseline and aT_maxfactor for DRAS-5 at the ward and predictor settings. At matched or lower over-escalation, a stateless scorer with every threshold lowered by 0.1 misses as few or fewer true peaks than DRAS-5 (ward hourly: 2.22% at OER 46.1% vs 2.44% at 59.5%; vital-sign predictor: 0.0% at 46.7% vs 2.0% at 77.7%). The C2 reach gain is a point on the reach/over-escalation trade-off, not a gain at matched burden (results/tradeoff_frontier.csv,results/tradeoff_matched.csv).- Two-hour episodes (
results/long_episodes.csv): DRAS-5 still makes only the 1,250 S4 -> S3 steps; the recoverable filters' advantage in end excess grows (paired difference +0.53 levels). - Premature step-downs against the noise-free trajectory (
results/premature_noisefree.csv): decayed max 1,221 of 8,892 step-downs (13.7%), timed release 10, hysteresis 0, DRAS-5 0. scripts/ward_timing.pynow also runs decayed max at ward rates and reports C2 timeouts per patient-day.
src/dras5/ package: state machine, constraints, decay, simulator, audit, CLI
scripts/ run_all.py (seed-42 driver) and generate_figures.py
results/ committed metric tables and summary.json written by run_all.py
figures/ publication figures (.png/.pdf) and FIGURE_MANIFEST.csv inventory
tests/ unit and behaviour checks for each constraint
notebooks/ worked examples of the state machine and governance workflow
data/, models/ placeholders (no external dataset is required)
git clone https://github.com/ChatchaiTritham/DRAS-5.git
cd DRAS-5
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .python scripts/run_all.py # fixed seed 42; a few minutes on a standard workstation
python scripts/generate_figures.py # redraws the data figures from results/*.csvrun_all.py writes the metric tables in results/ (mer_by_type.csv, oer_by_type.csv, c5_outcomes.csv, ml_wrapper.csv, latency.csv) and summary.json. Per-trajectory seeds derive from a stable type index, independent of PYTHONHASHSEED, so cohort counts and safety metrics are deterministic. Wall-clock latency is machine-dependent, and GBT RMSE may vary in the fourth decimal place across numerical-library versions; the manuscript therefore reports RMSE to three decimal places.
The current manuscript tables are reconciled to the committed seed-42 outputs: baseline missed-escalation is 74.2% for NEWS2 and 75.6% for MEWS, DRAS-5 missed escalation is 0%, and C5 grants 1,250 of 115,757 requests with zero premature de-escalations. REPRODUCIBILITY.md records the exact commands, artifacts, and scope of each reproducible claim. Over-escalation magnitudes remain cohort- and parameter-dependent and are reported as illustrative rather than portable constants.
The curated set is tracked in FIGURE_MANIFEST.csv. Two of the data figures (fig4_mer, fig5_oer) are redrawn directly from the committed CSVs; several others are schematic diagrams or analytical illustrations that do not read from results/ — those are flagged below.
figures/fig1_state_machine.png— the five acuity states with their thresholds, timeouts, and the escalation (solid) versus C5 de-escalation (dashed) transitions. Schematic; layout and labels are drawn from fixed parameters, not run output.figures/fig2_pipeline.png— the order in which an update is checked (C2 → C1 → C4 → C5, then audit). Schematic of Algorithm 1.figures/fig3_c5_decay.pngandfigures/fig3b_decay_comparison.png— the exponential-decay envelope that gates C5, and how the per-state decay rates compare. Analytical curves from the published λ values; they do not depend onrun_all.py.figures/fig4_mer.png— missed-escalation rate by trajectory type, with DRAS-5 flat at 0% beside the stateless baselines. Driven byresults/mer_by_type.csv.figures/fig5_oer.png— over-escalation rate with and without C5; the two series coincide, the visual counterpart of C5 granting nothing here. Driven byresults/oer_by_type.csv.figures/fig7_c5_rejection.png— the C5 outcome breakdown, showing 1,250 grants and the cooling/decay denial counts. Driven byresults/c5_outcomes.csv.figures/fig9_3d_trajectory.png— three example trajectories regenerated from the simulator at seed 42 (computed, not hardcoded).
Removed figures. Five figures whose values were typed into the script rather than produced by any analysis have been removed, along with both their generator functions and their committed .png/.pdf outputs:
fig6_sensitivity/fig8_3d_sensitivity— threshold and 3D sensitivity panels. The OER/MTCS curves and the 3D OER surface were typed in; no perturbation sweep exists in this repository, and the values contradicted the seed-42 results. The only reproducible part of the sensitivity claim (MER stays 0% under perturbation) is structural.fig10_performance/fig11_regulatory/fig12_compliance— the per-operation latency bars, throughput gauge, IEC/EU-AI-Act regulatory mapping, and per-constraint event counts were all written into the script.run_all.pyemits only one aggregate transition latency (results/latency.csv); the rest had no computational source, andfig10's 8,333-updates/s gauge contradicted the committed aggregate measurement.
run_all.py is the authoritative source for any quoted metric; only figures that read from results/ (or are clearly labelled schematic/analytical diagrams) are retained.
No human-subject data is used. All trajectories are generated synthetically inside src/dras5/simulator.py from parametric profiles (monotonic, oscillating, spike-and-recover) seeded at 42. Because there are no patient records, no ethics approval or IRB review applies.
No external or clinical dataset is distributed or required. Every input is synthetic and is
generated inside src/dras5/simulator.py at seed 42: 5,000 trajectories of 100 steps each
(500,000 risk-score evaluations), drawn from four families of 1,250 trajectories — monotonic
deterioration, oscillating deterioration, spike-to-emergency and spike-to-critical. Each sample is a
scalar risk score in [0, 1] with its timestamp; the state machine consumes it unchanged. The
committed outputs of a seeded run are the CSV and JSON tables in results/ (summary.json,
mer_by_type.csv, oer_by_type.csv, oer_by_truelevel.csv, c5_outcomes.csv, latency.csv,
ml_wrapper.csv). data/ and models/ are placeholders kept for structural consistency with the
other repositories in this portfolio.
src/dras5/— the package: state machine, the five constraints (C1–C5), the exponential-decay gate, the trajectory simulator, the append-only audit log and a command-line interface.scripts/run_all.py— the single deterministic driver (seed 42) that regenerates every number inresults/.scripts/generate_figures.py— redraws the manuscript figures fromresults/.tests/— unit and behaviour tests, one group per constraint.notebooks/— worked examples of the state machine and the governance workflow.
Python 3.9 or newer is required by the package metadata; the reported results were produced and
tested only with CPython 3.11.15 (NumPy 2.4.6, scikit-learn 1.9.0) on an Intel Core i7-7700HQ
(2.80 GHz, 8 logical processors) with 15.9 GiB RAM under Windows 11, no GPU; run_all.py records
this in results/environment.json. Runtime dependencies are NumPy, scikit-learn,
Matplotlib and Seaborn; tests additionally need pytest and pytest-cov. Exact versions are pinned in
requirements.txt, and Dockerfile / docker-compose.yml provide a container with the same stack.
The state machine itself is pure Python, so results are host-independent; only the latency table
depends on hardware.
- Generate the seeded synthetic cohort with the four trajectory families (
simulator.py). - Feed each score, in order, to the five-state machine; every transition is checked against C1–C5 and appended to the audit log.
- Score the stateless baselines (NEWS2, MEWS) on the same cohort under intermittent observation (every second and third step) for comparison.
- Compute the missed-escalation rate, over-escalation rate, de-escalation outcomes, per-update latency and the machine-learning wrapper experiment, with bootstrap confidence intervals (1,000 resamples, seed 42).
- Write every table to
results/and redraw the figures from those tables.
No data cleaning, imputation, scaling or feature engineering is applied at any step.
pip install -e . # install the package
python scripts/run_all.py # regenerate every table in results/ (seed 42)
python scripts/generate_figures.py
pytest -q # run the constraint test suite@article{tritham_dras5,
title = {{DRAS-5}: A Runtime Safety Layer for Clinical Decision Support
with Bounded, Decay-Gated De-escalation},
author = {Tritham, Chatchai and Namahoot, Chakkrit Snae},
journal = {PeerJ Computer Science},
year = {2026},
note = {Under review}
}This release is archived on Zenodo, which mints a permanent DOI for the exact snapshot cited
by the manuscript. Cite the archived version, not the mutable main branch:
- Archived snapshot: 10.5281/zenodo.21881957
(the immutable DOI for release
v1.0.0) - Release tag:
v1.0.0 - Deposit metadata:
.zenodo.json; citation metadata:CITATION.cff
Released under the MIT License (see LICENSE). Contributions are welcome: please read CONTRIBUTING.md and CODE_OF_CONDUCT.md before opening an issue or a pull request.
Chatchai Tritham — Department of Computer Science and Information Technology, Faculty of Science, Naresuan University, Phitsanulok 65000, Thailand. Email: [email protected] · ORCID: 0000-0001-7899-228X Chakkrit Snae Namahoot — same affiliation. Email: [email protected] · ORCID: 0000-0003-4660-4590
| Repository | Role |
|---|---|
| BASICS-CDSS | Beyond-accuracy evaluation methodology |
| TRI-X | Framework-level package |
| ORASR | Routing and safety-action component |
| DRAS-5 | Dynamic risk-state component |
| SAFE-Gate | Safety-gated ensemble framework |
| SynDX | Synthetic validation and explainability evidence |
| SURgul | SRGL/governance reproducibility component |
| TRI-X-CDSS | Integration and implementation package |
| Selective-CDSS | Risk-controlled selective-prediction (abstention) component |
| Causal-CDSS | Causal-inference evaluation component |
| Beyond-Accuracy | Simulation-based safety/calibration evaluation framework |