# MASHLipidDroplet (매시리피드드롭렛)

**도메인:** MASLD / MASH (간 지질방울 정량)
**카테고리:** 동물실험 도구 — 이미지 정량
**MVP 한 줄:** hepatocyte / 세포주 / iPSC / spheroid / organoid / in-vivo cryosection BODIPY·ORO·Nile Red imaging 일괄 import → LD count/area/diameter/subtype + LD-mito/LD-ER contact + PLIN per-LD intensity 자동 정량 → 약물 dose-response · MOA 자동 분류 + 한국어 screening 보고서.

> ⚠️ **연구·참고용 — 임상 의사결정에 직접 사용 금지 (Research / reference use only).**
> 본 도구는 in-vitro/in-vivo screening 보조용으로, 어떤 환자 진료, 임상시험 결정,
> 또는 식약처/FDA 인허가 자료에 단독으로 사용해서는 안 됩니다.

## 핵심 기능 5개

1. **Imaging 입력 + 메타데이터** — 96/384-well plate confocal HCS(Operetta CLS · ImageXpress Micro · IN Cell · Nikon Ti2 · Zeiss · Leica) tiff/czi/lif/nd2/oir bioformats 자동 감지 (MVP에서는 이미 추출된 per-LD object table을 입력으로 사용 — `lib/schemas.py`에서 sample type / staining / loading / drug 메타 검증).
2. **LD segmentation + 정량** — per-LD area · diameter · circularity · max/integrated intensity, per-cell LD count/total area/mean diameter (`lib/quant.py`).
3. **Subtype 분류** — macrosteatosis(>5 µm) · medium(1–5 µm) · microsteatosis(<1 µm) 자동 분류, 약물별 subtype shift heatmap, resmetirom-like(macro→micro) · DGAT2(전체 size↓) · SCD1 · FGF21 등 MOA fingerprint pattern matching.
4. **Co-localization + coat protein** — LD-mito Manders M1/M2 + Pearson + per-LD distance to nearest mito, LD-ER contact, perilipin 1/2/3/5 per-LD ring intensity, vehicle 대비 PLIN coat composition log2 FC (`lib/coloc.py`).
5. **Dose-response + 보고서** — 4PL sigmoidal dose-response fit, IC50/EC50 자동 추출 (`lib/dose_response.py`), MOA fingerprint cosine similarity matching (`lib/moa.py`), 한국어 PDF + figure-ready PNG/PDF + CSV export (`lib/report.py`).

## MVP scope vs Future scope

| 기능 | MVP | Future scope |
| --- | --- | --- |
| 실제 이미지 segmentation (Cellpose 2 / StarDist) | ❌ | ✅ |
| Bioformats raw image import (czi/lif/nd2/oir) | ❌ (메타 schema만) | ✅ |
| 미리 추출된 per-LD object table 입력 → 정량 + screening 보고서 | ✅ | ✅ |
| 4PL IC50 / EC50 fit | ✅ | ✅ |
| MOA fingerprint matching (cosine) | ✅ | random forest / VAE 임베딩 |
| LD-mito/ER contact + PLIN coat shift | ✅ (precomputed) | 3D contact site reconstruction |
| 한국어 PDF screening 보고서 | ✅ | LaTeX/Quarto 풀버전 |

## 디렉토리 구성

```
.
├── README.md
├── main.py                # CLI
├── data/                  # --demo 시 자동 생성되는 합성 input
├── output/                # 보고서/figure/CSV 산출물
├── lib/
│   ├── schemas.py         # pydantic schema (LD object, plate map, cell meta)
│   ├── quant.py           # per-cell / per-well aggregation, subtype 분류
│   ├── coloc.py           # Manders/Pearson, PLIN coat composition shift
│   ├── dose_response.py   # 4PL sigmoidal fit + IC50/EC50
│   ├── moa.py             # MOA fingerprint cosine matching
│   ├── report.py          # 한국어/영문 PDF + figure-ready PNG
│   └── synth.py           # 합성 데이터 생성 (96 well, 8 drug × 6 dose × 2 rep)
└── QA.md                  # 검수 로그
```

