# DKDComboMiner (디케이디콤보마이너)

> **Research-use only. Not for clinical decision-making.**
> 본 도구는 연구용·참고용입니다. 임상의사결정에 직접 사용하지 마십시오.
> 생성된 가설은 IRB 승인·전문가 검토를 거친 후에만 활용하십시오.
> All data are synthetic/mock; no external network calls are performed.

## 목적
DKD(당뇨병성 신증) 연구의 ~70,000개 (drug-combo × KDIGO stage × biomarker × population) cell 중
- 문헌 근거가 적고 (literature gap)
- 한국 사이트 기반 IIS(연구자 주도 시험) 설계가 가능하며
- 기전적으로 타당하고
- KDIGO 2024 권고 강도가 뒷받침되며
- FAERS 안전 신호 부담이 낮은
"미탐색 cell"을 자동 ranking하여 grant-ready / KDA·KSAD abstract 초안까지 산출.

## 도메인 / 카테고리
- 도메인: **DM (당뇨신증 약물조합)**
- 카테고리: **연구 아이디어 생성** (가설 생성 + 문헌 갭 분석 + 온톨로지) — Friday rotation
- 대상 사용자: 한국 내분비내과·신장내과 임상연구자(KSAD·KDA DKD task force·대한신장학회 ~600명), 닥터앤서 3.0 당뇨 sub-task DKD 모듈 연구자, FLOW·EMPA-KIDNEY·FIDELIO/FIGARO 후속 RWE study PI

## 핵심 기능
1. **DKD ontology**
   - 약물 23종 (SGLT2i 5 + GLP-1RA 5 + MRA 4 + RAS blocker 4 + adjunct candidate 5)
   - KDIGO 2024 G1A1 ~ G5A3 18 cell
   - biomarker 7종 (UACR, eGFR slope, FGF-23, suPAR, KIM-1, NGAL, UACR variability)
   - population 8종 (T1DM/T2DM/MODY × 한국 lean/non-albuminuric × HFrEF/HFpEF/ASCVD/retinopathy)
2. **문헌·trial 채굴 (synthetic)**
   - PubMed 결과 수·5년 추세를 SHA-256 기반 결정론적 mock으로 시연
   - ClinicalTrials.gov v2 한국 사이트 active count mock
   - FAERS PRR/ROR class-level + combo synergy caution mock
   - KDIGO 2024 권고 강도 (A/B/C × 1/2)
3. **한국 공개 코호트 메타데이터 매핑**
   - K-DPP, KNOW-CKD, NHIS-NSC, HIRA, KDA registry 합성 메타데이터
   - biomarker coverage × 사이트 수 × 인구학 prevalence × stage difficulty 결합 → KR IIS feasibility score
4. **미탐색 cell ranking**
   - 가중합: gap(0.20) + trend(0.10) + trial_gap(0.10) + KDIGO(0.15) + mechanism(0.20) + feasibility(0.20) − FAERS_penalty(0.15)
5. **출력**
   - top-N hypothesis card (Markdown)
   - grant-ready specific aims (top-1)
   - KDA / KSAD 학술대회 abstract 250 word (한국어 + 영문)
   - 선택적 CSV dump (--csv)

## 실행
```
# 기본 (top 50)
python3 main.py

# top 100, 별도 출력 파일
python3 main.py --top 100 --output outputs/my_run.md

# biomarker / population / stage 필터링
python3 main.py --top 30 --biomarkers UACR,EGFRSLOPE --populations T2DM_NONALB,T2DM_LEAN

# 3-drug 조합까지 (대규모 — 수십만 cell)
python3 main.py --top 20 --max-combo 3

# CSV 덤프 (전체 ranked cells; ~20MB at max-combo=2)
python3 main.py --top 50 --csv outputs/all.csv

# seed/메서드 정보만
python3 main.py --seed-info
```

## 사용 라이브러리
- 표준 라이브러리만 사용: `argparse`, `json`, `csv`, `dataclasses`, `pathlib`, `hashlib`, `itertools`, `math`, `sys`, `typing`
- **외부 의존성 없음.** pydantic / pandas / DuckDB 등 명세에 거론된 라이브러리는 더 무거운 production 버전에서 도입할 후보로만 README에 명시.
- 프로덕션 확장 시 후보: Streamlit (GUI), DuckDB (cell store 캐시), polars (CSV 가속), scipy (검정력)

## 데이터
모두 `data/` 하위 합성 데이터. 외부 API 호출 없음.
- `ontology.json` — 약물/stage/biomarker/population
- `pubmed_evidence.json` — synthetic seed 메타데이터
- `faers_signals.json` — class-level + combo-level synthetic caution
- `korea_cohorts.json` — K-DPP / KNOW-CKD / NHIS-NSC / HIRA / KDA-REG 합성 메타데이터

## 출력 샘플
- `outputs/run_top10.md` — 상위 10개 cell + grant aims + 한·영 abstract
- `outputs/run_top100.md` — 상위 100개 cell + grant aims + 한·영 abstract

## 검수 체크리스트
- [x] Python 구문 체크 통과 (`python3 -c "import ast; ast.parse(open('main.py').read())"`)
- [x] `python3 main.py --help` 정상 동작
- [x] JSON 데이터 파일 로드 가능
- [x] top-10 / top-100 샘플 실행 성공 (235,872 cell scored)
- [x] 외부 네트워크 호출 없음 (`requests`/`httpx`/`urllib` 사용 없음)
- [x] 디스클레이머 README + 모든 출력물에 명시

## 출처 / 디스클레이머
- 본 도구는 **연구용·참고용**입니다. 임상의사결정에 직접 사용하지 마십시오.
- 생성된 가설은 IRB 승인·전문가 검토를 거친 후에만 활용하십시오.
- 모든 PubMed 수·trial count·FAERS 신호·코호트 메타데이터는 **합성 mock**입니다 (실제 PubMed/CTG/FAERS API 호출 없음).
- KDIGO 2024 권고 강도, ontology 구조는 공개 가이드라인을 참고한 단순화 버전입니다 — 실제 권고문과 차이가 있을 수 있습니다.
- 한국 코호트(K-DPP·KNOW-CKD·NHIS-NSC·HIRA·KDA-REG) 가용성·feasibility score는 **시연용 합성값**이며, 실제 데이터 접근 가능성·계약·IRB 조건과 다릅니다.

## 라이선스 / 책임
이 코드와 데이터는 데모·연구 디자인 brainstorming 용도이며, 결과물의 의학적 정확성·임상 적합성을 보장하지 않습니다.