# HepatoSliceAssay (헤파토슬라이스어세이)

정밀절단 간조직 슬라이스(precision-cut liver slice, **PCLS**) ex vivo 배양 어세이로부터
**MASLD/MASH 약물의 효능과 독성**을 정량하는 단독 실행형 Streamlit 도구.

- **도메인**: MASLD (대사성간질환 — MASLD/MASH/간섬유화)
- **카테고리**: 동물실험 도구 (animal experiment tool)
- **대상 사용자**: 간대사·약리 ex vivo 동물조직 실험 연구실

> ⚠ **참고용 · 연구용 도구입니다 (for reference / research use only).**
> 본 도구의 계산 결과는 ex vivo 동물조직 실험 데이터 분석 보조용이며,
> 임상 진단·치료 목적으로 사용할 수 없습니다.

---

## 한 줄 요약

생존율(LDH/ATP/WST-1/resazurin), 기능(알부민/요소/TG), 섬유화(αSMA/COL1A1)의
시간경과·용량반응 raw 데이터를 입력하면 → 슬라이스 정규화 후 자연 감쇠와 약물독성을
분리하고, 효능 EC50·독성 IC50·치료지수(TI)를 산출하며, 동물/슬라이스 분산분해와
코호트 통계, 동물사용 절감(3R) 효과까지 한 번에 계산한다.

---

## 5개 핵심 기능

| # | 기능 | 설명 |
|---|------|------|
| 1 | **다중 리드아웃 입력 + 슬라이스 정규화** | plate-reader(흡광/형광/발광)·qPCR(Ct→ΔΔCt)·ELISA(표준곡선) raw CSV 입력 · 리드아웃별 표준곡선/ΔΔCt 처리 · 슬라이스 두께/무게/단백질량 정규화 · well/plate 레이아웃 매핑 |
| 2 | **생존율 감쇠(viability-decay) 보정 엔진** | LDH 누출/ATP/WST-1/resazurin을 time-0 및 시간대응 vehicle 대비로 정규화 → 자연 시간경과 감쇠와 약물유발 독성을 분리 · 생존율 임계 이상 유지 구간(사용가능 배양 윈도우) 자동 산출 |
| 3 | **효능 EC50 + 독성 IC50 + 치료지수(TI)** | 기능/섬유화 리드아웃(αSMA/COL1A1/TG 감소)의 4PL 용량-반응 → 효능 EC50 · 생존율 용량-반응 → 독성 IC50(CC50) · 치료지수 TI=IC50/EC50 및 치료창 시각화(효능/독성 농도 분리) |
| 4 | **동물/슬라이스 분산분해 + 모델 참조** | 동물 간 vs 동물 내(슬라이스 간) 분산을 중첩 분산분해(ICC)로 분리 · MASLD/MASH 모델별(GAN/CDAHFD/MCD/AMLN/HFD/db/db/ob/ob) PCLS 생존율·기능 참조 범위 내장 · 생존율 미달·비단조 용량반응·표준곡선/적합 R² 미달 자동 플래그 |
| 5 | **코호트 통계 + 3R 리포트** | 약물×농도×시점 ANOVA·쌍별 비교·혼합효과모형(statsmodels 설치 시) · 치료지수/효능·독성 요약 · 분류(antifibrotic-dominant vs antisteatotic-dominant vs toxicity-limited) · 동물사용 절감(3R) 효과 기록 · 방법/결과 섹션 KO/EN docx export |

---

## 실행 방법

```bash
# 1. 의존성 설치
pip install -r requirements.txt

# 2. (선택) 합성 샘플 데이터 재생성 — 이미 data/ 에 포함되어 있음
python3 generate_sample_data.py

# 3. 앱 실행
streamlit run app.py
```

브라우저에서 자동으로 열리며, 사이드바에서 **"데모 데이터 로드"**를 선택하면
업로드 없이 합성 데이터로 모든 기능을 바로 확인할 수 있다(완전 오프라인 동작).

> `statsmodels`는 선택 의존성입니다. 미설치 시 혼합효과모형만 비활성화되고,
> ANOVA·쌍별 비교·분산분해 등 나머지 기능은 scipy 기반으로 정상 동작합니다.
> `python-docx` 미설치 시 .docx 리포트만 비활성화되며 .md/.csv export는 정상 동작합니다.

---

## 파일 구성

```
2026-05-25-3-hepato-slice-assay/
├── app.py                  # Streamlit 앱 (메인 진입점, 5개 기능 탭)
├── pcls_core.py            # 순수 Python 계산 모듈 (4PL/감쇠보정/분산분해, 단독 테스트 가능)
├── generate_sample_data.py # 합성 샘플 데이터 생성 스크립트 (재현용)
├── requirements.txt        # 고정 버전 의존성
├── data/
│   ├── viability_timecourse.csv  # 시점별 생존율 리드아웃 (LDH/ATP/WST-1/resazurin)
│   ├── dose_response.csv         # 농도별 효능(섬유화/지방증) + 독성(생존율)
│   └── qpcr_elisa.csv            # qPCR Ct(αSMA/COL1A1/GAPDH) + ELISA(알부민/TG) raw
├── README.md
└── QA.md                   # QA 점검 로그
```

