# 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 분포 시각화