| ---
|
| license: cc-by-4.0
|
| library_name: pytorch
|
| pipeline_tag: audio-classification
|
| datasets:
|
| - InsectSet32
|
| metrics:
|
| - accuracy
|
| - f1
|
| tags:
|
| - audio-classification
|
| - insect
|
| - bioacoustics
|
| - experimental
|
| - local-inference
|
| - litert
|
| - tflite
|
| ---
|
|
|
| # Kernel Insect Sound Classifier (InsectCNN `full_model`, experimental 0.1.0)
|
|
|
| A compact CNN (159k parameters) that classifies **32 sound-producing insect species** (9 Orthoptera, 23 Cicadidae) from audio. It was trained on [InsectSet32](https://zenodo.org/records/7072196).
|
|
|
| > **This is not a grain-pest detector.** Do not use it to certify grain as clean or safe, to accept or reject lots, or to trigger treatment. It is a research baseline trained on a small dataset.
|
|
|
| ## Model details
|
|
|
| | | |
|
| |---|---|
|
| | Architecture | `InsectCNN`: 3 conv blocks (16/32/64 ch, BatchNorm, ReLU) + dense head (128) with dropout 0.25 (`src/model.py`) |
|
| | Input | Mono audio → resampled to 16 kHz → 2 s windows, peak-normalised → 64-bin log-mel (n_fft 512, hop 160), per-record standardised (`src/audio.py`) |
|
| | Inference | Softmax averaged over 5 evenly spaced 2 s windows (`eval_crops: 5` in `config.json`) |
|
| | Output | 32 species scores, plus a hierarchical species → genus → group answer |
|
| | Base model | None. Trained from scratch (no pretrained weights, not a fine-tune) |
|
| | Framework | PyTorch & Google LiteRT / TFLite |
|
|
|
| ### Files
|
|
|
| - `model.tflite`: Google LiteRT / TensorFlow Lite on-device model for Android / edge mobile deployment.
|
| - `model.pt`: PyTorch state dict weights. Load it with `torch.load(..., weights_only=True)`.
|
| - `model.h5`: PyTorch state dict in a project-specific HDF5 layout (`kernel-pytorch-state-dict-hdf5-v1`). **It is not a Keras model.** `src.inference.load_model` reads it.
|
| - `config.json`, `labels.json`: architecture, preprocessing settings and class-index → species mapping.
|
| - `metrics.json`, `history.json`: test metrics (with per-class report) and the training curve.
|
| - `src/`, `predict.py`, `export_litert.py`, `test_inference.py`: model definition, audio frontend, exporter and testing scripts.
|
| - `train.py`, `evaluate.py`, `data/*.csv`: reproduction scripts and the official split annotations (the audio itself is not included).
|
|
|
| ## Usage
|
|
|
| This is a custom PyTorch model. It does **not** load with `transformers`, and the hosted inference widget and Inference API don't support it. Run it locally:
|
|
|
| ```bash
|
| pip install huggingface_hub
|
| python -c "from huggingface_hub import snapshot_download; print(snapshot_download('ganesh333/kernel-insect-classifier', local_dir='kernel-insect-classifier'))"
|
| cd kernel-insect-classifier
|
| pip install -r requirements.txt
|
| python predict.py path/to/recording.wav
|
| ```
|
|
|
| WAV works out of the box. FLAC, OGG and MP3 need `soundfile`, which `requirements.txt` includes. Inference is fully local; no audio is sent anywhere.
|
|
|
| Python API:
|
|
|
| ```python
|
| from src.inference import predict_wav
|
| r = predict_wav("recording.wav", model_dir=".")
|
| print(r["identification"]) # {'level': 'species'|'genus'|'group'|'unknown', 'name': ..., 'confidence': ...}
|
| print(r["predicted_species"], r["confidence"]) # raw top-1
|
| print(r["top_k"], r["quality_pass"], r["quality_reasons"])
|
| ```
|
|
|
| **Hierarchical identification.** The model reports the most specific level whose summed probability is at least 0.6: species, then genus, then group (cicadas vs crickets/grasshoppers). Otherwise it reports `unknown`. The threshold was chosen on the validation split.
|
|
|
| ## Training
|
|
|
| Data: InsectSet32. Using the dataset's official `train`/`validation`/`test` partitions, 331 recordings were loaded (206 / 51 / 74).
|
|
|
| ```bash
|
| # place Cicadidae.csv, Orthoptera.csv, Cicadidae.zip, Orthoptera.zip in data/
|
| python train.py --epochs 60 --random-crop --eval-crops 5 --output .
|
| ```
|
|
|
| - AdamW (lr 1e-3, weight decay 1e-4), batch size 16, class-weighted cross entropy (weights from train only), seed 42.
|
| - Each epoch trains on a fresh random 2 s window per file.
|
| - The checkpoint is chosen by best validation macro-F1 (0.548). The test split was scored once, after selection.
|
| - About 4 minutes on a CPU.
|
|
|
| ## Evaluation
|
|
|
| Official test split (n = 74 recordings). 95% CIs from a file-level bootstrap:
|
|
|
| | Metric | Value |
|
| |---|---|
|
| | Accuracy | 0.486 [0.38, 0.59] |
|
| | Macro-F1 | 0.400 [0.29, 0.47] |
|
| | Weighted-F1 | 0.474 |
|
| | Session-clean accuracy / macro-F1 (n = 48) | 0.458 / 0.343 |
|
|
|
| "Session-clean" counts only test files whose source recording session never appears in train or validation. See *Data leakage* below.
|
|
|
| Accuracy among test files whose score at that level is at least 0.6:
|
|
|
| | Level | Share of test files ≥ 0.6 | Accuracy on those (val / test) |
|
| |---|---|---|
|
| | Species | 43% | 77% / 72% |
|
| | Genus | 77% | 90% / 95% |
|
| | Group | 96% | 98% / 99% |
|
|
|
| For comparison, the earlier center-crop baseline of the same architecture scored 0.392 accuracy and 0.329 macro-F1 on the same split. The CIs overlap, so with only 74 test files these differences are not conclusive.
|
|
|
| ## Limitations
|
|
|
| - **Small, imbalanced data.** Species have 4–22 recordings each, and `Roeselianaroeselii` has no test files. All scores are uncertain.
|
| - **Data leakage.** The official split groups by file, not by source recording: 26 of the 74 test files share a source session with train or validation. Official-split scores are therefore optimistic; the session-clean numbers are the more honest estimate.
|
| - **Label noise.** Five `MHV 318 P.capensis` source files are labelled `Platypleuracfcatenata`. They were kept as published.
|
| - **Closed set.** Every input is mapped onto the 32 trained species. Silence, pure tones and white noise can receive high-confidence species predictions. Use `quality_reasons` and treat `genus`/`unknown` answers as exactly that.
|
| - **Noise sensitivity.** Added background noise (SNR 0–20 dB) often changes the prediction.
|
| - **Not calibrated.** The scores are not probabilities of grain infestation. Recording conditions differ from grain sacks and warehouses.
|
| - **Not mobile-ready.** This is not a validated Android LiteRT/TFLite model. See `docs/deployment.md` before any on-device port.
|
| - `model.pt` is a pickle-based file and may be flagged by the Hub's pickle scanner. It contains only tensors. Prefer `model.h5`, or load with `weights_only=True`.
|
|
|
| ## Dataset attribution and citation
|
|
|
| Trained on **InsectSet32** by Marius Faiß, Baudewijn Odé and Ed Baker (CC BY 4.0, [Zenodo 7072196](https://zenodo.org/records/7072196)). Orthoptera recordings: Baudewijn Odé. Cicadidae recordings: the Global Cicada Sound Collection on Bioacoustica ([doi.org/10.1093/database/bav054](https://doi.org/10.1093/database/bav054)). Copyright in individual recordings belongs to the recordists. See `data/README.txt`.
|
|
|
| For academic use, please cite the dataset paper: Faiß, M. & Stowell, D. *Adaptive representations of sound for automatic insect recognition*, PLOS Computational Biology (2023), [doi.org/10.1371/journal.pcbi.1011541](https://doi.org/10.1371/journal.pcbi.1011541).
|
|
|
| ## License
|
|
|
| - Model weights and this card: **CC BY 4.0**, matching the training data's license. Keep the attribution above when you redistribute.
|
| - Code (`src/`, `*.py`): **MIT**. See `LICENSE`.
|
|
|
