# CholangioDuctReact v0

MASLD/MASH 마우스 모델 간조직의 **Ductular Reaction (DR)** 정량/분류 standalone 도구.

## 목적
- **도메인**: MASLD (대사관련 지방간질환)
- **카테고리**: 동물실험 도구
- **대상**: MASH/PBC/PSC/BDL/CDAA/CDAHFD 마우스 모델의 paired serial section
  (H&E + CK19/SOX9 IHC + Sirius Red)

CK19/SOX9 양성 cholangiocyte / hepatic progenitor compartment의 활성화는
MASLD-MASH-cirrhosis 진행의 핵심 표지로 간주되지만, 표준화된 정량 도구가
부족하다. 본 MVP는 portal tract 단위 자동 검출 + DR Type1/2/3 분류 +
Sirius Red bridging 동시분석을 단일 Streamlit 앱으로 묶는다.

## 핵심기능 5
1. **Paired WSI 로딩 + serial section 자동 정렬**
   - rigid translation registration (phase-correlation 휴리스틱)
   - H&E / CK19 / SOX9 / Sirius Red 4채널 동기 미리보기
2. **Portal tract auto-detection**
   - H&E의 빈 lumen(혈관) + 인접 CK19+ → portal triad (PV + HA + BD) 인식
   - 룰베이스 (MVP는 U-Net 대신 휴리스틱)
3. **DR area/count + Type 분류**
   - Type1: reactive ductule (lumen+, 작음)
   - Type2: intermediate hepatocyte (CK19+ 산발, hepatocyte 형태)
   - Type3: ductular metaplasia mass-like (큰 cluster)
   - 크기/lumen 점수/CK19 강도 기반 룰베이스
4. **Fibrosis overlay + bridging 분류**
   - Sirius Red collagen area 정량
   - portal-portal bridge 위 CK19+ 동반 여부 → `pure_fibrosis` vs `ductular_bridge`
5. **Per-portal tract + cohort 통계 + export**
   - mouse-level dr_per_portal, t1/t2/t3 count, sirius area %
   - 그룹간 one-way ANOVA, plotly violin / facet bar
   - CSV / JSON 다운로드

## 기존 형제 도구 대비 차별성
| 도구 | 분석 대상 cell | 핵심 신호 |
|------|----------------|-----------|
| MASLDStager | 환자 staging | 임상지표 |
| HepatoQuantum | 간 H&E + collagen | hepatocyte/fibrosis |
| StellateActivStain | HSC (간성상세포) | αSMA/Desmin |
| MASHLipidDroplet | hepatocyte | lipid droplet |
| **CholangioDuctReact (본)** | **cholangiocyte / progenitor** | **CK19/SOX9 + portal tract** |

cell type 자체가 다르다 (cholangiocyte/progenitor compartment).

## OpenClaw 바이오 피벗 alignment
- OpenClaw는 비만/근감소 약물 재조합 DB 구축 중. resmetirom (THR-β) 같은
  hepatic 표적 약물의 효과를 ductular reaction 회복으로 시각화 가능 →
  약물 재조합 후보의 in vivo 표현형 증거 모듈로 확장 가능.

## 설치 및 실행
```bash
cd "projects/2026-05-10-3-cholangio-duct-react"
pip install -r requirements.txt
streamlit run main.py
```

오프라인 환경에서는 numpy / streamlit / pandas / plotly만 있으면 동작.
scipy 없으면 ANOVA p값은 NaN으로 보고 (F값은 계산).

## 디렉토리 구조
```
2026-05-10-3-cholangio-duct-react/
  README.md
  QA.md
  main.py
  requirements.txt
  lib/
    __init__.py
    synth_liver.py
    registration.py
    portal_detect.py
    dr_classify.py
    fibrosis_overlay.py
    stats.py
  data/
    demo_cohort.json
    sample_wsi/
  output/
```

## 검수 체크리스트
1. 모든 .py 파일 ast 구문 체크 → QA.md 참조
2. lib 모듈 import-able
3. 합성 데이터 생성기 1회 실행 → portal tract / DR 검출 결과 비어 있지 않음
4. demo 코호트 통계 + ANOVA F 출력 확인

## 한계
- MVP는 **합성 데이터**로 파이프라인/UI 시연 목적. 실제 WSI 적용 시
  segmentation_models_pytorch + StarDist + 학습된 ResNet 분류기로 교체 필요.
- portal tract 휴리스틱은 lumen 기반이라 sinusoid 등 false positive 가능.
- DR Type 분류는 룰베이스라 인간 라벨 학습 단계 필요.
- registration은 rigid translation만. 실제는 affine + non-rigid 필요.

## 의학 디스클레이머
**본 도구는 연구·참고용입니다. 임상 진단·치료 결정에 사용하지 마십시오.
합성 데이터는 시연 목적이며 실제 환자/실험 데이터가 아닙니다.**

## 출처
- 2026-05-10 metabolic daily ideas, idea #3 (CholangioDuctReact)
- step1 추출 → step2 자동 빌드 (auto-builder agent)