# ObesityRecruitFeas-Kor (오베시티리크루트피즈)

항비만 임상연구 모집 feasibility 계산기 — standalone MVP

## 목적

항비만(비만 치료제 RCT 등) 임상연구의 적격성 기준을 입력하면,
KNHANES(국민건강영양조사) 형식의 공개 microdata 추세를 모사한 합성
데이터셋에 적용하여 한국 성인 적격 모집단 규모, screen-fail율, 사이트별
모집 timeline을 시뮬레이션하는 feasibility 설계 보조 도구이다.

- **도메인**: Obesity (비만 / 비만대사질환)
- **카테고리**: 인체실험 도구 (RCT/관찰연구 설계·계산기)

## 핵심 기능 (5개)

1. **적격성 기준 빌더** — BMI 컷오프, 연령, 동반질환(T2DM·고혈압·이상지질혈증·MASLD
   대용지표·OSA 위험), 허리둘레, 제외 기준을 조합 → KNHANES형 가중표본에 적용해
   한국 성인 인구로 외삽한 적격 모집단 규모 + 95% 신뢰구간 산출.
2. **기준 민감도 분석** — BMI 컷오프 ±1, 연령 한계, 동반질환 요구 개수, 제외기준
   해제 등 각 기준을 단독으로 완화했을 때의 모집단 증가량을 tornado 차트로 제시
   → "가장 비싼 기준" 식별.
3. **screen-fail 예측** — 제외 기준 적용 전후 적격자 비율 차이로 예상 screen-fail율
   산출 + 제외기준별 단독 영향 분해 + 목표 등록 N 대비 필요 스크리닝 수 환산.
4. **모집 timeline 시뮬레이터** — 사이트 수·사이트당 월간 스크리닝 capacity·
   screen-fail율·사이트 가동 지연을 입력 → Monte-Carlo로 목표 N 도달 기간의
   P10/P50/P90 분포 산출.
5. **feasibility 리포트** — 적격 모집단·민감도·screen-fail·timeline을 프로토콜
   feasibility 섹션 형식의 국문 텍스트로 생성.

## 파일 구성

```
2026-05-17-2-obesity-recruit-feas-kor/
├── core.py                          # 핵심 계산 로직 (pandas/numpy만)
├── app.py                           # Streamlit UI
├── main.py                          # argparse CLI 진입점
├── data/
│   ├── generate_knhanes_synthetic.py  # 합성 microdata 생성 스크립트
│   └── knhanes_synthetic.csv          # 생성 산출물 (7,000행)
├── README.md
└── QA.md                            # 검수 로그
```

## 실행법

### 사전 준비 — 패키지

- 필수: `pandas`, `numpy` (core.py / main.py / 데이터 생성)
- 선택: `streamlit` (웹 UI app.py 사용 시)

설치되어 있지 않으면:

```
pip install pandas numpy        # CLI/core 용
pip install streamlit           # 웹 UI 용 (선택)
```

`pandas`/`numpy`가 없으면 `main.py` 실행 시 안내 메시지와 함께 종료한다.
`streamlit`이 없어도 CLI(`main.py`)로 모든 분석을 오프라인 수행할 수 있다.

### 1) 합성 데이터 생성 (최초 1회)

`data/knhanes_synthetic.csv`는 저장소에 포함되어 있으나, 재생성하려면:

```
cd data
python3 generate_knhanes_synthetic.py
```

seed가 고정되어 있어 항상 동일한 데이터가 생성된다.

### 2) CLI (Streamlit 불필요 — 오프라인 시연)

```
python3 main.py --help          # 옵션 도움말
python3 main.py --demo          # 예제 적격성 기준으로 전체 분석 출력
python3 main.py --bmi-min 30 --age-max 65 --target-n 150 --sites 8
python3 main.py --comorbidity t2dm --comorbidity htn --comorbidity-count 1
```

### 3) Streamlit 웹 UI

```
streamlit run app.py
```

사이드바에서 적격성 기준과 모집 설정을 조정하면 5개 탭(적격 모집단 /
기준 민감도 / screen-fail / 모집 timeline / feasibility 리포트)이 실시간
갱신된다.

## 합성 데이터 주의 (중요)

`data/knhanes_synthetic.csv`는 **실제 KNHANES 데이터가 아니다.** 실제
국민건강영양조사 microdata는 공개 다운로드/네트워크 접근이 제한되므로,
공개적으로 알려진 유병률 추세(아래)에 통계적으로 근접하도록 난수
생성한 **합성 데이터셋**이다. 도구 시연·방법론 검증 목적에 한해 사용해야
하며, 산출된 적격 모집단 추정치는 실제 인구 추정치로 해석할 수 없다.

근사 목표 추세 (생성 스크립트 기준):

| 지표 | 목표 | 합성 데이터 실측(가중) |
|---|---|---|
| 비만 (BMI>=25) | ~38% | 39.7% |
| 고도비만 (BMI>=30) | ~7% | 6.8% |
| T2DM | ~12-13% | 10.6% |
| 고혈압 | ~28-30% | 27.9% |
| 이상지질혈증 | ~38-40% | 37.4% |
| 현재 흡연 | ~18-20% | 19.6% |
| 최근 GLP-1RA 사용 | ~1-2% | 0.8% |

복합표본 설계는 단순 모사로, `weight` 컬럼(합 = 한국 성인 인구 약
4,400만 외삽 기준)과 Kish 근사 설계효과(deff)로 신뢰구간을 보정한다.

## 방법론 메모

- **적격 모집단**: 적격 boolean mask에 해당하는 행의 `weight` 합. 95% CI는
  가중 비율 p에 대해 유효표본(n/deff) 기반 이항 표준오차로 산출.
- **MASLD 대용지표**: KNHANES형 데이터에 영상검사가 없으므로 BMI>=25 + ALT
  상승(남>40, 여>35 U/L)을 보수적 대용지표로 사용.
- **OSA 위험**: 수면검사 부재 → STOP-Bang 유사 대용 점수(비만·허리둘레·연령·
  성별·고혈압) >= 3 을 고위험으로 정의.
- **screen-fail율**: 포함기준은 충족했으나 제외기준에 걸리는 가중 비율. 운영상
  동의철회 등은 별도 `attrition` 파라미터로 timeline에서 처리.
- **timeline Monte-Carlo**: 사이트 가동 시점은 지수분포, 월간 스크리닝 수는
  감마분포(변동계수 0.35), 스크리닝→등록은 이항분포로 모사.

## 검수 체크리스트

- [x] `core.py`, `app.py`, `main.py`, `data/generate_knhanes_synthetic.py`
      AST 파싱 통과
- [x] `data/generate_knhanes_synthetic.py` 실행 → CSV 생성 확인
- [x] CSV 로드 테스트 (7,000행 × 25열, `weight` 컬럼 포함)
- [x] `python3 main.py --help` 정상 동작
- [x] `python3 main.py --demo` 정상 동작
- [x] 커스텀 기준 CLI 실행 정상 동작
- [x] `app.py` 모듈 import 무오류
- [x] 합성 데이터 유병률이 공개 추세 근사 범위 내
- [x] 면책 문구가 README·CLI·앱 출력에 포함

자세한 검수 로그는 `QA.md` 참고.

## 면책

본 도구는 **참고용·연구용** feasibility 설계 보조 도구이다. 적격 모집단
추정치는 합성 데이터 기반이며, 실제 임상시험 feasibility 산정은 **CRO 및
생물통계 전문가의 검토가 필수**이다. 본 도구의 산출물은 의학적·규제적
판단 근거로 사용할 수 없다.

## 출처 / 참고

- 국민건강영양조사(KNHANES), 질병관리청 — 합성 데이터의 모사 대상(실데이터 미사용)
- 비만 진료지침(대한비만학회) — BMI 분류 기준 참고
- KDA 2023, ADA 2025 — T2DM 진단 기준 참고
- STOP-Bang 설문 — OSA 위험 대용 점수 설계 참고
- 본 MVP는 2026 Metabolic Daily Idea 파이프라인 산출물
  (2026-05-17, Obesity 도메인 / 인체실험 도구 카테고리)