"""The adaptive HMM switch (``decoder="adaptive"``) and the validation-data handling it shares. Decision rule. The same fitted model decodes the validation windows twice: with the HMM (offline Viterbi per group) and with per-window argmax. The HMM is kept only when its validation macro-F1 is strictly higher; a tie gives ``"none"``. The final model is then fitted on all fitting data with the chosen decoder, so it is the fixed-decoder model with that setting. Decision data: an explicit validation set when one is given, otherwise a group-wise hold-out of the training windows (``validation_size``, default 0.125, ``GroupShuffleSplit`` seeded with ``random_state``, as in WISPSelect/WISPSearch). Test data are never used. Edge cases: * no ``groups``: the HMM is unavailable, the decoder is ``"none"`` (reason ``"no groups"``); * no sequences: when no training group has two or more windows the HMM has no transitions to learn, and decoding a one-window sequence gives ``argmax_k(prior_k * P_k)`` (``prior_k`` is the class frequency in the training labels). That is prior reweighting, not sequence smoothing, so the decoder is ``"none"`` (reason ``"no sequences"``); * fewer than two groups, so no group-wise hold-out is possible: the recipe's own decoder is used with a warning (reason ``"fewer than 2 groups"``). Reasons recorded in ``decoder_reason_``: ``"validation"``, ``"no groups"``, ``"no sequences"``, ``"fewer than 2 groups"`` and ``"fixed"`` (a decoder other than ``"adaptive"`` was requested). """ from __future__ import annotations import warnings from dataclasses import dataclass from typing import Any import numpy as np from ._validation import as_windows, check_aligned DECODERS = ("adaptive", "recipe", "hmm", "none", "auto") VALIDATION = "validation" FIXED = "fixed" NO_GROUPS = "no groups" NO_SEQUENCES = "no sequences" FEW_GROUPS = "fewer than 2 groups" def normalize_decoder(value: Any) -> str: """Check ``decoder`` and map the deprecated alias ``"auto"`` to ``"recipe"``.""" if value not in DECODERS: raise ValueError(f"decoder must be one of {', '.join(map(repr, DECODERS[:4]))}; got {value!r}") if value == "auto": warnings.warn("decoder='auto' is deprecated and will be removed; use decoder='recipe' (same meaning: " "the recipe's own decoder setting)", FutureWarning, stacklevel=3) return "recipe" return value def has_sequences(groups: Any) -> bool: """True when at least one group has two or more windows.""" if groups is None: return False _, counts = np.unique(np.asarray(groups), return_counts=True) return bool(counts.size and counts.max() >= 2) def macro_f1(y_true: Any, y_pred: Any, n_classes: int) -> float: """Validation macro-F1 with the benchmark scorer (``wisp_release.scoring.score``).""" from wisp_release.scoring import score return float(score(np.asarray(y_true, dtype=np.int64), np.asarray(y_pred, dtype=np.int64), int(n_classes))["macro_f1"]) def compare(y_true: Any, hmm_pred: Any, none_pred: Any, n_classes: int) -> tuple[str, dict[str, float]]: """The decision rule: keep the HMM only if its macro-F1 is strictly higher.""" scores = {"hmm": macro_f1(y_true, hmm_pred, n_classes), "none": macro_f1(y_true, none_pred, n_classes)} return ("hmm" if scores["hmm"] > scores["none"] else "none"), scores def hmm_labels(model: Any, proba: np.ndarray, groups: Any, time_index: Any) -> np.ndarray: """HMM-decoded labels of a fitted kernel model with a smoother, from its probabilities.""" if hasattr(model, "decode_proba"): return np.asarray(model.decode_proba(proba, groups=groups, time_index=time_index)) smoother = getattr(model, "smoother_", None) if smoother is None: raise RuntimeError("the decision model has no HMM smoother") return np.asarray(smoother.predict_from_proba(proba, groups=groups, time_index=time_index)) def argmax_labels(proba: np.ndarray) -> np.ndarray: return np.argmax(np.asarray(proba, dtype=np.float64), axis=1).astype(np.int64) @dataclass class Split: """Fitting data and decision data. ``train``/``valid`` hold ``(X, y, groups, time_index)``. ``full`` is all fitting data in the order the final model is fitted on: training then validation windows for an explicit validation tuple, the original rows of ``X`` otherwise. ``valid`` is ``None`` when no hold-out is possible or needed. """ mode: str train: tuple valid: tuple | None full: tuple def _rows_mask(validation: Any, n: int) -> np.ndarray | None: """A 1-D boolean mask or integer row indices of ``X`` given as ``validation``.""" if isinstance(validation, (tuple, list)): return None arr = np.asarray(validation) if arr.ndim != 1: return None if arr.dtype == bool: if arr.shape != (n,): raise ValueError(f"a boolean validation mask needs one entry per window ({n})") mask = arr.copy() elif np.issubdtype(arr.dtype, np.integer): if arr.size and (arr.min() < -n or arr.max() >= n): raise ValueError("validation row indices fall outside X") mask = np.zeros(n, dtype=bool) mask[arr] = True else: return None if not mask.any() or mask.all(): raise ValueError("validation rows must leave both training and validation windows") return mask def parse_validation(Xw: np.ndarray, y: np.ndarray, groups: Any, time_index: Any, validation: Any, layout: str) -> tuple[str, tuple, tuple | None]: """Explicit validation data: a tuple ``(X_val, y_val, groups_val[, time_val])`` or rows of ``X``. Returns ``(mode, train, valid)`` with mode ``"tuple"``, ``"rows"`` or ``"none"``. """ if validation is None: return "none", (Xw, y, groups, time_index), None mask = _rows_mask(validation, len(Xw)) if mask is not None: def take(a, m): return None if a is None else a[m] train = (Xw[~mask], y[~mask], take(groups, ~mask), take(time_index, ~mask)) valid = (Xw[mask], y[mask], take(groups, mask), take(time_index, mask)) return "rows", train, valid if not isinstance(validation, (tuple, list)) or len(validation) not in (3, 4): raise ValueError("validation must be (X_val, y_val, groups_val), (X_val, y_val, groups_val, time_val), " "or validation rows of X (integer indices or a boolean mask)") Xv = as_windows(validation[0], layout) yv = np.asarray(validation[1]) gv = check_aligned("validation groups", validation[2], len(Xv)) tv = check_aligned("validation time_index", validation[3] if len(validation) == 4 else None, len(Xv)) if len(yv) != len(Xv): raise ValueError("validation labels and windows differ in length") if Xv.shape[1:] != Xw.shape[1:]: raise ValueError("training and validation windows must share (T, C)") return "tuple", (Xw, y, groups, time_index), (Xv, yv, gv, tv) def group_holdout(n: int, groups: Any, size: float, random_state: int) -> tuple[np.ndarray, np.ndarray]: """Group-wise hold-out (the splitter and seed handling of WISPSelect/WISPSearch).""" from sklearn.model_selection import GroupShuffleSplit if not 0 < size < 1: raise ValueError("validation_size must be in (0, 1)") split = GroupShuffleSplit(n_splits=1, test_size=size, random_state=int(random_state)) tr, va = next(split.split(np.zeros((n, 1)), np.zeros(n), groups)) return tr, va def concat(a: tuple, b: tuple) -> tuple: """Training then validation windows (the paper's train+validation order).""" out = [] for u, v in zip(a, b): if u is None or v is None: out.append(None if (u is None and v is None) else _fill(u, v)) else: out.append(np.concatenate([np.asarray(u), np.asarray(v)])) return tuple(out) def _fill(u, v): # one side has no time_index: the kernel then uses row order, so pass none at all return None