# 서로게이트회귀워치코어 / SurrogacyMetaReg-Kor

> **참고용·연구용 (research / reference only).**
> 대리지표(surrogate)의 타당성은 본질적으로 불확실합니다. 이 도구의 어떤 출력도
> 규제(regulatory) 또는 임상(clinical) 의사결정에 사용해서는 안 됩니다.
> **과신(over-confidence)은 이 주제에서 안전(safety) 문제입니다.** 데이터가
> 희박(sparse)하고 시간지연(time-lagged)되어 있어 단일 trial 하나가 결론을 크게
> 흔들 수 있습니다. R² 가 높게 나와도 반드시 LOO 민감도와 sparsity 경고를 확인하세요.

## 목적 (Purpose)

MASLD/MASH 영역에서 **대리지표(surrogate endpoint) × 임상결과(hard outcome)** 쌍마다
**trial-level surrogacy meta-regression** 을 유지하고, 새로 들어온 trial-level 데이터가
대리지표의 **신뢰도(reliability)를 강화/약화**시킬 때만 알림을 발생시키는 오프라인 MVP.

- **도메인 (Domain):** MASLD (대사성간질환 / metabolic dysfunction-associated steatotic liver disease)
- **카테고리 (Category):** 연구 알림 (research-alert / curation)

각 쌍에 대해 다음을 산출합니다:

- 가중최소제곱(weighted least squares) **trial-level meta-regression** (각 점 = 한 RCT의
  (대리지표 치료효과, 동일 trial 의 임상결과 치료효과))
- **trial-level R²**
- **기울기(slope) + 표준오차(SE) + 95% 신뢰구간(CI)**
- **surrogate threshold effect (STE)** — 예측 상한이 benefit 경계(0)를 가로지르는 최소
  대리지표 효과
- **prediction interval** (새 trial 예측 불확실성)
- **leave-one-trial-out (LOO) 민감도** — 데이터가 희박하므로 점 하나의 영향이 큼

## 대상 대리지표 / 임상결과 (Surrogates / Hard outcomes)

- **Surrogates:** fibrosis ≥1-stage improvement, MASH resolution, MRI-PDFF ≥30% decrease,
  FAST / FIB-4 change
- **Hard outcomes:** cirrhosis progression, transplant, liver-related death, HCC, MELD

데모 데이터에 포함된 쌍(`data/pairs.json`):

| pair id | surrogate | hard outcome | 의도된 동작 |
|---|---|---|---|
| `PDFF/cirrhosis` | MRI-PDFF ≥30% decrease | cirrhosis progression | R² 가 임계(0.7)를 **넘어 강화되고 유지**됨 |
| `fibrosis/liver-death` | fibrosis ≥1-stage | liver-related death | 조밀한 강한 신호, 신뢰 후보로 유지 |
| `FAST/HCC` | FAST score change | HCC | trial 3개뿐 — **too sparse / low-confidence** 유지 |
| `MASH-resolution/transplant` | MASH resolution | transplant | slope CI / R² 가 임계 근처에서 진동 |

## 기능 (Features)

1. **대리지표 × 임상결과 레지스트리(매트릭스)** — `--registry`
2. **Trial-level 데이터 수집** — `data/pairs.json` 의 합성/mock 파일에서 로드
   (네트워크 없음). 각 점은 사용자가 직접 검증 가능한 (surrogate effect, outcome
   effect, weight) 튜플.
3. **Meta-regression 재계산** — 가중회귀 → R², STE, slope+CI, prediction interval.
   trial 누적 시 BEFORE vs AFTER 비교(`--demo` 스트리밍).
4. **신뢰도 전이 알림** — R² 가 임계(0.7) 통과/이탈, STE 가 임상달성범위 진입/이탈,
   slope CI 가 0 제외/포함 → **신뢰도 변화 이벤트만** emit.
5. **불확실성 시각화/보고** — LOO 민감도 + sparsity/funnel 경고로 과신 방지.

## 실행법 (Usage)

순수 Python 3 stdlib 만 사용합니다 (numpy 불필요; 있으면 감지만 하고 계산은 동일한
stdlib 경로 사용). 네트워크/유료 API/전역 pip 설치 불필요.

```bash
cd "/Users/sangjoonpark/claude daily project/2026 metabolic daily idea/projects/2026-06-04-3-surrogacy-meta-reg-kor"

python3 main.py                          # 기본=데모: 전 쌍 스트리밍 + 전이 알림
python3 main.py --demo                   # 위와 동일
python3 main.py --registry               # 쌍 매트릭스 요약
python3 main.py --pair "PDFF/cirrhosis"  # 한 쌍 상세 + 알림로그 + LOO 민감도
python3 main.py --list                   # 사용 가능한 쌍 id 목록
python3 main.py --help                   # 사용법
python3 main.py --data /path/to/other.json   # 다른 데이터 파일 사용
```

## 데이터 출처 (Data source)

`data/pairs.json` 의 모든 수치는 **합성(synthetic) 데모 데이터**입니다. 실제 trial
데이터가 아닙니다. 구조와 시나리오는 공개된 MASH/MASLD trial 및 surrogacy
meta-analysis 의 **개념(trial-level surrogacy, STE, prediction interval, sparsity)**
을 본떠 만들었으나, 특정 시험·논문의 실제 수치를 옮긴 것이 아닙니다. 실제 사용
시에는 검증된 trial-level 추정치(치료효과 및 분산)로 교체해야 합니다.

효과 스케일: x, y 는 비교 가능한 표준화 로그 스케일(예: 치료-대조 log HR/OR 차이)
상의 값으로 간주합니다. y<0 = 임상결과 감소(benefit). weight = 임상결과 추정치의
역분산 정밀도(1/SE²) 유사값.

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

자세한 실행 로그는 `QA.md` 참조.

- [x] `python3 -c "import ast; ast.parse(open('main.py').read())"` 통과
- [x] `python3 main.py --help` 실행 및 usage 출력
- [x] 데모/단일쌍 모드에서 **reliability 전이 알림 발생**(`PDFF/cirrhosis` 가 R²
      임계를 넘어 강화)
- [x] sparse 쌍(`FAST/HCC`)에서 **sparsity / LOW-CONFIDENCE 경고 표시**
- [x] `data/*.json` 파싱 성공

## 방법론 주의 (Methodological caveats)

- trial-level surrogacy 는 **개별 환자 수준이 아니라 trial 수준**의 연관입니다.
  높은 trial-level R² 도 인과적 surrogate 타당성을 보장하지 않습니다.
- 점 개수가 적을 때(n < 4) R²·CI 는 신뢰할 수 없으며, 도구는 이를 **TOO SPARSE**로
  표시합니다. n ≤ 5 면 funnel/publication-bias 평가가 불가하여 **SPARSITY WARNING**
  을 띄웁니다.
- STE 는 예측구간 상한이 benefit 경계를 가로지르는 지점으로 정의했으며, 데이터·가정에
  매우 민감합니다. 임상달성범위(achievable range)는 데이터 파일에서 쌍별로 지정합니다.
- 본 MVP 는 의료기기/임상결정 지원도구가 아닙니다.