API reference¶

Generated from the docstrings of ibbi. The everyday entry points are at the top; the model, evaluation and data classes follow.

Top-level functions¶

ibbi.create_model ¶

create_model(model_name: str, pretrained: bool = True, **kwargs: Any) -> ModelType

Creates a model from its name or a task alias.

Parameters:

Name	Type	Description	Default
`model_name`	`str`	A model name (see `ibbi.list_models()`) or an alias: "arthropod_detector" (also "beetle_detector"), "species_detector", "hierarchical_classifier" (also "species_classifier" and "feature_extractor") or "zero_shot_detector".	required
`pretrained`	`bool`	Load the trained IBBI weights (default True). For detectors, False loads the generic Ultralytics COCO checkpoint of the same architecture.	`True`
`**kwargs`	`Any`	Passed to the model factory, e.g. `device="cpu"`, `revision=...`, `operating_point="0.95"` for classifiers, `prompts=[...]` / `tile=0` for zero-shot detectors.	`{}`

Returns:

Name	Type	Description
`ModelType`	`ModelType`	The model, ready for `predict`, `predict_proba` and `extract_features`.

Raises:

Type	Description
`KeyError`	If the name is neither a model nor an alias.

ibbi.create_pipeline ¶

create_pipeline(detector: str | Any = 'arthropod_detector', classifier: str | Any = 'hierarchical_classifier', det_conf: float | None = None, operating_point: str | None = None, device: str | None = None, fast: bool | None = None, batch_size: int = 64) -> IdentificationPipeline

Builds the two-stage identification pipeline.

Parameters:

Name	Type	Description	Default
`detector`	`str \| model`	Model name/alias or an instantiated detector. Defaults to the arthropod detector.	`'arthropod_detector'`
`classifier`	`str \| model`	Model name/alias or an instantiated hierarchical classifier. Defaults to the DINOv3 classifier.	`'hierarchical_classifier'`
`det_conf`	`float \| None`	Detector confidence threshold (default 0.25).	`None`
`operating_point`	`str \| None`	Classifier operating point.	`None`
`device`	`str \| None`	Device for models created here.	`None`
`fast`	`bool \| None`	GPU fast path (default: on when running on CUDA); see `IdentificationPipeline`.	`None`
`batch_size`	`int`	Crops per classifier forward pass in the fast path.	`64`

Returns:

Type	Description
`IdentificationPipeline`	IdentificationPipeline

ibbi.list_models ¶

list_models(as_df: bool = False)

Displays or returns a summary of available models and their key information.

This function reads the model summary CSV file included with the package, which contains a comprehensive list of all available models, their tasks, and key performance metrics. It can either print this information to the console in a human-readable format or return it as a pandas DataFrame for programmatic access.

Parameters:

Name	Type	Description	Default
`as_df`	`bool`	If True, the function returns the model information as a pandas DataFrame. If False (the default), it prints the information directly to the console.	`False`

Returns:

Type	Description
	pd.DataFrame or None: If `as_df` is True, a pandas DataFrame containing the model summary is returned. Otherwise, the function returns None.

ibbi.utils.data.get_dataset ¶

get_dataset(split: str = 'iid_test', local_dir: str | Path | None = None, revision: str = BENCHMARK_REVISION, download: bool = True, **kwargs) -> BenchmarkDataset

Loads one split of the Bark and Ambrosia Beetle Detection Benchmark.

Parameters:

Name	Type	Description	Default
`split`	`str`	One of "train", "iid_test", "inat_test", "semantic_ood". Defaults to "iid_test".	`'iid_test'`
`local_dir`	`str \| Path \| None`	Where the benchmark is (or should be) stored. Defaults to the ibbi cache.	`None`
`revision`	`str`	Dataset revision. Defaults to the pinned v2.0.1 commit.	`BENCHMARK_REVISION`
`download`	`bool`	Download missing files from the Hugging Face Hub. Defaults to True.	`True`
`**kwargs`		Accepted for backwards compatibility; `repo_id` other than the benchmark raises an error.	`{}`

Returns:

Name	Type	Description
`BenchmarkDataset`	`BenchmarkDataset`	The split, indexable and iterable; each item has "image" and "objects" keys.

ibbi.utils.data.download_benchmark ¶

download_benchmark(splits: str | Sequence[str] | None = None, local_dir: str | Path | None = None, revision: str = BENCHMARK_REVISION, images: bool = True) -> Path

Downloads (or completes) a local copy of the benchmark and returns its root directory.

Parameters:

Name	Type	Description	Default
`splits`	`str \| Sequence[str] \| None`	Splits whose images should be downloaded. `None` downloads all four.	`None`
`local_dir`	`str \| Path \| None`	Target directory. Defaults to `<ibbi cache>/datasets/bark-ambrosia-beetle-benchmark-<version>`.	`None`
`revision`	`str`	Dataset revision on the Hugging Face Hub. Defaults to the pinned v2.0.1 commit, so results are reproducible; pass "main" for the newest version.	`BENCHMARK_REVISION`
`images`	`bool`	If False, only the annotations, taxonomy, licences and evaluation scripts are downloaded.	`True`

Returns:

Name	Type	Description
`Path`	`Path`	The benchmark root (it contains `detection/annotations_coco/`, `detection/images/<split>/`,
	`Path`	`species_taxonomy.csv` and `evaluation/`).

