Speeding up taxonomy in the digital age: A deep learning approach for identifying cryptic freshwater snails

Speeding up taxonomy in the digital age: A deep learning approach for identifying cryptic freshwater snails We demonstrate how to use multimodal siamese networks to achieve high performance in the taxonomy of cryptic specieswith _Radomaniola_ as model genus. Dataset download The dataset can be obtained from zenodo: [The Radomaniola Dataset](https://zenodo.org/records/18745386).Replicating experiments might require adaption of the dataset directory in `experiments/experiment_base.py`; once inthe variable `data_dir`, once in the method `initialize_data_module`(see `ExperimentBase.run_experiment`) to reflect the local data setup. Installation This code was developed with python 3.13 and cuda 13.2. First, clone repository files into new directory: git clone https://github.com/dennisrv/identifying-cryptic-snails identifying_cryptic_snailscd identifying_cryptic_snails To install requried packages run pip install -r requirements.txt Important caveat: there is no package install step, the repository root has to be on `PYTHONPATH` so that `src` and`experiments` import as top-level packages. For example to run the cross-validation experiment use PYTHONPATH=$PYTHONPATH:$(pwd) python experiments/crossval.py --device=cuda:0 --epochs=20 --batch_size=64 --folds=5 --repeats=5 This command makes the local library files available to python, and runs the experiment on GPU 0, with 20 epochs oftraining, a batch size of 64 and 5-fold cross validation (5 times repeats with different splits). For a full list of supported command line arguments see method `get_commandline_args` in file `experiments/__init__.py`. The available experiments are `crossval.py`, `new_site.py`, `iterative_retrain.py`, `reduced_size_retrain.py` and`online_embeddings.py`; `run_all.py` runs all of them in sequence. Each experiment trains several runs on the samedata splits, so the resulting numbers are directly comparable across training regimes. Important: Current logic puts the whole training dataset on the GPU to accelerate training. Training with the_Radomaniola_ dataset and MobileNetV3small network on a batch size of 64 requires ~6GB available VRAM and takes ~2minutes per single 20 epoch training run.Use of larger backbone models and / or datasets might drastically increase required GPU memory. To run the unit tests use PYTHONPATH=$PYTHONPATH:$(pwd) python -m pytest Repository Structure `src/` - core library code, containing the models (`src/models/`) and the training framework(`src/training/`). `src/training/` - the training framework: the training loop (`trainer.py`), reporting and checkpointing(`callbacks/`), data splitting schemes (`validation/`), and the training regimes themselves (`styles/`:supervised classification, embedding / metric learning, and self-supervised). `src/datasets/` - dataset loading and pre-processing logic. `tests/` - unit tests for some components. `experiments/` - implementation of the different experiments described in the paper.These configure and run the framework in `src/training/`. `notebooks/` - exploratory notebooks. `graphs.ipynb` contains the logic to reproduce the graphs in thepaper. Due to github filesize limitations, the experiment result files under notebooks/data are compressed; rerunning the graphs notebook requires uncompressing them first. `end_to_end.ipynb` walks through the full training and application pipeline of a single model,including confidence analysis, t-SNE visualization of the embedding space and Grad-CAM explanations;`explore_embeddings.ipynb` contains additional code to investigate the embedding space of trainedmodels. How the pieces fit together Four orthogonal components are combined by a `Trainer` (`src/training/trainer.py`) that owns the training loop: - **models** (`src/models/`) — every model is a serializable `*Spec` config object plus the `*Network` it builds, which makes trained models fully reconstructible from a JSON config;- **training styles** (`src/training/styles/`) — *how* a model is trained: plain classification, embedding / metric learning, or self-supervised;- **validation strategies** (`src/training/validation/`) — *how* the data is split into train / validation / test sets;- **data modules** (`src/datasets/`) — loading images and morphometric measurements into GPU tensors. A `TrainingRun` (`src/training/training_run.py`) bundles model specs, one training style and a set of splits, andtrains every model × split combination. Progress and results are reported through callbacks(`src/training/callbacks/`) that print metrics, write TensorBoard logs and CSV files, store model weights andplot embedding spaces. Where a split provides a validation set, the trainer selects the model with the best validation score, calibrates itby temperature scaling on the same validation data, and only then evaluates the test set once — so reported testmetrics describe the selected, calibrated model rather than the last training epoch. Results layout Each experiment writes into a timestamped directory, with one subtree per kind of artifact: results//// model_snapshots////epoch-model.weights.pt logged_metrics/ ///tracked_metrics.csv embedding_plots////embeddings_epoch.svg run_metadata/ split_info.json run_metadata/ //{model.conf.json, test_summary.csv} TensorBoard event files are written to a separate `logs/` tree with the same sub-hierarchy, so the bulky event filesdo not have to be transferred along with the results. `split_info.json` records the actual train / validation / testindices and `model.conf.json` the configuration that rebuilds the stored weights, which together allow a saved modeland its evaluation to be reproduced later (see `src/training/saved_models.py`). `test_summary.csv` reports thefinal test metrics as mean ± standard deviation across splits. The helper `collect_results`(`experiments/__init__.py`) aggregates the per-split CSV files into the tables used by thenotebooks. Extending this code To implement new pre-trained networks, extend `BackboneSpec` (or `TimmSpec`) in `src/models/backbone/`; toimplement new methods for embedding learning extend `StrategyBase` in`src/training/styles/embedding_strategies/`. See the respective directories for exampleimplementations (e.g. `MobileNetSpec`/`ResNetSpec` for backbones, `Siamese`/`Triplet` for embedding learning). New training regimes should extend `TrainingBase` in `src/training/styles/`, new data splitting schemes`ValidationStrategy` in `src/training/validation/`, and new reporting or checkpointing logic `Callback` in`src/training/callbacks/`. New experiments should inherit from abstract class `ExperimentBase` in `experiments/experiment_base.py`. Different datasets should be implemented similar to `SnailDataModule` / `RadomaniolaDataModule` in `src/datasets`;including all required pre-processing logic. License This code is available under the MIT license. See `LICENSE.md` file for more info. Citation If you use this work, please cite the corresponding paper: