src/meowcontext_lab/evaluate.py

"""Benchmark result helpers."""

from __future__ import annotations

import numpy as np
import pandas as pd

from meowcontext_lab.data import BENCHMARK_ROWS, EXPECTED_LABELS


def canonical_results() -> pd.DataFrame:
    """Return the canonical benchmark results."""

    return pd.DataFrame(BENCHMARK_ROWS)


def balanced_accuracy_from_confusion(confusion: np.ndarray) -> float:
    """Compute balanced accuracy from a square confusion matrix."""

    recalls = []
    for idx in range(confusion.shape[0]):
        total = confusion[idx, :].sum()
        recalls.append(0.0 if total == 0 else confusion[idx, idx] / total)
    return float(np.mean(recalls))


def approximate_confusion_matrix(score: float, *, samples_per_class: int = 30) -> np.ndarray:
    """Create a deterministic illustrative confusion matrix for a balanced score."""

    correct = int(round(score * samples_per_class))
    incorrect = samples_per_class - correct
    matrix = np.zeros((len(EXPECTED_LABELS), len(EXPECTED_LABELS)), dtype=int)
    for idx in range(len(EXPECTED_LABELS)):
        matrix[idx, idx] = correct
        matrix[idx, (idx + 1) % len(EXPECTED_LABELS)] = incorrect // 2
        matrix[idx, (idx + 2) % len(EXPECTED_LABELS)] = incorrect - incorrect // 2
    return matrix