ibbi.utils.data.get_taxonomy ¶

get_taxonomy() -> pd.DataFrame

Taxonomy of all 175 benchmark species (subfamily, tribe, genus, species, benchmark role, distance band).

benchmark_role is "trainable" for the 65 species the IBBI models know and "semantic_ood" for the 110 held-out species; distance_band_vs_trainable is "near_genus", "mid_tribe" or "far_tribe" for held-out species. Source: species_taxonomy.csv of the benchmark v2.0.1 (CC BY 4.0).

ibbi.utils.data.get_shap_background_dataset ¶

get_shap_background_dataset(image_size: tuple[int, int] = (224, 224), n_images: int = 32, seed: int = 0, revision: str = BENCHMARK_REVISION) -> list[dict]

Returns a small background set for SHAP, sampled from the benchmark's train split.

Only the sampled images are downloaded. The old IBBI-bio/ibbi_shap_dataset is deprecated.

Parameters:

Name	Type	Description	Default
`image_size`	`tuple[int, int]`	Size (width, height) the images are resized to. Should match the size of the images being explained. Defaults to (224, 224).	`(224, 224)`
`n_images`	`int`	Number of background images. Defaults to 32.	`32`
`seed`	`int`	Sampling seed. Defaults to 0.	`0`
`revision`	`str`	Dataset revision. Defaults to the pinned v2.0.1 commit.	`BENCHMARK_REVISION`

Returns:

Type	Description
`list[dict]`	list[dict]: `[{"image": PIL.Image}, ...]`, ready for `ibbi.Explainer.with_shap`.

ibbi.utils.data.taxonomic_distance_matrix ¶

taxonomic_distance_matrix(species: Sequence[str] | None = None) -> pd.DataFrame

Taxonomic distance between species: 0 same species, 1 same genus, 2 same tribe, 3 same subfamily, 4 otherwise.

Parameters:

Name	Type	Description	Default
`species`	`Sequence[str] \| None`	Species names to include. Defaults to all 175 benchmark species.	`None`

Returns:

Type	Description
`DataFrame`	pd.DataFrame: Symmetric matrix indexed by species name.

ibbi.utils.data.get_ood_dataset ¶

get_ood_dataset(local_dir: str | Path | None = None, revision: str = BENCHMARK_REVISION, **kwargs) -> BenchmarkDataset

Deprecated: returns the benchmark's semantic_ood split (110 species never seen in training).

The old IBBI-bio/ibbi_ood_data dataset is no longer used. Call ibbi.get_dataset("semantic_ood") instead.

ibbi.utils.cache.get_cache_dir ¶

get_cache_dir() -> Path

Gets the cache directory for the ibbi package.

This function determines the appropriate directory for storing cached files, such as downloaded model weights and datasets. It first checks for a custom path set by the IBBI_CACHE_DIR environment variable. If the variable is not set, it defaults to a standard user cache location (~/.cache/ibbi).

The function also ensures that the cache directory exists by creating it if it does not already.

Returns:

Name	Type	Description
`Path`	`Path`	A `pathlib.Path` object representing the path to the cache directory.

ibbi.utils.cache.clean_cache ¶

clean_cache()

Removes the entire ibbi cache directory.

This function will permanently delete all downloaded models and datasets associated with the ibbi package's cache. This can be useful for forcing a fresh download of all assets or for freeing up disk space.

Pipeline¶

ibbi.pipeline.IdentificationPipeline ¶

Detector + hierarchical classifier.

Parameters:

Name	Type	Description	Default
`detector`	`Any`	A detector created with `ibbi.create_model` (normally "yolo11x_arthropod_detector").	required
`classifier`	`Any`	A hierarchical classifier created with `ibbi.create_model`.	required
`det_conf`	`float \| None`	Detector confidence threshold. Defaults to 0.25, the detector's general setting; use `detector.operating_conf` (0.70) for fewer false alarms.	`None`
`operating_point`	`str \| None`	Classifier operating point ("0.90", "0.95", "0.99", "gallery").	`None`
`fast`	`bool \| None`	GPU fast path: decode JPEG files on the GPU, letterbox for the detector and crop for the classifier on the GPU, and classify the crops of several images together. Defaults to True when the classifier runs on CUDA. Results match the reference path up to resize rounding (see `docs/benchmark.md`).	`None`
`batch_size`	`int`	Crops per classifier forward pass in the fast path (crops of several images are pooled).	`64`

predict ¶

predict(image, det_conf: float | None = None, operating_point: str | None = None, **kwargs)

Detects and classifies every specimen in one image or a list of images.

Returns:

Type	Description
	dict \| list[dict]: Per image {"boxes" (xyxy), "det_scores", "scores" (detector confidence x calibrated
	species probability), "labels" (reported identification), "species" (best species), "classifications"
	(full per-level records)}.

predict_proba ¶

predict_proba(images: list[ImageInput], **kwargs) -> np.ndarray

Per image, the highest (detector confidence x species probability) of every species: [N, 65].

extract_features ¶

extract_features(image: ImageInput, **kwargs)

Classifier embedding of the whole image (treated as one specimen).

Models¶

ibbi.models.detectors.UltralyticsDetector ¶

