# HepatoSeahorse (헤파토씨호스)

> **의학적 디스클레이머**: 본 도구는 연구·참고용입니다. in vitro 세포실험 Seahorse XF raw data의 사후 분석을 보조하기 위한 standalone 도구이며, 임상 의사결정·진단·치료 결정에 사용해서는 안 됩니다.

## 목적
Agilent Seahorse XFe96 / XF Pro Wave에서 export된 raw data (`.asyr` 바이너리 / Excel / CSV)를 직접 받아 4개 표준 프로토콜을 자동 감지하고, 11개 표준 bioenergetic parameter를 계산하여 **bioenergetic phenotype map**과 cohort 통계를 한국어 manuscript-ready 포맷으로 export하는 standalone Streamlit 도구.

- **도메인**: MASLD (대사성 간질환, Metabolic dysfunction-Associated Steatotic Liver Disease)
- **카테고리**: 동물실험 도구 (in vitro / ex vivo cellular bioenergetics raw → 자동 분석)
- **MVP 한 줄**: Seahorse XFe96/XF Pro Wave .asyr/Excel raw → 4-protocol auto-detect + per-well QC + 11 parameter + substrate dependence + bioenergetic phenotype map + cohort 통계 standalone Streamlit 도구

## 핵심 기능 5개
1. **Multi-plate ingest + 4 protocol auto-detect**
   - Wave `.asyr` binary (MVP에서는 stub 처리 — 실제 reverse engineering은 24h 범위 초과) / Excel `.xlsx` export / CSV
   - Injection sequence pattern matching으로 Mito Stress (Oligo → FCCP → Rot/AA), Glycolysis Stress (Glucose → Oligo → 2-DG), FAO (etomoxir/BSA-palmitate), ATP Rate Assay (Oligo → Rot/AA) 자동 분류
2. **Per-well QC**
   - Basal OCR/ECAR CV%
   - Oligomycin response (≥30% OCR drop), FCCP response (≥50% OCR increase), Rot/AA response (≥80% OCR drop)
   - Drift linear regression (basal 구간 slope test)
   - IQR / Mahalanobis distance outlier
   - Low-quality well auto-flag (Excludable / Borderline / Pass)
3. **표준 parameter 11종 산출**
   - Mito Stress 6종: basal OCR, ATP-linked, maximal, spare respiratory capacity, proton leak, non-mitochondrial
   - Glycolysis Stress 3종: basal ECAR (glycolysis), glycolytic capacity, glycolytic reserve
   - ATP Rate Assay 2종: basal ATP rate (glyco+mito), max ATP rate
4. **Substrate-specific fuel flexibility (Mootha/Houtkooper framework)**
   - Palmitate-BSA vs BSA-only → FAO 의존도
   - ± Etomoxir (CPT1 inhibitor) → CPT1-dependent FAO
   - ± BPTES (glutaminase inhibitor) → glutamine 의존도
   - ± UK5099 (MPC inhibitor) → pyruvate 의존도
   - Fuel flexibility map (3축: glucose / glutamine / FAO)
5. **Bioenergetic phenotype map + cohort + 한국어 export**
   - OCR vs ECAR quadrant map (energetic / glycolytic / aerobic / quiescent — Mootha framework)
   - Drug × dose × cell type × substrate heat map
   - One-way ANOVA + Tukey HSD pairwise (statsmodels 있으면 사용, 없으면 scipy 기반 fallback)
   - 한국어 manuscript-ready 표·요약 (Hepatology / Cell Metabolism 포맷 모사)

## 데이터
`data/synthetic/`에 합성 Seahorse plate CSV 4종 제공 (seed=42).
- 4 protocol × 5 cell type (PMH / HepG2 / AML12 / HepaRG / LX-2) × 5 drug (resmetirom / pegozafermin / efruxifermin / lanifibranor / vehicle)
- 12-15 timepoint, 4 injection step, 24-48 well per plate
- baseline OCR/ECAR + cell-type baseline + drug-specific delta + injection response 모사

## 실행법
```bash
# Streamlit UI (인터랙티브)
streamlit run main.py

# CLI demo (서버 preview 캡처 / streamlit 미설치 환경)
python3 main.py --demo
```

## 검수 체크리스트
- [x] `seahorse_parser.py` — Wave `.asyr` stub + Excel/CSV parser + 4 protocol auto-detect
- [x] `bioenergetics.py` — 11 parameter + substrate dependency + phenotype quadrant
- [x] `qc.py` — per-well QC (CV%, injection response, drift, outlier)
- [x] `data/synthetic_generator.py` — 4 protocol × 5 cell type × 5 drug 합성 CSV (seed=42)
- [x] `main.py` — Streamlit UI + `--demo` CLI 모드 (offline)
- [x] 외부 네트워크 호출 없음 (pure offline)
- [x] 의학적 디스클레이머 포함

## 출처 / 참고
- Mootha VK et al. — Cellular bioenergetic phenotype quadrant framework (energetic / glycolytic / aerobic / quiescent)
- Houtkooper RH et al. — Substrate fuel flexibility (Cell Metabolism 2014 / Nat Rev Endocrinol 2017)
- Agilent Seahorse Wave protocol — Cell Mito Stress Test / Glycolysis Stress Test / FAO Assay / Real-Time ATP Rate Assay (Agilent technical notes, public)
- TeSlaa T & Teitell MA. Techniques to monitor glycolysis. Methods Enzymol. 2014.

## 알려진 제한
- Wave `.asyr` 바이너리 포맷은 비공개라 MVP에서 stub (Excel/CSV export 사용 필요). 실제 binary parser는 별도 reverse engineering 필요.
- 합성 데이터는 실제 plate 특성을 단순화한 것이며 진짜 Agilent normalization (cell number / protein) 보정은 미포함 (post-hoc factor 입력 필드만 제공).
- statsmodels / plotly 미설치 환경에서는 자동 fallback (scipy + matplotlib 텍스트 요약).