tools: analyze_csv.py — App CSV → Python pipeline 비교/검증 CLI

App 측정 시 자동 저장되는 CSV (Downloads/VesiScan_ADC/*.csv) 를
appshare for_app_share / vesiscan_test.library.method_d 로 재계산해
다음을 비교/시각화하는 영구 분석 툴.

4 modes:
  1. Basic compare: App BV vs Python BV (mean/std/bias/CV)
  2. Ablation: 5 algorithm config (DPS, lr floor 등) 개별 영향
  3. Plot: BV timeseries / app↔py scatter / lr_ratio histogram
  4. Cycle inspect: 특정 scan_id 의 raw → walls → BV detail

설계 의도:
  - 알고리즘 변경 후 회귀 자동 검증
  - 임상 측정 정확도 (catheter ground truth) 비교
  - device-to-device variance 분석
  - lr_ratio 분포로 phantom vs human anatomy 패턴 차이 확인

appshare 경로 자동 탐색 + APPSHARE_DIR env var 지원.

검증: phantom 150 mL CSV (2547 scans) 로 smoke test 통과.
  APP mean=147.6 (-1.6%), Python NEW mean=93.0 (-38%, lr=0.67)
  → ablation 으로 lr_ratio 가 차이의 주범 확인.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

tools/README.md

@@ -0,0 +1,77 @@
+# tools/
+
+VesiScan-Basic 측정 결과 분석 / 검증 툴.
+
+## analyze_csv.py — App CSV → Python pipeline 비교
+
+App 이 측정 시 저장하는 CSV (`Downloads/VesiScan_ADC/*.csv`) 를 읽어,
+appshare 의 Python pipeline (`for_app_share`) 으로 BV 를 재계산하고
+다음을 비교한다:
+
+- App-computed BV vs Python BV (per-scan, aggregate)
+- Method D wall detection rate
+- lr_ratio 분포
+- DPS / lr floor 등 알고리즘 변경 사항의 ablation
+
+### Setup
+
+```bash
+# 의존성
+pip install numpy pandas matplotlib
+
+# appshare repo 경로 (둘 중 하나)
+export APPSHARE_DIR=/path/to/appshare/piezo-phantom-test
+# 또는 명시: --appshare /path/...
+```
+
+### Usage
+
+```bash
+# 기본 비교 (phantom 150 mL)
+python tools/analyze_csv.py ~/Desktop/measure.csv --true 150
+
+# Ablation — 5가지 알고리즘 config 비교 (어느 fix 가 임팩트 큰지)
+python tools/analyze_csv.py measure.csv --true 150 --ablation
+
+# 시각화 plot 저장
+python tools/analyze_csv.py measure.csv --true 195 --plot ./out
+
+# 특정 cycle 디테일 (per-channel walls + signals)
+python tools/analyze_csv.py measure.csv --true 150 --cycle 42
+```
+
+### 출력 예시 (compare mode)
+
+```
+=== BV comparison ===
+  APP (Kotlin): mean= 148.1± 4.2  trim10%= 148.5  bias=  -1.9 ( -1.3%)  CV= 2.9%  lr mean=1.154
+       Python : mean=  92.7±13.4  trim10%=  91.1  bias= -57.3 (-38.2%)  CV=14.4%  lr mean=0.680
+
+=== App ↔ Python diff ===
+  mean= +55.03  std=15.83  range=[-45.3, +74.7]
+  |diff| < 5 mL: 5/551 (0.9%)
+```
+
+### Ablation Config 종류
+
+| 코드 | DPS | lr_ratio | 설명 |
+|---|---|---|---|
+| A | 1.936 | =1.0 강제 | OLD Kotlin equivalent (sim) |
+| B | 1.981 | =1.0 강제 | DPS fix 단독 |
+| C | 1.981 | Python 알고리즘 | **현재 b733d4f 결과** |
+| D | 1.981 | Python + floor 1.0 | hybrid |
+| E | 1.936 | Python 알고리즘 | lr 단독 영향 |
+
+### CSV 포맷 (AdcCsvLogger 기준)
+
+```
+scan_id, timestamp, ..., volume_ml, lr_ratio, ..., channel, s0..s99
+```
+한 scan = 6 rows (CH0..CH5), 100 samples / row.
+
+### 활용 예
+
+1. **임상 BV 검증**: catheter 직후 측정 → `--true <catheter_vol>` 로 정확도 비교
+2. **알고리즘 변경 검증**: 새 fix 후 같은 CSV 로 `--ablation` 돌려 회귀 여부 확인
+3. **Device-to-device variance**: 두 device 의 같은 phantom 측정 → CV 비교
+4. **lr_ratio 패턴**: human cohort 의 `--plot` 으로 lr 분포 시각화