Scikit-learn
human-activity-recognition
wearable
wrist
time-series
cpu
scikit-learn
WISP / src /wisp /classifier.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
18.1 kB
"""WISPClassifier: a WISP recipe as a scikit-learn classifier."""
from __future__ import annotations
import pickle
import time
import warnings
import numpy as np
from sklearn.base import BaseEstimator, ClassifierMixin, clone
from sklearn.utils.validation import check_is_fitted
from . import _adaptive as adaptive
from ._validation import (SEQUENCES, SPEEDS, as_windows, check_aligned, check_choice, check_disjoint_groups,
check_input_shape, check_targets, encode_labels, kernel_context)
from .recipes import Recipe, resolve
class WISPClassifier(ClassifierMixin, BaseEstimator):
"""Fit and predict with one WISP recipe.
Parameters
----------
recipe : str, Recipe or dict, default="cis"
Catalog name (``"cis"``, ``"cis:RS"``, ``"best:capture24"``; see
``wisp.recipes.list()``), a :class:`~wisp.recipes.Recipe`, or a dictionary in the
``canonical_recipe`` format.
decoder : {"adaptive", "recipe", "hmm", "none"}, default="adaptive"
``"adaptive"`` decides on validation data whether HMM decoding helps: the same model
fitted on training windows decodes the validation windows with the HMM and with
per-window argmax, the HMM is kept only if its validation macro-F1 is strictly higher,
and the final model is fitted on all fitting data with the chosen decoder. Validation
data are ``validation`` when given to :meth:`fit`, otherwise a group-wise hold-out of
``validation_size`` (default 0.125) of the groups. Without groups, or without
sequences (no group with two or more windows), the decoder is ``"none"``.
``"recipe"`` uses the recipe's own setting (the paper configuration; ``"auto"`` is a
deprecated alias), ``"hmm"`` forces sequence decoding, ``"none"`` forces argmax.
readout : scikit-learn classifier or None, default=None
``None`` runs the recipe's own readout inside the frozen kernel. Otherwise the
recipe's representation (:class:`~wisp.WISPRepresentation`) is fed to a clone of this
estimator, which needs ``fit`` plus ``predict_proba`` or ``decision_function``.
Only single-readout recipes (SS, RC, SO, GIS, CIS and its subsets) accept a readout.
classes : array-like or None, default=None
Global class table. Needed when the training windows miss a class.
layout : {"NTC", "NCT"}, default="NTC"
Axis order of the windows: ``(n, T, C)`` or ``(n, C, T)``.
speed : {"exact", "fast"}, default="exact"
``"exact"``: outputs identical to the paper code (docs/SPEED.md). ``"fast"``:
screened Ridge solver; Ridge readouts can change slightly, other recipes are
unaffected.
sequence : {"subject", "recording"}, default="subject"
How the HMM decoder forms chains (see docs/METHODS.md, "Speed and HMM smoothing
sequence"). ``"recording"`` needs :meth:`fit_confidence_scale` on validation data.
n_jobs : int, default=1
Threads for tree ensembles inside the kernel.
random_state : int, default=42
Recipe seed (random kernels, intervals, shapelets and tree seeds).
Attributes
----------
classes_, recipe_, model_, decoder_, decoder_scores_, decoder_reason_, has_paper_results_,
fit_seconds_, decision_seconds_, model_size_mb_
``decoder_`` is the decoder of the final model (``"hmm"`` or ``"none"``),
``decoder_scores_`` the validation macro-F1 with each decoder (``"adaptive"`` only, else
``None``) and ``decoder_reason_`` why it was chosen (``"validation"``, ``"no groups"``,
``"no sequences"``, ``"fewer than 2 groups"`` or ``"fixed"``). ``decision_seconds_`` is the
time of the extra fit on the training part used for the decision (0 when none was needed).
"""
def __init__(self, recipe="cis", *, decoder="adaptive", readout=None, classes=None, layout="NTC",
speed="exact", sequence="subject", n_jobs=1, random_state=42):
self.recipe = recipe
self.decoder = decoder
self.readout = readout
self.classes = classes
self.layout = layout
self.speed = speed
self.sequence = sequence
self.n_jobs = n_jobs
self.random_state = random_state
# ------------------------------------------------------------------ helpers
def _check_params(self):
check_choice("decoder", self.decoder, adaptive.DECODERS)
check_choice("speed", self.speed, SPEEDS)
check_choice("sequence", self.sequence, SEQUENCES)
if not isinstance(self.n_jobs, (int, np.integer)) or self.n_jobs < 1:
raise ValueError("n_jobs must be a positive integer")
if self.readout is not None and self.sequence != "subject":
raise ValueError("sequence='recording' is available for the recipe's own readout only")
def _use_hmm(self, recipe: Recipe, groups, decoder: str) -> bool:
"""Fixed decoders ("recipe", "hmm", "none")."""
if decoder == "none":
return False
if decoder == "hmm":
if groups is None:
raise ValueError("decoder='hmm' needs groups (the sequence ID of every window) in fit")
return True
if recipe.use_hmm and groups is None:
warnings.warn("This recipe uses the HMM decoder but fit() received no groups; fitting with "
"per-window prediction (decoder='none'). Pass groups (and time_index) to fit "
"and predict for sequence decoding, or set decoder='none' to silence this.",
UserWarning, stacklevel=3)
return False
return recipe.use_hmm
def _paper_backed(self, recipe: Recipe, use_hmm: bool) -> bool:
if self.readout is not None or self.speed != "exact" or self.sequence != "subject":
return False
if recipe.source in ("fixed", "cis_subset"):
return ("hmm" if use_hmm else "none") in recipe.provenance.get("paper_ids", {})
if recipe.source == "search_best":
return use_hmm == recipe.use_hmm
return False
# ------------------------------------------------------------------ API
def fit(self, X, y, groups=None, time_index=None, validation=None, validation_size=None):
"""Fit on windows ``X`` and labels ``y``.
groups : array-like of shape (n,), optional
Sequence (participant or recording) ID of each window; needed for HMM decoding.
time_index : array-like of shape (n,), optional
Position of each window within its sequence; row order is used when omitted.
validation : tuple or array-like, optional
``(X_val, y_val, groups_val[, time_val])``, or validation rows of ``X`` (integer
indices or a boolean mask). Validation windows are part of the fitting data: the
final model is fitted on training plus validation windows (for a tuple, training
windows first, as in the paper's train+validation refit). With
``decoder="adaptive"`` they also decide the decoder.
validation_size : float, optional
``decoder="adaptive"`` without ``validation``: fraction of the groups held out to
decide the decoder (default 0.125); the final model is then fitted on all of ``X``.
"""
self._check_params()
decoder = adaptive.normalize_decoder(self.decoder)
recipe = resolve(self.recipe)
if self.readout is not None and not recipe.single_readout:
raise ValueError(f"readout replacement needs a single-readout recipe; {recipe.family} "
"(WISP-CSE/WISP-ESE) fuses several readouts")
Xw = as_windows(X, self.layout)
y = check_targets(self, y)
if validation is not None and validation_size is not None:
raise ValueError("Pass either validation or validation_size")
if len(y) != len(Xw):
raise ValueError(f"y has {len(y)} labels for {len(Xw)} windows")
groups = check_aligned("groups", groups, len(Xw))
time_index = check_aligned("time_index", time_index, len(Xw))
mode, train, valid = adaptive.parse_validation(Xw, y, groups, time_index, validation, self.layout)
labels = np.concatenate([np.asarray(y), np.asarray(valid[1])]) if mode == "tuple" else y
self.classes_, _ = encode_labels(labels, self.classes)
n_classes = len(self.classes_)
full = self._encode(adaptive.concat(train, valid) if mode == "tuple" else (Xw, y, groups, time_index))
scale = None
self.decision_seconds_ = 0.0
if decoder == "adaptive":
decision = (self._holdout(full, validation_size) if mode == "none"
else (self._encode(train), self._encode(valid)))
use_hmm, reason, scores, scale = self._decide(recipe, full, decision)
else:
use_hmm, reason, scores = self._use_hmm(recipe, full[2], decoder), adaptive.FIXED, None
start = time.perf_counter()
self._fit_final(recipe, full, use_hmm, n_classes)
if scale is not None and use_hmm and self.readout is None:
with kernel_context():
self.model_.set_confidence_scale(scale)
self.fit_seconds_ = time.perf_counter() - start
self.recipe_ = recipe
self.decoder_ = "hmm" if use_hmm else "none"
self.decoder_scores_ = scores
self.decoder_reason_ = reason
self.input_shape_ = Xw.shape[1:]
self.n_features_in_ = int(np.prod(self.input_shape_))
self.has_paper_results_ = self._paper_backed(recipe, use_hmm)
return self
# ------------------------------------------------------------------ fitting helpers
def _encode(self, part):
X, y, g, t = part
_, codes = encode_labels(y, self.classes_)
return (X, codes, g, t)
def _holdout(self, full, validation_size):
"""Group-wise hold-out of the fitting data for the decision, or None when impossible."""
X, codes, g, t = full
if g is None:
return None
if not adaptive.has_sequences(g):
return "no sequences"
if len(np.unique(np.asarray(g))) < 2:
return "few"
size = 0.125 if validation_size is None else float(validation_size)
tr, va = adaptive.group_holdout(len(X), g, size, int(self.random_state))
def take(a, idx):
return None if a is None else np.asarray(a)[idx]
return tuple(take(a, tr) for a in full), tuple(take(a, va) for a in full)
def _decide(self, recipe, full, decision):
"""``decoder="adaptive"``: (use_hmm, reason, scores, confidence scale)."""
if full[2] is None or decision is None:
return False, adaptive.NO_GROUPS, None, None
if decision == "no sequences":
return False, adaptive.NO_SEQUENCES, None, None
if isinstance(decision, str):
warnings.warn("decoder='adaptive' needs at least 2 groups for a group-wise hold-out; using the "
"recipe's own decoder", UserWarning, stacklevel=3)
return recipe.use_hmm, adaptive.FEW_GROUPS, None, None
(Xt, yt, gt, tt), (Xv, yv, gv, tv) = decision
if gt is None or not adaptive.has_sequences(gt):
return False, (adaptive.NO_GROUPS if gt is None else adaptive.NO_SEQUENCES), None, None
if gv is None:
raise ValueError("decoder='adaptive' needs groups for the validation windows")
check_disjoint_groups(gt, gv)
start = time.perf_counter()
n_classes = len(self.classes_)
scale = None
if self.readout is None:
model = self._kernel(recipe, True)
with kernel_context():
model.fit(Xt, yt, groups=gt, time_index=tt, n_classes=n_classes)
P = model.predict_proba(Xv)
if self.sequence == "recording":
model.fit_confidence_scale(Xv, yv)
scale = model.confidence_scale
hmm = adaptive.hmm_labels(model, P, gv, tv)
else:
from wisp.cpu.hmm import TransitionSmoother
from wisp.cpu.probability import estimator_proba
rep, readout = self._fit_readout(recipe, Xt, yt)
with kernel_context():
P = estimator_proba(readout, rep.transform(Xv), np.arange(n_classes))
smoother = TransitionSmoother().fit(yt, groups=gt, time_index=tt, n_classes=n_classes)
hmm = smoother.predict_from_proba(P, groups=gv, time_index=tv)
choice, scores = adaptive.compare(yv, hmm, adaptive.argmax_labels(P), n_classes)
self.decision_seconds_ = time.perf_counter() - start
return choice == "hmm", adaptive.VALIDATION, scores, scale
def _kernel(self, recipe, use_hmm):
from ._engine import build_kernel
return build_kernel(recipe, use_hmm=use_hmm, speed=self.speed, sequence=self.sequence,
seed=int(self.random_state), n_jobs=int(self.n_jobs))
def _fit_readout(self, recipe, X, codes):
from .representation import WISPRepresentation
rep = WISPRepresentation(recipe, layout="NTC", random_state=int(self.random_state))
with kernel_context():
Z = rep.fit_transform(X)
readout = clone(self.readout).fit(Z, codes)
if not (hasattr(readout, "predict_proba") or hasattr(readout, "decision_function")):
raise ValueError("readout must provide predict_proba or decision_function")
return rep, readout
def _fit_final(self, recipe, full, use_hmm, n_classes):
X, codes, groups, time_index = full
if self.readout is None:
model = self._kernel(recipe, use_hmm)
with kernel_context():
model.fit(X, codes, groups=groups, time_index=time_index, n_classes=n_classes)
self.model_ = model
self.representation_ = self.readout_ = self.smoother_ = None
else:
from wisp.cpu.hmm import TransitionSmoother
rep, readout = self._fit_readout(recipe, X, codes)
self.representation_, self.readout_ = rep, readout
self.smoother_ = (TransitionSmoother().fit(codes, groups=groups, time_index=time_index,
n_classes=n_classes) if use_hmm else None)
self.model_ = readout
@property
def model_size_mb_(self) -> float:
"""Size of the fitted model in MB (default-protocol pickle, as the paper's size column)."""
check_is_fitted(self, "model_")
obj = self.model_ if self.readout is None else (self.representation_, self.readout_, self.smoother_)
return len(pickle.dumps(obj)) / (1024.0 * 1024.0)
def _windows(self, X):
check_is_fitted(self, "model_")
Xw = as_windows(X, self.layout)
check_input_shape(self, X, Xw)
return Xw
def _scores(self, Xw):
if self.readout is None:
with kernel_context():
return self.model_.predict_proba(Xw)
from wisp.cpu.probability import estimator_proba
with kernel_context():
Z = self.representation_.transform(Xw)
return estimator_proba(self.readout_, Z, np.arange(len(self.classes_)))
def predict_proba(self, X):
"""Per-window class scores in ``classes_`` order (never HMM-smoothed)."""
return self._scores(self._windows(X))
def predict(self, X, groups=None, time_index=None):
"""Labels. With ``groups`` and an active decoder, each sequence is HMM-decoded;
without ``groups`` every window is classified independently (argmax)."""
Xw = self._windows(X)
groups = check_aligned("groups", groups, len(Xw))
time_index = check_aligned("time_index", time_index, len(Xw))
if self.readout is None:
with kernel_context():
codes = self.model_.predict(Xw, groups=groups, time_index=time_index)
else:
P = self._scores(Xw)
if self.smoother_ is not None and groups is not None:
codes = self.smoother_.predict_from_proba(P, groups=groups, time_index=time_index)
else:
codes = np.argmax(P, axis=1)
return self.classes_[np.asarray(codes, dtype=np.int64)]
def fit_confidence_scale(self, X_valid, y_valid):
"""``sequence="recording"`` only: choose the confidence scaling on validation windows."""
check_is_fitted(self, "model_")
if self.readout is not None:
raise ValueError("Confidence scaling applies to the recipe's own readout")
_, codes = encode_labels(y_valid, self.classes_)
with kernel_context():
self.model_.fit_confidence_scale(self._windows(X_valid), codes)
return self
@property
def confidence_scale_(self):
check_is_fitted(self, "model_")
return getattr(self.model_, "confidence_scale", None)
def __sklearn_tags__(self):
tags = super().__sklearn_tags__()
tags.input_tags.three_d_array = True
return tags
# used by WISPSelect / WISPSearch to adopt an already fitted kernel object
def _adopt(self, model, *, classes, input_shape, use_hmm, fit_seconds, reason=adaptive.FIXED,
scores=None, decision_seconds=0.0):
self._check_params()
recipe = resolve(self.recipe)
self.classes_ = np.asarray(classes)
self.model_ = model
self.representation_ = self.readout_ = self.smoother_ = None
self.fit_seconds_ = float(fit_seconds)
self.recipe_ = recipe
self.decoder_ = "hmm" if use_hmm else "none"
self.decoder_scores_ = scores
self.decoder_reason_ = reason
self.decision_seconds_ = float(decision_seconds)
self.input_shape_ = tuple(input_shape)
self.n_features_in_ = int(np.prod(self.input_shape_))
self.has_paper_results_ = self._paper_backed(recipe, use_hmm)
return self