# 이슬렛퍼퓨젼애널라이저 (IsletPerifusionAnalyzer)

**Domain:** Diabetes Mellitus — β-cell GSIS in vitro
**Category:** 동물실험 도구 — 데이터 분석 (in vitro perifusion)
**Slug:** `islet-perifusion-analyzer`
**Build date:** 2026-05-02 (MVP #1)

## 한 줄 요약
Perifusion raw CSV 일괄 import → flow rate / dead volume / degradation 보정 → 1st/2nd phase·AUC·fold-change·KCl normalization·multi-analyte co-analysis 자동 산출 → batch normalization + Diabetes/Diabetologia reproducibility checklist PDF + GraphPad-ready export.

## 핵심 기능 5개
1. **Raw 입력 + 메타데이터:** BioRep / Brandel / in-house perifusion CSV column-header 자동 감지, sample kind(primary mouse/rat/human islet, INS-1 832/13, MIN6, HIT-T15, EndoC-βH1/βH3, iPSC/hPSC-SC-β D14/21/28), IEQ/cell/protein 기준, channel × condition × genotype × pre-treatment, glucose/secretagogue 매트릭스, flow rate · dead volume · tubing length, ELISA/Luminex/HTRF + LLOD/ULOQ를 pydantic schema(혹은 dataclass fallback)로 검증.
2. **자동 보정 모듈:** dead volume transit-time lag(volume/flow rate), degradation drift(시간 × storage hours linear), baseline subtraction(low-glucose pre-stimulus mean ± 2SD), inter-channel normalization(IEQ / cell / protein), multi-batch normalization(reference KCl peak intra-batch CV ≤15% pass).
3. **Kinetic parameter 산출:** 1st phase(10–20 min) peak / time-to-peak / slope, 2nd phase(20–40 min) plateau slope / steady-state, AUC 0–10 / 10–30 / 30–60 (trapezoidal), fold-change vs basal, GSIS ratio(16.7/2.8 mM), KSIS ratio(KCl/glucose), GLP-1 potentiation index, FFA-mediated lipotoxicity 비교, proinsulin/insulin ratio.
4. **Multi-analyte co-analysis:** insulin · C-peptide · glucagon · proinsulin 동시 측정 시 분자별 trace overlay, C-peptide:insulin ratio, counter-regulatory glucagon suppression %, iPSC-SC-β maturation index trajectory(D14/D21/D28 vs primary).
5. **보고서 + export:** condition별 spaghetti curve + median±IQR PNG, kinetic parameter table CSV/XLSX, GraphPad Prism `.pzfx` stub + GraphPad-ready CSV, Diabetes/Diabetologia reproducibility checklist (Markdown + PDF, WeasyPrint→matplotlib fallback), Markdown methods section auto-draft.

## 실행법

### Demo (가장 빠른 검증 경로)
```bash
cd /Users/sangjoonpark/claude\ daily\ project/2026\ metabolic\ daily\ idea/projects/2026-05-02-1-islet-perifusion-analyzer/
python3 main.py --demo --report-dir ./output
```
- `data/` 아래 합성 CSV 5개를 생성 후 end-to-end 파이프라인 실행
- `output/` 에 trace PNG, kinetic CSV/XLSX, GraphPad CSV, reproducibility checklist MD/PDF, summary MD 생성

### Real input
```bash
python3 main.py --input ./mydata --analyte insulin --graphpad --checklist
python3 main.py --input ./mydata --analyte all
```

### CLI 옵션
| Flag | 설명 |
|------|------|
| `--input <csv|dir>` | 단일 CSV 파일 또는 CSV 디렉토리 |
| `--demo` | 합성 데이터 생성 후 end-to-end 실행 |
| `--analyte` | `insulin` / `c-peptide` / `glucagon` / `proinsulin` / `all` |
| `--report-dir` | 결과 저장 위치 (기본 `./output`) |
| `--graphpad` | GraphPad-ready CSV + .pzfx stub export |
| `--checklist` | Diabetes/Diabetologia reproducibility checklist 생성 |
| `--ieq` | IEQ basis (기본 100) |
| `--flow` | flow rate mL/min (기본 0.1) |
| `--dead-volume` | dead volume µL (기본 100) |
| `--storage-hours` | 분해보정용 storage hours (기본 4) |

## 출력 파일 (output/)
- `trace_<file>.png` — condition별 spaghetti + median±IQR
- `multi_analyte_<channel>.png` — insulin/C-pep/glucagon/proinsulin overlay (해당 시)
- `kinetic_parameters.csv` / `.xlsx` — 모든 file × channel kinetic 파라미터
- `graphpad_<file>.csv` / `kinetics.pzfx` — Prism import용
- `reproducibility_checklist.md` / `.pdf` — 항목별 fill-in 표
- `methods_draft.md` — 논문 methods section 초안
- `summary.md` — pass/fail + 주요 지표 요약

## 검수 체크리스트 (사용자가 결과 확인 시)
- [ ] `python3 main.py --help` 정상 출력
- [ ] `python3 main.py --demo --report-dir ./output` 종료코드 0
- [ ] `output/` 에 PNG 5+, CSV 1+, MD 3+, PDF 1 존재
- [ ] `summary.md` 에 KCl CV % + PASS/FAIL 표시
- [ ] `kinetic_parameters.csv` 첫 줄에 ≥20 column (현재 21: basal/phase1/phase2/KCl/AUC/fold/GSIS/KSIS + meta)

## 기술 스택
- Python 3.11 stdlib + numpy + scipy + pandas + matplotlib
- Optional: pydantic (schema validation), openpyxl (XLSX), weasyprint (PDF). 없으면 graceful fallback.
- 모든 처리 오프라인. 외부 네트워크 호출 없음.

## 데이터 출처
- 합성 raw csv 5개 (자체 생성, `lib/synth.py`)
- iPSC-SC-β maturation reference profile은 합성 anchor (외부 fetch 없음)

## 출처 (idea provenance)
- 아이디어 #1 from `daily-ideas/2026-05-02.md` (today's metabolic daily idea, slot 1pm)

## 디스클레이머
**본 도구는 연구·참고용이며 임상 의사결정에 직접 사용 금지.**
- 본 분석은 in vitro perifusion 실험 데이터 처리만 다루며 환자 진료, 처방, 진단 결정의 근거로 사용할 수 없음
- 합성 데이터로 학습/검증된 보정 파라미터(decay rate, KCl target peak)는 실제 실험 시스템에서 재교정 필요
- iPSC-SC-β maturation reference는 일반적인 프로토콜 anchor로, 실제 vendor protocol에 맞게 사용자가 재정의해야 함