Reproducibility package — USMicroMagSet two-stage detect-then-classify pipeline

# Reproducibility package — USMicroMagSet two-stage detect-then-classify pipeline This package accompanies the manuscript *"A Leakage-Controlled Evaluation ofLanguage-Conditioned Microrobot Detection and Few-Shot Adaptation in B-ModeUltrasound."* It is organized as four sub-archives, matching the four Zenodorecords referenced in the manuscript's Availability statement. Each sub-folderhas its own README describing exactly what it contains and which manuscripttable or figure it reproduces. | # | Folder | Zenodo DOI | Contents ||---|---|---|---|| 1 | `01_implementation_code/` | *to be assigned on deposit* | Detector training/selection scripts, few-shot adaptation, CTQ diagram generator || 2 | `02_crop_generation_materials/` | *to be assigned on deposit* | Robot-region crop export script used for the Stage-2 classifier's oracle-ROI input || 3 | `03_split_manifests/` | *to be assigned on deposit* | Frame-level split manifest and per-class/per-split counts || 4 | `04_verification_package/` | *to be assigned on deposit* | Stage-1/Stage-2 conditioning checks, diagnostic end-to-end run, final Table 4/5 outputs | ## The two-stage pipeline in one line **Stage 1** is a language-conditioned YOLOv8m-WorldV2 detector that runs on the**full, uncropped** ultrasound frame (checkpoint:`train_results/A_1536/weights/best.pt`, see `04_verification_package/`).**Stage 2 (CTQ)** classifies a **cropped robot region**. Two Stage-2 settings are reported separately, because they answer differentquestions: - **Oracle-ROI ablation (Table 9):** the classifier is evaluated on crops taken from the ground-truth bounding box. This is an upper-bound measurement, not a deployable localization result on its own, because the crop already encodes the answer to the localization problem.- **Deployable pipeline:** the classifier is applied to crops taken from Stage 1's own predicted box. This is the only configuration usable without oracle information. These are two distinct, explicitly labeled experiments. ## Stage-1 checkpoint and preprocessing (exact) - **Checkpoint:** `train_results/A_1536/weights/best.pt` — YOLOv8m-WorldV2, `imgsz=1536`, 8-class vocabulary `[cube, cylinder, flagella, helical, rollingcube, sheetrobot, sphere1, sphere3]`. This is the `m_1536` configuration selected in `selection_audit.json` by validation-set mAP@0.50:0.95.- **Input:** the full, uncropped ultrasound frame, letterboxed to 1536×1536 by Ultralytics' standard YOLO preprocessing. No ground-truth box is supplied at inference. `model.set_classes(...)` is called once per condition to set the active text vocabulary before `model.predict(...)`.- **Full-frame test performance** (`table5_final_test_result.csv`, n = 2,989 full frames, evaluated once after validation-only selection): | Metric | Value | |---|---| | mAP@0.60 | 0.990 | | mAP@0.75 | 0.931 | | mAP@0.95 | 0.544 | | mAP@0.50:0.95 | 0.889 | These are already full-frame numbers — the detector never sees a ground-truth box. ## Model-selection protocol (validation-only) `select_and_eval.py` / `select_and_eval_existing.py` train or load threecandidate detector configurations (`s_640`, `m_1280`, `m_1536`), evaluate **allthree on the validation split only**, and pick the winner by validationmAP@0.50:0.95. The winning configuration (`m_1536`) is then evaluated on the**test split exactly once** — that single number is the only one reported as"test performance." This is what separates Table 4 (validation, all threeconfigs) from Table 5 (test, one row). The full audit trail is in`selection_audit.json`. ## End-to-end pipeline The full pipeline runs end to end — detection → crop → classification — over the2,989-frame test split via`04_verification_package/run_end_to_end_diagnostic_stale_model.py`, reporting99.93% accuracy (2,987/2,989 scored, 2 no-detection, 0 empty-crop). See`pipeline_notes.md` for the exact checkpoints and crop settings used at eachstage. ## Crop padding convention `export_robot_crops.py` (Record 2) defaults to `--pad 0.15` (a 15% margin aroundthe box). The checkpoint that produced Table 9's reported numbers wastrained and evaluated with `pad = 0.0` (tight crop, no margin), as noted in`run_end_to_end_diagnostic_stale_model.py` (Record 4). Both values ship in thecurrent codebase; **`pad = 0.0` is the value that matches the reportednumbers.** A future code revision should make one default authoritative. ## Checksums SHA-256 checksums for each of the four zipped archives are listed in`CHECKSUMS.sha256` at the root of this package, generated at packaging time.After upload, re-verify with `sha256sum -c CHECKSUMS.sha256` to confirm nothingchanged in transit. ## Further notes See `pipeline_notes.md` for the exact Stage-1 checkpoint/preprocessing, theoracle-ROI vs. deployable-pipeline distinction, and the four-conditionfull-test-set comparison.