# MASLDTrialReadQC-Kor (매슬드트라이얼리드큐씨코어)

MASH RCT 판독 데이터 품질 감시 도구 — RBQM / Central Statistical Monitoring

> **면책 / 안전성 고지**
> 본 도구는 **연구용·참고용**이며, 실제 임상시험 모니터링 의사결정은 자격을 갖춘
> 담당자(임상시험 모니터, 통계가, central reader/pathologist 등)가 수행해야 합니다.
> 본 도구가 사용하는 NIT 품질 기준·생물학적 자연 변화율 임계값 등은 **예시적·교육용**
> 이며, ICH E6(R2)/E6(R3), FDA RBM guidance, AASLD/EASL MASLD 가이드라인 등
> **최신 문서로 반드시 검증**해야 합니다. 기본 제공 데이터는 전적으로 **합성
> 데이터**이며 실제 환자·시험 데이터가 아닙니다.

---

## 목적

MASH(metabolic dysfunction-associated steatohepatitis) RCT에서 누적되는
비침습 검사(NIT)·영상·biopsy 판독 데이터의 품질을 자동 감시하여, 임상시험
진행 중 발생하는 측정 품질 저하·central reader drift·사이트/스캐너 systematic
bias·생물학적으로 불가능한 데이터·biopsy 일치도 저하를 조기에 탐지하고
RBQM(Risk-Based Quality Management) 리포트와 reader 재교정 권고를 생성한다.

- **도메인**: MASLD (대사성간질환 / metabolic dysfunction-associated steatotic liver disease)
- **카테고리**: 인체실험 도구 — RCT 데이터 품질 감시 (RBQM / central statistical monitoring)

## 핵심 기능 5개

1. **NIT·영상·biopsy ingest + 측정 품질 플래그**
   VCTE LSM/CAP·IQR/median·유효측정 수, MRI-PDFF, MRE, FIB-4, ELF, biopsy
   NAS/fibrosis stage를 central reader/사이트/스캐너 ID와 함께 CSV로 ingest하고,
   측정별 품질 기준(VCTE IQR/median < 30%, 유효측정 ≥ 10회) 위반을 자동 플래그.

2. **Central reader 종단 drift 탐지**
   reader별 판독값(환자 평균 centering 잔차)의 trial week 추세를 회귀로 추정하고,
   **reader 간 상대 편차(robust z, MAD 기반)** 로 systematic drift를 플래그.
   drift 크기·방향을 막대그래프와 잔차 산점도로 시각화.

3. **사이트/스캐너 systematic bias (funnel plot)**
   사이트·스캐너별 NIT 값을 case-mix(age·bmi·week) 보정 후 평균 잔차로 비교하고,
   funnel plot의 ±2 SD 한계를 벗어나는 calibration outlier 기관·스캐너를 탐지.

