# MASLDNITSchedule-Kor (매슬드엔아이티스케줄)

MASLD/MASH 관찰연구의 비침습검사(NIT) 종단 측정 스케줄을 설계·계산하는 오프라인 standalone 도구.

- **도메인**: 대사성간질환 — MASLD (former NAFLD) / MASH (former NASH)
- **카테고리**: 인체실험 도구 (관찰연구 설계·계산기)
- **빌드 일자**: 2026-05-17

---

## 한 줄 요약

MASLD/MASH 관찰연구의 NIT 종단 측정 스케줄을 NIT별 측정 변동성·최소검출변화(MDC)·섬유화/지방
진행률 기반으로 설계하고, 결측을 최소화하는 visit window와 연구기간 vs 검출력 tradeoff를
계산하는 standalone 설계 도구.

---

## 면책 (반드시 숙지)

> 본 도구(MASLDNITSchedule-Kor)는 **참고용·연구용 설계 보조 도구**입니다.
> 실제 관찰연구 설계는 **생물통계학자 검토가 필수**이며,
> NIT 변동성·진행률·검사 단가 값은 **발표 문헌 기반 추정치**입니다. 정밀 값이 아닙니다.
> 실제 설계 시 최신 1차 문헌 및 기관 IRB·통계 자문을 반드시 확인하십시오.

---

## 핵심 기능 (6개)

1. **NIT 측정 스케줄 빌더** — FIB-4 · ELF · VCTE LSM(kPa) · MRE(kPa) · MRI-PDFF(%) 중 선택,
   baseline·추적 visit 수/간격 입력 → 스케줄 시각화.
2. **MDC 산출기** — NIT별 내장 변동성 문헌값(측정-재측정 SD/CV, VCTE IQR/median<30% 등
   품질기준)으로 검출 가능한 최소 변화(MDC)를 NIT·반복측정 횟수별로 계산 →
   "이 스케줄로는 0.X kPa 미만 변화 검출 불가" 경고.
3. **연구기간 vs 진행률 tradeoff** — 섬유화/지방량 자연 진행률(문헌 기반, subgroup별)과 MDC
   비교 → "검출 가능 변화 도달까지 최소 N개월" 곡선.
4. **visit window 최적화 + 결측 영향** — visit window(±주) 폭과 결측률 입력 → 종단
   Monte-Carlo 시뮬레이션으로 집단 검정력·**피험자 단위 변화 검출률**·엔드포인트 완전성
   산출, 최소 결측 스케줄 추천.
5. **NIT 조합·비용 비교** — 무료(FIB-4) vs 저가(VCTE) vs 고가(MRE/MRI-PDFF) 조합별
   검정력 대비 1인당 예상 검사비 → 비용효율 frontier.
6. **설계 리포트** — 권장 스케줄·MDC·기간·예산을 관찰연구 프로토콜 측정계획 섹션(국문)
   형식 텍스트로 생성.

---

## 구성 파일

```
2026-05-17-3-masld-nit-schedule-kor/
├── core.py                  핵심 계산 (numpy/scipy만, statsmodels 미사용)
├── app.py                   Streamlit UI
├── main.py                  argparse CLI
├── data/
│   └── nit_variability.json NIT 변동성·재현성·진행률·단가 라이브러리
├── README.md                본 문서
├── QA.md                    검수 로그
└── CHANGELOG.md             작업 이력
```

---

## 의존성

- **Python 3** (표준 라이브러리: json, os, math, argparse, ast)
- **numpy** (필수 — core 계산)
- **scipy** (선택 — 정규분포 분위수. 미설치 시 내장 근사값/`math.erf` 사용, 정상 동작)
- **streamlit** (선택 — `app.py` GUI 전용. 미설치 시 CLI로 모든 계산 가능)

설치(전역 설치 금지, 사용자 영역):
```
pip install --user numpy scipy streamlit
```

> 본 빌드 환경에서는 numpy 2.0.2 / scipy 1.13.1 / streamlit 1.50.0 확인됨.
> numpy 미설치 시 `core.py` import 단계에서 안내 메시지와 함께 실패합니다.

---

## 실행법

### CLI (Streamlit 없이 오프라인 시연)

```bash
# 전체 데모 — 예제 스케줄로 MDC·tradeoff·결측시뮬·비용 전부 출력
python3 main.py --demo

# 도움말
python3 main.py --help

# 개별 NIT 설계 리포트
python3 main.py --nit VCTE_LSM --followups 3 --interval 6 --subjects 150
python3 main.py --report MRE --subjects 100 --budget 80000000
```

### Streamlit GUI

```bash
streamlit run app.py
```

좌측 사이드바에서 NIT·표본 수·visit 수/간격·반복측정·window·결측률·예산을 입력하면
6개 탭(스케줄/MDC/tradeoff/window·결측/비용/리포트)에 결과가 갱신됩니다.

---

## 계산 방법론 (출처 주석)

- **MDC (최소검출변화, Minimal Detectable Change)**
  `MDC = 1.96 × √2 × SEM / √(반복횟수)`  (95% 신뢰)
  SEM = 측정-재측정 표준오차.
  출처: 측정학 표준 공식 (de Vet 등, *Measurement in Medicine*; Weir 2005).
- **연구기간 vs 진행률**
  `MDC 도달 개월 = MDC / |연간 진행률| × 12`.
- **집단 평균 기울기 검정력**
  임의기울기 선형혼합모형 근사 `Var(slope_i) = τ² + σ_e²/Sxx`,
  집단 평균의 SE = √(Var/n). 비중심 z 검정.
  출처: Fitzmaurice 등 *Applied Longitudinal Analysis*; Diggle 등 *Analysis of Longitudinal Data*.
- **피험자 단위 변화 검출률** (스케줄 품질 핵심 지표)
  baseline~종료 관찰 변화 |Δ| > MDC 인 피험자 비율.
  결측(엔드포인트 소실)·visit window 지터에 직접 민감.
- **결측·window Monte-Carlo**
  피험자별 임의절편·임의기울기·측정오차 + visit 시점 균등 지터 + per-visit 결측 마스크.

> 집단 평균 기울기 검정력은 표본이 크면 100%로 포화되어 스케줄 미세 차이에 둔감하므로,
> visit window·결측 최적화 비교는 **피험자 단위 변화 검출률**을 1차 기준으로 사용합니다.

---

## 내장 데이터 (`data/nit_variability.json`)

5종 NIT (FIB-4, ELF, VCTE_LSM, MRE, MRI_PDFF) 각각에 대해:
- 측정-재측정 SD 또는 CV(%), 단위, 일반 baseline 값
- 검사 품질기준 (예: VCTE IQR/median < 30%)
- 섬유화/지방 자연 진행률 추정값 (subgroup별: T2DM_or_MASH 등)
- 1회 검사 단가(원, 한국 비급여 추정)

**모든 수치는 발표 문헌 기반 추정치**이며 출처 미상의 항목은 JSON `note`에 명시.

---

## 검수 체크리스트

- [ ] `python3 -c "import ast; ast.parse(open('core.py').read())"` — core/app/main 모두 통과
- [ ] `data/nit_variability.json` JSON 파싱 성공 (NIT 5종)
- [ ] `python3 main.py --help` 정상 출력
- [ ] `python3 main.py --demo` 정상 종료(exit 0), 6개 기능 출력 확인
- [ ] 개별 리포트 `python3 main.py --report <NIT>` 정상 동작
- [ ] (선택) `streamlit run app.py` 6개 탭 렌더링 확인
- 상세 로그는 `QA.md` 참조.

---

## 출처·참고 가이드라인

- **AASLD Practice Guidance on MASLD** (Hepatology 2023) — NIT 권고
- **EASL-EASD-EASO Clinical Practice Guidelines on MASLD** (J Hepatol 2024) — NIT 권고
- VCTE(FibroScan) IQR/median < 30% 품질기준 — 제조사 및 다수 검증연구 공통 기준
- MRI-PDFF/MRE 재현성 — 다기관 reproducibility 연구 보고 범위 기반 추정

---

## 제약

- 외부 네트워크/API 호출 없음. 완전 오프라인. 내장 문헌 기반 데이터만 사용.
- 전역 패키지 설치하지 않음.
- 본 도구는 24시간 MVP 범위로 빌드됨. 확장은 별도 작업으로 진행.