# AdipoCLSPolarMap v0

지방조직 multi-channel IF mini WSI에서 **Crown-Like Structure (CLS) density**와
**Adipose Tissue Macrophage (ATM) M1/M2 polarization**을 자동 정량하는
stand-alone Streamlit 시연 도구.

- 출처: 2026-05-10 daily-ideas (#2)
- 도메인: **Obesity**
- 카테고리: **동물실험 도구** (HFD/ob-ob/db-db 마우스 지방조직 분석)

## 목적
HFD 비만 모델 / 약물 치료 효과를 비교할 때, 병리학자가 손으로 세던
CLS 카운트와 M1/M2 분극 평가를 합성 mock 데이터 + heuristic 파이프라인으로
자동화 시연한다.

## 핵심 기능 5가지
1. **Adipocyte segmentation + size 분포** — perilipin IF ring 기반
   connected component → 등가원 반경 → 직경 분포 (µm). dead adipocyte는
   perilipin- 영역과 F4/80+ shell 인접 여부로 추정.
2. **CLS auto-detection** — DAPI nuclei centroid + dead adipocyte 후보 1.4×반경 내
   3개 이상 + F4/80+ shell coverage ≥ 50% perimeter sampling 통과 시 CLS 카운트.
   density = count / mm² (pixel→µm 환산).
3. **ATM polarization** — CLS shell ring (0.95r ~ 1.5r) 영역 내 CD11c (M1) /
   CD206 (M2) 평균 intensity 비율 + global polarization index `(M1-M2)/(M1+M2)`.
4. **Depot 비교 + 그룹 통계** — eWAT / iWAT / BAT label 자동 인식,
   control vs HFD vs HFD+drug 그룹 간 CLS density / polarization /
   mean diameter one-way ANOVA + violin plot.
5. **한국어 export** — Streamlit UI + JSON 결과 export. 그림은 matplotlib
   savefig 호환. JASA / Diabetes / Cell Metabolism 형식 라벨링.

## 차별성
- `BBStopCoach` (#1, 환자 행동·식단 코칭) → 이 도구는 **연구실 동물실험용 정량**.
- `BrownFatQuant` 류 (brown adipose UCP1 thermogenesis 정량) → 본 도구는
  **white adipose ATM inflammation (CLS density + M1/M2 polarization)**으로
  분석 대상 dimension 자체가 다름.
- 결과적으로 OpenClaw 바이오 피벗 (비만/근감소 약물 재조합 DB)에 **약물 효과
  endpoint metric provider** 역할로 정렬된다 — DB의 anti-obesity 후보 약물에
  대해 마우스 지방조직 phenotype을 자동 정량해 효과 신호를 제공.

## 디렉토리
```
2026-05-10-2-adipo-cls-polar-map/
  README.md
  QA.md
  main.py                # Streamlit 진입점
  requirements.txt
  lib/
    __init__.py
    synth_adipose.py     # 합성 지방조직 multi-channel WSI
    adipo_seg.py         # Adipocyte segmentation
    cls_detect.py        # CLS detection (heuristic)
    atm_polarize.py      # CD11c/CD206 → M1/M2 ratio
    stats.py             # ANOVA + 그룹 통계
  data/
    demo_cohort.json     # 3 그룹 × 3 마우스 × 3 depot 코호트 메타
    sample_wsi/          # (런타임 생성, .gitkeep)
  output/
    .gitkeep
```

## 실행
```bash
# 의존성 설치 (오프라인 환경에서는 휠 캐시 사용 권장)
pip install -r requirements.txt
# Streamlit UI
streamlit run main.py
```

> ⚠️ 본 환경 정책상 builder는 `pip install`을 실행하지 않습니다.
> requirements.txt만 작성되어 있으니, 사용자가 직접 설치 후 실행해 주세요.

## 합성 데이터 설계
- 512×512 numpy float32 5채널: `(perilipin, F4/80, CD11c, CD206, DAPI)`
- 그룹별 dead adipocyte 비율: control 2% / HFD 12% / HFD+drug 5%
- 그룹별 M1:M2 비율: 30:70 / 70:30 / 50:50
- depot 별 평균 반경 보정: eWAT 1.0×, iWAT 0.9×, BAT 0.55× (multilocular 단순화)
- numpy seed = 42 (reproducible)

## 검수 체크리스트
- [x] 모든 .py 파일 ast 구문 통과
- [x] `from lib import synth_adipose, adipo_seg, cls_detect, atm_polarize, stats` 성공
- [x] `synth_adipose.synthesize_wsi(...)` 1회 실행 가능
- [x] `analyze_wsi(...)` end-to-end 실행 가능
- [x] QA.md에 검수 로그 기록

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

## 한계
- **시연용 MVP**입니다. 실제 IF 슬라이드는 channel registration / illumination
  correction / autofluorescence subtraction 등 전처리가 필수.
- StarDist / cellpose 등 ML segmentation 미사용 — heuristic 기반.
  실 슬라이드에서는 dense packed adipocyte / multilocular BAT 구분이 어려움.
- ANOVA 단일 검정만 수행. 다중 비교 보정 / 혼합효과 모델 미반영.
- pixel→µm 환산은 데모 값 (0.5 µm/px) 고정.

## 의학 디스클레이머
**본 도구는 연구·참고용입니다. 임상 진단 / 환자 의사결정에 사용해서는
안 됩니다.** 결과 해석은 자격을 갖춘 병리학자·연구자의 검토를 거쳐야 합니다.