# GlucoTrialMonitor-Kor

당뇨 RCT(무작위 대조 임상시험)의 누적 데이터 품질을 자동 감시하는
**오프라인 standalone RBQM(Risk-Based Quality Management) / central
statistical monitoring** 도구.

> ⚠️ **디스클레이머**
> 본 도구는 **연구용·참고용** 자동 분석 도구입니다. 산출되는 사이트
> 위험점수·플래그·central monitoring 리포트는 모니터링 검토의 **보조
> 자료**이며, 실제 임상시험 모니터링 의사결정(source data verification,
> on-site visit, 사이트 조치 등)은 ICH E6(R2/R3) 및 해당 SOP에 따라
> **자격을 갖춘 담당자**(임상시험 모니터·의학 전문가·통계 전문가 등)가
> 수행해야 합니다.

---

## 도메인 / 카테고리

- **도메인**: DM (당뇨병) — T1DM/T2DM RCT
- **카테고리**: 인체실험 도구 — RCT 데이터 품질 감시 (RBQM / central
  statistical monitoring)
- **2026 Metabolic Daily Idea** 파이프라인 산출물 (2026-05-19, idea #1)

## 한 줄 요약

당뇨 RCT의 누적 데이터(HbA1c·FPG·SMBG·CGM·체중·AE)를 받아 사이트별
자릿수 선호·CGM trace 무결성·과분산/과소분산·implausible 종단 궤적을
자동 탐지하고, 사이트 위험점수·KRI 대시보드와 ICH E6 형식 central
monitoring 리포트를 생성하는 Streamlit 도구.

---

## 핵심 기능 (5개)

### ① 누적 데이터 ingest + KRI 산출
visit 단위 CSV(HbA1c·FPG·SMBG·CGM 요약·체중·AE)를 import 하여
사이트별 **KRI(Key Risk Indicator)** — 결측율·visit 지연·장기지연율·
환자당 AE 보고율 — 를 산출하고, 코호트 내 z-score 표준화로 종합
위험점수와 **risk heat map** 을 생성합니다.

### ② 자릿수 선호 (digit preference) 탐지
HbA1c **소수 첫째자리** 와 FPG **정수 끝자리** 분포를 균등분포 대비
**chi-square 검정** 합니다. 특정 자릿수(흔히 0·5)가 과대표집된 사이트를
자동 플래그 — 데이터 반올림 습관·기록 오류·조작 가능성을 시사.

### ③ CGM trace 무결성 check
CGM raw trace(24h, 15분 간격 96점) 단위로:
- **flatline**: 센서 고정값 연속 (표준편차 < 2.0)
- **복사 trace**: 사이트 내 환자 간 거의 동일 trace (Pearson r > 0.999)
- **implausible 변화율**: 인접 15분 180mg/dL 초과 점프 (생리적 불가능)
- **implausible TIR**: 전 구간 in-range 인데 변동성이 비현실적으로 작음

### ④ 사이트 과분산/과소분산 + 종단 plausibility
- 사이트별 잔차 분산을 전체 코호트와 비교 (분산비 < 0.4 과소, > 2.5 과분산)
- HbA1c·FPG·SMBG·체중 평균 프로파일에 대한 **Mahalanobis 거리** 기반
  다변량 outlier site 탐지
- 생물학적으로 불가능한 HbA1c **종단 급변**(12주 환산 3.0%p 초과) 플래그

### ⑤ Central Monitoring 리포트
사이트 risk 순위·플래그된 패턴·권고 조치를 **ICH E6 형식**의
텍스트/HTML 리포트로 생성·다운로드.

---

## 기술 스택

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

- `app.py` — Streamlit 메인 진입점 (5개 기능을 탭으로 구성)
- `analysis.py` — 핵심 분석 로직 모듈 (streamlit 미사용, CLI 검수 가능)
- `data/generate_synthetic.py` — 합성 다기관 trial 데이터 생성 스크립트
- `data/*.csv` — 사전 생성된 합성 데이터 (커밋 포함)

---

## 실행 방법

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

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

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

브라우저에서 앱이 열리면 좌측 사이드바에서 **"합성 데모 데이터 사용"**
(기본) 또는 **"CSV 업로드"** 를 선택합니다.

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

```bash
python3 analysis.py        # central monitoring 리포트를 콘솔 출력
```

---

## 합성 데이터 구성

`data/generate_synthetic.py` 가 다기관 당뇨 RCT 를 모사합니다.

| 파일 | 내용 | 규모 |
|------|------|------|
| `sites.csv` | 사이트 메타 (국가, 환자 수, ground-truth 라벨) | 12 사이트 |
| `visits.csv` | visit 단위 종단 데이터 (HbA1c·FPG·SMBG·체중·CGM 요약) | 1,080 레코드 |
| `cgm_traces.csv` | 환자-visit 단위 CGM 96점 raw trace | 1,080 trace |
| `adverse_events.csv` | 이상반응(AE) 기록 | ~270 레코드 |

**조작 시그널 삽입 사이트** (검출 검증용):
- **SITE_07** — 자릿수 선호(HbA1c 0/5 편향, FPG 끝자리 0 편향) +
  CGM flatline + CGM 과소분산
- **SITE_12** — CGM trace 복사(환자 간 동일 trace) + implausible
  종단 급변 + AE 과소보고
- 나머지 10개 사이트(SITE_01~06, 08~11)는 정상

도구가 두 조작 사이트를 각각 MEDIUM/HIGH 위험으로 정확히 분리하고,
정상 사이트에는 신호가 발생하지 않는 것을 확인할 수 있습니다.

---

## 검수 체크리스트

- [ ] `python3 -c "import ast; ast.parse(open('app.py').read())"` — 구문 OK
- [ ] `python3 -c "import ast; ast.parse(open('analysis.py').read())"` — 구문 OK
- [ ] `python3 -c "import ast; ast.parse(open('data/generate_synthetic.py').read())"` — 구문 OK
- [ ] `python3 data/generate_synthetic.py` 실행 → 4개 CSV 생성
- [ ] 생성된 CSV 4개 pandas 로드 성공
- [ ] `import analysis` 시 streamlit 미로딩 (CLI 검수 가능)
- [ ] `python3 analysis.py` 실행 → central monitoring 리포트 출력, exit 0
- [ ] SITE_07·SITE_12 가 위험 사이트로 탐지, 정상 사이트 false-positive 0건
- [ ] `streamlit run app.py` 실행 → 5개 탭 정상 렌더

상세 검수 로그는 `QA.md` 참조.

---

## 출처 / 참고

- **ICH E6(R2)** — Good Clinical Practice, Section 5.0 *Quality
  Management* / Section 5.18 *Monitoring* (risk-based monitoring 도입)
- **ICH E6(R3)** — Good Clinical Practice 개정판, Quality by Design 및
  central monitoring 강화
- **FDA Guidance (2013)** — *Oversight of Clinical Investigations — A
  Risk-Based Approach to Monitoring* (RBM)
- **TransCelerate RBM** — Risk-Based Monitoring 방법론, KRI 개념 참고
- CGM TIR 기준(목표범위 70–180 mg/dL): Battelino et al., *Diabetes
  Care* 2019 international consensus 참고
- 평균혈당-HbA1c 환산: ADAG study (Nathan et al., *Diabetes Care*
  2008) — mean glucose ≈ 28.7 × HbA1c − 46.7

> 본 도구의 임계값(분산비 0.4/2.5, chi-square p<0.001, 종단 변화
> 3.0%p/12주 등)은 데모용 기본값이며, 실제 적용 시 해당 trial의
> 통계 분석 계획·SOP에 맞춰 자격을 갖춘 담당자가 조정·검증해야 합니다.