# ExVivoMyoUptake (엑스비보마이오업테이크)

적출 골격근(soleus / EDL / FDB) 인큐베이션 **[3H/14C]2-deoxyglucose(2-DG)
포도당 흡수 assay**를 분석하는 단독 실행형 Streamlit 도구.
섬광계수기(scintillation counter) 원자료(dpm)를 입력하면 → 보정된 포도당
흡수율, 인슐린 용량-반응 EC50, 수축 자극 효과, 코호트 통계까지 산출한다.

- **도메인**: DM (당뇨병)
- **카테고리**: 동물실험 도구 (animal experiment tool)
- **대상 사용자**: 내분비·대사·약리 동물실험 연구실 (근 인슐린 저항성/포도당 흡수 연구)

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

---

## 한 줄 요약

96-well/vial 섬광계수 export(3H & 14C 채널 dpm), 인슐린 용량-반응, assay
메타데이터, 생존능 마커 CSV를 입력하면 → 이중표지 spillover 보정, [14C]mannitol
세포외공간 보정, 비방사능 환산으로 흡수율(pmol/mg/min, µmol/g/h)을 구하고,
인슐린 4PL EC50, 수축 효과, 모델 참조·생존능 QC, 코호트 통계와 기전 분류까지
한 화면에서 처리한다.

---

## 5개 핵심 기능

| # | 기능 | 설명 |
|---|------|------|
| 1 | **섬광계수 원자료 입력 + 이중표지 spillover 보정** | 96-well/vial 섬광계수 export(3H & 14C dpm, 단일표지도 지원) 입력 · 사용자 지정 2x2 spillover 행렬(3H↔14C crossover)로 선형계를 풀어 진짜 3H/14C dpm 복원 · blank 차감 · 저신호(quench) QC |
| 2 | **세포외공간 + 비방사능 보정 엔진** | [14C]mannitol dpm으로 well별 세포외공간(ECS)을 계산해 차감 → 세포내 [3H]2-DG 분리 · hot/cold 2-DG 농도·배지부피로 비방사능 산출 · 조직 습/건중량 정규화 → 흡수율(pmol/mg/min 또는 µmol/g/h) |
| 3 | **조건/근육 흡수 + 인슐린 용량-반응** | basal vs insulin(농도 시리즈) vs contraction(전기자극)을 soleus/EDL/FDB 근육별 비교 · 4-parameter logistic(4PL) 인슐린 용량-반응 적합 → EC50, Emax, fold-stimulation, 인슐린 감수성 지수(insulin/basal) |
| 4 | **모델 참조 + 생존능 QC** | C57BL/6·db/db·ob/ob·DIO·HFD·aging 모델별 전형 basal/insulin 흡수 참조 범위 내장 · 생존능 마커(ATP·lactate 누출·oxygenation) 이상 시 경고 · spillover/mannitol 보정 누락 자동 경고 |
| 5 | **코호트 통계 + 리포트** | group × muscle × condition 이원배치 ANOVA / 혼합효과모형(statsmodels 설치 시) · 그룹 간 EC50 비교 · 기전 분류("근 인슐린 감수성 개선제 vs 수축-흡수 개선제") · 한국어/영어 methods+results docx export |

---

## 실행 방법

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

# 2. (선택) 합성 샘플 데이터 재생성 — 이미 data/ 에 포함되어 있음
#    생성기는 표준 라이브러리만 사용하므로 numpy 없이도 동작
python3 generate_sample_data.py

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

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

> `statsmodels`·`python-docx`는 선택 의존성입니다. 미설치 시 이원배치 ANOVA의
> 일원배치 대체와 .md 리포트는 정상 동작하며, 혼합효과모형/.docx export만
> 비활성화됩니다(ANOVA·쌍별 비교·4PL은 scipy 기반으로 정상 동작).

---

## 파일 구성

```
2026-05-25-1-exvivo-myo-uptake/
├── app.py                  # Streamlit 앱 (메인 진입점, 5개 기능 탭)
├── myo_core.py             # 순수 Python 계산 모듈 (spillover/4PL 등, 단독 테스트 가능)
├── generate_sample_data.py # 합성 샘플 데이터 생성 스크립트 (stdlib only, 재현용)
├── requirements.txt        # 고정 버전 의존성
├── data/
│   ├── well_counts.csv     # well/vial별 섬광계수 원자료 (3H/14C dpm, 조직중량)
│   ├── dose_response.csv   # 인슐린 농도 시리즈별 흡수율 (4PL 적합용)
│   ├── assay_metadata.csv  # assay 상수 (배지 SA, spillover 행렬, 인큐베이션)
│   └── viability.csv       # 근 생존능 마커 (ATP / lactate 누출 / PO2)
├── README.md
└── QA.md                   # QA 점검 로그
```

