Scikit-learn
human-activity-recognition
wearable
wrist
time-series
cpu
scikit-learn
WISP / src /wisp /_adaptive.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
8.05 kB
"""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