# DMCausalTriangulate-Kor (디엠코절트라이앵귤레이트코어)

> **⚠️ 본 도구는 연구 가설 생성·문헌 갭 분석 목적의 연구용·교육용 도구입니다.
> 임상의사결정·환자 진료에 직접 사용해서는 안 되며, 모든 분석 결과는 추가 검증이 필요합니다.**

T2DM 약물(SGLT2i · GLP-1RA · tirzepatide · DPP-4i · metformin 등) × 다양한 outcome
(MACE · HHF · DKD · 암 · 인지 · sarcopenia · DKA · pancreatitis · MTC · suicidality 등)
격자에 대해 5-design(RCT · observational · target-MR · ex vivo · within-subject) effect
추정치를 한 grid에 통합하고, design 간 concordance/discordance를 정량화하고,
discordance bias direction을 자동 진단하고, triangulation-targeted 후속 연구
가설·설계 카드를 생성하는 standalone 도구.

이론적 토대: **Lawlor, Tilling, Davey Smith 2016 *IJE* 5-criterion triangulation
framework**, Hill 1965 인과성 기준 보강, Hernán target trial emulation,
classical bias direction taxonomy.

## 도메인

- 1차 도메인: **DM (T2DM 약물 인과추론)**
- 사용자: causal-epidemiology 연구자 · CVOT meta-analyst · target validation BD/R&D ·
  HTA(보험약가) · 규제과학자 · systematic reviewer · OpenClaw 당뇨 약물 재조합
  후보 BD · 닥터앤서 3.0 sub-task evidence robustness layer

## 핵심 기능 (5개)

1. **5-design effect ingest + 약물-outcome 온톨로지** — ATC class × outcome MeSH 격자
   (CSV 입력, 사용자 업로드 지원).
2. **5-design triangulation grid + concordance metric** — 방향 일치, CI 중첩,
   coverage를 가중합한 0–1 concordance score.
3. **Lawlor 2016 5-criterion 자동 채점** — internal validity / external validity /
   bias direction known / bias direction differs / triangulation strength (각 0–2).
4. **Discordance bias direction 자동 진단** — confounding by indication ·
   healthy-user · survivor · detection · protopathic · canalization · pleiotropy ·
   dose-translation · off-target · external validity taxonomy + rule-based 진단.
5. **Triangulation-targeted 후속 연구 design 카드 (7가지)** — active comparator
   new-user / target-MR pQTL IV / negative control outcome / 2x2 factorial RCT /
   N-of-1 crossover / 자연실험 IV / bridging ex vivo. Markdown / docx 리포트
   export (python-docx 없으면 .md fallback).

## 실행

### 1) CLI (의존성 최소 — Python 3 stdlib만)

```bash
python3 main.py --help
python3 main.py --grid                            # 전체 쌍 요약
python3 main.py --pair "SGLT2i" "CV death"        # 특정 쌍
python3 main.py --pair "DPP-4i" "pancreatitis"    # 대표적 discordance
python3 main.py --discordant --top 5              # 최상위 discordant 쌍
python3 main.py --pair "metformin" "cancer" --report-md out.md
python3 main.py --grid --report grid.json
```

### 2) Streamlit UI

```bash
pip install -r requirements.txt
python3 -m streamlit run app.py
# 또는
streamlit run app.py
```

브라우저에서 `http://localhost:8501` 열림. 사이드바에서 drug class /
outcome category 필터, 사용자 CSV 업로드 가능. 탭: 격자 개요(heatmap) /
쌍 분석(grid + Lawlor radar + bias diagnosis + design 카드 deck) /
Discordance 랭킹 / Markdown 리포트 다운로드.

## 데이터