## 실행법

### Demo (합성 데이터 + 한국어 보고서, MOA + IC50 모두)
```bash
cd "/Users/sangjoonpark/claude daily project/2026 metabolic daily idea/projects/2026-05-02-3-mash-lipid-droplet"
python3 main.py --demo --report-dir ./output --moa-match --ic50 --language ko
```

### 실제 데이터
```bash
python3 main.py \
  --ld-table /path/to/ld_objects.csv \
  --plate-map /path/to/plate_map.csv \
  --reference-moa /path/to/reference_moa_fingerprints.csv \
  --report-dir ./output --moa-match --ic50 --language ko
```

`python3 main.py --help` 으로 모든 옵션 확인.

## 입력 컬럼 스펙

### `ld_objects.csv` (per-LD object table)
`well, cell_id, ld_id, area_um2, diameter_um, circularity, max_intensity, integrated_intensity, distance_to_mito_um, manders_m1, manders_m2, pearson, plin1_intensity, plin2_intensity, plin3_intensity, plin5_intensity`

### `plate_map.csv`
`well, drug, dose_uM, replicate`

### `cell_meta.csv` (선택)
`well, cell_count, cell_type` — cell_type ∈ {HepG2, Huh7, primary_mouse, primary_rat, primary_human, iPSC, HepaRG, spheroid, organoid, STAM_cryosection, HFD_cryosection, MCD_cryosection, CDAA_HFD_cryosection}

### `reference_moa_fingerprints.csv`
`drug, macro_pct, medium_pct, micro_pct, total_LD_area_per_cell, ld_count_per_cell, manders_m1, plin1_mean, plin5_mean`

## 산출물

`output/` 디렉토리에 생성:

- `MASHLipidDroplet_report.pdf` — 한국어/영문 screening 보고서 (요약 · IC50 · figure 포함)
- `fig_subtype_heatmap.png` — 약물별 LD subtype % heatmap
- `fig_dose_response_ld_count.png`, `fig_dose_response_total_area.png` — 용량-반응 곡선
- `fig_moa_top1.png` — 약물 → reference MOA top-1 매핑 heatmap
- `fig_plin_coat_shift.png` — vehicle 대비 PLIN1/2/3/5 coat composition log2 FC
- `per_cell_summary.csv`, `per_well_summary.csv`, `per_well_coloc.csv`, `per_well_plin_coat.csv`
- `dose_response_fits.csv` — 약물 × response 별 EC50/IC50 / hill / R²
- `moa_match_long.csv`, `moa_match_top1.csv` — MOA fingerprint 매칭 결과
- `manifest.json` — 산출물 인덱스

## 검수 체크리스트

1. `python3 -c "import ast; ast.parse(open('main.py').read())"` 통과 + `lib/*.py`
2. `python3 main.py --demo --report-dir ./output --moa-match --ic50 --language ko` 종료코드 0
3. `output/MASHLipidDroplet_report.pdf`, `output/*.png`, `output/*.csv` 생성 확인
4. `python3 main.py --help` 정상

자세한 검수 로그는 `QA.md` 참조.

## 출처

아이디어 #3 from `daily-ideas/2026-05-02.md` (2026-05-02 metabolic daily idea pipeline).

## 디스클레이머 (재차)

- 본 도구의 결과는 **참고용 screening 보조 데이터**입니다.
- **임상 진료 / 환자 의사결정 / 정부·인허가 제출 자료에 단독으로 사용하지 마십시오.**
- 모든 결과는 wet-lab 검증 및 외부 통계 검토를 거친 뒤 사용해야 합니다.
- 합성 데이터로 동작 시연한 결과(`--demo`)는 **실제 약물 효과를 의미하지 않습니다**.