# MASHePRO-Kor (매시이프로한국)

> **연구·교육용 prototype 입니다. 실제 임상시험 데이터에 사용 시 IRB 검토와 정식 검증이 필수입니다.**
>
> 본 키트는 합성 데이터 기반 시연을 위한 MVP이며, 한국 IRB·MFDS 제출용 정식 ePRO 시스템이 아닙니다.

## 목적

MASH(이전 NASH) 임상시험에 필요한 **한국어 ePRO 5종 + 컴플라이언스 추적 + 검정력 시뮬레이션 + REDCap·CDISC SDTM export** 를 한 패키지로 제공하는 통합 키트의 24h MVP.

- 도메인: MASLD (MASH RCT ePRO)
- 카테고리: 인체실험 도구 (ePRO 데이터 수집·계산기)

## 한 줄 설명

MASH 환자가 한국어 PWA로 5종 ePRO 매주 입력 → 사이트 PI dashboard 컴플라이언스 실시간 추적 → 누락 환자 자동 alert + 검정력 시뮬레이션 + REDCap·CDISC SDTM export.

## 5종 척도 (검증 상태 메타데이터 포함)

| 척도 | 한국어 검증 | 비고 |
|------|------------|------|
| CLDQ-NASH-Kor (단축형 8문항 데모) | **PARTIAL** | 영문판 NASH 검증(Younossi 2018), 한국어판 forward-back 번역만 보고 |
| FACIT-Fatigue-Kor (13문항) | **VALIDATED** | FACIT.org 한국어 라이선스, 다수 만성질환 연구 검증 |
| PROMIS-Fatigue-Kor SF8a (8문항) | **PARTIAL** | PROMIS Health Org 공식 번역, SF8a calibration 진행 중 |
| Hepatic Itch NRS (0–10) | **STANDARD** | NRS 단순 척도, ICE-NASH 2023 PRO consensus 수록 |
| EQ-5D-5L-Kor (5문항 + VAS) | **VALIDATED** | Kim SH 2016 Korean value set |

투명성 라벨(VALIDATED / PARTIAL / STANDARD)을 환자용 화면과 export에 모두 노출합니다.

## 구성 파일

```
.
├── README.md                ← 본 문서
├── QA.md                    ← 검수 로그
├── backend.py               ← Python CLI 진입점
├── scales.py                ← 5종 척도 정의 + scoring + 검증 상태
├── notifications.py         ← 일정·푸시·dropout risk
├── power.py                 ← 검정력 시뮬레이션 (z-test + Monte Carlo)
├── exports.py               ← REDCap dict / CDISC SDTM-QS / DSMB·sponsor 보고서
├── epro.html                ← 환자용 단일 PWA 데모 (한국어, localStorage)
├── dashboard.html           ← PI dashboard 단일 파일 (합성 데이터 inline)
├── _dashboard_template.html ← (빌드용 내부 파일)
├── _build_dashboard.py      ← (빌드용 내부 스크립트)
├── data/
│   ├── patients.json          ← 합성 50명 × 12주 ePRO entries
│   └── dashboard_data.json    ← dashboard inline 용 통계 payload
└── exports/
    ├── redcap_dictionary.csv  ← REDCap data dictionary
    ├── sdtm_qs.csv            ← CDISC SDTM-QS 도메인
    ├── dsmb_kr_report.md      ← 한국 IRB·MFDS DSMB 보고서 (시연)
    └── sponsor_en_report.md   ← 영문 sponsor compliance 보고서
```

## 실행법

요구: Python 3.9+ (표준 라이브러리만; 외부 패키지 불필요)

```bash
# 0) 모든 명령 도움말
python3 backend.py --help

# 1) 합성 데이터 (재)생성
python3 backend.py gendata --N 50 --weeks 12

# 2) 일정 생성 (예: 매주 + milestone, 12주)
python3 backend.py schedule --protocol weekly+milestone --duration 12 --limit 6

# 3) 검정력 시뮬레이션 (예: 단일 컴플라이언스 시나리오 + 다단표)
python3 backend.py power --p-control 0.10 --p-treatment 0.25 \
                         --compliance 0.85 --n-current 200 --target-n 600

# 4) Export (전체)
python3 backend.py export --format all
# 또는 단일: redcap | sdtm | dsmb-kr | sponsor-en

# 5) end-to-end 시연 (합성 → 통계 → export → dashboard 데이터 갱신)
python3 backend.py demo

# 6) 환자용 ePRO / PI dashboard
#    브라우저에서 epro.html, dashboard.html 직접 열기
```

## 주요 기능

1. **환자용 ePRO** (`epro.html`) — 5종 척도 한국어 단일 페이지, 검증 상태 라벨, 진행률 bar, localStorage 자동 저장, JSON export.
2. **시점·알림 최적화** (`notifications.py`) — `weekly` / `milestone` / `weekly+milestone` 프로토콜 시점 자동 생성, chronotype 기반 push timing 휴리스틱 추천.
3. **PI dashboard** (`dashboard.html`) — KPI 카드, 사이트별 평균 SVG 차트, power 시나리오 표, 환자별 컴플라이언스/risk/마지막 입력, 누락 환자 alert + 액션 권고.
4. **검정력 시뮬레이션** (`power.py`) — 두 비율 z-test 기반 sample size, 컴플라이언스·dropout 보정, Monte Carlo 옵션.
5. **Export 4종** (`exports.py`) — REDCap data dictionary CSV, CDISC SDTM-QS 도메인 CSV, 한국 IRB·MFDS DSMB Markdown, 영문 sponsor 보고서.

## 검수 체크리스트 (모두 통과 — 상세는 `QA.md`)

- [x] 모든 .py `ast.parse()` 통과
- [x] `python3 backend.py --help` 동작
- [x] `python3 backend.py demo` end-to-end 실행
- [x] HTML 2개 파일 존재 + 5종 척도 ID 모두 포함
- [x] 검증 상태 라벨 (VALIDATED/PARTIAL/STANDARD) 노출
- [x] dashboard 컴플라이언스 표 + power 시나리오 표 존재
- [x] 검정력 sanity: compliance 90%→124, 80%→139, 70%→159 (감소시 sample size 증가)

## 출처 / 참고

- FDA. *Noncirrhotic NASH with Liver Fibrosis: Developing Drugs for Treatment.* Draft Guidance, 2018.
- EMA. *Reflection paper on regulatory requirements for the development of medicinal products for chronic non-infectious liver diseases (PBC, PSC, NASH).* 2021.
- ICE-NASH 2023 PRO consensus statement.
- Cella D. *FACIT measurement system.*
- Kim SH et al. *Korean valuation of the EQ-5D-5L health states.* Qual Life Res 2016.
- Younossi ZM et al. *CLDQ-NASH validation.* Hepatology 2018.
- PROMIS Health Organization translation registry (Korean).

## 의학적 디스클레이머 (재명시)

본 prototype은 의료 행위/임상 의사결정 도구가 아닙니다. 출력되는 점수·요약·권고는 모두 합성 데이터 시연 또는 단순 휴리스틱이며, 실제 환자 진료·임상시험 데이터 처리에 사용 시 다음이 필수입니다:

1. 기관 IRB(생명윤리심의위원회) 검토 및 승인
2. 척도 한국어판 정식 라이선스/계약(특히 FACIT, PROMIS, EuroQol)
3. CRO/sponsor 별 ePRO 시스템 검증 (CSV/IQ/OQ/PQ)
4. CDISC SDTM 변환·REDCap dict의 study-specific 검토
5. 한국 MFDS DSMB 양식 정합성 별도 확인