Common wrapper for Ultralytics YOLO / RT-DETR checkpoints.

Parameters:

Name	Type	Description	Default
`model_path`	`str`	Path to the `.pt` checkpoint.	required
`config`	`dict \| None`	The repository's `config.json` (image size, defaults, class mapping).	`None`
`device`	`str \| None`	"cuda", "cpu", "mps", ... Defaults to the best available device.	`None`
`name`	`str \| None`	Registry name of the model.	`None`
`fast`	`bool \| None`	Letterbox on the GPU and pass Ultralytics a ready tensor (default: True on CUDA). Same geometry as Ultralytics' CPU letterbox; resize rounding differs slightly. Set `detector.fast = False` for the reference path that produced the published benchmark numbers.	`None`

predict ¶

predict(image, **kwargs)

Detects objects in one image or a list of images.

Parameters:

Name	Type	Description	Default
`image`	`str \| Path \| ndarray \| Image \| list`	Image(s) to process (path, URL, RGB array or PIL).	required
`**kwargs`		Passed to Ultralytics `predict` (e.g. `conf`, `iou`, `max_det`, `imgsz`, `agnostic_nms`).	`{}`

Returns:

Type	Description
	dict \| list[dict]: Per image, {"boxes" (xyxy), "scores", "labels", "class_ids"}.

predict_proba ¶

predict_proba(images: list[ImageInput], **kwargs) -> np.ndarray

Per image, the highest detection confidence of every class: array [N, n_classes] (used by LIME / SHAP).

extract_features ¶

extract_features(image: ImageInput, **kwargs) -> torch.Tensor | None

Image-level embedding from the detector backbone (Ultralytics embed).

get_classes ¶

get_classes() -> list[str]

Class names, in class-index order.

ibbi.models.detectors.SpeciesDetector ¶

Bases: UltralyticsDetector

Detects and names the 65 trainable species of the benchmark in one step.

predict(..., level="genus") reports labels at a coarser taxonomic level (subfamily, tribe or genus) by mapping each predicted species to its lineage.

predict ¶

predict(image, level: str = 'species', **kwargs)

Like UltralyticsDetector.predict; level in {"species", "genus", "tribe", "subfamily"} sets the label level.

The predicted species is always also returned under "species".

ibbi.models.detectors.ArthropodDetector ¶

Bases: UltralyticsDetector

Single-class detector that finds any arthropod ("arthropod").

operating_conf (0.70) is the confidence at which the detector makes at most 0.2 false alarms per image on its validation sample; use predict(image, conf=detector.operating_conf) for a high-precision operating point.

ibbi.models.codino.CoDINODetector ¶

Single-class Co-DINO detector ("arthropod").

Parameters:

Name	Type	Description	Default
`weights_path`	`str`	Path to the `model.safetensors` state dict.	required
`config`	`dict`	The repository's `config.json` (architecture, preprocessing, defaults).	required
`device`	`str \| None`	Device; defaults to the best available.	`None`
`name`	`str \| None`	Registry name.	`None`

operating_conf (0.65) is the confidence at which the detector makes at most 0.2 false alarms per image on the arthropod corpus validation sample.

predict ¶

predict(image, conf: float | None = None, max_det: int | None = None, **kwargs)

Detects arthropods in one image or a list of images.

Parameters:

Name	Type	Description	Default
`image`	`str \| Path \| ndarray \| Image \| list`	Image(s) to process.	required
`conf`	`float \| None`	Confidence threshold (default 0.25; `operating_conf` = 0.65 for ≤ 0.2 false alarms per image on the validation sample).	`None`
`max_det`	`int \| None`	Maximum detections per image (default 300).	`None`

Returns:

Type	Description
	dict \| list[dict]: Per image, {"boxes" (xyxy), "scores", "labels", "class_ids"}.

predict_proba ¶

predict_proba(images: list[ImageInput], **kwargs) -> np.ndarray

Per image, the highest detection confidence: array [N, 1] (used by LIME / SHAP).

extract_features ¶

extract_features(image: ImageInput, **kwargs) -> torch.Tensor

Image-level embedding: the mean of the EVA-02 backbone's last feature map, shape [1, 1024].

ibbi.models.classifiers.HierarchicalClassifier ¶

Specimen-crop classifier at subfamily, tribe, genus and species with per-level abstention.

Parameters:

Name	Type	Description	Default
`config`	`dict`	The repository's config.json.	required
`weights_path`	`str`	model.safetensors.	required
`deploy_path`	`str`	deploy.safetensors (kNN reference bank and the validation score distributions).	required
`device`	`str \| None`	Device; defaults to the best available.	`None`
`operating_point`	`str \| None`	"0.90", "0.95", "0.99" (share of known validation beetles accepted at every level) or "gallery" (0.99 at subfamily, 0.95 below; the default).	`None`
`name`	`str \| None`	Registry name.	`None`

get_classes ¶

get_classes() -> list[str]

The species the classifier knows, in output order (65 for the benchmark-trained models, 400 for the 400-species model).

crop ¶

crop(image: ImageInput, box_xyxy, pad: float | None = None) -> Image.Image

