# CHANGELOG — RodentMealScope

## [2026-05-18]

### 수행 내용
- 비만 도메인 동물실험 도구 MVP "RodentMealScope" 신규 구축.
- 설치류 자동 급이기 섭식 이벤트 로그를 식사(meal) 미세구조로 분해하는
  단독 실행형 Streamlit 앱 개발.
- 5개 핵심 기능 구현:
  1. 다중 하드웨어 이벤트 정규화 (BioDAQ/FED3/feeder/lickometer/PhenoMaster)
     + QC 플래그(흘림·이중계수·장비누락).
  2. Tolkamp 로그-생존곡선 변곡점법 기반 객관적 식사 기준 도출 + 수동 override.
  3. 식사 미세구조 지표 (크기·시간·빈도·IMI·섭취속도·포만비·첫식사잠복기).
  4. 일주기 분해 (dark/light 위상, ZT bin, 급성 vs 만성 약효 분리).
  5. 코호트 통계 (ANOVA·MixedLM) + 기전 분류 + Method/Result 리포트(한/영).
- 합성 데이터 생성기로 24개체 3군 5일치 5563 이벤트 로그 생성.
- QA 6개 항목 수행, 전부 PASS.

### 주요 결정 사항
- **계산 로직을 meal_core.py 로 분리**: Streamlit 없이 단독 테스트·CI 가능하도록.
  app.py 는 UI/오케스트레이션만 담당.
- **식사 기준 변곡점 선택 알고리즘**: 봉우리 '높이' 상위 2개가 아니라 시간
  축 양 끝(최단=식사내부, 최장=식사사이) 봉우리 사이의 최소밀도 '연속구간
  중앙'을 antimode 로 선택. 식사 내부 간격이 식사 사이 간격보다 압도적으로
  많아 높이 기준은 두 within-meal 봉우리를 잘못 고르기 때문.
- **합성 데이터에 최소 식사간격(12분) 강제**: 간격 분포의 이봉성을 보장하여
  Tolkamp 변곡점법이 의미 있게 작동하도록.
- **statsmodels 미설치 graceful degradation**: MixedLM 적합 실패 시 예외를
  잡아 메시지 반환, 앱 크래시 없음. requirements.txt 에는 명시.
- **개체 ID 군별 고유 접두(CTL/DGA/DGB)**: 초기 `grp[:1]` 방식이 Drug-A/B
  ID 충돌을 일으켜 수정.

### 변경된 파일
- `meal_core.py` (신규) — 순수 파이썬 계산 모듈.
- `app.py` (신규) — Streamlit 앱, 5개 탭 UI.
- `generate_sample_data.py` (신규) — 재현 가능 합성 데이터 생성기.
- `data/sample_feeder_events.csv` (신규) — 메인 합성 로그.
- `data/sample_fed3_export.csv` (신규) — FED3 포맷 예시.
- `data/sample_lickometer_export.csv` (신규) — lickometer 포맷 예시.
- `requirements.txt` (신규) — 고정 버전 의존성.
- `README.md` (신규) — 한국어 기준 문서, 면책 문구 포함.
- `QA.md` (신규) — QA 점검 로그.

### 재현 방법
1. 프로젝트 디렉터리로 이동.
2. `pip install -r requirements.txt`
3. (선택) `python3 generate_sample_data.py` — 합성 데이터 재생성
   (고정 시드 20260518, 결정론적).
4. `streamlit run app.py` — 브라우저에서 사이드바 "데모 데이터 불러오기"
   선택 시 즉시 전체 기능 확인 가능.
5. 계산 로직만 검증하려면: `python3 -c "import pandas as pd, meal_core as mc;
   print(mc.run_pipeline(pd.read_csv('data/sample_feeder_events.csv'))['criterion'])"`