feat(examples): Add end-to-end reproduction of Boag et al. 2018 mistrust pipeline on MIMIC-III

[vtewari2]

Summary

Adds a complete, runnable end-to-end example that reproduces the medical
mistrust classification pipeline from:

Boag et al. "Racial Disparities and Mistrust in End-of-Life Care."
MLHC 2018. arXiv:1808.03827
Original code: github.com/wboag/eol-mistrust

The example ties together all PyHealth components introduced in PRs #960 and
#961 into a single runnable script, and serves as a reference implementation
for reproducing the paper's supervised mistrust classifiers using modern
Python tooling.

Background

Boag et al. 2018 establishes that racial disparities in aggressive
end-of-life ICU care are better explained by medical mistrust than by
race alone. The paper trains L1-regularised logistic regression models on
interpersonal CHARTEVENTS features to produce continuous mistrust scores,
then uses those scores to stratify treatment duration disparities.

Key findings reproduced by this pipeline:

• Black EOL patients receive ~879 min more mechanical ventilation than White
  patients (p=0.009)
• Mistrust stratification amplifies this gap to ~2,319 min (3× larger)
• Noncompliance mistrust score AUC-ROC: 0.667
• Autopsy-consent mistrust score AUC-ROC: 0.531
• LogisticRegression + all mistrust features improves mortality AUC from
  0.629 (baseline demographics) to 0.661

New: examples/mistrust_prediction/mistrust_mimic3_logistic_regression.py

What it does

MIMIC-III v1.4
└── MIMIC3Dataset(tables=["CHARTEVENTS", "NOTEEVENTS"])
│
├── build_interpersonal_itemids(D_ITEMS.csv.gz)
│ → {itemid: label} (~168 entries)
│
├── MistrustNoncomplianceMIMIC3.set_task()
│ → interpersonal_features (sequence) + noncompliance (binary)
│ → LogisticRegression(l1_lambda=2.62e-4)
│ → Trainer.train() + evaluate() → AUC-ROC
│
└── MistrustAutopsyMIMIC3.set_task()
→ interpersonal_features (sequence) + autopsy_consent (binary)
→ LogisticRegression(l1_lambda=1.43e-2)
→ Trainer.train() + evaluate() → AUC-ROC

L1 lambda derivation (paper-equivalent)

The original paper uses sklearn LogisticRegression(C=0.1, penalty='l1').
The PyHealth equivalent uses l1_lambda = 1 / (C × n_train):

Task	n_train (70%)	l1_lambda
Noncompliance	~38,157	2.62e-4
Autopsy consent	~697	1.43e-2

Modes

# Full run against real MIMIC-III data (requires PhysioNet access)
python mistrust_mimic3_logistic_regression.py \
    --mimic3_root /path/to/physionet.org/files/mimiciii/1.4

# Smoke-test — no data access needed (synthetic MIMIC-III)
python mistrust_mimic3_logistic_regression.py --synthetic

Expected output (real MIMIC-III v1.4)

Task: NoncompliantMistrust
  Test metrics:
    roc_auc : 0.667

Task: AutopsyConsentMistrust
  Test metrics:
    roc_auc : 0.531
Dependencies

- Requires PR #1 (l1_lambda in LogisticRegression)
- Requires PR #2 (MistrustNoncomplianceMIMIC3, MistrustAutopsyMIMIC3,
build_interpersonal_itemids)
- MIMIC-III v1.4 with PhysioNet credentialed access (or --synthetic for
smoke-test)


References

┌─────────────────────────────┬─────────────────────────────────────────────┐
│          Resource           │                    Link                     │
├─────────────────────────────┼─────────────────────────────────────────────┤
│ Paper (MLHC 2018)           │ https://arxiv.org/abs/1808.03827            │
├─────────────────────────────┼─────────────────────────────────────────────┤
│ Original code               │ https://github.com/wboag/eol-mistrust       │
  ├─────────────────────────────┼─────────────────────────────────────────────┤
│ PyHealth LogisticRegression │ pyhealth/models/logistic_regression.py      │
├─────────────────────────────┼─────────────────────────────────────────────┤
│ PyHealth Mistrust Tasks     │ pyhealth/tasks/mistrust_mimic3.py           │
├─────────────────────────────┼─────────────────────────────────────────────┤
│ ```                         │                                             │
└─────────────────────────────┴─────────────────────────────────────────────┘

## PRs
Merge order

PR #960 -> PR #961 -> PR #962 (this PR)
Merging out of order will cause import errors in the example script.