"""HMMSmoother: the kernel's transition smoother as a standalone, model-agnostic decoder.""" from __future__ import annotations import numpy as np from sklearn.base import BaseEstimator from sklearn.utils.validation import check_is_fitted from . import _adaptive as adaptive from ._validation import check_aligned, encode_labels class HMMSmoother(BaseEstimator): """Offline Viterbi smoothing of per-window class scores from any model. The public name of ``wisp.cpu.hmm.TransitionSmoother``; numerical behaviour is the kernel's. The transition matrix is estimated from adjacent training labels within each group (sequence), with additive smoothing ``alpha`` and a diagonal ``persistence_boost``. Decoding is offline: each sequence is decoded as a whole, so a window's label can depend on later windows. It is not an online (causal) decoder. Parameters are the kernel's (``alpha=1.0``, ``persistence_boost=2.0``), plus ``decoder``: decoder : {"adaptive", "recipe", "hmm", "none"}, default="adaptive" ``"adaptive"`` decides whether to decode with the HMM when :meth:`fit` receives validation scores, ``validation=(scores_val, y_val, groups_val[, time_val])``: the HMM is kept only if its validation macro-F1 is strictly higher than per-window argmax of the same scores (a tie gives argmax). The transitions are then counted on the training and validation labels. Without groups, or when no training group has two or more windows (no sequences), the decision is argmax. Without validation scores nothing can be decided and the smoother decodes with the HMM, as before. ``"recipe"`` and ``"hmm"`` always decode with the HMM; ``"none"`` always takes the argmax. ``decoder_`` holds the result, ``decoder_scores_`` the two validation macro-F1 values and ``decoder_reason_`` the reason. ``scores`` passed to :meth:`decode` must be non-negative class scores such as probabilities, with columns in ``classes_`` order; they are clipped to [1e-12, 1] and renormalised per row, as in the kernel. Convert logits with a softmax first. """ def __init__(self, alpha: float = 1.0, persistence_boost: float = 2.0, decoder: str = "adaptive"): self.alpha = alpha self.persistence_boost = persistence_boost self.decoder = decoder def _kernel(self, codes, groups, time_index): from wisp.cpu.hmm import TransitionSmoother return TransitionSmoother(alpha=float(self.alpha), persistence_boost=float(self.persistence_boost)).fit( codes, groups=groups, time_index=time_index, n_classes=len(self.classes_)) def fit(self, y, groups=None, time_index=None, classes=None, validation=None): """Count label transitions within each group, ordered by ``time_index`` when given. ``classes`` fixes the class table (column order of the scores); by default the sorted unique labels of ``y`` (and of the validation labels, when given). ``validation=(scores_val, y_val, groups_val[, time_val])``: class scores of validation windows from the model being smoothed (fitted without those windows), used by ``decoder="adaptive"``. """ decoder = adaptive.normalize_decoder(self.decoder) y = np.asarray(y) if validation is not None: if not isinstance(validation, (tuple, list)) or len(validation) not in (3, 4): raise ValueError("validation must be (scores_val, y_val, groups_val[, time_val])") Pv = np.asarray(validation[0], dtype=np.float64) yv = np.asarray(validation[1]) gv = check_aligned("validation groups", validation[2], len(yv)) tv = check_aligned("validation time_index", validation[3] if len(validation) == 4 else None, len(yv)) self.classes_, _ = encode_labels(np.concatenate([y, yv]), classes) _, codes_v = encode_labels(yv, self.classes_) if Pv.ndim != 2 or Pv.shape != (len(yv), len(self.classes_)) or not np.isfinite(Pv).all(): raise ValueError(f"validation scores must be finite with shape ({len(yv)}, {len(self.classes_)})") else: self.classes_, _ = encode_labels(y, classes) _, codes = encode_labels(y, self.classes_) n = len(codes) groups = check_aligned("groups", groups, n) time_index = check_aligned("time_index", time_index, n) scores, use_hmm = None, decoder != "none" if decoder != "adaptive": reason = adaptive.FIXED elif validation is None: reason = "no validation scores" elif groups is None or gv is None: use_hmm, reason = False, adaptive.NO_GROUPS elif not adaptive.has_sequences(groups): use_hmm, reason = False, adaptive.NO_SEQUENCES else: trained = self._kernel(codes, groups, time_index) hmm = trained.predict_from_proba(Pv, groups=gv, time_index=tv) choice, scores = adaptive.compare(codes_v, hmm, adaptive.argmax_labels(Pv), len(self.classes_)) use_hmm, reason = choice == "hmm", adaptive.VALIDATION if validation is not None and decoder == "adaptive" and reason in (adaptive.VALIDATION, adaptive.NO_SEQUENCES): # all labelled windows count transitions (training then validation) _, codes = encode_labels(np.concatenate([y, yv]), self.classes_) groups = np.concatenate([np.asarray(groups), np.asarray(gv)]) time_index = (None if time_index is None or tv is None else np.concatenate([np.asarray(time_index), np.asarray(tv)])) self.smoother_ = self._kernel(codes, groups, time_index) self.transition_ = self.smoother_.transition_ self.prior_ = self.smoother_.prior_ self.decoder_ = "hmm" if use_hmm else "none" self.decoder_scores_ = scores self.decoder_reason_ = reason return self def decode(self, scores, groups=None, time_index=None): """Most likely label path per group. Without ``groups`` all rows form one sequence.""" check_is_fitted(self, "smoother_") P = np.asarray(scores, dtype=np.float64) if P.ndim != 2 or P.shape[1] != len(self.classes_): raise ValueError(f"scores must have shape (n, {len(self.classes_)}) in classes_ order; got {P.shape}") if not np.isfinite(P).all(): raise ValueError("scores must be finite") groups = check_aligned("groups", groups, len(P)) time_index = check_aligned("time_index", time_index, len(P)) if getattr(self, "decoder_", "hmm") == "none": return self.classes_[adaptive.argmax_labels(P)] path = self.smoother_.predict_from_proba(P, groups=groups, time_index=time_index) return self.classes_[path]