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
File size: 8,047 Bytes
93a9282 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 | """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
|