"""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