Confound-aware benchmarking of automated wing landmarking in honey bees

Analysis code, processed metadata, trained model weights, per-wing predictions and all metric files underlying the manuscript *"Automated Wing Landmarking for Honey Bee Monitoring: Wing Shape Adds Geographic Information Beyond Acquisition Metadata"* and its Supplementary Materials. Authors: Abdulaziz Seraj Alnori, Zool Hilmi Ismail, Gianmarco Goycochea Casas. ## What is here | Folder | Contents | |---|---| | `code/analysis/` | The analysis pipeline: dataset preparation, detector training, controls, inferential statistics, figures and the verification script | | `code/seed_replication/` | The independent-seed replication reported in Supplementary Section S1 | | `data_processed/` | The processed manifest (17,457 wings, 1,557 colonies) with landmark coordinates, colony and country labels, acquisition metadata and the split assignment | | `results_main/` | Every metric file and prediction table quoted in the main text | | `results_seed_replication/` | Per-seed metrics, predictions and the summary tables of Supplementary Section S1 | | `model_weights/` | Trained weights for the one-stage detector, the two-stage detector, the heatmap ablation and the site-grouped retraining | | `figures/` | The six manuscript figures | | `figure_source_data/` | Workbook with the numeric source data behind the plotted figures and the two main tables | ## Source images The wing images themselves are not redistributed here. They are public and must be downloaded from their original deposits: - Southwestern Asian forewings: <https://doi.org/10.5281/zenodo.17075125> - Kazakh forewings: <https://doi.org/10.5281/zenodo.8128010> Extract both so that images sit under `data/raw/images/<COUNTRY>/`, where `<COUNTRY>` is the two-letter code used in `manifest.csv` (AZ, CY, GE, IQ, IR, KZ, SA, TJ, TR). `manifest.csv` stores absolute paths from the machine that produced it; the scripts rebuild them from the country code and file name, so no editing is required. ## Environment Python 3.11.9 on Windows 11. Install with: ``` pip install -r requirements.txt ``` Networks were trained with mixed precision on one NVIDIA GeForce RTX 4060 Laptop GPU (8 GB, compute capability 8.9), PyTorch 2.10.0 with CUDA 12.8 and cuDNN 9.10.2. Because cuDNN kernels are not bit-deterministic, repeated runs differ in the fourth decimal place of the landmark error; the magnitude of that variation is quantified in `results_seed_replication/`. ## Reproducing the main analysis Run from `code/analysis/`, in this order. The detector stages require a CUDA GPU; everything else runs on CPU. ``` python prepare_dataset.py python run_landmark_detector.py python run_two_stage_detector.py python run_metadata_baseline.py python run_landmark_baseline.py python run_crop_heatmap_detector.py python refine_landmarks_with_cornerness.py python evaluate_detector_downstream.py python run_inferential_statistics.py python run_revision_analyses.py python predict_validation_split.py python run_revision2_analyses.py python run_site_grouped_detector.py python run_site_grouped_controls.py python run_revision3_analyses.py python make_figure_source_data.py ``` Outputs are written to `analysis/results/`, mirrored here as `results_main/`. ## Reproducing the seed replication Run from `code/seed_replication/`. It imports the training and inference functions from `code/analysis/` without modification, so each replicate is the same computation as the published run with a different random seed. It writes only into its own output directory and does not alter any artefact of the published run. ``` python run_seed_replication.py --seeds 1 7 2024 python predict_train_per_seed.py python per_class_recall.py ``` Each replicate takes about 32 minutes on the GPU named above. ## Verification `code/analysis/check_manuscript_numbers.py` re-reads every headline number in the manuscript source and checks it against the saved result files, and reports uncited references and undefined citations. Pass the manuscript path as the first argument: ``` python check_manuscript_numbers.py /path/to/insects_manuscript.tex ``` `code/analysis/check_figure_source_data.py` re-resolves every formula in the source-data workbook and checks it against the underlying result files. ## Licence Code is released under the MIT Licence. Data files and figures are released under CC BY 4.0. The source wing images remain under the licences of their original deposits, cited above.