# ObesityCVHypoMap (오베시티시브이하이포맵)

## 디스클레이머 (필수)

본 도구는 **연구용/참고용**입니다. 임상의사결정에 직접 사용하지 마십시오.
생성된 가설은 **IRB 승인과 전문가 검토를 거친 후에만** 활용하십시오.
항비만 약물의 CV outcome 권고는 **학회 가이드라인(KSSO/대한심장학회/AHA/ESC)을
우선시하십시오**. 본 저장소의 모든 PMID/NCT/DOI/PRR/카운트는 합성 mock입니다.

## 목적

항비만 약물 8+ × CV outcome subtype 11 (MACE 4 + HF 4 + AF 3) × baseline phenotype 5 ×
mediation pathway 5 의 6D 온톨로지에서 미탐색 cell을 ranking하고,
각 cell에 대해 mediation analysis framework + 한국 RWE/IIS 가능성 score +
grant-ready hypothesis card를 생성한다.

- **도메인**: Obesity (항비만약물 × CV outcome subtype × phenotype × mediation)
- **카테고리**: 연구 아이디어 생성 (가설 생성 + 문헌 갭 분석 + 온톨로지) — Friday rotation
- **대상 사용자**: SELECT/STEP-HFpEF/SUMMIT/SURPASS-CVOT/SURMOUNT-MMO 후속 RWE PI,
  KSSO·KDA·대한심장학회 비만의학·내분비·심혈관 연구자, 닥터앤서 3.0 비만 sub-task
  CV 모듈 연구자

## 핵심 기능 5개

1. **6D ontology**:
   - 약물 9종: semaglutide 2.4mg, liraglutide 3.0mg, tirzepatide, retatrutide,
     CagriSema, orforglipron, MariTide, setmelanotide, pioglitazone
   - MACE 4: MI, ischemic stroke, hemorrhagic stroke, CV death
   - HF 4: HFrEF, HFpEF, HFmrEF, RV dysfunction
   - AF 3: paroxysmal, persistent, permanent
   - Phenotype 5: T2DM±, sleep apnea±, sarcopenic obesity, post-bariatric,
     lean diabetic Asian
   - Mediation 5 (각 surrogate 포함): weight loss(% TBWL), glucose(ΔHbA1c),
     anti-inflammatory direct(hs-CRP/IL-6/GDF-15), natriuresis(NT-proBNP/eGFR),
     autonomic(HR/HRV)
2. **4종 데이터 채굴 (모두 mock)**: PubMed query bank, ClinicalTrials.gov v2 active
   trial + 한국 사이트, FAERS PRR/ROR signal, medRxiv/bioRxiv preprint signal
3. **미탐색 cell ranking** (현재 9 drugs × 11 cv × 5 pheno = 495 cell): 가중 score
   = 1.5·gap + 1.2·FAERS + 1.0·trial+한국 + 0.8·preprint + 0.7·mediation + 1.3·korea_rwe
4. **Mediation analysis framework**: 각 cell에 baseline-W12-W24-W52 surrogate
   측정 권고, 분석 모델 권고 (VanderWeele 2014 또는 Imai-Keele-Tingley natural
   direct/indirect effect), 검정력 simulation (HR 0.80, alpha 0.05, 3-year FU,
   incidence-기반 toy model), 5 mediation 동시 분리 가능성
5. **출력**: top-N hypothesis card (Markdown), grant-ready Markdown 1편,
   AHA abstract (영문 ~250 word), KSSO abstract (한국어 ~250 단어)

## 실행법

```bash
# help
python3 main.py --help

# 전체 cell 중 top 50 카드 출력
python3 main.py --top 50

# top 50 + 4종 markdown 산출물 outputs/ 에 저장
python3 main.py --top 50 --write

# 한국 허가 약물만, semaglutide 검색
python3 main.py --korea-only --drug semaglutide --summary

# 점수 요약만
python3 main.py --top 25 --summary
```

표준 라이브러리만 사용. 별도 `pip install` 불필요. Python 3.9+.

## 디렉터리

```
2026-05-01-3-obesity-cv-hypo-map/
  main.py              CLI 엔트리포인트
  data/
    drugs.json         항비만 약물 9 (mock 메타데이터)
    cv_subtypes.json   CV outcome 11
    phenotypes.json    baseline phenotype 5
    mediations.json    mediation pathway 5 + surrogate marker
    evidence.json      mock PubMed/CTG/FAERS/preprint
  outputs/
    top_hypothesis_cards.md
    grant_draft.md
    aha_abstract.md
    ksso_abstract.md
  README.md
  QA.md
```

## 검수 체크리스트

- [x] `python3 -c "import ast; ast.parse(open('main.py').read())"` 통과
- [x] `python3 main.py --help` 정상 동작 (표준 라이브러리만 사용)
- [x] 5개 JSON 데이터 파일 모두 `json.loads` 통과
- [x] `python3 main.py --top 50 --write` 실행 시 outputs/ 4개 파일 생성
- [x] `--korea-only`, `--drug`, `--summary` 필터 동작
- [x] 모든 출력물에 디스클레이머 포함

## 출처/디스클레이머 (재게시)

- 모든 PMID/NCT/DOI/PRR/카운트는 **합성 mock**. 외부 네트워크 호출 없음.
- 약물명·trial program명(SELECT/STEP/SUMMIT/SURPASS/SURMOUNT 등)은 공개 학회·임상시험
  레퍼런스이며 본 도구가 결과를 재구성하지 않는다.
- 한국 RWE 가능성 score는 NHIS/HIRA 발생률 추정치(toy)와 약물 한국 허가 여부에 기반한
  rule-based 점수이며 실제 코호트 N이 아니다.
- 검정력 시뮬레이션은 toy model (HR 0.80, alpha 0.05, 3-year FU, fixed-budget N=5000
  power 추정)이며, 실제 sample size 계산은 PASS/nQuery/R `powerSurvEpi` 등으로
  재계산해야 한다.
- 본 도구의 가설은 **연구 가설 생성을 돕기 위한 것**이며, 인용/임상 권고를 위한
  것이 아니다.