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: 22,919 Bytes
ac7f7cb | 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 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 | """Accelerated CPU execution of the seven fixed WISP families and search recipes."""
from copy import deepcopy
from dataclasses import dataclass
import time
import numpy as np
from sklearn.ensemble import ExtraTreesClassifier, RandomForestClassifier
from sklearn.linear_model import RidgeClassifier
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.utils.class_weight import compute_sample_weight
from wisp.cpu.algorithms import _classifier, build_cpu_estimator
from wisp.cpu.probability import align_proba, estimator_proba, global_classes, labels_from_proba
from wisp.registry import build_method, list_specs
from wisp_release.methods import build_reference_family as reference_family
from . import features as fx
from .cache import _ACTIVE, _SEARCH, transform_blocks
from .decoder import FastSmoother, check_sequence, fit_confidence_scale
from .forest import ForestPlan, local_proba
CLASS_TO_ID = {spec.code_class: spec.method_id for spec in list_specs()}
# "original": the paper's RidgeClassifierCV. "screened": Ridge strength chosen on a
# 512-row training subsample, then one Ridge fit on all rows (approximate, faster).
RIDGE_SOLVERS = ("original", "screened")
@dataclass(frozen=True)
class TurboBudget:
"""Upper limits. The canonical HMM sees all training labels and timestamps."""
kernels: int = 32
intervals: int = 4
shapelets: int = 6
trees: int = 24
max_steps: int = 96
max_train: int = 4096
ridge_alpha: float = 1.0
def __post_init__(self):
for field in ("kernels", "intervals", "shapelets", "trees", "max_steps", "max_train"):
val = getattr(self, field)
if not isinstance(val, (int, np.integer)) or val < 1:
raise ValueError(f"{field} must be a positive integer")
if self.max_steps < 15:
raise ValueError("max_steps must allow the longest standard convolution (15)")
if self.ridge_alpha <= 0 or not np.isfinite(self.ridge_alpha):
raise ValueError("ridge_alpha must be finite and positive")
def uses_ridge_head(template):
"""True for RC/CIS templates whose classifier is the Ridge head the solver option changes."""
return (CLASS_TO_ID.get(type(template).__name__) in ("wisp_rc", "wisp_cis")
and getattr(template, "classifier", None) == "ridge")
def with_ridge_solver(template, mode="exact", budget=None, ridge_solver="original", sequence="subject",
feature_workers=1):
"""Wrap a reference template; apply ``ridge_solver`` wherever a Ridge head exists.
RC/CIS Ridge models use the solver directly, the CSE/ESE ensembles pass it to their
RC/CIS members, and families without a Ridge head are unaffected by the choice.
"""
if ridge_solver not in RIDGE_SOLVERS:
raise ValueError(f"ridge_solver must be one of {', '.join(RIDGE_SOLVERS)}")
direct = ridge_solver if mode == "exact" and uses_ridge_head(template) else "original"
model = FastFamily(template, mode, budget, ridge_solver=direct, feature_workers=feature_workers,
sequence=sequence)
if mode == "exact" and model.method_id in ("wisp_cse", "wisp_ese"):
model.member_ridge_solver = ridge_solver
return model
def build_family(method_id, *, seed=42, n_jobs=1, direct=False, overrides=None,
mode="exact", budget=None, ridge_solver="original", feature_workers=1,
sequence="subject"):
model = reference_family(method_id, seed=seed, n_jobs=n_jobs, direct=direct,
overrides=overrides)
return with_ridge_solver(model, mode, budget, ridge_solver, sequence, feature_workers)
def build_recipe(recipe_id, *, seed=42, n_jobs=1, mode="exact", budget=None, ridge_solver="original",
feature_workers=1, sequence="subject"):
"""Seven non-empty controlled R/I/S combinations crossed with direct/Viterbi."""
from wisp.ablations import build_recipe as original_recipe
if n_jobs < 1:
raise ValueError("n_jobs must be positive")
model = FastFamily(original_recipe(recipe_id, seed=seed, n_jobs=n_jobs), mode, budget,
ridge_solver=ridge_solver, feature_workers=feature_workers, sequence=sequence)
model.recipe_id = recipe_id
return model
def build_candidate(spec_dict, *, mode="exact", budget=None, ridge_solver="original", sequence="subject"):
if isinstance(spec_dict, dict) and spec_dict.get("route", "cpu") != "cpu":
raise ValueError("Only CPU WISP candidates are released")
return with_ridge_solver(build_cpu_estimator(spec_dict), mode, budget, ridge_solver, sequence)
def _training_rows(y, cap, seed):
"""Roughly proportional stratified random sample, retaining every observed class."""
labels, inverse, counts = np.unique(y, return_counts=True, return_inverse=True)
if cap < len(labels):
raise ValueError("max_train is smaller than the number of observed classes")
# Reserve one per class, then allocate remaining slots proportionally to capacity.
quota = (counts - 1) * ((cap - len(labels)) / (len(y) - len(labels)))
floor = np.floor(quota).astype(int)
sizes = floor + 1
order = np.argsort(-(quota - floor), kind="stable")
sizes[order[:cap - sizes.sum()]] += 1
rng = np.random.default_rng(seed)
return np.sort(np.concatenate([
rng.choice(np.flatnonzero(inverse == j), size=size, replace=False)
for j, size in enumerate(sizes)]))
class FastFamily:
"""fit/predict API of the release. Inference batching never splits a sequence decoder."""
def __init__(self, template, mode="exact", budget=None, ridge_solver="original", feature_workers=1,
sequence="subject"):
if not isinstance(feature_workers,(int,np.integer)) or feature_workers<1:
raise ValueError("feature_workers must be a positive integer")
self.feature_workers = feature_workers
self.sequence = check_sequence(sequence)
if ridge_solver not in RIDGE_SOLVERS:
raise ValueError("Unknown Ridge solver")
if ridge_solver!="original" and (mode!="exact" or CLASS_TO_ID[type(template).__name__]
not in ("wisp_rc","wisp_cis") or template.classifier!="ridge"):
raise ValueError("Custom solvers are supported for exact RC/CIS Ridge models and CIS recipes")
self.ridge_solver = ridge_solver
if mode not in {"exact", "turbo"}:
raise ValueError("mode must be exact or turbo")
if budget is not None and mode != "turbo":
raise ValueError("budget is only meaningful in turbo mode")
if budget is not None and not isinstance(budget, TurboBudget):
raise TypeError("budget must be a TurboBudget")
self.template = template
self.method_id = CLASS_TO_ID[type(template).__name__]
self.mode = mode
self.budget = (budget or TurboBudget()) if mode == "turbo" else None
self.n_jobs = template.n_jobs
self.smoother_ = None
self.members_ = []
self.blocks_ = []
self.model_ = None
self.classes_ = None
self.input_shape_ = None
self.checkpoint_only_ = False
def __getstate__(self):
# Process-local pointers cannot be serialized or included in a size tiebreak.
state = self.__dict__.copy()
state.pop("_forest_plan", None)
return state
def design_profile(self):
return self.template.design_profile()
def _blocks(self):
m, family, b = self.template, self.method_id, self.budget
fast = {"fast_profile": self.mode == "turbo"}
if family == "wisp_ss":
return [fx.WearableFeatureExtractor(segment_sizes=m.segment_sizes,
symbolic_bins=m.symbolic_bins, **fast)]
if family == "wisp_so":
return [fx.WearableFeatureExtractor(
include_raw_stats=True, include_magnitude=True, include_jerk=False,
include_multiscale=True, segment_sizes=(5, 10, 20), include_spectral=False,
include_autocorr=False, include_cross_channel=True, include_symbolic=True,
symbolic_bins=8, **fast)]
if family == "wisp_gis":
return [fx.InvariantPhysicsFeatureExtractor(
segment_sizes=m.segment_sizes, symbolic_bins=m.symbolic_bins,
random_intervals=min(24, b.intervals) if b else 24,
random_state=m.seed, include_axis_features=True, **fast),
fx.RandomShapeletSketch(
n_shapelets=min(m.n_shapelets, b.shapelets) if b else m.n_shapelets,
random_state=m.seed+17, **fast)]
if family in {"wisp_cis", "wisp_rc"}:
kernels = min(m.n_kernels, b.kernels) if b else m.n_kernels
blocks = []
if getattr(m, "use_rocket", True):
blocks.append(fx.RandomConvSketch(n_kernels=kernels, random_state=m.seed, **fast))
if family == "wisp_cis" and getattr(m, "use_intervals", True):
blocks.append(fx.IntervalDistributionSketch(
n_random_intervals=min(m.n_intervals, b.intervals) if b else m.n_intervals,
random_state=m.seed+29, **fast))
if family == "wisp_cis" and getattr(m, "use_state", True):
blocks.append(fx.WearableFeatureExtractor(
include_raw_stats=False, include_magnitude=True, include_jerk=True,
include_multiscale=False, include_spectral=True, include_autocorr=True,
include_cross_channel=True, include_symbolic=True, symbolic_bins=6, **fast))
return blocks
raise ValueError(f"{family} has no base feature blocks")
def _inputs(self, X):
X = np.asarray(X)
if X.ndim == 2:
X = X[..., None]
if X.ndim != 3 or min(X.shape) < 1:
raise ValueError("X must have nonempty shape (N,T,C) or (N,T)")
return X
def _times(self, X):
if self.budget and X.shape[1] > self.budget.max_steps:
def sample():
take = np.linspace(0, X.shape[1]-1, self.budget.max_steps, dtype=np.intp)
return np.ascontiguousarray(X[:, take, :])
memory = _SEARCH.get()
return sample() if memory is None else memory.sampled(X, self.budget.max_steps, sample)
return X
def _fit_base(self, X, y):
self.blocks_ = self._blocks()
for block in self.blocks_:
block.fit(X, y)
self._fit_head(self._features(X), y)
def _fit_head(self, F, y):
m, b = self.template, self.budget
kind = getattr(m, "classifier", "extratrees")
if self.method_id == "wisp_so":
head = ExtraTreesClassifier(n_estimators=160, max_features="sqrt",
class_weight="balanced", random_state=m.seed, n_jobs=self.n_jobs)
elif b and kind == "ridge":
head = RidgeClassifier(alpha=b.ridge_alpha, solver="cholesky")
elif getattr(self,"ridge_solver","original") == "screened":
from .ridge_fast import ScreenedRidgeClassifierCV
head = ScreenedRidgeClassifierCV(alphas=np.logspace(-3,3,9))
elif hasattr(self, "recipe_id"):
from wisp.cis_algorithms import _classifier as recipe_classifier
head = recipe_classifier(kind, seed=m.seed, n_jobs=self.n_jobs,
class_balance=m.class_balance)
else:
head = _classifier(kind, seed=m.seed, n_jobs=self.n_jobs)
if b:
if kind in {"rf", "extratrees"}:
head.set_params(n_estimators=min(head.n_estimators, b.trees))
elif kind == "logreg":
head.set_params(max_iter=250, tol=1e-3)
weighted = kind == "ridge" and getattr(m, "class_balance", "balanced") == "balanced"
kwargs = {"clf__sample_weight": compute_sample_weight("balanced", y)} if weighted else {}
if self.method_id in {"wisp_cis", "wisp_rc"} or kind == "logreg":
head = Pipeline([("scale", StandardScaler()), ("clf", head)])
# Upstream only uses ridge via the RC/CIS scaled pipeline in its search grammar.
if kind == "ridge" and not isinstance(head, Pipeline):
kwargs = {}
forest = head.steps[-1][1] if isinstance(head, Pipeline) else head
if _SEARCH.get() is not None and type(forest) in (ExtraTreesClassifier,RandomForestClassifier):
from .search_forest import forest_fit_plan
with forest_fit_plan(forest):
self.model_ = head.fit(F, y, **kwargs)
else:
self.model_ = head.fit(F, y, **kwargs)
self.__dict__.pop("_forest_plan", None)
def _features(self, X):
if getattr(self,"feature_workers",1)>1:
from .parallel import parallel_rows
return parallel_rows(self._feature_batch,X,self.feature_workers)
return self._feature_batch(X)
def _feature_batch(self, X):
blocks = transform_blocks(self.blocks_, X)
return blocks[0] if len(blocks) == 1 else np.concatenate(blocks, axis=1)
def _member_models(self):
seed = self.template.seed
if self.method_id == "wisp_cse":
configs = [("wisp_ss", {}), ("wisp_rc", {"n_kernels": 256}), ("wisp_so", {})]
else:
configs = [("wisp_cis", {"n_kernels": 256, "n_intervals": 16}),
("wisp_gis", {"n_shapelets": 24}), ("wisp_so", {})]
members = []
for j, (name, params) in enumerate(configs):
template = build_method(name, seed=seed+j, n_jobs=self.n_jobs,
overrides={"use_hmm": False, **params})
member = FastFamily(template, self.mode, self.budget)
solver = getattr(self, "member_ridge_solver", "original")
if solver != "original" and uses_ridge_head(template):
member.ridge_solver = solver
members.append(member)
return members
def fit(self, X, y, *, groups=None, time_index=None, n_classes=None):
if self.checkpoint_only_:
raise ValueError("Construct a new family for refitting an imported checkpoint")
start = time.perf_counter()
X = self._inputs(X)
y = np.asarray(y, dtype=np.int64)
if y.shape != (len(X),):
raise ValueError("y must have one label per window")
self.classes_ = global_classes(y, n_classes)
self.trained_classes_ = np.unique(y)
self.input_shape_ = X.shape[1:]
k = len(self.classes_)
self.smoother_ = (FastSmoother(getattr(self, "sequence", "subject")).fit(
y, groups=groups, time_index=time_index, n_classes=k)
if self.template.use_hmm else None)
if self.budget and len(y) > self.budget.max_train:
rows = _training_rows(y, self.budget.max_train, self.template.seed)
X, y = X[rows], y[rows]
self.fit_windows_ = len(y)
if self.method_id in {"wisp_cse", "wisp_ese"}:
self.members_ = self._member_models()
for member in self.members_:
member.fit(X, y, n_classes=k)
else:
self._fit_base(self._times(X), y)
self.fit_seconds_ = time.perf_counter() - start
calibration = self.__dict__.pop("calibration_data", None)
if calibration is not None and groups is not None:
self.fit_confidence_scale(*calibration)
return self
# ---- recording-level smoothing: confidence scaling chosen on validation data ----
@property
def use_hmm(self):
return bool(self.template.use_hmm)
def fit_confidence_scale(self, X_valid, y_valid):
"""Choose the confidence-scaling factor on validation windows (``sequence="recording"``).
Has no effect for ``sequence="subject"``, for models without HMM smoothing, or
when recording-level smoothing was skipped at fit time.
"""
sm = self.smoother_
if getattr(self, "sequence", "subject") != "recording" or sm is None or not sm.active:
return self
sm.set_confidence_scale(fit_confidence_scale(self.predict_proba(X_valid), y_valid))
return self
@property
def confidence_scale(self):
sm = self.smoother_
if getattr(self, "sequence", "subject") != "recording" or sm is None or not sm.active:
return None
return sm.confidence_scale
def set_confidence_scale(self, scale):
"""Reuse a factor chosen for a train-only fit (e.g. after refitting on train+validation)."""
sm = self.smoother_
if scale is not None and sm is not None and sm.active and getattr(self, "sequence", "subject") == "recording":
sm.set_confidence_scale(scale)
return self
def _head_proba(self,features,*,private=False):
head=self.model_
# Standalone fitted model only. Shared panels, disk cache mappings,
# and externally supplied feature arrays take the read-only path.
if (private and type(head) is Pipeline and len(head.steps)==2
and type(head.steps[0][1]) is StandardScaler
and features.dtype==np.float64 and features.flags.writeable and features.flags.owndata):
scaled=head.steps[0][1].transform(features,copy=False)
return estimator_proba(head.steps[1][1],scaled,self.classes_)
if isinstance(head,(ExtraTreesClassifier,RandomForestClassifier)) and head.n_jobs==1:
plan=getattr(self,"_forest_plan",None)
if plan is None:plan=self._forest_plan=ForestPlan(head)
return align_proba(local_proba(head,features,plan),head.classes_,self.classes_)
return estimator_proba(head,features,self.classes_)
def _proba(self, X):
if not self.members_:
private=(self.method_id in ("wisp_cis","wisp_rc") and len(self.blocks_)>=2
and _SEARCH.get() is None and _ACTIVE.get() is None)
return self._head_proba(self._features(self._times(X)),private=private)
return self._combine(lambda member:member._proba(X),len(X))
def _combine(self,score,n):
# Accumulate in canonical order without retaining all member scores.
if self.method_id == "wisp_cse":
out = score(self.members_[0]).copy()
for member in self.members_[1:]:
out += score(member)
out /= len(self.members_)
else:
w = np.asarray(self.template.weights, dtype=np.float64)
if w.size != len(self.members_):
w = np.ones(len(self.members_))
w = w / np.maximum(w.sum(), 1e-12)
out = np.zeros((n, len(self.classes_)))
for wi, member in zip(w, self.members_):
if wi != 0:
out += wi * score(member)
return out / np.maximum(out.sum(axis=1, keepdims=True), 1e-12)
def predict_proba(self, X, *, batch_size=None):
if self.classes_ is None:
raise RuntimeError("Unfitted estimator")
X = self._inputs(X)
if self.input_shape_ is not None and X.shape[1:] != self.input_shape_:
raise ValueError(f"Fitted T,C={self.input_shape_}; got {X.shape[1:]}")
if batch_size is None:
return self._proba(X)
if not isinstance(batch_size, (int, np.integer)) or batch_size < 1:
raise ValueError("batch_size must be a positive integer")
out = np.empty((len(X), len(self.classes_)), dtype=np.float64)
for start in range(0, len(X), batch_size):
stop = min(len(X), start + batch_size)
out[start:stop] = self._proba(X[start:stop])
return out
def decode_proba(self, proba, *, groups=None, time_index=None):
if self.smoother_ is not None and groups is not None:
return self.smoother_.predict_from_proba(proba, groups=groups, time_index=time_index)
return labels_from_proba(proba, self.classes_)
def predict(self, X, *, groups=None, time_index=None, batch_size=None):
return self.decode_proba(self.predict_proba(X, batch_size=batch_size),
groups=groups, time_index=time_index)
def _convert_block(block):
cls = getattr(fx, type(block).__name__)
obj = cls(**block.get_params(deep=False))
for name, value in vars(block).items():
if name.endswith("_"):
setattr(obj, name, _convert_block(value) if name == "interval_" and value is not None
else deepcopy(value))
return obj
def accelerate_checkpoint(model):
"""Convert a trusted, already-loaded release estimator. Does not refit or unpickle.
Returns an independent inference-only copy, including fitted head and transition
probabilities. For guarded file loading use wisp_release.checkpoints.load_checkpoint.
"""
if isinstance(model, FastFamily):
return deepcopy(model)
if type(model).__name__ not in CLASS_TO_ID or getattr(model, "classes_", None) is None:
raise ValueError("Expected a fitted WISP CPU family from the release")
out = FastFamily(type(model)(**model.get_params(deep=False)))
out.classes_ = model.classes_.copy()
out.trained_classes_ = deepcopy(getattr(model, "trained_classes_", None))
out.fit_seconds_ = getattr(model, "fit_seconds_", None)
out.checkpoint_only_ = True
if getattr(model, "members_", None):
out.members_ = [accelerate_checkpoint(member) for member in model.members_]
else:
if getattr(model, "model_", None) is None or getattr(model, "use_anchor_stats", False):
raise ValueError("Unsupported or incomplete WISP checkpoint")
out.model_ = deepcopy(model.model_)
names = {"wisp_ss": ("feature_extractor_",), "wisp_so": ("feature_extractor_",),
"wisp_rc": ("sketch_",), "wisp_gis": ("physics_", "shapelets_"),
"wisp_cis": ("rocket_", "interval_", "state_")}
out.blocks_ = [_convert_block(getattr(model, name)) for name in names[out.method_id]
if getattr(model, name, None) is not None]
if not out.blocks_:
raise ValueError("No fitted feature blocks found")
smoother = getattr(model, "smoother_", None)
if smoother is not None:
s = FastSmoother()
s.transition_ = smoother.transition_.copy()
s.prior_ = smoother.prior_.copy()
s.log_A_ = np.ascontiguousarray(np.log(np.clip(s.transition_, 1e-12, 1.0)))
s.log_pi_ = np.ascontiguousarray(np.log(np.clip(s.prior_, 1e-12, 1.0)))
out.smoother_ = s
return out
|