# AdipoGlowIVIS — rodent IVIS 지방 depot 광학영상 정량 도구

## 목적
설치류(rodent) IVIS 광학영상에서 지방 depot ROI 의 **total flux**(photons/s)·**average radiance**(p/s/cm²/sr)·노출/binning 메타데이터를 받아, 노출 normalize·배경/자가형광 차감·BAT vs WAT depot 비교·동일 개체 종단 fold·cohort 통계를 표준 산출하는 standalone 동물 광학영상 정량 도구.

- **도메인**: Obesity (비만)
- **카테고리**: 동물실험 도구 — in vivo 이미지 정량
- **진입점**: Streamlit 앱 `app.py` + 오프라인 시연용 CLI `main.py`

> ⚠️ **디스클레이머**: 본 도구는 **연구용·참고용**이며, 정량 결과는 **사용자 검증이 필요**합니다. 기본 제공 샘플 데이터(`data/sample_roi.csv`)와 reference(`data/reporter_reference.json`)는 **합성(synthetic)/가정 데이터**이며 실제 IVIS 캘리브레이션·문헌 절대값과 동일하지 않습니다.

## 핵심 기능 5개
1. **ROI radiance ingest + 노출 normalize**: depot ROI별 total flux·average radiance·노출시간·binning·f-stop·기질(luciferin) 주입 후 경과시간 CSV import → 노출/binning normalize 로 이미지 간 비교 가능 단위 변환, QC(saturation·노출 불일치·기질 시점 미기록 flag).
2. **배경 차감 + depot 비교**: 동일 개체·시점 배경 ROI 차감, 견갑간 BAT(iBAT)·서혜부 iWAT·부고환 eWAT depot별 신호 테이블, total flux(전체 신호) vs average radiance(밀도) 병기로 ROI 크기 의존성 분리.
3. **종단 within-animal fold + 기질 동역학**: 동일 개체 baseline 대비 fold-change(paired), bioluminescence 기질 peak 시점 기록·정렬 안내(주입 후 경과시간 보정), 반복측정 요약.
4. **모델·reporter reference + QC**: UCP1-luc(BAT 활성)·NF-κB-luc(염증)·NIR-ATM probe 등 reporter별·DIO/HFD/ob-ob 모델별 전형 신호 범위 내장, 노출 불일치·기질 시점 미기록·saturation·baseline 누락 자동 flag.
5. **cohort 통계 + 리포트**: 군×depot×시점 radiance 요약 + paired t-test(앱: scipy.stats.ttest_rel / CLI: 표준 라이브러리 정규근사), "BAT 활성형 vs 지방염증 감소형 vs depot 선택형" 약력 분류, 방법·결과 텍스트 리포트(국문/영문) 출력.

## 실행법
### CLI (표준 라이브러리만 — 설치 불필요)
```bash
python3 main.py --help
python3 main.py --demo
# 사용자 데이터:
python3 main.py --demo --csv path/to/roi.csv --ref path/to/reference.json
```
`main.py` 는 numpy/pandas/scipy 가 없어도 동작합니다.

### Streamlit 앱
```bash
# 가상환경 권장 (전역 설치 금지)
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
streamlit run app.py
```
사이드바에서 CSV 업로드 또는 "샘플 데이터 로드" 버튼.

## 입력 CSV 스키마 (`data/sample_roi.csv`)
| 컬럼 | 의미 |
|---|---|
| animal_id | 개체 ID |
| group | 실험군 (예: vehicle, cl316243) |
| timepoint | 시점 (baseline, week2 ...) |
| depot | iBAT / iWAT / eWAT / background |
| total_flux_ps | total flux (photons/s) |
| avg_radiance | average radiance (p/s/cm²/sr) |
| exposure_sec | 노출시간(초) — 이미지마다 다를 수 있음 |
| binning | binning factor |
| f_stop | f-stop |
| substrate_post_min | luciferin 주입 후 경과 분 |
| is_background | 배경 ROI 여부 (1=배경) |

## Normalize 정의
```
factor = (REF_EXPOSURE/exposure_sec) * (REF_BINNING/binning)   # REF_EXPOSURE=30s, REF_BINNING=8
norm_value = raw_value * factor
```
노출이 길수록·binning 이 클수록 신호가 커지므로 기준값으로 down/up-scale 하여 이미지 간 비교 가능 단위로 환산. 배경 차감은 normalize 후 동일 (animal, timepoint) 배경 ROI 값을 빼서 수행.

## 검수 체크리스트
- [ ] `python3 -c "import ast; ast.parse(open('app.py').read()); ast.parse(open('main.py').read()); print('OK')"`
- [ ] `python3 main.py --help` 정상
- [ ] `python3 main.py --demo` 가 표준 라이브러리만으로 5기능 산출물 출력
- [ ] `python3 -c "import csv; print(len(list(csv.DictReader(open('data/sample_roi.csv')))))"`
- [ ] `python3 -c "import json; print(len(json.load(open('data/reporter_reference.json'))))"`
- [ ] normalize/fold 손계산 1건 일치 (QA.md 참조)

## 출처/모델 가정
- 샘플 데이터·reference 신호 범위는 **합성/문헌 가정치**이며 절대 캘리브레이션값이 아님.
- depot 명명: iBAT(견갑간 갈색지방), iWAT(서혜부 백색지방), eWAT(부고환 백색지방) — 설치류 표준 명명 가정.
- reporter: UCP1-luc(열발생/BAT 활성), NF-κB-luc(염증), NIR-ATM(adipose tissue macrophage probe) — 통상 사용 reporter 가정.
- β3 agonist(예: CL316,243) 투여 시 iBAT UCP1 신호 증가 패턴을 시연용으로 합성.
- 외부 네트워크/유료 API 미사용. 완전 오프라인.

## 안전성
연구용·참고용 도구. 임상 판단·진단 용도가 아니며, 모든 정량 결과는 사용자(연구자)의 독립 검증을 거쳐야 합니다.