# CVOT-MACEAdjudicate-Kor (씨브이오티맥어드주디케이트-코어)

> **참고용 · 연구용 도구입니다. 임상 의사결정용이 아닙니다 (Not for clinical decision).**
> 본 도구는 T2DM CV outcome trial의 CEC(Clinical Events Committee) 운영을 위한
> 합성 데이터 기반 데모이며, 실제 환자 데이터/실제 임상시험 판정에 그대로 사용해서는 안 됩니다.

## 목적

T2DM(제2형 당뇨병) Cardiovascular Outcome Trial(CVOT)의 의심 MACE event packet을 받아
charter-driven 표준에 따라 자동 보조 분류·CEC 운영·sensitivity analysis까지
한 화면에서 표준 산출하는 standalone Streamlit 도구.

- **도메인**: DM (당뇨병)
- **카테고리**: 인체실험 도구 (RCT/observational study CEC 운영)
- **빌드일**: 2026-05-26

## 핵심 기능 5개

1. **Event packet ingest + de-identification + charter 매핑**
   - eCRF / ECG / troponin 시계열 / imaging metadata / discharge summary CSV 입력
   - 환자 식별자 SHA-256 hash, 날짜 site별 random shift, site mask
   - charter YAML 입력: 3/4/5-point MACE, Type 2 MI 포함 여부, HHF 정의, CV death 인과성

2. **UDM(Universal Definition of MI) 2018 MI Type 자동 보조 분류**
   - troponin 99th percentile URL 대비 rise/fall pattern
   - ECG(STEMI/NSTEMI), angiography(plaque rupture vs stable stenosis), 임상 정황
   - Type 1 (plaque rupture), Type 2 (supply-demand mismatch),
     Type 3 (sudden death pre-troponin), Type 4a (PCI), Type 4b (stent thrombosis),
     Type 4c (restenosis), Type 5 (CABG)

3. **Stroke · HF · CV death 분류 보조**
   - **AHA/ASA stroke**: ischemic / hemorrhagic / SAH / TIA
     (NIHSS, imaging, 24h 증상 지속 기준)
   - **ESC HF**: BNP / NT-proBNP, imaging, hemodynamic, diuretic IV, length-of-stay
   - **CV death 인과성**: MI / HF / arrhythmia / stroke / 기타 CV vs non-CV / SUD

4. **2-reader paired blinded adjudication + drift dashboard**
   - 사건별 random 2명 adjudicator blinded 배정, timer, 불일치 시 3rd reader/panel routing
   - **Adjudicator drift**: 시간 분기별 분류 분포 변화, Cohen's kappa 추이, 평균 turnaround
   - calibration round case 재배정, workload balancing

5. **Sensitivity analysis + DSMB·CSR-ready 리포트**
   - 3-point vs 4-point vs 5-point MACE endpoint count 비교
   - Type 2 MI 포함/제외별 endpoint count
   - DSMB-ready interim summary
   - CSR/manuscript supplementary `.docx` export
     (adjudicator kappa · discordance · drift · sensitivity table)

## 실행법

### 1. 가상환경 + 의존성 설치
```bash
cd "projects/2026-05-26-1-cvot-mace-adjudicate-kor"
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### 2. CLI 데모 실행 (의존성 설치 후)
```bash
python3 main.py --demo
```
- 합성 packet 30~50건을 로드
- UDM 2018 / AHA / ESC 분류 보조를 일괄 수행
- 2-reader adjudication 시뮬레이션
- kappa, drift, sensitivity 표를 콘솔에 출력
- `reports/` 폴더에 `.docx` 리포트 저장

### 3. Streamlit UI 실행
```bash
streamlit run app.py
```
- 좌측 사이드바: charter YAML 선택, packet CSV 업로드
- 탭 1: Ingest / De-ID
- 탭 2: 자동 분류 보조 (UDM/AHA/ESC/CV death)
- 탭 3: CEC 2-reader 워크플로우 + drift dashboard
- 탭 4: Sensitivity analysis + 리포트 생성

## 검수 체크리스트

- [ ] Python 구문(ast.parse) 통과
- [ ] `python3 main.py --help` 정상 출력 (의존성 미설치 환경에서도 argparse는 출력)
- [ ] `data/synthetic_packets.csv` 30~50건 로드 가능
- [ ] `python3 main.py --demo` 실행 시, 의존성 없으면 친절한 안내 메시지 출력
- [ ] 의학 디스클레이머가 README와 app.py 상단에 명시되어 있음
- [ ] 외부 네트워크 호출 없음 (offline standalone)

## 출처 / 표준 근거

- **UDM 2018** — Fourth Universal Definition of Myocardial Infarction
  (Thygesen K, et al. Circulation 2018; 138(20):e618–e651)
- **AHA/ASA Stroke** — An Updated Definition of Stroke for the 21st Century
  (Sacco RL, et al. Stroke 2013;44(7):2064–89)
- **ESC HF** — 2021 ESC Guidelines for the diagnosis and treatment of acute
  and chronic heart failure (McDonagh TA, et al. Eur Heart J 2021;42:3599–3726)
- **CEC charter 가이드** — Hicks KA, et al. 2017 Cardiovascular and Stroke
  Endpoint Definitions for Clinical Trials. JACC 2018;71(9):1021–1034.
- **DSMB 운영** — FDA Guidance for Clinical Trial Sponsors: Establishment and
  Operation of Clinical Trial Data Monitoring Committees (2006)

본 도구의 모든 합성 데이터는 알고리즘으로 생성된 가짜 데이터이며 실제 환자/시험 데이터를 사용하지 않습니다.

## 라이선스 & 안전

- 합성 데이터만 포함하므로 환자 정보 위험 없음.
- 임상 의사결정 / 실제 CEC 판정의 단독 근거로 사용 금지.
- 실제 사용 시: 사이트 IRB 승인, CEC charter 정식 채택, vendor 21 CFR Part 11 compliance 필요.