### 입력 CSV 스키마

**viability_timecourse.csv**: `model, animal_id, compound, conc_uM, slice_rep,
time_h, thickness_um, weight_mg, protein_ug, atp_lum, wst1_abs, resazurin_fluor, ldh_abs`

**dose_response.csv**: `model, animal_id, compound, conc_uM, slice_rep, time_h,
asma_rel_expr, col1a1_rel_expr, tg_rel, viability_pct`
(asma/col1a1/tg/viability 는 vehicle=100 기준 상대값)

**qpcr_elisa.csv**: `model, animal_id, compound, conc_uM, slice_rep, time_h,
gapdh_ct, asma_ct, col1a1_ct, albumin_elisa_abs, tg_elisa_abs`

---

## 핵심 계산식

- **슬라이스 정규화**: `normalized = raw / (protein_ug | weight_mg | thickness_um)`
- **qPCR ΔΔCt**: `ΔΔCt = (Ct_target − Ct_ref) − (Ct_target,cal − Ct_ref,cal)`, `fold = 2^(−ΔΔCt)`
- **생존율 감쇠 보정**: `corrected[t] = treated_viab[t] / vehicle_viab[t]`
  (1.0 = 약물독성 없음, <1 = 약물유발 독성; vehicle = 자연 감쇠)
- **4PL 용량-반응**: `y = bottom + (top − bottom) / (1 + (x/EC50)^hill)`
- **치료지수**: `TI = IC50(독성) / EC50(효능)`, 치료창 = `log10(TI)`
- **분산분해(ICC)**: `ICC = σ²_animal / (σ²_animal + σ²_slice)` (중첩 ANOVA 분산성분)
- **3R 절감**: PCLS 소요 = `⌈(조건수×반복수)/슬라이스수⌉`, in vivo 환산 = `조건수×arm당 동물수`

---

## QA 체크리스트

- [x] 모든 `.py` 파일 Python 구문 검사 (`ast.parse`)
- [x] `generate_sample_data.py` 실행 → CSV 3종 생성 확인
- [x] 생성된 CSV pandas 로드/파싱 확인
- [x] `pcls_core.py` 단독 import (streamlit 불필요)
- [x] `pcls_core.py` 자체 검증 (`python3 pcls_core.py`)
- [x] 헤드리스 코어 테스트 — 샘플 데이터로 감쇠보정/EC50/IC50/TI 계산 (유한·양수 확인)
- [x] Streamlit headless AppTest 스모크 런 (5개 탭, 예외 0건)
- [x] 오프라인 동작 — 외부 네트워크/API 호출 없음
- [x] 앱·README에 참고용·연구용 면책 문구 표기

자세한 결과는 `QA.md` 참조.

---

## 데이터 출처

`data/` 의 CSV는 모두 **합성(synthetic) 데이터**이며,
`generate_sample_data.py`가 고정 시드(20260525)로 생성한다.
실제 동물 데이터가 아니며, 외부 데이터를 다운로드하지 않는다.

모델별 참조 범위(`pcls_core.MODEL_REFERENCE`)는 PCLS/MASH 문헌의 전형적
값을 근사한 것으로, 정밀 분석 시 각 실험실 기준값으로 교체 권장.

가이드라인 참고: AASLD MASLD 2023, EASL-EASD-EASO MASLD 2024
(약물 분류·섬유화/지방증 효능 해석의 도메인 맥락).

---

## 3R (Reduction) 메모

PCLS는 **한 마리의 간에서 다수의 슬라이스**를 얻어 여러 화합물×농도를 동시에
평가할 수 있어, 동일 스크리닝을 in vivo로 수행할 때 대비 사용 동물 수를 크게
절감한다. 본 도구의 ⑤ 탭은 조건 수·동물당 슬라이스 수를 입력받아 절감 효과를
정량 추정하고 리포트에 기록한다(Replacement/Reduction/Refinement 중 **Reduction**).

---

## 한계 및 주의

- 합성 데이터 기반 MVP — 실제 실험 데이터로의 적용 전 검증 필요.
- 4PL 적합은 양의 농도(>0)만 사용하며, 적합 실패/저 R² 시 EC50/IC50가
  불안정할 수 있어 QC 탭에서 R² 플래그를 확인할 것.
- ICC 분산분해는 단일 조건(약물×농도)에서 동물 간 변동이 슬라이스 변동보다
  작으면 0에 수렴할 수 있다(슬라이스-지배 변동). 동물 간 효과 검정에는
  여러 조건/혼합효과모형 병용을 권장.
- 본 도구는 **연구 보조용**이며 임상적 판단을 대체하지 않는다.

---

*2026 metabolic daily idea pipeline · 2026-05-25 · MASLD 동물실험 도구*