# EquityLens — 대사진료 형평성 격차 대시보드

> Obesity · DM · MASLD 코호트를 계층변수별로 집계해 처방·검사·이탈의
> 형평성 격차를 정량·시각화하는 **오프라인 단일 HTML 대시보드**.

⚠️ **참고용 · 연구용 도구입니다. 합성(synthetic) 데이터 기반이며 임상
의사결정을 대체하지 않습니다.** 형평성 지표는 방법론 시연 목적의 근사치입니다.

---

## 1. 목적
대사질환(비만·당뇨·MASLD) 진료에서 **누가 적정 약물·검사·추적관리를 덜 받는가**를
계층화(stratification) 관점에서 정량화한다. 환자 단위 코호트 CSV를 계층변수별로
집계해 처방률·검사 커버리지·12개월 추적유지율의 격차를 산출하고, 표준 형평성
지표(집중지수·SII·격차비)와 함께 시각화한다.

## 2. 도메인 / 카테고리
- **도메인:** Obesity · DM · MASLD
- **카테고리:** 웹기반 대시보드 (형평성 KPI 모니터링)
- **slug:** `equitylens`

## 3. 핵심 기능
1. **격차 히트맵** — 5개 핵심 지표(GLP-1 RA / SGLT2i 처방률, FIB-4·망막검진
   커버리지, 12개월 추적유지율) × 계층변수(소득분위 프록시·거주지·보험·연령·성별) 교차.
2. **형평성 지수** — 집중지수(Concentration Index), 슬로프지수(SII), 격차비
   (Disparity Ratio)를 자동 산출하고 95% 신뢰구간(정규근사 + 부트스트랩) 표시.
3. **이탈 격차(equity in attrition)** — 계층별 Loss-to-Follow-up 곡선
   (Kaplan–Meier 유사 step survival) 비교.
4. **What-if** — "최하위 계층을 전체 평균까지 끌어올리면 추가로 필요한 환자 수" 추정.
5. **프라이버시 가드** — 소셀 n<임계(기본 5) 마스킹.

## 4. 실행법
별도 설치·서버 불필요.

```
브라우저로 index.html 더블클릭 → 즉시 동작 (기본 합성데이터 자동 로드)
```

- 페이지 로드 시 `EMBEDDED_CSV`(합성 코호트)가 자동 로드되어 업로드 없이 데모가 표시됨.
- 상단 컨트롤에서 지표/계층변수/질환필터/마스킹 임계 변경.
- **사용자 CSV 업로드** 입력으로 자체 코호트 분석 가능(컬럼 구조는 아래와 동일해야 함).
- "기본 합성데이터로 복귀" 버튼으로 임베드 데이터 재로드.

## 5. 데이터
`data/cohort_synthetic.csv` (480행) — 전부 **합성**.

| 컬럼 | 설명 |
|---|---|
| `patient_id` | 환자 ID |
| `disease` | DM / Obesity / MASLD |
| `income_quintile` | 소득분위 프록시 Q1(최하)–Q5(최상) |
| `residence` | urban / rural |
| `insurance` | NHI(국민건강보험) / Medicaid(의료급여 프록시) |
| `age_group` | <40 / 40-64 / 65+ |
| `sex` | M / F |
| `glp1_rx` | GLP-1 RA 처방 여부 (0/1) |
| `sglt2i_rx` | SGLT2i 처방 여부 (0/1) |
| `fib4_done` | FIB-4 검사 시행 여부 (0/1) |
| `retinal_screen` | 망막검진 시행 여부 (0/1) |
| `retained_12m` | 12개월 추적유지 (1=유지, 0=이탈) |
| `ltfu_month` | 이탈 월(1–11), 유지 시 12(censored) |

격차는 **로지스틱 로그-오즈 조정**으로 주입(저소득·농촌·의료급여·고령·여성 계층에서
처방/검사/유지율이 체계적으로 낮음). 데이터 재생성:
```
python3 data/gen_cohort.py
python3 data/build_index.py   # CSV를 index.html에 다시 임베드
```

## 6. 형평성 지표 방법론 (출처)
- **집중지수 (Concentration Index, CI):** 사회경제적 순위로 정렬한 인구가중
  지표 농도. Wagstaff / O'Donnell 등 보건경제 형평성 측정 표준. 0=형평,
  양수=상위 계층 유리.
- **슬로프지수 (SII, Slope Index of Inequality):** 사회경제 순위(0–1) 대비
  지표율의 가중회귀 기울기 = 최하위→최상위 절대격차(%p). WHO Health Equity
  Monitor 권고 절대격차 지표. 부트스트랩(300회) 95% CI.
- **격차비 (Disparity Ratio):** 최고율 계층 / 최저율 계층. 로그비 정규근사 95% CI.
- **벤치마크 수준:** KNHANES(국민건강영양조사) 공개 요약통계 근사치(합성/근사).

## 7. 검수 체크리스트
- [x] `index.html` 존재 + HTML 구문 유효
- [x] Plotly CDN pinned 버전 1개만 (`plotly-2.27.0.min.js`)
- [x] CSV 행/열 로드 확인 (480행, 13열)
- [x] 계층별 격차가 데이터에 실재 (통계 확인 — `QA.md` 참조)
- [x] 페이지 로드 시 업로드 없이 즉시 동작 (임베드 데이터)
- [x] 소셀 n<5 마스킹 동작
- [x] 디스클레이머 README + index.html 양쪽 포함
- [x] 외부 네트워크 호출 없음 (Plotly CDN 외)

## 8. 제약 / 안전
- 오프라인 우선. 외부 유료 API 없음. CDN은 Plotly pinned 1개만.
- **의학적 안전성:** 본 도구는 참고용·연구용이며 임상 의사결정을 대체하지 않는다.

## 9. 산출물
```
2026-06-07-3-equitylens/
├── README.md
├── index.html                 # 단일 파일 대시보드 (CSV 임베드)
├── QA.md                       # 검수 로그
└── data/
    ├── cohort_synthetic.csv    # 합성 코호트 (480행)
    ├── gen_cohort.py           # 데이터 생성 스크립트
    ├── build_index.py          # CSV→index.html 임베드 빌드
    └── index_template.html     # 빌드 템플릿
```