# CumulMetaDelta-Kor / 큐뮬메타델타워치코어

> **참고용 / 연구용 (research / reference only — NOT for clinical decisions).**
> 본 도구는 **합성(synthetic) 데모 데이터**로만 동작합니다. 실제 임상시험 결과가 아니며,
> 어떠한 진료·처방 의사결정에도 사용해서는 안 됩니다.

누적 메타분석(cumulative meta-analysis) 기반 당뇨 약물군 RCT **임계전이(threshold-transition) 알림** MVP.

---

## 1. 목적 (Purpose)

당뇨 약물군 RCT가 누적될 때, **(약물군 × 사전등록 아웃컴) 셀(cell)** 단위로 풀링된 효과추정치를
지속적으로 재계산하고, 새 RCT가 들어와 **임계선을 넘는 순간에만** 알림을 발생시킨다.
"또 하나의 trial 요약"이 아니라, **누적 증거 상태가 *바뀌는 순간*** 만 큐레이션하는 것이 핵심.

- **Domain:** DM (당뇨)
- **Category:** 연구 알림 (research-alert / cumulative-meta curation)
- **Entry point (검수 대상):** `main.py` — Python 3 CLI, **완전 오프라인 / 합성 데이터**

## 2. 셀 구조 (Drug-class × Outcome matrix)

| 축 | 값 (데모) |
|----|-----------|
| 약물군 (drug_class) | GLP-1RA, SGLT2i, finerenone (ns-MRA), dual/triple agonist |
| 아웃컴 (outcome) | MACE, HHF(심부전입원), renal_composite, mortality |

각 셀은 연도순으로 정렬된 trial들의 **누적 forest**를 보유한다.

## 3. 기능 (Features)

1. **약물군 × 아웃컴 매트릭스** — 각 셀이 누적 forest(trial들의 풀링 추정치)를 유지.
2. **신규 RCT 인제스션** — `data/trials.json`(합성/mock)에서 후보 trial이 해당 셀에 진입 → 재계산. (네트워크 없음)
3. **누적 delta 알림** — 새 trial 추가 *전/후*의 pooled RR/HR, 95% CI, I², tau², prediction interval을 비교해
   **전이 이벤트만** 발생:
   - **significance cross** — 풀링 95% CI가 null(=1.0)을 새로 제외/포함
   - **I² 이질성 밴드 변화** — low ↔ moderate ↔ substantial ↔ considerable
   - **prediction interval의 null 교차 변화**
4. **GRADE certainty 전이** — inconsistency(I²) / imprecision(CI null 교차) / publication bias(Egger) 재평가 →
   certainty 등급(High/Moderate/Low/Very low) 상승·하락 flag.
5. **Source/audit trace** — 모든 forest point가 출처 trial(trial_id, name, source, n, effect)로 역추적됨.

## 4. 메타분석 수학 (직접 구현, 순수 stdlib)

`statsmodels`/`scipy` **불필요**, numpy도 사용 안 함 (`math` 모듈만):

- 효과크기 변환: ratio measure(HR/RR) + 95% CI → log scale + SE
  (`SE = (ln(CI_high) − ln(CI_low)) / (2 × 1.959964)`)
- **Inverse-variance fixed effect**
- **DerSimonian–Laird random effects** — Cochran's Q, τ²(tau²), I²
- **HKSJ (Hartung–Knapp–Sidik–Jonkman)** 분산보정 → random-effects pooled CI (소수 trial에서 더 보수적)
- **95% prediction interval** (random effects)
- **Egger's regression test** — 소규모연구/출판편향 신호 (k ≥ 4에서만 평가)

t 임계값은 내장 테이블+보간, 정규분포 꼬리확률은 `math.erfc`로 구현 (외부 의존성 0).

## 5. 실행법 (Usage)

```bash
# 도움말
python3 main.py --help

# 기본/데모: 합성 trial 시퀀스를 스트리밍하며 전이 알림만 출력
python3 main.py
python3 main.py --demo

# 셀 목록
python3 main.py --list

# 단일 셀: 누적 forest 전체 + 알림 로그
python3 main.py --class SGLT2i --outcome HHF
python3 main.py --class GLP-1RA --outcome MACE

# 다른 데이터 파일 사용
python3 main.py --data path/to/other_trials.json
```

(선택) Streamlit UI — **검수 대상 아님**:
```bash
pip install streamlit   # (선택, 전역설치 불필요 환경에서는 생략 가능)
streamlit run app.py
```

## 6. 검수 체크리스트 (Verification checklist)

| # | 항목 | 명령 |
|---|------|------|
| 1 | 문법 파싱 | `python3 -c "import ast; ast.parse(open('main.py').read())"` |
| 2 | help 동작 | `python3 main.py --help` |
| 3 | 전이 알림 실제 발생 | `python3 main.py --demo` / `python3 main.py --class SGLT2i --outcome HHF` |
| 4 | (app.py 존재 시) 문법 파싱 | `python3 -c "import ast; ast.parse(open('app.py').read())"` |

상세 실행 로그는 `QA.md` 참조. 데모에서 **SGLT2i × HHF** 셀은 T004(2020) 추가 시
풀링 95% CI가 null을 새로 제외하는 **SIGNIFICANCE CROSS** 전이를 명확히 발생시킨다.

## 7. 데이터 출처 (Data provenance)

- `data/trials.json` 은 **합성(synthetic) 데모 데이터**다.
- 개념적으로는 *공개 RCT 메타데이터*(약물군별 CVOT/renal trial의 effect size + 95% CI, 발표연도)를
  모사하도록 구성했으나, **수치는 전이 이벤트 시연을 위해 절차적으로 만든 가짜 값**이다.
- 실제 trial명(EMPA-REG, LEADER, FIDELIO 등)은 `MOCK-…(synthetic)` 형태로만 *연상*시키며,
  보고된 실제 추정치와 일치하지 않는다.
- 실데이터 연동 시: 동일 스키마(`trial_id, drug_class, outcome, year, trial_name, effect, ci_low, ci_high, n, source`)로
  공개 메타데이터를 채우면 그대로 동작한다.

## 8. 디스클레이머 (Disclaimer)

본 소프트웨어는 **연구·교육·방법론 시연** 목적이다. 출력되는 모든 풀링 추정치·알림은
합성 데이터에 기반하며, **임상적 판단·진료지침·처방 결정의 근거로 사용할 수 없다.**
실제 의사결정은 반드시 원논문, 정식 메타분석, 진료지침, 그리고 임상 전문가의 판단을 따른다.