Regenerate, from a fixed seed, every headline number behind the SynDX-Hybrid synthetic vestibular cohort and its explainability and counterfactual evidence.
Clinical machine learning is held back by two stubborn facts: real patient records are scarce and tightly governed, and the synthetic substitutes built to replace them rarely respect clinical guidelines. A generator can reproduce a marginal distribution and still emit records that no clinician would accept, because nothing in the pipeline checks whether each case is medically coherent or where its values came from.
SynDX-Hybrid takes a different route. It layers five complementary methods so that each generated record is constrained by formal clinical rules, kept close to published epidemiological distributions, and tagged with the guideline source behind every populated field. Three layers generate records (combinatorial enumeration, Bayesian networks, rule-based expert logic), a fourth attaches provenance metadata, and a fifth probes diagnostic logic by perturbing decisive clinical axes and re-checking the constraints. The worked example is dizziness triage, where the TiTrATE framework supplies the rules that separate benign from dangerous presentations.
This repository holds the reproducible core of that work. It does not ship the full five-layer production system; instead it rebuilds a seeded synthetic cohort with the packaged modules and recomputes the statistical, diagnostic, coverage, traceability, and counterfactual numbers that the paper reports, so a reader can confirm them rather than take them on trust.
All figures below are produced by scripts/run_all.py on a 10,000-record seeded synthetic cohort spanning 16 vestibular diagnostic categories. They are computed at run time, not stored as constants.
- Distributional realism is high: mean per-feature KL divergence of 0.071, mean Jensen-Shannon divergence of 0.009, and mean Wasserstein-1 distance of 0.078 between the generated cohort and the guideline-derived archetypes.
- An XGBoost classifier (70/30 split, diagnosis label held out of the inputs) reaches a macro ROC-AUC of 0.85, with macro specificity 0.96 and macro sensitivity 0.43. This measures internal diagnostic coherence on synthetic data, not generalisation to real patients; the modest sensitivity comes from catch-all categories with no distinctive signature, and these are honest outputs rather than tuned ones.
- Every retained case satisfies the formal TiTrATE constraints (100%), drawn from a candidate acceptance rate of 71.6%; all 52 populated features carry a named guideline-block citation (100% traceability).
- Perturbing the symptom-timing axis flips the validity verdict in 72.4% of probed cases, which is the expected behaviour when the perturbed axis is clinically decisive.
- Expert plausibility ratings, inter-rater agreement (Fleiss kappa), and any real-patient metric are not produced here. None can be regenerated by code, so the paper presents them as planned validation rather than results, and this repository does the same.
SynDX/
├── src/syndx/ # five-layer package: phase1_knowledge, phase2_synthesis, phase3_validation, pipeline
├── scripts/ # run_all.py (headline metrics) + figure/visualisation generators
├── examples/ # standalone visualisation and chart examples
├── notebooks/ # phase-by-phase walkthroughs of the pipeline
├── data/ # archetype_sample.csv (small seeded sample)
├── results/ # metrics.json, metrics.csv (run_all.py output)
├── figures/manuscript/ # the three curated manuscript figures (PNG + PDF)
├── outputs/ # detailed per-module artifacts (SHAP, NMF, counterfactual, validation)
├── tests/ # import and behaviour checks
├── FIGURE_MANIFEST.csv # curated figure inventory (IDs, sources, captions, DPI)
└── pyproject.toml, requirements.txt
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install -e .python scripts/run_all.py # fixed seed 42; ~45 min for full 10,000-patient generation on a standard workstationThe script builds the seeded synthetic cohort with the real package modules, computes the metrics described above, and writes them to results/metrics.json and results/metrics.csv. The scientific outputs are deterministic: re-running with seed 42 yields the same metric values to full precision. Only wall-clock timing and progress logging vary between runs. The figure scripts read these values from results/metrics.json rather than from hard-coded numbers, so the charts track whatever the pipeline actually produced.
The curated set is governed by FIGURE_MANIFEST.csv, which links each figure to its source script, source data, caption, and export DPI (600). The three manuscript figures live in figures/manuscript/.
figures/manuscript/fig1_shap_importance_clinical.png— Clinically labelled SHAP feature-importance bars for the dizziness model. Read it top to bottom: vascular risk score, vertigo severity, and prior stroke/TIA carry the largest mean absolute SHAP values, which matches the stroke-versus-benign reasoning that TiTrATE encodes.figures/manuscript/fig2_focused_validation_metrics.png— A four-bar summary of the validation panel: SHAP bootstrap rank correlation (0.67), counterfactual success rate (0.70), clinically plausible counterfactuals (0.85), and NMF variance retained (0.39). The take-away is that the explanation rankings and the counterfactual generator are stable and clinically sensible, while a single NMF factor captures a moderate share of variance.figures/manuscript/fig3_counterfactual_quality_profile.png— A radar plot scoring the generated counterfactuals on clinical plausibility, sparsity, diversity, and (inverted) proximity. The shape is widest on plausibility and diversity, showing the perturbations stay clinically credible while still exploring distinct alternatives; the supporting numbers are inoutputs/validation_demo/counterfactual/validation_metrics.json(mean sparsity 3.3 edits, 85% plausible).
The CSV alongside the charts, results/metrics.csv, is the flat record of every headline number and is the canonical reference if a figure and the text ever disagree.
No human subjects or real patient records are involved, so no IRB approval is required. The cohort is fully synthetic: archetypes are enumerated from the TiTrATE clinical rules, expanded into 10,000 patients across 16 diagnostic categories, filtered against the formal constraints, and annotated with guideline provenance. A small seeded sample sits in data/archetype_sample.csv; the full cohort is regenerated by scripts/run_all.py.
@unpublished{Tritham_SynDX_2026,
author = {Tritham, Chatchai and Snae Namahoot, Chakkrit},
title = {SynDX-Hybrid: A Five-Layer Framework for Guideline-Grounded,
Explainable Synthetic Medical Data Generation},
year = {2026},
note = {Manuscript under review}
}Released under the MIT License (see LICENSE).
Chatchai Tritham — Department of Computer Science and Information Technology, Faculty of Science, Naresuan University, Phitsanulok 65000, Thailand. Email: chatchait66@nu.ac.th · ORCID: 0000-0001-7899-228X Chakkrit Snae Namahoot — same affiliation. Email: chakkrits@nu.ac.th · 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 |