synthmind 0.1.0

Synthetic patients and psychotherapy-protocol simulation for clinical psychology research and teaching.

synthmind

Languages: English · Türkçe · Español · Français · Deutsch · Português · Italiano · 中文 · 日本語

synthmind is a Python library for clinical-psychology research and teaching. It generates clinically realistic synthetic patients with DSM-5 -- style mental-health conditions and simulates eight evidence- based psychotherapy protocols (CBT, DBT, PE, EMDR, IPT, ACT, MBCT and short-term psychodynamic therapy). On top of those primitives it provides RCT engines, causal-inference utilities, OSCE-style teaching cases, validation against five landmark trials, and a Streamlit interface.

Disclaimer. synthmind is a research and teaching tool. The patients generated in this interface are not real; the numbers shown cannot be used as clinical recommendations. For patient care always consult a qualified registered specialist.

Author

Buğra Ayan — Ankara, Türkiye · bugraayan.com

Features

• 27 mental-health disorders across ten DSM-5 categories with parametric response curves calibrated to published meta-analyses.
• 31 psychometric instruments (PHQ-9, GAD-7, HAMD-17, MADRS, BDI-II, PCL-5, CAPS-5, Y-BOCS, PANSS, CGI, WHOQoL-BREF, SDS, WAI-SR, AUDIT, DAST-10, ISI, PSQI, WHO-5, ORS, IIP-32 and more) with severity cut-offs and reliable-change values.
• Eight evidence-based psychotherapy presets that share a uniform InterventionPlan interface.
• Two simulation engines — a generic Simulator and the domain-specific SymptomTrajectoryEngine (exponential decay + alliance moderator + dose response).
• Five generators (Random, Distribution, Copula, CohortSpec, Markov).
• Five behaviour models (constant, decaying, stochastic-skip, perceived-burden, Weibull dropout).
• Three RCT engines (parallel, crossover, factorial) with ITT/PP/AT and ANCOVA on baseline-adjusted change.
• Causal-inference toolkit — counterfactual simulation, naive + IPTW + g-formula ATE estimators, conditional ATE, an E-value sensitivity sweep, and a hand-rolled CausalDAG.
• Reliable-change & clinically-significant-change indices (Jacobson-Truax), Cohen's d, Hedges' g, response and remission helpers.
• Statistical helpers — power, sample-size, bootstrap CI, permutation, Benjamini-Hochberg, ANCOVA.
• Measurement-error & missingness injection (CV%, MCAR, MAR, MNAR).
• 15 OSCE-style teaching cases with a weighted rubric grader.
• Validation against five landmark trials (STAR*D, TADS-equivalent, CALM, CATIE-equivalent, PROSPECT-equivalent).
• Streamlit web app with a clinical-clean theme, Plotly trajectory animations and a custom CONSORT diagram.
• Documentation in nine languages (en, tr, es, fr, de, pt, it, zh, ja).

Installation

pip install -e ".[viz,causal,app,dev]"

For the Streamlit app you only need the app extra:

pip install -e ".[app]"
streamlit run app/streamlit_app.py

60-second tour

import synthmind as sm

cohort = sm.DistributionGenerator(
    primary_diagnosis="major_depressive_disorder", seed=42,
).sample(80)

trial = sm.ParallelTrial(
    cohort=cohort,
    arms={
        "waitlist": sm.cbt_intervention(
            sessions_total=4, sessions_per_week=0.25,
            homework_minutes_per_week=0,
            expected_adherence=0.95, name="Waitlist (sham)",
        ),
        "active": sm.cbt_intervention(),
    },
    simulator=sm.Simulator(
        adherence=sm.WeibullDropout(),
        engine=sm.SymptomTrajectoryEngine(),
    ),
    duration_weeks=12,
    primary_biomarker="phq9",
)
result = trial.run(seed=7)
print(result.intention_to_treat())   # ANCOVA on PHQ-9 change
print(result.consort_diagram())

Project layout

synthmind/
├── app/                     # Streamlit (5 pages + components + theme)
├── docs/                    # 9 languages (en + tr + es + fr + de + pt + it + zh + ja)
├── examples/                # 4 end-to-end Python scripts
├── paper/                   # JOSS draft
├── scripts/                 # build_translations + capture_screenshots + build_hero
├── src/synthmind/
│   ├── behavior/            # adherence + dropout
│   ├── causal/              # counterfactual + ATE + DAG + sensitivity
│   ├── diseases/            # 27-disorder registry
│   ├── education/           # 15 cases + OSCE
│   ├── evaluation/          # outcome reporting
│   ├── generators/          # 5 strategies
│   ├── indices/             # RCI + Jacobson-Truax + d / g
│   ├── interactions/        # ≥12 drug-biomarker interactions
│   ├── interventions/       # 8 psychotherapy presets
│   ├── noise/               # measurement-error + missingness
│   ├── patients/            # Patient + sub-records
│   ├── psychometrics/       # 31 instruments
│   ├── simulation/          # Simple + SymptomTrajectory engines
│   ├── stats/               # power + bootstrap + permutation + FDR + ANCOVA
│   ├── trials/              # parallel + crossover + factorial
│   ├── utils/               # constants + RNG + validators
│   ├── validation/          # 5 landmark-trial validators
│   └── viz/                 # optional matplotlib plots
└── tests/                   # 97 tests (92 fast + 5 slow validation)

Extending

Register a new disease:

from synthmind.diseases import (
    Disease, DiseaseCategory, PsychConstraints, register,
)

def my_response(patient, intervention, weeks):
    return {"phq9": -2.0 * weeks / 12}

register(Disease(
    name="my_new_diagnosis",
    label="My new diagnosis",
    icd10="F99",
    mesh="Mental Disorders",
    category=DiseaseCategory.MOOD,
    primary_biomarker="phq9",
    psych_constraints=PsychConstraints(citations=("Smith 2025",)),
    response_to_intervention=my_response,
))

Citation

@software{ayan2026synthmind,
  author  = {Ayan, Buğra},
  title   = {synthmind: synthetic patients and psychotherapy
             simulation for clinical psychology},
  version = {0.1.0},
  year    = {2026},
  url     = {https://github.com/bugraayancom/synthmind},
}

License

MIT — see LICENSE.