islkit 0.1.0__py3-none-any.whl

islkit/__init__.py

@@ -0,0 +1,88 @@
+"""islkit — Indian Sign Language recognition from MediaPipe landmarks.
+
+Landmark features, a dual-branch TCN, the INCLUDE loader, live inference and a
+small HTTP/SSE recognition service.
+"""
+
+import importlib
+
+from islkit.baseline import pooled_stats, stratified_folds
+from islkit.data import IncludeData, load_include
+from islkit.features import DIM_FRAME, DIM_GEOM, RawFrame, encode_clip, encode_frame
+from islkit.labels import LabelMap, build_dataset, decode_prediction
+from islkit.metrics import accuracy, confusion_matrix, per_class_f1, top_confusions
+from islkit.plotting import plot_confusion, plot_curves, plot_f1_distribution
+from islkit.viz import animate_replay, reconstruct, still_replay
+
+# device, seeding and model are the only modules that import torch, and they are
+# loaded on first use rather than at import time. Not for speed: torch bundles its
+# own libomp, XGBoost links Homebrew's, and macOS aborts the process when both land
+# in it (OMP Error #15). The XGBoost baseline is pure numpy and must be able to import
+# load_include without dragging torch in behind it. See islkit/baseline.py.
+_LAZY = {
+    "describe_device": "islkit.device",
+    "pick_device": "islkit.device",
+    "set_seed": "islkit.seeding",
+    "Backbone": "islkit.model",
+    "SignClassifier": "islkit.model",
+    "build_model": "islkit.model",
+    "freeze_backbone": "islkit.model",
+    "replace_head": "islkit.model",
+    "ClipStore": "islkit.infer",
+    "ClipTooShort": "islkit.infer",
+    "HolisticExtractor": "islkit.infer",
+    "Prediction": "islkit.infer",
+    "SignRecogniser": "islkit.infer",
+}
+
+
+def __getattr__(name: str):
+    module = _LAZY.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(importlib.import_module(module), name)
+    globals()[name] = value  # bind so this runs once per name
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)
+
+
+__all__ = [
+    "DIM_FRAME",
+    "DIM_GEOM",
+    "Backbone",
+    "ClipStore",
+    "ClipTooShort",
+    "HolisticExtractor",
+    "IncludeData",
+    "LabelMap",
+    "Prediction",
+    "RawFrame",
+    "SignClassifier",
+    "SignRecogniser",
+    "accuracy",
+    "animate_replay",
+    "build_dataset",
+    "build_model",
+    "confusion_matrix",
+    "decode_prediction",
+    "describe_device",
+    "encode_clip",
+    "encode_frame",
+    "freeze_backbone",
+    "load_include",
+    "per_class_f1",
+    "pick_device",
+    "plot_confusion",
+    "plot_curves",
+    "plot_f1_distribution",
+    "pooled_stats",
+    "reconstruct",
+    "replace_head",
+    "set_seed",
+    "still_replay",
+    "stratified_folds",
+    "top_confusions",
+]

islkit/adapters.py

