Instructions to use Zipeng365/WISP with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Scikit-learn
How to use Zipeng365/WISP with Scikit-learn:
from huggingface_hub import hf_hub_download import joblib model = joblib.load( hf_hub_download("Zipeng365/WISP", "sklearn_model.joblib") ) # only load pickle files from sources you trust # read more about it here https://skops.readthedocs.io/en/stable/persistence.html - Notebooks
- Google Colab
- Kaggle
Download src/wisp/classifier.py from Zipeng365/WISP: direct link, hf CLI and curl.
- Browser
- Download file 18.1 kB
-
https://huggingface.co/Zipeng365/WISP/resolve/main/src/wisp/classifier.py
- Command line
-
hf download hf://Zipeng365/WISP/src/wisp/classifier.py
-
curl -L -o classifier.py https://huggingface.co/Zipeng365/WISP/resolve/main/src/wisp/classifier.py
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 | |
| 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 | |
| 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 | |