### 입력 CSV 스키마

**well_counts.csv**: `well_id, group, model, muscle, condition, replicate,
tissue_weight_mg, meas_3h_ch_dpm, meas_14c_ch_dpm`
(meas_*_ch_dpm = 섬광계수기 채널 A=3H 윈도우 / 채널 B=14C 윈도우 관측 dpm)

**dose_response.csv**: `group, model, muscle, insulin_nM, replicate,
uptake_pmol_mg_min` (insulin_nM=0 = basal)

**assay_metadata.csv**: `key, value, description`
(spillover_m_aa/ab/ba/bb, mannitol_sa_dpm_per_uL, dg_3h_sa_dpm_per_uL,
cold_2dg_conc_mM, dg_sa_dpm_per_pmol, incubation_min, blank_3h/14c_dpm)

**viability.csv**: `well_id, group, model, muscle, replicate,
atp_nmol_mg, lactate_leak_umol_g_h, po2_pct`

---

## 핵심 계산식

- **spillover 보정**: 관측 = M @ true → `true = M⁻¹ @ 관측`
  (M = [[3H→A, 14C→A], [3H→B, 14C→B]])
- **세포외공간 ECS(µL)** = 조직 14C dpm / mannitol SA(dpm/µL)
- **세포내 2-DG dpm** = 전체 3H dpm − ECS × [3H]2-DG SA(dpm/µL)
- **비방사능 SA(dpm/pmol)** = hot dpm/µL / (총 2-DG mM × 1e3 pmol/µL)
- **흡수율(pmol/mg/min)** = (세포내 dpm / SA) / 조직중량(mg) / 시간(min)
- **단위환산**: pmol/mg/min × 60 / 1000 = µmol/g/h
- **4PL**: `y = bottom + (top − bottom) / (1 + (EC50/x)^hill)` → EC50, Emax
- **인슐린 감수성 지수** = insulin 흡수율 / basal 흡수율 (배수)

---

## QA 체크리스트

- [x] 모든 `.py` 파일 Python 구문 검사 (`ast.parse`)
- [x] `generate_sample_data.py` 실행 → CSV 4종 생성 확인 (stdlib only)
- [x] 생성된 CSV pandas 로드/파싱 확인
- [x] `myo_core.py` 단독 import (streamlit 불필요)
- [x] `myo_core.py` 자체 검증 (`python3 myo_core.py`)
- [x] 헤드리스 핵심 수식 테스트 (spillover 복원 · ECS 차감 · SA · 4PL EC50)
- [x] 오프라인 동작 — 외부 네트워크/API 호출 없음
- [x] 앱·README에 참고용·연구용 면책 문구 표기

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

---

## 데이터 출처

`data/` 의 CSV는 모두 **합성(synthetic) 데이터**이며,
`generate_sample_data.py`가 고정 시드(20260525)로 생성한다.
실제 동물 데이터가 아니며, 외부 데이터를 다운로드하지 않는다.
생성기는 numpy 없이 **표준 라이브러리(csv/random/math)만** 사용한다.

모델별 참조 범위(`myo_core.MODEL_REFERENCE`)와 생존능 범위
(`myo_core.VIABILITY_REFERENCE`)는 적출근 2-DG 흡수 문헌의 전형적 값을
근사한 것으로, 정밀 분석 시 각 실험실 기준값으로 교체 권장.

---

## 한계 및 주의

- 합성 데이터 기반 MVP — 실제 실험 데이터로의 적용 전 검증 필요.
- spillover 행렬·비방사능·세포외공간 분율은 각 실험실의 calibration 값으로
  교체해야 정확하다(본 데모는 대표 근사치).
- 생존능 QC는 간이 임계 점검이며, 정밀 평가에는 산소소비·ATP/PCr 등
  추가 마커 병행 권장.
- 본 도구는 **연구 보조용**이며 임상적 판단을 대체하지 않는다.

---

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