Intelligent Bark Beetle Identifier (IBBI)

IBBI is a Python package that provides a simple and unified interface for detecting and classifying bark and ambrosia beetles from images using state-of-the-art computer vision models.

This package is designed to support entomological research by automating the laborious task of beetle identification, enabling high-throughput data analysis for ecological studies, pest management, and biodiversity monitoring.

Motivation

The ability to accurately detect and identify bark and ambrosia beetles is critical for forest health and pest management. However, traditional methods face significant challenges:

• They are slow and time-consuming.
• They require highly specialized expertise.
• They create a bottleneck for large-scale research.

The IBBI package provides a powerful, modern solution to overcome these obstacles by making available pre-trained, open-source models to automate detection and classification from images, lowering the barrier to entry for researchers. The IBBI package also makes other advanced techniques available to the user such as general zero-shot detection, general feature extraction, model evaluation, and model explainability.

Key Features

• Model Access: Access powerful models with a single function call ibbi.create_model(). The following types of models are available:

  • Single-Class Bark Beetle Detection: Detect the presence of any bark beetle in an image. These models have been trained with the task of single-class object detection on Bark and ambrosia beetle specific data. These models do not classify the species of beetle, only its presence and location in an image.

  • Multi-Class Species Detection: Identify the species of a beetle from an image. These models have been trained with the task of multi-class object detection on Bark and ambrosia beetle specific data. These models classify the species of beetle, as well as its presence and location in an image.

  • General Zero-Shot Detection: Detect objects using a text prompt (e.g., "insect"), without prior training on bark and ambrosia beetle specific data (e.g., GroundingDINO, YoloWorld). These models have been trained on large, diverse datasets and can generalize to detect a wide range of objects based on textual descriptions.

  • General Pre-trained Feature Extraction: Extract feature embeddings from images using pre-trained models without additional training for specifically identifying bark and ambrosia beetles (e.g., DINOv3, EVA-02).

• Model Evaluation: This package includes a small set of ~2 000 images of 63 species for benchmarking model performance using a simple call to the ibbi.Evaluator() wrapper. The evaluation wrapper makes computing of the following types of metrics easy:

  • Classification Metrics: Assesses the model's ability to correctly classify species. The evaluator.classification() method returns a comprehensive set of metrics including accuracy, balanced accuracy, F1-score, Cohen's Kappa, precision, and recall alongside a confusion matrix.

  • Object Detection Metrics: Evaluates the accuracy of bounding box predictions. The evaluator.object_detection() method calculates the mean Average Precision (mAP) over a range of Intersection over Union (IoU) thresholds. You can also get per-class AP scores to understand performance on a species-by-species basis.

  • Embedding & Clustering Metrics: Evaluates the quality of the feature embeddings generated by the models. The evaluator.embeddings() method performs dimensionality reduction with Uniform Manifold Approximation and Projection (UMAP) and clustering with Hierarchical Density-Based Spatial Clustering of Applications with Noise (HDBSCAN), then calculates:

---

Table of Contents

• Intelligent Bark Beetle Identifier (IBBI)
  • Motivation
  • Key Features
  • Table of Contents
  • Workflow: How the Models Were Built
  • Package API and Usage
  • Installation
    • Hardware Requirements
  • Quick Start
  • Available Models
  • Advanced Usage
  • How to Contribute
  • License

---

Workflow: How the Models Were Built

The trained models in ibbi are the result of a comprehensive data collection, annotation, and training pipeline by the Forest Entomology Lab at the University of Florida.

1. Data Collection and Curation: The process begins with data collection from various sources. A zero-shot detection model performs initial bark beetle localization, followed by human-in-the-loop verification to ensure accurate bounding box annotations. Species classification is performed by expert taxonomists to provide high-quality species labels.

2. Model-Specific Training Data: The annotated dataset is curated for different model types:

   • Single-Class Detection: Trained in a supervised manner on the task of object-detection and object-classification using all images with verified bark beetle localizations.
   • Multi-Class Species Detection: Trained in a supervised manner on the task of object-detection and object-classification using images with both verified localizations and species-level labels. To ensure robustness, species with fewer than 50 images are excluded.

   Note - No additional training is performed for the zero-shot detection and general feature extraction models, as they leverage pre-trained weights from large, diverse datasets.

3. Evaluation and Deployment: A held-out test set is used to evaluate all models. A summary of performance metrics can be viewed with ibbi.list_models() or by simply viewing the model summary table. Alternatively evalutation can be done independently by running ibbi.Evaluator(). The trained models are stored under the IBBI-bio Hugging Face Hub community for easy access.

---

Package API and Usage

The ibbi package is designed to be simple and intuitive. The following diagram summarizes the main functions, classes and methods including their inputs and outputs.

---

Installation

This package requires PyTorch. For compatibility with your specific hardware (e.g., CUDA-enabled GPU), please install PyTorch before installing ibbi.

1. Install PyTorch

Follow the official instructions at pytorch.org to install the correct version for your system.

2. Install IBBI

Once PyTorch is installed, install the package from PyPI:

pip install ibbi

Or install the latest development version directly from GitHub:

pip install git+https://github.com/ChristopherMarais/IBBI.git

Hardware Requirements

• Disk Space: A minimum of 10-20 GB of disk space is recommended to accommodate the Python environment, downloaded models, and cached datasets.

• CPU & RAM: Running inference on a CPU is possible but can be slow. For model evaluation on large datasets (like the built-in test set), a significant amount of RAM (16GB, 32GB, or more) is highly recommended to avoid memory crashes.

• GPU (Recommended): A CUDA-enabled GPU (e.g., NVIDIA T4, RTX 3060 or better) with at least 8GB of VRAM is strongly recommended for both inference and model evaluation.

---

Quick Start

Using ibbi is straightforward. Load a model and immediately use it for inference.

import ibbi

# --- List Available Models ---
ibbi.list_models()

# --- Create a Model ---
classifier = ibbi.create_model(model_name="species_classifier", pretrained=True)

# --- Perform Inference ---
results = classifier.predict("path/to/your/image.jpg")

For more detailed demonstrations, please see the example notebooks located in the notebooks/ folder of the repository.

---

Available Models

To see a list of available models and their performance metrics directly from Python, run:

ibbi.list_models()

Replace model_name with one of the available model names to use those models.

Model Summary Table

The most detailed version of the table can also be found here.

ID = In-Distribution (i.e., species seen during training) OOD = Out-of-Distribution (i.e., species not seen during training)

| Model Name | Tasks | Pretrained Weights Repository | Paper | Model Size (Parameters) | Image size | Embedding vector shape | # of images fine-tuned | Epochs fine-tuned | Species mAP (ID) | Genus mAP (ID) | Genus mAP (OOD) | Organism mAP (ID) | Organism mAP (OOD) | Silhouette (ID) | Davies-Bouldin (ID) | Calinski-Harabasz (ID) | ARI (ID) | NMI (ID) | Cluster Purity (ID) | Mantel R (ID) | p-value (ID) | Mantels R support (ID) | Silhouette (OOD) | Davies-Bouldin (OOD) | Calinski-Harabasz (OOD) | ARI (OOD) | NMI (OOD) | Cluster Purity (OOD) | Mantel R (OOD) | p-value (OOD) | Mantels R support (OOD) | |-------------------------------------------------|------------