4. **Implausible 변화율 + biopsy 일치도 drift**
   생물학적으로 불가능한 종단 변화(LSM·PDFF 급감)·비단조 패턴을 플래그하고,
   두 central pathologist 간 fibrosis stage 일치도(선형 가중 Cohen's κ)와
   NAS 일치도(ICC)를 trial 등록 구간(EARLY/LATE)별로 추적해 일치도 저하를 경고.

5. **RBQM 리포트 + reader 재교정 권고**
   사이트/reader risk 순위, 품질 실패율, drift 패턴, 권고 조치를 ICH E6 central
   monitoring 형식의 텍스트/HTML 리포트로 생성하고 다운로드 제공.

## 기술 스택

Python · Streamlit · pandas/numpy · scipy.stats · scikit-learn · matplotlib.
오프라인 standalone — 외부 네트워크/API/CDN 호출 없음.

가중 Cohen's κ와 ICC는 외부 의존성을 줄이기 위해 `analysis.py`에 직접 구현되어
있다(scikit-learn은 requirements에 포함하나 핵심 분석에는 필수 아님).

## 파일 구성

```
2026-05-19-3-masld-trial-read-qc-kor/
├── app.py                     # Streamlit 메인 진입점 (기능 5개를 탭으로 구성)
├── analysis.py                # 핵심 분석 로직 (streamlit 비의존, CLI 검수 가능)
├── requirements.txt           # pinned 버전
├── README.md                  # 본 문서
├── QA.md                      # 검수 로그
└── data/
    ├── generate_synthetic.py  # 합성 데이터 생성 스크립트 (pandas/numpy만 사용)
    ├── measurements.csv        # 합성 NIT 측정 데이터 (640행)
    ├── biopsy.csv              # 합성 biopsy 판독 데이터 (320행)
    └── sites.csv               # 사이트 메타데이터 (8행)
```

## 실행법

```bash
# 1) 의존성 설치
pip install -r requirements.txt

# 2) (선택) 합성 데이터 재생성 — 이미 CSV가 커밋되어 있어 생략 가능
python3 data/generate_synthetic.py

# 3) Streamlit 앱 실행
streamlit run app.py
```

CLI로 분석 로직만 검수하려면 (streamlit 불필요):

```bash
python3 analysis.py        # RBQM 텍스트 리포트를 표준출력으로 인쇄
```

## 합성 데이터 설계

`data/generate_synthetic.py`는 8개 사이트·6명 central reader·160명 환자의 다기관
MASH RCT를 모사한다. 정상 reader/site 다수에 더해 검수·데모용으로 다음 품질
시그널을 의도적으로 삽입한다:

| 시그널 | 위치 | 내용 |
|--------|------|------|
| READER_DRIFT | reader `R03` | trial 진행에 따라 LSM을 systematic하게 과대평가 |
| SITE_BIAS    | site `S07`   | VCTE 스캐너가 일관되게 +bias (calibration offset) |
| LOW_QUALITY  | site `S05`   | VCTE 측정 IQR/median이 자주 품질기준 위반 |
| KAPPA_DRIFT  | 후반 등록 구간 | 두 pathologist 간 fibrosis stage 일치도 저하 |
| IMPLAUSIBLE  | 환자 4명     | 생물학적으로 불가능한 종단 급변/비단조 패턴 |

## 검수 체크리스트

- [ ] 모든 `.py` 파일이 구문 오류 없이 파싱된다 (`python3 -c "import ast; ast.parse(...)"`)
- [ ] `data/generate_synthetic.py`가 streamlit 없이 실행되어 3개 CSV를 생성한다
- [ ] 생성된 CSV가 pandas로 로드된다
- [ ] `analysis.py`가 streamlit 없이 import된다 (streamlit import는 app.py에만)
- [ ] `python3 analysis.py`가 RBQM 리포트를 RuntimeWarning 없이 출력한다
- [ ] reader drift 탐지가 삽입 시그널 `R03`을 단독 플래그한다
- [ ] 사이트 bias 탐지가 삽입 시그널 `S07`을 outlier로 플래그한다
- [ ] 품질 플래그가 `S05`를 높은 실패율로 식별한다
- [ ] biopsy 일치도 drift가 EARLY→LATE κ 저하를 경고한다

검수 결과는 `QA.md`에 기록되어 있다.

## 출처 / 참고

수치 기준·방법론은 아래 가이드라인을 참고한 **예시·교육용**이며, 실제 적용 전
최신 원문으로 검증해야 한다.

- **ICH E6(R2)** Good Clinical Practice — Addendum on centralized monitoring /
  risk-based quality management.
- **ICH E6(R3)** Good Clinical Practice (2023~) — quality-by-design,
  risk-proportionate monitoring.
- **FDA (2013)** *Guidance for Industry: Oversight of Clinical Investigations —
  A Risk-Based Approach to Monitoring* (RBM guidance).
- **AASLD (2023)** MASLD/MASH nomenclature 및 임상 가이드라인.
- **EASL-EASD-EASO (2024)** Clinical Practice Guidelines on the management of MASLD.
- VCTE(FibroScan) 신뢰성 통념: IQR/median ratio < 30%, 유효측정 ≥ 10회 (예시값).

---
*생성일: 2026-05-19 · MASLD daily idea 파이프라인 MVP*