@@ -0,0 +1,237 @@
+"""Inspect a downloaded landmark dataset, then feed it into the same encoder
+your own recordings use.
+
+Two jobs:
+
+  1. inspect_dataset(root)  — tells you what layout you actually got.
+     Do NOT skip this. Assuming a layout and being wrong produces a model that
+     trains fine and predicts nonsense.
+
+  2. unflatten(vec)         — turns one flattened MediaPipe Holistic vector
+     back into structured per-part arrays, so features.encode_frame() works on
+     public data unchanged.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from pathlib import Path
+
+import numpy as np
+
+from islkit.features import RawFrame
+
+# ---------------------------------------------------------------------------
+# Known flatten layouts
+# ---------------------------------------------------------------------------
+# The 1662 layout comes from a widely-copied tutorial and is by far the most
+# common in public ISL landmark dumps. Order is always:
+#     pose(33x4) -> face(468x3) -> left_hand(21x3) -> right_hand(21x3)
+# Missing parts are zero-filled, which is recoverable: an all-zero block means
+# the tracker lost that part, NOT that it sat at the origin.
+
+LAYOUTS = {
+    1662: {
+        "pose": (0, 132, 33, 4),
+        "face": (132, 1536, 468, 3),
+        "lh": (1536, 1599, 21, 3),
+        "rh": (1599, 1662, 21, 3),
+    },
+    1629: {
+        "pose": (0, 99, 33, 3),
+        "face": (99, 1503, 468, 3),
+        "lh": (1503, 1566, 21, 3),
+        "rh": (1566, 1629, 21, 3),
+    },
+    258: {
+        "pose": (0, 132, 33, 4),
+        "face": None,
+        "lh": (132, 195, 21, 3),
+        "rh": (195, 258, 21, 3),
+    },
+    225: {
+        "pose": (0, 99, 33, 3),
+        "face": None,
+        "lh": (99, 162, 21, 3),
+        "rh": (162, 225, 21, 3),
+    },
+}
+
+
+def unflatten(vec: np.ndarray, layout: int = 1662):
+    """One flattened frame -> dict of per-part arrays (None if absent).
+
+    Returns arrays shaped (33,4) / (468,3) / (21,3) / (21,3). A part is
+    reported as None when its whole block is exactly zero, which is how the
+    standard extractor encodes 'tracker lost this'.
+    """
+    spec = LAYOUTS[layout]
+    out = {}
+    for name in ("pose", "face", "lh", "rh"):
+        s = spec[name]
+        if s is None:
+            out[name] = None
+            continue
+        a, b, n, d = s
+        block = np.asarray(vec[a:b], np.float32)
+        out[name] = None if not np.any(block) else block.reshape(n, d)
+    # normalise pose to (33,4) so downstream code has one shape to expect
+    if out["pose"] is not None and out["pose"].shape[1] == 3:
+        vis = np.ones((33, 1), np.float32)
+        out["pose"] = np.concatenate([out["pose"], vis], axis=1)
+    return out
+
+
+def to_raw_frames(seq: np.ndarray, layout: int = 1662) -> list[RawFrame]:
+    """(T, D) flattened sequence -> list of RawFrame for the encoder."""
+    frames = []
+    for row in seq:
+        p = unflatten(row, layout)
+        frames.append(
+            RawFrame(pose=p["pose"], face=p["face"], hand_left=p["lh"], hand_right=p["rh"])
+        )
+    return frames
+
+
+# ---------------------------------------------------------------------------
+# Inspector
+# ---------------------------------------------------------------------------
+
+
+def _load_any(path: Path):
+    """Best-effort load of one sample file. Returns (array, note)."""
+    sfx = path.suffix.lower()
+    try:
+        if sfx == ".npy":
+            return np.load(path, allow_pickle=True), "npy"
+        if sfx == ".npz":
+            z = np.load(path, allow_pickle=True)
+            keys = list(z.keys())
+            return z[keys[0]], f"npz keys={keys}"
+        if sfx == ".parquet":
+            import pandas as pd
+
+            df = pd.read_parquet(path)
+            return df, f"parquet cols={list(df.columns)[:8]}"
+        if sfx == ".csv":
+            import pandas as pd
+
+            df = pd.read_csv(path)
+            return df, f"csv cols={list(df.columns)[:8]}"
+        if sfx == ".json":
+            return json.loads(path.read_text()), "json"
+    except Exception as e:
+        return None, f"load failed: {e}"
+    return None, "unrecognised extension"
+
+
+def inspect_dataset(root: str | Path, max_files: int = 400):
+    root = Path(root)
+    files = [
+        p
+        for p in root.rglob("*")
+        if p.is_file() and p.suffix.lower() in {".npy", ".npz", ".parquet", ".csv", ".json"}
+    ]
+
+    print(f"root            : {root}")
+    print(f"data files found: {len(files)}")
+    if not files:
+        print("\nNothing recognised. List the directory manually — the archive")
+        print("may nest one level deeper, or store raw video instead.")
+        return
+
+    exts = Counter(p.suffix.lower() for p in files)
+    print(f"extensions      : {dict(exts)}")
+
+    # Directory structure often carries the label and sometimes the signer.
+    depths = Counter(len(p.relative_to(root).parts) for p in files)
+    print(f"path depths     : {dict(depths)}")
+    parents = sorted({p.parent.name for p in files})
+    print(f"distinct folders: {len(parents)}")
+    print(f"  sample        : {parents[:6]}")
+    print(f"sample filenames: {[p.name for p in files[:4]]}")
+
+    # Probe the most common extension, not files[0]. A dump that ships a
+    # label_map.json beside its clips would otherwise be inspected via its
+    # manifest and report a scalar array shape.
+    main_ext, _ = exts.most_common(1)[0]
+    probe = next(p for p in files if p.suffix.lower() == main_ext)
+    sample, note = _load_any(probe)
+    print(f"\nfirst file      : {probe.relative_to(root)}")
+    print(f"loaded as       : {note}")
+    if sample is None:
+        return
+
+    if hasattr(sample, "columns"):
+        print(f"dataframe shape : {sample.shape}")
+        print(sample.head(3).to_string())
+        print("\nTabular layout — likely one row per landmark per frame.")
+        print("Pivot on (frame, type, landmark_index) before using unflatten().")
+        return
+
+    arr = np.asarray(sample)
+    print(f"array shape     : {arr.shape}  dtype={arr.dtype}")
+
+    D = arr.shape[-1] if arr.ndim >= 2 else arr.shape[0]
+    layout = D if D in LAYOUTS else None
+    print(f"feature dim     : {D}  -> {'KNOWN layout' if layout else 'UNKNOWN layout'}")
+
+    if not layout:
+        print("\nUnknown width. Check the dataset description for the field order")
+        print("before assuming anything. Known widths:", sorted(LAYOUTS))
+        return
+
+    # Sanity: MediaPipe normalised coords mostly land in [0, 1] for x,y.
+    flat = arr.reshape(-1, D)
+    print(f"value range     : [{flat.min():.3f}, {flat.max():.3f}]")
+    print(f"exact zeros     : {(flat == 0).mean() * 100:.1f}% of all values")
+
+    spec = LAYOUTS[layout]
+    print("\nper-part presence across this file:")
+    for name in ("pose", "face", "lh", "rh"):
+        s = spec[name]
+        if s is None:
+            print(f"  {name:5s}: not in this layout")
+            continue
+        a, b, _, _ = s
+        present = np.any(flat[:, a:b] != 0, axis=1).mean()
+        print(f"  {name:5s}: present in {present * 100:5.1f}% of frames")
+
+    # Scan more files for class balance and tracking quality.
+    lost = 0
+    total = 0
+    labels = Counter()
+    for p in files[:max_files]:
+        labels[p.parent.name] += 1
+        a, _ = _load_any(p)
+        if a is None:
+            continue
+        a = np.asarray(a)
+        if a.ndim < 2 or a.shape[-1] != D:
+            continue
+        f = a.reshape(-1, D)
+        lh, rh = spec["lh"], spec["rh"]
+        both = np.any(f[:, lh[0] : lh[1]] != 0, axis=1) & np.any(f[:, rh[0] : rh[1]] != 0, axis=1)
+        lost += (~both).sum()
+        total += len(f)
+
+    print(f"\nscanned {min(len(files), max_files)} files")
+    if total:
+        print(f"frames missing a hand : {(1 - lost / total) * 100:.1f}% have BOTH hands")
+        print("  ISL is largely two-handed. A low number here is a warning:")
+        print("  either heavy occlusion or a single-handed vocabulary.")
+    print(f"distinct label folders: {len(labels)}")
+    common = labels.most_common(5)
+    print(f"  most populated      : {common}")
+    counts = np.array(list(labels.values()))
+    print(
+        f"  clips per label     : min={counts.min()} "
+        f"median={int(np.median(counts))} max={counts.max()}"
+    )
+
+    print("\n--- next steps ---")
+    print(f"use: to_raw_frames(seq, layout={layout}) -> features.encode_clip()")
+    print("BEFORE training, find the signer/session identifier. If filenames or")
+    print("folders encode it, group by it. If nothing does, you cannot build an")
+    print("honest split from this data alone — treat it as pretraining only.")

islkit/baseline.py

@@ -0,0 +1,287 @@
+"""The baseline the TCN has to beat: pooled statistics over time + XGBoost.
+
+Baseline before model. If a gradient-boosted tree on six
+summary statistics per feature dimension already does well, the features carry
+the signal and the sequence model is only being asked for the rest. If it does
+badly, the bug is in the features and no amount of TCN tuning will find it.
+
+**On the split.** Own recordings are evaluated leave-one-session-out, because
+consecutive frames of one recording are near-duplicates. INCLUDE has no grouping
+at all — no signer, no session, in any file, folder or metadata of the dump — so
+no group split is available and none is faked. `stratified_folds` is the
+replacement: a class-stratified k-fold over whole clips, shared with the TCN.
+
+It is **optimistic** and is named and reported as such everywhere it is used. It
+does not leak *frames* — pooling collapses each clip to one row, so a clip is
+wholly in train or wholly in test — but it does leak *signers*, and every fold's
+training set contains the same seven people as its test set. Read the number it
+produces as an upper bound on a features-sanity check, never as a generalisation
+estimate.
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+from dataclasses import dataclass, field
+
+import numpy as np
+
+# Named spans of the 352-dim frame vector, for attributing importance back to
+# something physical. Deliberately duplicated here rather than added to
+# features.py: the INCLUDE cache filename is a hash of that file's source bytes,
+# so a one-line addition there would silently invalidate 291 MB and re-encode
+# 4,284 clips. Kept in sync by test_baseline.py, which checks the spans against
+# features.py's own DIM_GEOM / DIM_FRAME rather than against these numbers.
+FEATURE_BLOCKS: dict[str, tuple[int, int]] = {
+    "hand_shape": (0, 126),  # 2 x 21 x 3 wrist-local handshape
+    "wrist_pos": (126, 132),  # 2 x 3 wrist position in the body frame
+    "pose": (132, 165),  # 11 x 3 upper body
+    "non_manual": (165, 169),  # brow raise/furrow, mouth open/wide
+    "mask": (169, 183),  # 2 hands + 11 pose visibility + 1 face
+    "d_hand_shape": (183, 309),
+    "d_wrist_pos": (309, 315),
+    "d_pose": (315, 348),
+    "d_non_manual": (348, 352),
+}
+
+# Frozen once, on purpose. A baseline should take twenty minutes and set a floor to
+# beat, not a tuned competitor: a baseline that has been searched over is no
+# longer a baseline, because the model it gates was never given the same budget.
+# Stock XGBoost defaults except for the two that only affect run time.
+XGB_PARAMS: dict[str, object] = {
+    "objective": "multi:softprob",
+    "max_depth": 6,
+    "eta": 0.3,
+    "subsample": 0.9,
+    "colsample_bytree": 0.6,  # 2,112 features, most of them near-duplicates
+    "tree_method": "hist",
+    "verbosity": 0,
+}
+N_ROUNDS = 60
+
+# Order of the statistic blocks in the pooled vector. Feature j of statistic i
+# lives at index i * D + j, which is what `pooled_feature_index` inverts.
+STAT_NAMES: tuple[str, ...] = ("mean", "std", "min", "max", "first", "last")
+
+
+def pooled_stats(X: np.ndarray) -> np.ndarray:
+    """(N, T, D) clips -> (N, 6D) rows of per-dimension summary statistics.
+
+    Six statistics per feature dimension, taken across time: mean, std, min,
+    max, first, last. Deliberately crude — this is the floor the sequence model
+    has to clear, so it must not be given anything resembling temporal
+    structure beyond the two endpoints.
+    """
+    X = np.asarray(X, dtype=np.float32)
+    if X.ndim != 3:
+        raise ValueError(f"expected (N, T, D), got shape {X.shape}")
+    if X.shape[1] == 0:
+        raise ValueError("clips have zero frames")
+
+    blocks = (
+        X.mean(axis=1),
+        X.std(axis=1),
+        X.min(axis=1),
+        X.max(axis=1),
+        X[:, 0, :],
+        X[:, -1, :],
+    )
+    return np.concatenate(blocks, axis=1).astype(np.float32, copy=False)
+
+
+def pooled_feature_index(stat: str, dim: int, n_dims: int) -> int:
+    """Index into a pooled row for one (statistic, source dimension) pair."""
+    return STAT_NAMES.index(stat) * n_dims + dim
+
+
+def stratified_folds(y: np.ndarray, n_folds: int = 5, seed: int = 0) -> list[np.ndarray]:
+    """Class-stratified k-fold over clips. Returns one test-index array per fold.
+
+    **Not a group split.** See the module docstring: no group identifier exists
+    for INCLUDE, and this function exists so a number can be reported with the
+    split it came from attached, not so a group split can be faked. Stratified
+    because 33 of the 262 classes have <= 8 clips and an unstratified fold can
+    miss one entirely, which scores that class 0.0 for reasons that have nothing
+    to do with the features.
+    """
+    y = np.asarray(y)
+    if n_folds < 2:
+        raise ValueError("n_folds must be at least 2")
+
+    rng = np.random.default_rng(seed)
+    fold_of = np.empty(len(y), dtype=np.int64)
+    for c in np.unique(y):
+        idx = np.flatnonzero(y == c)
+        rng.shuffle(idx)
+        # Rotate the starting fold per class so the remainder when a class does
+        # not divide evenly doesn't always pile into fold 0.
+        offset = int(rng.integers(n_folds))
+        fold_of[idx] = (np.arange(len(idx)) + offset) % n_folds
+    return [np.flatnonzero(fold_of == f) for f in range(n_folds)]
+
+
+def _import_xgboost():
+    """Import xgboost, refusing to proceed if torch is already in the process.
+
+    torch ships its own libomp and the XGBoost wheel links Homebrew's. With both
+    loaded, macOS aborts with `OMP: Error #15` — an exit code and no traceback,
+    twenty minutes into a run. islkit.__init__ keeps torch lazy so this never
+    happens by accident; this turns the remaining case into a sentence.
+    """
+    if "torch" in sys.modules:
+        raise RuntimeError(
+            "torch is already imported; loading xgboost now will abort the process "
+            "(two OpenMP runtimes, macOS OMP Error #15). The pooled-stats baseline "
+            "needs no torch — import islkit.baseline before anything that pulls it in."
+        )
+    import xgboost  # noqa: PLC0415 — deliberately deferred, see above
+
+    return xgboost
+
+
+@dataclass
+class XGBBaseline:
+    """XGBoost over pooled statistics. Thin wrapper on the native Booster API.
+
+    Not `XGBClassifier`: that path requires scikit-learn, and this package writes
+    its metrics out by hand (see metrics.py) rather than taking the dependency.
+    """
+
+    n_classes: int
+    n_rounds: int = N_ROUNDS
+    seed: int = 0
+    params: dict = field(default_factory=lambda: dict(XGB_PARAMS))
+    booster: object | None = None
+
+    def fit(self, X: np.ndarray, y: np.ndarray) -> XGBBaseline:
+        xgb = _import_xgboost()
+        params = {**self.params, "num_class": self.n_classes, "seed": self.seed}
+        self.booster = xgb.train(params, xgb.DMatrix(X, label=y), num_boost_round=self.n_rounds)
+        return self
+
+    def predict_proba(self, X: np.ndarray) -> np.ndarray:
+        xgb = _import_xgboost()
+        if self.booster is None:
+            raise RuntimeError("fit() first")
+        return np.asarray(self.booster.predict(xgb.DMatrix(X)))
+
+    def gain(self, n_features: int) -> np.ndarray:
+        """Total gain per feature, as a dense vector. Unsplit features are 0."""
+        if self.booster is None:
+            raise RuntimeError("fit() first")
+        out = np.zeros(n_features, dtype=np.float64)
+        for key, value in self.booster.get_score(importance_type="total_gain").items():
+            out[int(key[1:])] = value  # keys are "f<index>"
+        return out
+
+
+def cross_val_predict(
+    make_model,
+    X: np.ndarray,
+    y: np.ndarray,
+    folds: list[np.ndarray],
+    n_classes: int = 0,
+    verbose: bool = True,
+) -> tuple[np.ndarray, list, list[float]]:
+    """Out-of-fold class probabilities for every row, the models, the fold accuracies.
+
+    Every clip is predicted exactly once, by a model that never saw it. That
+    matters more than the mean of per-fold accuracies here: with 262 classes and
+    a median of 15 clips each, per-class F1 from a single held-out fold rests on
+    three examples. Pooling out-of-fold predictions puts all 4,284 behind it.
+
+    Full probabilities rather than argmax, because top-3 and the confidence
+    threshold for declining are both read off them afterwards.
+
+    `make_model` is a zero-argument factory so each fold gets a fresh estimator.
+    """
+    n_classes = n_classes or int(np.max(y)) + 1
+    proba = np.full((len(y), n_classes), np.nan, dtype=np.float32)
+    models, accs = [], []
+    all_idx = np.arange(len(y))
+
+    for k, test_idx in enumerate(folds):
+        train_idx = np.setdiff1d(all_idx, test_idx)
+        t0 = time.time()
+        model = make_model()
+        model.fit(X[train_idx], y[train_idx])
+        proba[test_idx] = model.predict_proba(X[test_idx])
+        models.append(model)
+        accs.append(float((proba[test_idx].argmax(axis=1) == y[test_idx]).mean()))
+        if verbose:
+            print(
+                f"  fold {k + 1}/{len(folds)}: train={len(train_idx):5d} test={len(test_idx):5d} "
+                f" acc={accs[-1] * 100:5.2f}%  ({time.time() - t0:.0f}s)",
+                flush=True,
+            )
+
+    if np.isnan(proba).any():
+        raise RuntimeError("folds did not cover every row")
+    if verbose:
+        print(f"  fold spread: {min(accs) * 100:.2f}% – {max(accs) * 100:.2f}%")
+    return proba, models, accs
+
+
+def nearest_neighbour_accuracy(X: np.ndarray, y: np.ndarray, folds: list[np.ndarray]) -> float:
+    """Out-of-fold 1-NN accuracy under cosine similarity on the raw features.
+
+    A leak check on the *split*, not a model. On this task, any number
+    above 95% is a leak until proven otherwise, and the first thing to rule out
+    is that held-out clips simply sit next to their training neighbours — which
+    is what a duplicated, near-duplicated, or otherwise degenerate split looks
+    like from the inside. If 1-NN is already near the model's score, the split
+    is giving the answer away and no model result from it means anything.
+
+    Deliberately parameter-free: it measures the geometry of the data under this
+    partition and nothing else.
+    """
+    X = np.asarray(X, dtype=np.float32).reshape(len(y), -1)
+    X = X / (np.linalg.norm(X, axis=1, keepdims=True) + 1e-9)
+    y = np.asarray(y)
+
+    pred = np.empty(len(y), dtype=y.dtype)
+    all_idx = np.arange(len(y))
+    for test_idx in folds:
+        train_idx = np.setdiff1d(all_idx, test_idx)
+        sim = X[test_idx] @ X[train_idx].T
+        pred[test_idx] = y[train_idx][sim.argmax(axis=1)]
+    return float((pred == y).mean())
+
+
+def top_k_accuracy(proba: np.ndarray, y: np.ndarray, k: int = 3) -> float:
+    """Share of rows whose true class is among the k highest-scored."""
+    top = np.argpartition(-proba, kth=k - 1, axis=1)[:, :k]
+    return float((top == np.asarray(y)[:, None]).any(axis=1).mean())
+
+
+def block_importance(
+    importance: np.ndarray, n_dims: int, blocks: dict[str, tuple[int, int]]
+) -> dict[str, float]:
+    """Sum a pooled-feature importance vector back onto named source blocks.
+
+    After body-frame normalisation, z is the highest-variance
+    channel in the pose block despite being MediaPipe's weakest estimate. Trees
+    split on whatever separates the training data, so where the gain actually
+    landed is the cheap way to see whether that spread is being leaned on.
+    """
+    importance = np.asarray(importance, dtype=np.float64)
+    if importance.size != len(STAT_NAMES) * n_dims:
+        raise ValueError(f"expected {len(STAT_NAMES) * n_dims} importances, got {importance.size}")
+
+    per_dim = importance.reshape(len(STAT_NAMES), n_dims).sum(axis=0)
+    total = per_dim.sum()
+    if total <= 0:
+        return {name: 0.0 for name in blocks}
+    return {name: float(per_dim[a:b].sum() / total) for name, (a, b) in blocks.items()}
+
+
+def stat_importance(importance: np.ndarray, n_dims: int) -> dict[str, float]:
+    """Share of total importance carried by each of the six statistics."""
+    importance = np.asarray(importance, dtype=np.float64).reshape(len(STAT_NAMES), n_dims)
+    total = importance.sum()
+    if total <= 0:
+        return {name: 0.0 for name in STAT_NAMES}
+    return {
+        name: float(row.sum() / total) for name, row in zip(STAT_NAMES, importance, strict=True)
+    }