# MASH-DILISurveil-Kor (매시디엘아이서베일-코어)

> **참고용·연구용 도구입니다. 임상적 의사결정·규제 제출에 그대로 사용해서는 안 됩니다. Not for clinical decision.**
> placebo arm reference 값은 공개 trial 보고를 단순화한 **mock** 입니다.

MASH(MASLD) phase 2/3 trial에서 발생하는 LFT 시계열과 약물 class별 safety panel raw를 받아,
**baseline-elevated MASH 인구를 보정한 Hy's law·RUCAM 인과성 자동 점수·CIOMS R-ratio·class별 panel·placebo arm attributable signal·DSC 분기 리포트·RMP/DSUR/PSUR docx**를 표준 산출하는 standalone Streamlit/CLI 도구.

- **카테고리**: 인체실험 도구 (RCT / observational study)
- **도메인**: MASLD (대사성간질환)
- **빌드 일자**: 2026-05-26

---

## 핵심 기능

1. **LFT + class별 safety panel ingest + baseline 보정**
   - ALT/AST/ALP/TBL/INR/Albumin/Platelet 시계열 CSV
   - 6개 class panel: THR-β, FGF21, ACC, FXR, GLP-1RA, GIP/glucagon
   - 일반 ULN과 MASH baseline 두 기준 병기

2. **baseline-adjusted Hy's law + eDISH plot**
   - 일반 Hy's law (FDA 2009): ALT ≥3× ULN + TBL ≥2× ULN + ALP <2× ULN
   - MASH-baseline-adjusted: ALT ≥3× *baseline* + TBL ≥2× ULN
   - eDISH log-log scatter, Hy zone·Temple corollary·Cholestatic zone 자동 라벨

3. **RUCAM·CIOMS·DILIN 인과성 자동 점수**
   - RUCAM 7 도메인 → highly probable / probable / possible / unlikely / excluded
   - CIOMS R-ratio (ALT/ULN ÷ ALP/ULN) → hepatocellular / cholestatic / mixed
   - Naranjo, Maria-Victorino 보조

4. **class별 통합 safety panel + class-effect 시그널**
   - THR-β: TSH 30% 억제, HR 8bpm 상승, SHBG 30%↑
   - FGF21: IGF-1 25%↓, P1NP↓·CTX↑ (골대사)
   - ACC: TG 30%↑ (class-effect hypertriglyceridemia)
   - FXR: LDL 15%↑, pruritus VAS ≥4
   - GLP-1RA: lipase/amylase ≥3× ULN
   - GIP/glucagon: 공복혈당 10%↑, urea 20%↑

5. **placebo arm background + DSC 리포트**
   - 5개 phase 3 placebo arm mock reference (MAESTRO-NASH·ENLIGHTEN·SYMMETRY·CONTROL·ESSENCE)
   - 시험약 attributable Hy's rate / Temple corollary rate
   - DSC quarterly JSON·docx, RMP/DSUR/PSUR docx, manuscript supplementary md

---

## 빠른 실행

```bash
cd "2026-05-26-3-mash-dili-surveil-kor"
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 1) 합성 데이터 생성 + end-to-end 분석
python3 main.py --demo

# 2) Streamlit UI
streamlit run app.py
```

CLI 옵션:

| 옵션 | 설명 |
|---|---|
| `--demo` | 합성 데이터 생성 후 파이프라인 실행 |
| `--generate-only` | 합성 데이터만 생성 |
| `--analyze` | 기존 data/ 사용해 분석만 |
| `--n` | 환자 수 (default 600) |
| `--seed` | 랜덤 시드 |
| `--quarter` | DSC 보고 분기 라벨 (e.g. Q1) |

---

## 디렉토리 구조

```
2026-05-26-3-mash-dili-surveil-kor/
├── README.md
├── app.py                # Streamlit UI
├── main.py               # CLI
├── requirements.txt
├── modules/
│   ├── ingest.py         # LFT + panel ingest + baseline 보정
│   ├── hys_law.py        # Hy's law + eDISH
│   ├── rucam.py          # RUCAM/Naranjo/Maria-Victorino
│   ├── class_panel.py    # 6개 class별 panel
│   └── report.py         # DSC + RMP/DSUR/PSUR + supplementary
├── data/
│   ├── synthetic_lft.csv
│   ├── synthetic_thrb_panel.csv
│   ├── synthetic_fgf21_panel.csv
│   ├── synthetic_acc_panel.csv
│   ├── synthetic_fxr_panel.csv
│   ├── placebo_reference.csv
│   └── charter_example.yaml
├── reports/
└── QA.md
```

---

## 검수 체크리스트

- [ ] `python3 -c "import ast; ..."` 모든 .py 구문 OK
- [ ] `python3 main.py --help` 정상 표시
- [ ] `python3 main.py --demo` 합성 데이터 생성 + 파이프라인 통과
- [ ] eDISH summary에 Hy zone case ≥1 존재
- [ ] RUCAM 분포에 probable 이상 ≥1 존재
- [ ] placebo arm attribution이 음/양 양쪽으로 합리적
- [ ] reports/ 디렉토리에 DSC_Q1.json·cases_Q1.csv 출력

---

## 한계와 면책

- 본 도구의 **placebo reference는 mock 값**입니다. 실제 trial 공개값을 그대로 쓰지 마세요.
- RUCAM의 derived inputs은 시그널 강도에 따른 **default 패턴**으로, 실제 인과성 평가에는 사이트 PI·메디컬 모니터의 case-by-case 입력이 필요합니다.
- 본 도구는 AASLD MASLD 2023, EASL-EASD-EASO MASLD 2024, FDA 2009 DILI Guidance, AASLD/IDILI causality consensus의 공개 가이드라인 텍스트만 내장 참조합니다. **외부 API·네트워크 호출 없음**.
- 한국 의약품안전관리원·MFDS DSUR/PSUR 표준 양식은 별도 메디컬 라이터의 검토가 필요합니다.

---

## 출처

- FDA Guidance for Industry: Drug-Induced Liver Injury (DILI) — Premarketing Clinical Evaluation, 2009
- AASLD Practice Guidance on MASLD, Hepatology 2023
- EASL-EASD-EASO Clinical Practice Guidelines on MASLD, 2024
- Danan G, Benichou C. RUCAM. J Clin Epidemiol 1993
- Aithal et al. DILI causality consensus. Clin Pharmacol Ther 2011
- Naranjo CA. ADR probability scale. Clin Pharmacol Ther 1981
- Maria VAJ, Victorino RMM. Hepatology 1997
- Watkins PB. eDISH plot. 2008
- (mock) MAESTRO-NASH, ENLIGHTEN, SYMMETRY, CONTROL, ESSENCE placebo arm 단순화 값