sleap_nn

sleap_nn

Main module for sleap_nn package.

Modules:

Name	Description
architectures	Modules related to model architectures.
cli	Unified CLI for SLEAP-NN using rich-click for styled output.
config	Configuration modules for sleap-nn.
data	Modules related to data loading and processing.
evaluation	This module is to compute evaluation metrics for trained models.
export	Export utilities for sleap-nn.
inference	Inference-related modules.
legacy_models	Utilities for loading legacy SLEAP models.
predict	Entry point for running inference.
system_info	System diagnostics and compatibility checking for sleap-nn.
tracking	Tracker related modules.
train	Entry point for sleap_nn training.
training	Training-related modules.

Functions:

Name	Description
load_metrics	Load metrics from a model folder or metrics file.

load_metrics(path, split='test', dataset_idx=0)

Load metrics from a model folder or metrics file.

This function supports both the new format (single "metrics" key) and the old format (individual metric keys at top level). It also handles both old and new file naming conventions in model folders.

Parameters:

Name	Type	Description	Default
path	str	Path to a model folder or metrics file (.npz).	required
split	str	Name of the split to load. Must be "train", "val", or "test". Default: "test". If "test" is not found, falls back to "val". Ignored if path points directly to a .npz file.	'test'
dataset_idx	int	Index of the dataset (for multi-dataset training). Default: 0. Ignored if path points directly to a .npz file.	0

Returns:

Type	Description
dict	Dictionary containing metrics with keys: voc_metrics, mOKS, distance_metrics, pck_metrics, visibility_metrics.

Raises:

Type	Description
FileNotFoundError	If no metrics file is found.

Examples:

>>> # Load from model folder (tries test, falls back to val)
>>> metrics = load_metrics("/path/to/model")
>>> print(metrics["mOKS"]["mOKS"])

>>> # Load specific split and dataset
>>> metrics = load_metrics("/path/to/model", split="val", dataset_idx=1)

>>> # Load directly from npz file
>>> metrics = load_metrics("/path/to/metrics.val.0.npz")

Source code in sleap_nn/evaluation.py

def load_metrics(
    path: str,
    split: str = "test",
    dataset_idx: int = 0,
) -> dict:
    """Load metrics from a model folder or metrics file.

    This function supports both the new format (single "metrics" key) and the old
    format (individual metric keys at top level). It also handles both old and new
    file naming conventions in model folders.

    Args:
        path: Path to a model folder or metrics file (.npz).
        split: Name of the split to load. Must be "train", "val", or "test".
            Default: "test". If "test" is not found, falls back to "val".
            Ignored if path points directly to a .npz file.
        dataset_idx: Index of the dataset (for multi-dataset training).
            Default: 0. Ignored if path points directly to a .npz file.

    Returns:
        Dictionary containing metrics with keys: voc_metrics, mOKS,
        distance_metrics, pck_metrics, visibility_metrics.

    Raises:
        FileNotFoundError: If no metrics file is found.

    Examples:
        >>> # Load from model folder (tries test, falls back to val)
        >>> metrics = load_metrics("/path/to/model")
        >>> print(metrics["mOKS"]["mOKS"])

        >>> # Load specific split and dataset
        >>> metrics = load_metrics("/path/to/model", split="val", dataset_idx=1)

        >>> # Load directly from npz file
        >>> metrics = load_metrics("/path/to/metrics.val.0.npz")
    """
    path = Path(path)

    if path.suffix == ".npz":
        metrics_path = path
    else:
        metrics_path = _find_metrics_file(path, split, dataset_idx)

    if not metrics_path.exists():
        raise FileNotFoundError(f"Metrics file not found at {metrics_path}")

    return _load_npz_metrics(metrics_path)