Crops a detection box grown by pad (default: the classifier's own 5%) on every side.

crop_tensors ¶

crop_tensors(image: Tensor, boxes) -> torch.Tensor

GPU version of crop + letterbox for many boxes of one image tensor (uint8 [3, H, W]): uint8 [N, 3, res, res].

classify_crops ¶

classify_crops(crops: list[ImageInput], operating_point: str | None = None, batch_size: int = 32) -> list[dict[str, Any]]

Classifies specimen crops (one specimen per image). Returns one record per crop (see module docstring).

Each record also has "depth" (0-4), "reported" (the human-readable result), "depth_by_op" (the depth under every stored operating point) and "embedding" is not included (use extract_features).

classify_tensors ¶

classify_tensors(crops_uint8: Tensor, operating_point: str | None = None, batch_size: int = 64) -> list[dict[str, Any]]

Like classify_crops for crops already letterboxed by crop_tensors (uint8 [N, 3, res, res]).

predict ¶

predict(image, boxes=None, operating_point: str | None = None, batch_size: int = 32, **kwargs)

Classifies a specimen image, or the given boxes in an image.

Parameters:

Name	Type	Description	Default
`image`		A crop of one specimen (path, URL, array or PIL), or a list of crops. With `boxes`, a full image.	required
`boxes`	`list \| None`	xyxy boxes to crop from `image` (e.g. from a detector) and classify.	`None`
`operating_point`	`str \| None`	Override the operating point for this call.	`None`
`batch_size`	`int`	Crops per forward pass.	`32`

Returns:

Type	Description
	dict \| list[dict]: One record for a single crop; a list for a list of crops or for `boxes`.

predict_proba ¶

predict_proba(images: list[ImageInput], level: str = 'species', **kwargs) -> np.ndarray

Calibrated probabilities of every taxon at level for each image: array [N, n_taxa].

extract_features ¶

extract_features(image: ImageInput, **kwargs) -> torch.Tensor

The classifier embedding of a crop (LayerNorm output), shape [1, D].

ibbi.models.zero_shot.ZeroShotDetector ¶

Base class: prompt handling, tiling, NMS and the common output format.

Parameters:

Name	Type	Description	Default
`prompts`	`list[str]`	Default text prompts (one class per prompt).	required
`tile`	`int`	Sliding-window size in px; 0 processes the whole image only.	`0`
`device`	`str \| None`	Device; defaults to the best available.	`None`
`operating_conf`	`float`	Confidence of the model's operating point on the detector-corpus validation sample (at most 0.2 false alarms per image).	`0.5`
`name`	`str`	Registry name.	`''`

set_classes ¶

set_classes(classes: list[str] | str) -> None

Sets the text prompts. A string is split on "." (e.g. "beetle . insect").

predict ¶

predict(image, text_prompt: str | list[str] | None = None, conf: float | None = None, tile: int | None = None, **kwargs)

Detects the prompted objects in one image or a list of images.

Parameters:

Name	Type	Description	Default
`image`		Path, URL, RGB array or PIL image, or a list of them.	required
`text_prompt`	`str \| list[str] \| None`	New prompts (sets the classes). Defaults to the current prompts.	`None`
`conf`	`float \| None`	Minimum score. Defaults to 0.05.	`None`
`tile`	`int \| None`	Sliding-window size (0 = whole image). Defaults to the model's chosen setting.	`None`

Returns:

Type	Description
	dict \| list[dict]: Per image, {"boxes" (xyxy), "scores", "labels" (the matching prompt)}.

predict_proba ¶

predict_proba(images: list[ImageInput], **kwargs) -> np.ndarray

Per image, the highest score for each prompt: array [N, n_prompts].

ibbi.models.zero_shot.GroundingDINOModel ¶

Bases: ZeroShotDetector

Grounding DINO (transformers).

extract_features ¶

extract_features(image: ImageInput, text_prompt: str = 'insect', **kwargs) -> torch.Tensor | None

Mean of the last vision-encoder state, conditioned on text_prompt.

ibbi.models.zero_shot.OWLv2Model ¶

Bases: ZeroShotDetector

OWLv2 (transformers).

ibbi.models.zero_shot.YOLOWorldModel ¶

Bases: ZeroShotDetector

YOLO-World v2-X (Ultralytics). The text encoder is installed by Ultralytics on first use.

ibbi.models.zero_shot.SAM3Model ¶

Bases: ZeroShotDetector

SAM 3 (transformers). Boxes come from its instance predictions, one prompt at a time.

Data¶

ibbi.utils.data.BenchmarkDataset ¶

Bases: Sequence

One split of the benchmark as an indexable sequence of examples.

Each item is a dictionary::

{
    "image": PIL.Image (RGB, loaded lazily),
    "image_id": int,                 # COCO image id, used in predictions
    "file_name": str, "image_path": str, "width": int, "height": int,
    "objects": {
        "bbox": [[x, y, w, h], ...],  # absolute pixels, COCO order
        "category": [species name, ...],
        "category_id": [int, ...],    # global benchmark category id (1..175)
        "iscrowd": [0 | 1, ...],      # 1 = real specimen that is not scored
        "subfamily": [...], "tribe": [...], "genus": [...],
    },
}

Use dataset.coco_path with ibbi.evaluate.benchmark for crowd-aware scoring.

categories `cached` `property` ¶

categories: dict[int, str]

Global category id -> species name for the categories of this split.

records ¶

records() -> Iterator[dict[str, Any]]

Iterates over the examples without opening the images (fast metadata access).

select ¶

select(indices: Sequence[int]) -> BenchmarkDataset

Returns a view restricted to the given positions (like datasets.Dataset.select).

Evaluation¶

ibbi.evaluate.Evaluator ¶

A unified evaluator for IBBI models.

Parameters:

Name	Type	Description	Default
`model`	`Any`	Any model created with `ibbi.create_model` or `ibbi.create_pipeline`.	required

predict_split ¶

predict_split(dataset: BenchmarkDataset, predict_kwargs: dict[str, Any] | None = None, max_images: int | None = None, progress: bool = True) -> list[dict[str, Any]]

Runs the model on every image of a benchmark split and returns COCO result dicts.

Species-level models write the benchmark's global category id of each predicted species; class-agnostic models write category 1.

benchmark ¶

benchmark(splits: Sequence[str] = DEFAULT_SPLITS, dataset_dir: str | Path | None = None, predict_kwargs: dict[str, Any] | None = None, max_images: int | None = None, output_dir: str | Path | None = None, model_name: str | None = None, operating_conf: float | None = None, revision: str = BENCHMARK_REVISION) -> dict[str, Any]

Runs the model on the benchmark splits and scores it with the benchmark's crowd-aware evaluator.

Species-level models (the species detectors and detector + classifier pipelines) get the full reference evaluation (COCO suite, detection / identification decomposition, taxonomic degradation on unseen species, calibration, novelty). Class-agnostic detectors (arthropod and zero-shot detectors) get class-agnostic AP/AR plus recall and precision at their operating confidence.

Parameters:

Name	Type	Description	Default
`splits`	`Sequence[str]`	Splits to evaluate. Defaults to iid_test, inat_test and semantic_ood.	`DEFAULT_SPLITS`
`dataset_dir`	`str \| Path \| None`	Benchmark root; downloaded to the ibbi cache when omitted.	`None`
`predict_kwargs`	`dict \| None`	Extra arguments for `model.predict` (override the model's benchmark defaults, e.g. the low confidence floor used for AP).	`None`
`max_images`	`int \| None`	Evaluate only the first N images of each split (quick checks; metrics are then not comparable to published numbers).	`None`
`output_dir`	`str \| Path \| None`	Write predictions and evaluator reports here.	`None`
`model_name`	`str \| None`	Name used for output files.	`None`
`operating_conf`	`float \| None`	Operating confidence for class-agnostic recall/precision. Defaults to the model's `operating_conf` attribute when it has one.	`None`
`revision`	`str`	Benchmark revision. Defaults to the pinned v2.0.1 commit.	`BENCHMARK_REVISION`

Returns:

Name	Type	Description
`dict`	`dict[str, Any]`	Evaluator output with a flat `"headline"` dict of the key metrics.

hierarchical_classification ¶

hierarchical_classification(splits: Sequence[str] = DEFAULT_SPLITS, dataset_dir: str | Path | None = None, include_crowd: bool = False, operating_point: str | None = None, max_images: int | None = None, batch_size: int = 32, revision: str = BENCHMARK_REVISION) -> dict[str, Any]

Scores a hierarchical classifier on ground-truth specimen crops of the benchmark.

Every annotated specimen is cropped at its box (grown by the classifier's padding) and classified. Metrics, per level (subfamily, tribe, genus, species): accuracy and expected calibration error on taxa the classifier knows; AUROC and FPR at 95% TPR of the novelty score for "known at this level" versus "unknown at this level" (the held-out species are unknown at species level, and also at genus and tribe level when their genus or tribe is absent from training); the reported depth against the ideal depth, including the over-commit rate (naming a taxon below the deepest level that could be right).

Parameters:

Name	Type	Description	Default
`splits`	`Sequence[str]`	Splits to use. Defaults to iid_test, inat_test and semantic_ood.	`DEFAULT_SPLITS`
`dataset_dir`	`str \| Path \| None`	Benchmark root; downloaded to the ibbi cache when omitted.	`None`
`include_crowd`	`bool`	Also classify the unscored crowd specimens of iid_test / inat_test (8x more known specimens; the benchmark standard is the scored ones only). Defaults to False.	`False`
`operating_point`	`str \| None`	Classifier operating point ("0.90", "0.95", "0.99", "gallery"). Defaults to the classifier's default.	`None`
`max_images`	`int \| None`	Use only the first N images per split.	`None`
`batch_size`	`int`	Crops per forward pass.	`32`
`revision`	`str`	Benchmark revision.	`BENCHMARK_REVISION`

Returns:

Name	Type	Description
`dict`	`dict[str, Any]`	`{"per_split": ..., "novelty": ..., "headline": {...}}`.

embeddings ¶

embeddings(dataset, evaluation_level: str = 'object', use_umap: bool = True, extract_kwargs: dict[str, Any] | None = None, batch_size: int = 32, include_crowd: bool = True, **kwargs)

Evaluates the quality of the model's feature embeddings.

Embeddings are extracted per specimen crop ("object", default) or per image ("image"), clustered (optionally after UMAP) and compared with the species labels (ARI, NMI, purity, internal cluster indices). A Mantel test compares between-species embedding distances with taxonomic distance (0 same species, 1 same genus, 2 same tribe, 3 same subfamily, 4 otherwise).

Parameters:

Name	Type	Description	Default
`dataset`		A `BenchmarkDataset` (or any iterable of items with "image" and "objects").	required
`evaluation_level`	`str`	"object" or "image".	`'object'`
`use_umap`	`bool`	Reduce with UMAP before clustering. Defaults to True.	`True`
`extract_kwargs`	`dict \| None`	Arguments for `model.extract_features`.	`None`
`batch_size`	`int`	Batch size for the distance computation of the Mantel test.	`32`
`include_crowd`	`bool`	Use unscored crowd specimens too (they carry true labels). Defaults to True.	`True`
`**kwargs`		Passed to `EmbeddingEvaluator`.	`{}`

Returns:

Name	Type	Description
`dict`		Clustering metrics, sample-level results and the Mantel correlation.

object_classification ¶

object_classification(dataset, **kwargs)

Deprecated: use Evaluator.benchmark, which scores with the benchmark's crowd-aware evaluator.

ibbi.evaluate.benchmark ¶

Crowd-aware scoring of predictions on the Bark and Ambrosia Beetle Detection Benchmark.

Two entry points:

evaluate_predictions scores species-level predictions (category ids are the benchmark's global ids, 1..175) with the benchmark's own reference evaluator (_reference_evaluator.py, vendored unchanged). It reports the COCO suite, per-species AP, class-agnostic detection, the detection / identification decomposition (detection recall, species accuracy given detection, end-to-end species recall), taxonomic graceful degradation on unseen species, calibration and known-vs-novel separation.
evaluate_class_agnostic scores detectors that only localise ("arthropod", zero-shot prompts): class-agnostic COCO AP/AR plus recall and precision at IoU 0.5 at an operating confidence. Crowd regions are ignored in both.

Predictions are COCO results: {"image_id": int, "category_id": int, "bbox": [x, y, w, h], "score": float} with absolute-pixel boxes in the frame of the benchmark's COCO files.

evaluate_predictions ¶

evaluate_predictions(predictions: dict[str, list[dict[str, Any]]], benchmark_dir: str | Path, iou: float = 0.5, quiet: bool = True, output_dir: str | Path | None = None, model_name: str = 'model') -> dict[str, Any]

Scores species-level predictions with the benchmark's reference evaluator.

Parameters:

Name	Type	Description	Default
`predictions`	`dict[str, list]`	split name -> COCO results list. Splits: "iid_test", "inat_test", "semantic_ood".	required
`benchmark_dir`	`str \| Path`	Benchmark root (see `ibbi.download_benchmark`); needs the annotations of every split (only the annotation files are read).	required
`iou`	`float`	IoU threshold for matching-based metrics. Defaults to 0.5.	`0.5`
`quiet`	`bool`	Suppress the evaluator's progress output. Defaults to True.	`True`
`output_dir`	`str \| Path \| None`	If given, the evaluator's files (summary JSON/CSV, per-species CSV, report) are written there.	`None`
`model_name`	`str`	File-name prefix for `output_dir`.	`'model'`

Returns:

Name	Type	Description
`dict`	`dict[str, Any]`	`{"per_split": {...}, "summary": {...}, "headline": {...}}`. `headline` holds the flat metrics listed in
	`dict[str, Any]`	`SPECIES_HEADLINE`.

evaluate_class_agnostic ¶

evaluate_class_agnostic(predictions: dict[str, list[dict[str, Any]]], benchmark_dir: str | Path, operating_conf: float | None = None, max_dets: int = 100) -> dict[str, Any]

Class-agnostic, crowd-aware detection metrics for every split in predictions.

Reported per split: COCO AP (IoU 0.50:0.95), AP50, AP75, AR@100 (pycocotools, crowd regions ignored), and at IoU 0.5 with at most max_dets detections per image: maximum recall (every score), and recall, precision and false positives per image at operating_conf (when given). Detections on crowd regions are neither true nor false positives.

Parameters:

Name	Type	Description	Default
`predictions`	`dict[str, list]`	split -> COCO results (category ids are ignored).	required
`benchmark_dir`	`str \| Path`	Benchmark root.	required
`operating_conf`	`float \| None`	Score threshold of the model's operating point.	`None`
`max_dets`	`int`	Detections per image considered. Defaults to 100.	`100`

Returns:

Name	Type	Description
`dict`	`dict[str, Any]`	`{split: {metric: value}}` and a flat `"headline"` dict.

to_coco_results ¶

to_coco_results(image_id: int, boxes_xyxy: Sequence[Sequence[float]], scores: Sequence[float], category_ids: Sequence[int] | None = None) -> list[dict[str, Any]]

Converts one image's xyxy boxes to COCO result dicts (xywh). category_ids=None writes category 1.

ibbi.evaluate.hierarchical.evaluate_hierarchical_records ¶

evaluate_hierarchical_records(records: list[dict[str, Any]], truths: list[dict[str, Any]], known_table: DataFrame) -> dict[str, Any]

Computes per-level accuracy, calibration, novelty separation and depth metrics.

Parameters:

Name	Type	Description	Default
`records`	`list[dict]`	Classifier outputs (`HierarchicalClassifier.classify_crops`), one per crop.	required
`truths`	`list[dict]`	`{"split": str, "species": str}` per crop, same order.	required
`known_table`	`DataFrame`	The classifier's species with columns subfamily, tribe, genus, scientificName.	required

Returns:

Name	Type	Description
`dict`	`dict[str, Any]`	`per_split` (accuracy / ECE / depth metrics), `novelty` (per-level AUROC, FPR@95TPR), `headline` (flat).

ibbi.evaluate.embeddings.EmbeddingEvaluator ¶

A unified class to evaluate feature embeddings.

This class provides a comprehensive suite of tools for evaluating the quality of feature embeddings. It can perform dimensionality reduction using UMAP, cluster the embeddings using HDBSCAN, and then calculate a variety of internal and external validation metrics.

Attributes:

Name	Type	Description
`embeddings`	`ndarray`	The raw, high-dimensional feature embeddings.
`processed_data`	`ndarray`	The embeddings after optional UMAP dimensionality reduction. This is the data used for clustering.
`predicted_labels`	`ndarray`	The cluster labels assigned by HDBSCAN.

get_sample_results ¶

get_sample_results(true_labels: ndarray | None = None, label_map: dict[int, str] | None = None) -> pd.DataFrame

Returns a DataFrame with true and predicted cluster labels for each sample.

Parameters:

Name	Type	Description	Default
`true_labels`	`Optional[ndarray]`	The ground truth labels for each sample. If provided, they will be included in the output DataFrame. Defaults to None.	`None`
`label_map`	`Optional[dict[int, str]]`	A dictionary to map integer labels to string names. Defaults to None.	`None`

Returns:

Type	Description
`DataFrame`	pd.DataFrame: A DataFrame with columns for true and predicted labels.

evaluate_against_truth ¶

evaluate_against_truth(true_labels: ndarray) -> pd.DataFrame

Calculates external clustering validation metrics against ground truth labels.

Parameters:

Name	Type	Description	Default
`true_labels`	`ndarray`	An array of ground truth labels for each sample.	required

Returns:

Type	Description
`DataFrame`	pd.DataFrame: A DataFrame containing external validation metrics like ARI, NMI, and Cluster Purity.

evaluate_cluster_structure ¶

evaluate_cluster_structure() -> pd.DataFrame

Calculates internal clustering validation metrics based on cluster structure.

Returns:

Type	Description
`DataFrame`	pd.DataFrame: A DataFrame containing internal validation metrics like Silhouette Score, Davies-Bouldin Index, and Calinski-Harabasz Index.

compare_to_distance_matrix ¶

compare_to_distance_matrix(true_labels: ndarray, label_map: dict[int, str] | None = None, embedding_metric: str = 'cosine', ext_distance: DataFrame | str | Path | None = None, batch_size: int = 32) -> tuple[float, float, int, pd.DataFrame]

Calculates Mantel correlation between embedding distances and an external distance matrix. The default is the taxonomic distance between benchmark species (ibbi.utils.data.taxonomic_distance_matrix). This version computes the average pairwise distances between all embeddings for each pair of species and leverages a GPU if available.

Parameters:

Name	Type	Description	Default
`true_labels`	`ndarray`	An array of ground truth labels for each sample.	required
`label_map`	`Optional[dict[int, str]]`	A dictionary to map integer labels to string names. Defaults to None.	`None`
`embedding_metric`	`str`	The distance metric to use for the embedding space ('cosine' or 'euclidean'). Defaults to "cosine".	`'cosine'`
`ext_distance`	`DataFrame \| str \| Path \| None`	External distance matrix (species x species), or a CSV path to one. Defaults to the taxonomic distance of the benchmark species.	`None`
`batch_size`	`int`	The batch size for GPU distance matrix calculation. Defaults to 32.	`32`

Returns:

Type	Description
`tuple[float, float, int, DataFrame]`	tuple[float, float, int, pd.DataFrame]: A tuple containing the Mantel correlation coefficient (r), the p-value, the number of items compared, and a DataFrame of the mean embedding vector for each class (for inspection).

Explainability¶

ibbi.explain.Explainer ¶

A wrapper for LIME and SHAP explainability methods.

This class provides a simple interface to generate model explanations using either LIME (Local Interpretable Model-agnostic Explanations) or SHAP (SHapley Additive exPlanations). It is designed to work with any model created using ibbi.create_model.

Parameters:

Name	Type	Description	Default
`model`	`ModelType`	An instantiated model from `ibbi.create_model`.	required

with_lime ¶

with_lime(image, **kwargs)

Generates a LIME explanation for a single image.

LIME provides a local, intuitive explanation by showing which parts of an image contributed most to a specific prediction. This method is a wrapper around the explain_with_lime function.

Parameters:

Name	Type	Description	Default
`image`	`Image`	The single image to be explained.	required
`**kwargs`		Additional keyword arguments to be passed to the underlying `ibbi.explain.lime.explain_with_lime` function. Common arguments include `image_size`, `batch_size`, `num_samples`, `top_labels`, and `num_features`.	`{}`

Returns:

Type	Description
	tuple[lime_image.ImageExplanation, PIL.Image.Image]: A tuple containing the LIME
	explanation object and the original image. The explanation object can be
	visualized using `ibbi.plot_lime_explanation`.

with_shap ¶

with_shap(explain_dataset, background_dataset, **kwargs)

Generates SHAP explanations for a set of images.

SHAP (SHapley Additive exPlanations) provides robust, theoretically-grounded explanations by attributing a model's prediction to its input features. This method is a wrapper around the explain_with_shap function and requires a background dataset to integrate out features.

Parameters:

Name	Type	Description	Default
`explain_dataset`	`list`	A list of dictionaries, where each dictionary represents an image to be explained (e.g., `[{'image': img1}, {'image': img2}]`).	required
`background_dataset`	`list`	A list of dictionaries representing a background dataset, used by SHAP to simulate feature absence.	required
`**kwargs`		Additional keyword arguments to be passed to the underlying `ibbi.explain.shap.explain_with_shap` function. Common arguments include `num_explain_samples`, `max_evals`, `image_size`, and `text_prompt`.	`{}`

Returns:

Type	Description
	shap.Explanation: A SHAP Explanation object containing the SHAP values for each image and each class. This object can be visualized using `ibbi.plot_shap_explanation`.

ibbi.explain.lime.plot_lime_explanation ¶

plot_lime_explanation(explanation: ImageExplanation, image: Image, top_k: int = 1, alpha: float = 0.6) -> None

Plots a detailed LIME explanation with a red-to-green overlay.

This function visualizes the output of explain_with_lime. It overlays the original image with a heatmap where green areas indicate features that positively contributed to the prediction, and red areas indicate negative contributions.

Parameters:

Name	Type	Description	Default
`explanation`	`ImageExplanation`	The explanation object generated by `explain_with_lime`.	required
`image`	`Image`	The original image that was explained.	required
`top_k`	`int`	The number of top classes to display explanations for. Defaults to 1.	`1`
`alpha`	`float`	The transparency of the color overlay. Defaults to 0.6.	`0.6`

ibbi.explain.shap.plot_shap_explanation ¶

plot_shap_explanation(shap_explanation_for_single_image: Explanation, model: ModelType, top_k: int = 5, text_prompt: str | None = None) -> None

Plots SHAP explanations for a SINGLE image.

This function is designed to visualize the output of explain_with_shap for one image. It uses SHAP's built-in image plotting capabilities to show which parts of the image contributed to the model's predictions for the top-k classes.

Parameters:

Name	Type	Description	Default
`shap_explanation_for_single_image`	`Explanation`	A SHAP Explanation object for a single image.	required
`model`	`ModelType`	The `ibbi` model that was explained.	required
`top_k`	`int`	The number of top class explanations to plot. Defaults to 5.	`5`
`text_prompt`	`Optional[str]`	The text prompt used for explaining a zero-shot model. Defaults to None.	`None`

API reference¶

Top-level functions¶

ibbi.create_model ¶

ibbi.create_pipeline ¶

ibbi.list_models ¶

ibbi.utils.data.get_dataset ¶

ibbi.utils.data.download_benchmark ¶

ibbi.utils.data.get_taxonomy ¶

ibbi.utils.data.get_shap_background_dataset ¶

ibbi.utils.data.taxonomic_distance_matrix ¶

ibbi.utils.data.get_ood_dataset ¶

ibbi.utils.cache.get_cache_dir ¶

ibbi.utils.cache.clean_cache ¶

Pipeline¶

ibbi.pipeline.IdentificationPipeline ¶

predict ¶

predict_proba ¶

extract_features ¶

Models¶

ibbi.models.detectors.UltralyticsDetector ¶

predict ¶

predict_proba ¶

extract_features ¶

get_classes ¶

ibbi.models.detectors.SpeciesDetector ¶

predict ¶

ibbi.models.detectors.ArthropodDetector ¶

ibbi.models.codino.CoDINODetector ¶

predict ¶

predict_proba ¶

extract_features ¶

ibbi.models.classifiers.HierarchicalClassifier ¶

get_classes ¶

crop ¶

crop_tensors ¶

classify_crops ¶

classify_tensors ¶

predict ¶

predict_proba ¶

extract_features ¶

ibbi.models.zero_shot.ZeroShotDetector ¶

set_classes ¶

predict ¶

predict_proba ¶

ibbi.models.zero_shot.GroundingDINOModel ¶

extract_features ¶

ibbi.models.zero_shot.OWLv2Model ¶

ibbi.models.zero_shot.YOLOWorldModel ¶

ibbi.models.zero_shot.SAM3Model ¶

Data¶

ibbi.utils.data.BenchmarkDataset ¶

categories cached property ¶

records ¶

select ¶

Evaluation¶

ibbi.evaluate.Evaluator ¶

predict_split ¶

benchmark ¶

hierarchical_classification ¶

embeddings ¶

object_classification ¶

ibbi.evaluate.benchmark ¶

evaluate_predictions ¶

evaluate_class_agnostic ¶

to_coco_results ¶

ibbi.evaluate.hierarchical.evaluate_hierarchical_records ¶

ibbi.evaluate.embeddings.EmbeddingEvaluator ¶

get_sample_results ¶

evaluate_against_truth ¶

evaluate_cluster_structure ¶

compare_to_distance_matrix ¶

Explainability¶

ibbi.explain.Explainer ¶

with_lime ¶

with_shap ¶

ibbi.explain.lime.plot_lime_explanation ¶

ibbi.explain.shap.plot_shap_explanation ¶

categories `cached` `property` ¶