Scikit-learn
human-activity-recognition
wearable
wrist
time-series
cpu
scikit-learn
WISP / src /wisp /sequence.py
Zipeng365's picture
wisp-har 0.4.0: WISP-Funnel search and the adaptive HMM switch (default decoder)
93a9282 verified
Raw History Blame Contribute Delete
6.9 kB
"""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]