# HepatoMRQuant — rodent in vivo 간 MRI 정량 도구

## 목적
설치류(rodent) **in vivo 간 MRI** 의 multi-echo PDFF 신호, ¹H-MRS spectra(지질/물 peak),
MRE/SWE 전단파(raw)를 받아 **T2* 보정 PDFF%**, **MRS lipid fraction**, **간 stiffness(kPa)**,
**종단(within-animal) 변화**, **terminal histology 상관**, **cohort 통계**를 표준 산출하는
standalone 동물 간영상 정량 도구.

- **도메인:** MASLD (대사이상 지방간질환)
- **카테고리:** 동물실험 도구 (in vivo 이미지 정량)
- **형태:** Streamlit 앱(`app.py`) + 오프라인 시연용 CLI(`main.py`)

## 디스클레이머 (중요)
> **본 도구는 연구용·참고용이며, 정량 결과는 사용자 검증이 필요합니다.**
> 원시 **k-space/DICOM 재구성은 범위 외**이며, **정량 CSV ingest를 전제**로 합니다.
> 동봉된 샘플 데이터는 모두 **합성(synthetic) 데이터**입니다.
> 외부 네트워크/API 호출은 하지 않습니다(오프라인).

## 핵심 기능 5개
1. **다중 readout ingest + ROI 매핑/QC** — 간 ROI multi-echo 신호(TE별), MRS 지질/물 peak 면적,
   MRE/SWE 전단파 속도, 시퀀스 파라미터 CSV import → 종단 재현 위치 매핑, QC(MRS SNR·T2* 미보정·
   ROI 매핑 flag).
2. **PDFF T2* 보정 엔진** — multi-echo magnitude 신호 `S(TE)=S0·exp(-TE/T2*)` 적합 후
   2-pool(water=적합곡선, fat=잔존성분) 분해로 proton density fat fraction(%) 산출.
   single-echo 비보정 PDFF 대비 표시.
3. **MRS line fitting + MRE stiffness** — MRS PDFF = lipid/(lipid+water);
   전단파 속도 → stiffness(kPa), `μ = ρ·c²` (ρ≈1000 kg/m³), 가진 주파수 기록.
   PDFF·MRS·stiffness 3 readout 통합 테이블.
4. **종단 within-animal + histology 상관 + 모델 reference** — 동일 개체 baseline vs post
   paired 변화, terminal histology(NAS·Sirius Red %·CPA) 상관(Pearson/Spearman),
   모델별(CDAHFD/MCD/AMLN/GAN/db-db/Control) 전형 PDFF/stiffness 참고 범위 내장.
5. **cohort 통계 + 리포트** — 군 × readout × 시점 요약, paired t-test,
   "steatosis 가역형 / fibrosis 가역형 / 무반응형" 분류, 영상-histology 상관 요약,
   방법·결과 텍스트 리포트(국문/영문).

## 실행법

### CLI (오프라인, 표준 라이브러리만 — 설치 불필요)
```bash
python3 main.py --help
python3 main.py --demo            # 국문 리포트
python3 main.py --demo --lang en  # 영문 리포트
```
`main.py` 는 numpy/scipy 없이 동작합니다. T2* 적합은 **log-linear 선형회귀**,
상관·t-test 는 **순수 파이썬**(불완전 베타함수 연분수)으로 계산합니다.

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

## 입력 CSV 스키마
- `data/sample_multiecho.csv` — `animal_id, group, timepoint, te_ms, signal`
- `data/sample_mrs_mre.csv` — `animal_id, group, timepoint, mrs_lipid_area, mrs_water_area, mre_freq_hz, shear_velocity_ms`
- `data/sample_histology.csv` — `animal_id, group, timepoint, nas_score, sirius_red_pct, cpa_pct`

샘플은 CDAHFD(steatosis 가역 시연) 3마리 + Control 3마리, 각 baseline/post 2시점, echo 6개.

## 검수 체크리스트
- [ ] `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기능 산출물 출력
- [ ] 3개 CSV 각각 `csv.DictReader` 로드 행수 확인
- [ ] T2* 보정 PDFF / stiffness 손계산 1건 대조 (QA.md)

## 모델 가정 / 출처 맥락
- 진단/치료 기준 맥락: **AASLD MASLD Practice Guidance 2023**, **EASL-EASD-EASO MASLD CPG 2024**.
- stiffness 변환은 전단탄성 근사 `μ=ρ·c²`(ρ=1000 kg/m³, 비점성 단순화). MRE 가진 주파수 기록.
- 모델별 참고 범위는 문헌 맥락 기반 **근사·합성 가정**이며 실제 검증 수치가 아님.
- 원시 신호 재구성·fat/water 위상 분리의 full 구현은 범위 외(정량값 ingest 전제).

## 제약
- 외부 네트워크/유료 API 0. 오프라인 우선.
- 전역 패키지 설치 금지(`requirements.txt`만 제공). `main.py` 는 의존성 0.
- 모든 데이터 합성. 결과는 사용자 검증 필요.