Skip to content
prof-chatchaiPublic

About

DRAS-5: Dynamic Risk Assessment State Machine with Exponential Decay De-escalation and Provable Safety Guarantees

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

37 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Dynamic Risk Assessment State Machine (DRAS-5)

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.

License Python Reproducible

Description

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.

Key results

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.

Revision v1.5.0 (2026-10-12): what changed in the findings

  • 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.py regenerates the TLC outputs; eight mutants are rejected.
  • Result keys follow the paper: mer_reach_* (never reached the sustained peak) and mer_end_* (final level below it). under_recognition_overall_pct in summary.json is 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.

Revision v1.6.0 (2026-10-12, round 2): what changed in the findings

  • Install from the clone. If another copy of dras5 is installed (for example an editable install of a different working tree), the scripts may import it instead of this clone. Run pip install -e . inside the clone, or prefix every command with PYTHONPATH=src (PowerShell: $env:PYTHONPATH="src").
  • scripts/tradeoff_frontier.py (about 5 min) sweeps a threshold shift for every baseline and a T_max factor 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.py now also runs decayed max at ward rates and reports C2 timeouts per patient-day.

Repository structure

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)

Installation

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 .

Reproducing the results

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/*.csv

run_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.

Results and figures

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.png and figures/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 on run_all.py.
  • figures/fig4_mer.png — missed-escalation rate by trajectory type, with DRAS-5 flat at 0% beside the stateless baselines. Driven by results/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 by results/oer_by_type.csv.
  • figures/fig7_c5_rejection.png — the C5 outcome breakdown, showing 1,250 grants and the cooling/decay denial counts. Driven by results/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.py emits only one aggregate transition latency (results/latency.csv); the rest had no computational source, and fig10'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.

Data

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.

Dataset information

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.

Code information

  • 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 in results/.
  • scripts/generate_figures.py — redraws the manuscript figures from results/.
  • tests/ — unit and behaviour tests, one group per constraint.
  • notebooks/ — worked examples of the state machine and the governance workflow.

Requirements

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.

Methodology

  1. Generate the seeded synthetic cohort with the four trajectory families (simulator.py).
  2. Feed each score, in order, to the five-state machine; every transition is checked against C1–C5 and appended to the audit log.
  3. Score the stateless baselines (NEWS2, MEWS) on the same cohort under intermittent observation (every second and third step) for comparison.
  4. 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).
  5. 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.

Usage instructions

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

Citation

@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

License and contribution guidelines

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.

Contact

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

Portfolio relationship

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

About

DRAS-5: Dynamic Risk Assessment State Machine with Exponential Decay De-escalation and Provable Safety Guarantees

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages