# ObesityEnrollFunnelOps-Kor (오베시티인롤펀널옵스코어)

비만 RCT *진행 중* 등록(enrollment) funnel 운영 분석기 — 단계별 bottleneck 진단,
screen-fail 근본원인, 등록곡선 재예측을 제공하는 standalone Streamlit 앱.

- **도메인**: Obesity
- **카테고리**: 인체실험 도구 (임상시험 운영 물류)
- **MVP 한 줄**: 비만 RCT 진행 중 등록 funnel 운영 분석기 — 6단계 bottleneck 진단·screen-fail 근본원인·등록곡선 Bayesian 재예측

> **디스클레이머**: 본 도구는 연구·운영 보조용 참고 도구이며 실제 임상시험 규제
> 의사결정을 대체하지 않는다. 모든 데모 데이터는 합성(synthetic)이다.

## 핵심 기능 5개

1. **6단계 funnel 분해 + 병목 자동 식별** — referral→prescreen→consent→screen→randomize→retain
   단계별 통과율·이탈수를 funnel 차트, site×단계 매트릭스, 주차별 추이로 시각화하고
   통과율이 가장 낮은 최대 bottleneck 구간을 자동 식별.
2. **screen-fail 근본원인 taxonomy** — 사유 코드(BMI 미달/초과·HbA1c·동반질환·금기약물·동의철회 등)
   분포, site별 사유 분포 편차, "회피 가능 vs 불가피" 분류.
3. **site별 등록곡선 Bayesian 재예측** — Poisson-Gamma 켤레 사전으로 주당 등록률을 갱신,
   목표 달성까지 남은 주차(평균/낙관/비관)와 기한 내 달성에 필요한 site 수를 예측 (scipy).
4. **retention/dropout 추적** — 방문(0/4/12/24/52주)별 잔류율과, 체중감량 시험 특유의
   early-responder 잔류 편향(잔류군 평균 BMI 이동)을 모니터링.
5. **다양성 representativeness** — 등록 인구의 성·연령대·인종·BMI 분포를 질환 역학
   reference와 비교하고 카이제곱 적합도 검정 p-value 제공.

## 실행법

```bash
pip install -r requirements.txt
streamlit run app.py
```

- CSV 업로드 없이도 `data/`의 합성 데모 데이터로 즉시 동작한다.
- 사이드바에서 "내 CSV 업로드 사용"을 켜면 본인 등록 로그로 대체 가능.
- 오프라인 전용 — 외부 네트워크/API 호출 없음.

데모 데이터를 재생성하려면:

```bash
python3 data/generate_demo_data.py
```

## 파일 구성

```
app.py                       Streamlit 진입점 (5개 기능 탭)
funnel_logic.py              순수 분석 로직 (streamlit/plotly 비의존, 단위테스트 대상)
test_logic.py                단위 테스트 (27 케이스)
requirements.txt             pinned 의존성
data/generate_demo_data.py   합성 데모 데이터 생성기
data/enrollment_funnel.csv   site×week×stage 카운트
data/screen_fail_reasons.csv 사유 코드별 카운트(site별)
data/site_enrollment.csv     site별 목표/경과/누적 등록
data/demographics.csv        등록 피험자 인구통계
data/retention_visits.csv    방문별 잔류/이탈
```

## 검수 체크리스트

- [x] `app.py` 구문 유효 (`ast.parse`)
- [x] 데모 데이터 생성 스크립트 실행 → 5개 CSV 생성
- [x] 합성 CSV 가 pandas 로 로드됨
- [x] 의존성 import 가능 (plotly 제외, 미설치 시 명시만)
- [x] 순수 로직(Bayesian 재예측·funnel·screen-fail·retention·대표성) 단위테스트 27/27 통과
- [x] 디스클레이머가 app.py UI 상단과 README 에 포함

## 출처 / 근거

- **CONSORT 2010 flow diagram** — enrollment → allocation → follow-up → analysis 구조.
  6단계 funnel(referral→prescreen→consent→screen→randomize→retain)은 이를 운영
  관점으로 세분화한 합성 모델이다.
- **비만 RCT screen-fail 사유** — BMI 기준 미충족, HbA1c/검사실 수치, 동반질환 배제기준,
  금기약물, 동의철회 등 일반 임상시험 문헌의 전형적 사유를 기반으로 한 합성 taxonomy.
- **역학 reference 분포** — 합성·가정치이며 실제 한국 비만 역학 통계를 정밀 반영하지 않는다.

모든 수치/데이터는 데모용 합성이며 실제 시험 데이터가 아니다.
```