# SarcopeniaMuscleTrack (사코페니아무스코트랙)

Sarcopenic obesity 동물모델 cohort raw 데이터를 import하여 baseline-locked % change trajectory, lean-mass-normalized 기능평가, myofiber type composition, muscle-sparing co-therapy decompose 분석을 수행하는 동물실험 데이터 분석 도구.

- **도메인**: Obesity (sarcopenic obesity 동물모델)
- **카테고리**: 동물실험 도구 — 데이터 분석·이미지 정량 (summary table 기반)
- **출처**: aaa idea #2 from `daily-ideas/2026-05-02.md` (2026 metabolic daily idea pipeline)
- **OpenClaw alignment**: `project_openclaw_bio_pivot.md`(비만/근감소 약물 재조합 DB)와 schema-level 호환

## 핵심 기능 5

1. **Cohort 등록 + 모델 메타데이터**
   - sarcopenic obesity 모델: HFD+aging, HFD+OVX, HFD+dexa, HFD+cachexia, db/db+aging, MSTN−/− HFD
   - 약물 군: vehicle / semaglutide / tirzepatide / retatrutide / bimagrumab / ActRIIB-Fc / trevogrumab / apitegromab / 조합
   - randomization seed · sample size pre-registration log

2. **6~8 modality import**
   - body weight (weekly)
   - EchoMRI/qNMR body composition (baseline·W4·…·W24)
   - grip strength force-meter csv
   - treadmill exhaustion csv
   - micro-CT muscle CSA region table (gastroc, soleus, TA, quad + IMAT)
   - myofiber HCS imaging summary table (fiber CSA distribution, MyHC type composition, Pax7, centronucleated %)
   - ex vivo force csv (LabChart-style summary)
   - myokine ELISA (myostatin, activin A, irisin, decorin, BAIBA)

3. **Baseline lock · % change trajectory**
   - 약물 시작 시점 baseline lock
   - BW · lean mass · fat mass · grip(absolute + per gram lean mass) · treadmill · myofiber CSA · myokine % change
   - spaghetti + median ± IQR
   - **sarcopenic obesity composite endpoint**: BW <-5% AND lean mass >-3% AND grip per lean mass >+5% (pass/fail)

4. **Muscle-sparing decompose**
   - GLP-1RA monotherapy로부터 expected lean-mass-loss linear 예측
   - co-therapy actual lean-mass-loss
   - **sparing effect = expected − actual**
   - **Muscle-Sparing Index (MSI) = lean preserved / fat lost**
   - fiber type protection 패턴 자동 탐지 (IIB > IIX > IIA > I)

5. **보고서 + OpenClaw hook**
   - cohort별 한국어 PDF (KSSO·KDA·국제비만학회 발표용 layout)
   - modality별 figure-ready PNG/PDF
   - OpenClaw 표준 schema export (Parquet 또는 JSON)
   - Methods section 자동 초안 (ARRIVE 2.0 호환)

## 실행

```bash
# 합성 cohort end-to-end demo (가장 중요)
python3 main.py --demo --report-dir ./output --decompose tirzepatide+bimagrumab --language ko

# 실제 cohort
python3 main.py --cohort-dir ./mycohort --report-dir ./output --decompose tirzepatide+bimagrumab --openclaw-export

# 도움말
python3 main.py --help
```

## 출력 파일

`./output/` 내:
- `report_<cohort>_ko.pdf` — 한국어 보고서
- `figures/*.png|*.pdf` — modality별 figure-ready
- `tables/*.csv` — % change, composite endpoint, MSI
- `openclaw_export.parquet` 또는 `openclaw_export.json`
- `methods_arrive2.md` — Methods section 초안

## 검수 체크리스트

- [ ] `python3 main.py --demo` 종료 코드 0
- [ ] output 디렉토리에 PDF/PNG/CSV/Parquet 또는 JSON 생성
- [ ] composite endpoint pass/fail 산출
- [ ] muscle-sparing decompose: expected − actual 분리값 출력
- [ ] OpenClaw schema export 유효 (parquet 또는 json schema 검증)
- [ ] 한국어 보고서 한글 정상 표시
- [ ] 외부 네트워크 호출 0

## 기술 스택 / 제약

- Python 3.11, stdlib + numpy + pandas + scipy + matplotlib
- pydantic optional (없으면 dataclass fallback)
- pyarrow optional (없으면 JSON export)
- 외부 네트워크 / 외부 API 0
- 무거운 segmentation 모델 (MONAI / Cellpose / nnU-Net) **MVP 미사용**
  - micro-CT / HCS는 미리 추출된 region/fiber summary table을 입력으로 받는다고 가정
  - 실제 segmentation은 **future scope**
- ARRIVE 2.0 reporting guideline 호환 Methods section 초안 생성

## 디스클레이머 / 안전성

- **본 도구는 동물실험 데이터 분석용 — 임상 의사결정 직접 사용 금지**
- 연구·교육·전임상 전용
- 합성 데모 데이터는 약물 효과를 단순화한 합성 시그널이며 실제 임상/전임상 반응을 대체하지 않음
- 재현 시 ARRIVE 2.0 (Animal Research: Reporting of In Vivo Experiments) 가이드라인 준수 권장
- IACUC 승인 / 윤리 심의 / sample size justification은 사용자 책임

## OpenClaw 바이오 피벗과의 alignment

본 도구의 OpenClaw export는 다음을 표준 schema로 emit:
- `cohort_id, mouse_id, model, treatment, dose_mg_kg, week`
- `bw_pct_change, lean_pct_change, fat_pct_change`
- `grip_per_lean_pct_change, treadmill_pct_change`
- `composite_pass, msi, fiber_protection_pattern`
- `myostatin_pct_change, activin_a_pct_change, ...`

→ OpenClaw "비만/근감소 약물 재조합 DB"의 trial-level / molecule-level 입력으로 직접 ingest 가능.