`data/effects_sample.csv` — 52행, 5-design × 대표 약물-outcome 쌍.
공개 RCT(EMPA-REG · CANVAS · DECLARE · CREDENCE · DAPA-CKD · LEADER ·
SUSTAIN-6 · REWIND · SAVOR-TIMI · TECOS · EXAMINE · UKPDS · STEP-1 ·
SURMOUNT-1 · SYNERGY-NASH 등), 공개 observational meta-analysis
(EMPRISE · CPRD · NHIS-NSC · TriNetX), 공개 drug-target MR
(SLC5A2 · GLP1R · DPP4 pQTL), 공개 ex vivo 출처. 자세한 출처는
`data/README.md` 참고.

## 디렉토리 구조

```
projects/2026-05-29-1-dm-causal-triangulate-kor/
├── README.md
├── app.py                  # Streamlit UI
├── main.py                 # CLI (stdlib만)
├── requirements.txt
├── QA.md
├── triangulation/
│   ├── __init__.py
│   ├── ontology.py         # 약물·outcome 온톨로지 로더, pair 정규화
│   ├── grid.py             # 5-design grid + concordance metric
│   ├── lawlor.py           # Lawlor 2016 5-criterion 자동 채점
│   ├── bias.py             # bias direction taxonomy + 진단 rule
│   ├── designs.py          # 7가지 후속 design 카드
│   └── report.py           # markdown/docx 리포트
└── data/
    ├── README.md           # 데이터 출처
    ├── drug_ontology.csv
    ├── outcome_ontology.csv
    └── effects_sample.csv  # 52행, 5-design x 대표 쌍
```

## 검수 체크리스트

`QA.md` 참고. 요약:

1. 모든 Python 파일 AST parse OK
2. CSV 무결성: 52행, 5 designs, 5 drug classes
3. `python3 main.py --help`, `--grid`, `--pair`, `--discordant` 모두 정상
4. Streamlit 미설치 환경에서도 main.py 정상 동작 (lazy import)
5. README + app.py 첫 화면 디스클레이머 명시 확인

## 한계

- effect 추정치는 공개 자료 큐레이션 starter set — 실제 사용 시 자체 큐레이션 필수.
- concordance metric은 (direction agreement + CI overlap + coverage)의 가중합으로
  의도적으로 단순화. 정식 메타-분석/혼합효과 prediction interval은 statsmodels
  로 확장 가능.
- bias direction 진단은 rule-based — Lawlor 2016 framework의 알려진 패턴을 구현.
  자동으로 새 bias 패턴을 학습하지 않음.
- 7가지 design 카드의 표본수·추적기간은 spec-level 기본값. 실제 protocol design은
  통계학자·임상시험 designer 자문 필요.
- streamlit · plotly · pandas · python-docx 없이도 CLI 핵심 기능은 동작.

## 카테고리·핀포인트 정합성

- 카테고리: **연구 아이디어 생성** (가설 생성·문헌 갭 분석·온톨로지 기반 새 연구 도출).
- 핀포인트 충돌 없음 — DM Agent (환자/임상의 도구) · HELIOS · MASLDStager · Yggdrasil
  (일반 endocrinology paper KG) · GlyceSurrogate-Kor (within-RCT trial-level
  surrogacy) · DMRepurpRank-Kor (재포지셔닝 ranker) 와 모두 dimension/사용자/
  axis 자체 다름.
- 직전 15개 금요일과 차별 — cross-design epidemiologic triangulation (Lawlor·
  Davey Smith 2016 framework)의 도메인 응용. single-design discovery·single-
  design surrogacy validation과 메타-축 자체 다름.

## 참고문헌

- Lawlor DA, Tilling K, Davey Smith G. Triangulation in aetiological epidemiology.
  *International Journal of Epidemiology*. 2016;45(6):1866-1886.
- Hill AB. The Environment and Disease: Association or Causation?
  *Proc R Soc Med*. 1965;58:295-300.
- Hernán MA, Robins JM. Using Big Data to Emulate a Target Trial when a
  Randomized Trial is Not Available. *Am J Epidemiol*. 2016;183(8):758-764.
- Schmidt AF, et al. PCSK9 genetic variants and risk of type 2 diabetes:
  a mendelian randomisation study. *Lancet Diab Endo*. 2017;5(2):97-105.
  (drug-target MR template)