Scikit-learn
human-activity-recognition
wearable
wrist
time-series
cpu
scikit-learn
WISP / docs /API.md
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
28.3 kB

API reference (wisp-har 0.4.0)

Import name wisp. Everything below is scikit-learn style: estimators take their settings in the constructor, fit learns, fitted attributes end with _, and clone, get_params and set_params work. Inputs are windows X of shape (n, T, C) (or (n, C, T) with layout="NCT"); a 2-D array is read as single-channel windows (n, T).

Contents: Data conventions · WISPClassifier · WISPRepresentation · wisp.blocks · HMMSmoother · The adaptive HMM switch · WISPSelect and WISPSearch · WISP-Funnel · wisp.integrations.optuna · wisp.recipes · wisp.datasets · wisp.adapters · wisp.metrics, wisp.hub, CLI · scikit-learn compatibility · Earlier interfaces

Data conventions

Item Convention
Windows (n_windows, n_timepoints, n_channels), as in WristHARBench window files; layout="NCT" accepts (n, C, T)
Values Finite numbers. Impute missing samples before windowing; the public layer rejects NaN/inf (the kernel itself would silently zero them)
Labels Any hashable type; encoded to 0..K-1 internally and decoded on output
Class table Train, validation and test must share one class table. When a split misses a class, pass the full table as classes=
groups Sequence ID of every window. Different participants, unrelated recordings and non-contiguous segments need different IDs
time_index Position of each window within its sequence; the row order is used when it is omitted
Standardisation Every kernel transformer standardises each window and channel (mean 0, standard deviation 1; deviations below 1e-6 use 1). Do not add a global standardisation of the raw windows

Known limitations:

  • Because of the per-window standardisation, the models do not see the gravity direction or the absolute signal intensity. This is a property of the method.
  • On rare inputs scikit-learn's RidgeClassifierCV, used by the Ridge readouts of the fixed families (RC, CIS and the RC/CIS members of CSE/ESE), can stop with LinAlgError: SVD did not converge. The paper code behaves the same way (the fixed-family kernel has no retry; the search kernel retries with another LAPACK driver). In the pinned environment this happened for one of the 1,260 fixed-family paper cells (see SPEED.md). speed="fast" uses a different Ridge solver and is a practical workaround, without the paper guarantee.

WISPClassifier

wisp.WISPClassifier(recipe="cis", *, decoder="adaptive", readout=None, classes=None, layout="NTC",
                    speed="exact", sequence="subject", n_jobs=1, random_state=42)
Parameter Meaning
recipe Catalog name ("cis", "cis:RS", "best:capture24"; see wisp.recipes.list()), a Recipe, or a dict in the canonical_recipe format
decoder "adaptive" (default since 0.4.0): validation data decide whether HMM decoding is used (rule); "recipe": the recipe's own setting (the paper configuration; "auto" is a deprecated alias); "hmm": force sequence decoding; "none": per-window argmax
readout None runs the recipe's own readout inside the frozen kernel. Any scikit-learn classifier (with predict_proba or decision_function) replaces it, fed by WISPRepresentation(recipe). Only single-readout recipes (SS, RC, SO, GIS, CIS and subsets) accept a readout; WISP-CSE/ESE raise ValueError
classes Global class table (needed when training data miss a class)
layout "NTC" or "NCT"
speed "exact" (default): outputs identical to the paper code. "fast": screened Ridge solver, Ridge readouts can change slightly. See SPEED.md
sequence "subject" (default) or "recording", as in 0.2.0 (see METHODS.md). "recording" needs fit_confidence_scale(X_valid, y_valid)
n_jobs Threads for tree ensembles inside the kernel
random_state Recipe seed (random kernels, intervals, shapelets, tree seeds; same offsets as the paper code)
Method Behaviour
fit(X, y, groups=None, time_index=None, validation=None, validation_size=None) Fit. With readout=None the kernel family object is built and fitted as in the paper runner; this path adds no numerical operation. validation: (X_val, y_val, groups_val[, time_val]) or validation rows of X (integer indices or a boolean mask); validation windows are fitting data, so 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; without them, validation_size (default 0.125) of the groups is held out for the decision and the final model is fitted on all of X
predict(X, groups=None, time_index=None) With groups and an active decoder: HMM decoding per sequence. Without groups: per-window argmax
predict_proba(X) Per-window class scores in classes_ order, never HMM-smoothed
score(X, y) scikit-learn default (accuracy of predict(X), i.e. without groups)
fit_confidence_scale(X_valid, y_valid) sequence="recording" only

Decoder and groups: decoder="hmm" without groups in fit raises ValueError; decoder="recipe" on an HMM recipe without groups warns once and fits the per-window variant (decoder_ == "none"); decoder="adaptive" without groups uses the per-window variant without a warning (decoder_reason_ == "no groups").

Fitted attributes: classes_, recipe_, model_ (the kernel family object, or the fitted readout), decoder_ ("hmm" or "none", the decoder of the final model), decoder_scores_ (validation macro-F1 with each decoder, decoder="adaptive" only), decoder_reason_, has_paper_results_, fit_seconds_ (final model), decision_seconds_ (the extra fit and validation decoding of decoder="adaptive"; 0 when no decision was needed), model_size_mb_ (default-protocol pickle size, as in the paper's size column), n_features_in_, input_shape_; with a readout also representation_, readout_, smoother_.

has_paper_results_ is True only for a catalog recipe with its own readout, speed="exact", sequence="subject" and a final decoder that has saved results (all fixed families with the HMM; WISP-CIS and the CIS subsets also without it; a search best recipe with its own decoder setting). With decoder="adaptive" this refers to the decoder the switch chose: the final model is then the fixed-decoder model with that setting. Results exist for the paper's seeds 42, 43 and 44. To reproduce a paper number, pass decoder="recipe" (with speed="exact", the default), and fit on training plus validation windows as the paper did.

Saving: joblib.dump(clf, path) / joblib.load(path) (pickle-based; load only trusted files).

WISPRepresentation

wisp.WISPRepresentation(recipe="cis", *, extra_blocks=None, layout="NTC", dtype="float64", random_state=42)

A recipe's representation as a scikit-learn transformer (fit, transform, fit_transform, usable in Pipeline). transform returns (n, d) features that are bit-identical to the feature matrix computed inside the family object for the same recipe and seed (test E4). WISP-CSE/ESE are score-level ensembles with no single feature vector and raise ValueError.

Attribute / method Meaning
block_slices_ Column range of each block, e.g. {"R": slice(0, 1536), "I": ..., "S": ...} for CIS; statistics (SS), symbolic (SO), R (RC), geometry_interval and shapelets (GIS); extra blocks extra0, ... or their given names
n_features_out_ Output dimension
get_feature_names_out() "<block>__<name>" (kernel names where they exist, else column numbers)
extra_blocks_ Fitted clones of extra_blocks

extra_blocks: a list of transformers or (name, transformer) pairs. Each must accept the windows in the estimator's layout and return (n, d); outputs are appended after the recipe's columns. Using extra_blocks makes the representation a custom one (is_catalog_representation_ == False). fit samples random kernels, intervals and (for GIS) subsequences from the training windows, so fit on training data only.

wisp.blocks

The three WISP-CIS blocks under their paper names; each returns an unfitted kernel transformer configured as inside WISP-CIS.

wisp.blocks.RandomConvolution(random_state=42, n_kernels=384)   # R
wisp.blocks.IntervalSummary(random_state=42, n_intervals=24)    # I (applies the CIS seed offset +29)
wisp.blocks.StateSpectral()                                      # S

HMMSmoother

sm = wisp.HMMSmoother(alpha=1.0, persistence_boost=2.0, decoder="adaptive").fit(
    y_train, groups=g_train, time_index=t_train, classes=None,
    validation=(scores_val, y_val, g_val, t_val))          # optional: decides HMM or argmax
labels = sm.decode(scores, groups=g_test, time_index=t_test)

The public name of the kernel's TransitionSmoother; outputs are identical to it (test E7). Transitions are counted between adjacent training labels within each group (ordered by time_index), plus alpha everywhere and persistence_boost on the diagonal. decode runs offline Viterbi on each group as a whole, so a window's label can depend on later windows; it is not an online (causal) decoder. Without groups all rows form one sequence. scores must be non-negative class scores (probabilities) with columns in classes_ order; they are clipped to [1e-12, 1] and renormalised per row. Apply a softmax to logits first.

decoder: with validation=(scores_val, y_val, groups_val[, time_val]) in fit (scores of validation windows from the model being smoothed, fitted without them), "adaptive" keeps the HMM only if its validation macro-F1 is strictly higher than the argmax of the same scores, and then counts transitions on the training and validation labels. Without validation scores nothing can be decided and it decodes with the HMM, exactly as before (decoder_reason_ == "no validation scores"). "recipe" and "hmm" always decode, "none" always takes the argmax. Fitted: decoder_, decoder_scores_, decoder_reason_.

The adaptive HMM switch (decoder="adaptive")

The default decoder of every WISP estimator since 0.4.0 (WISPClassifier, WISPSelect, WISPSearch with every strategy, custom readouts, and HMMSmoother when given validation scores). It decides on validation data whether HMM decoding helps:

  1. Decision data. The explicit validation data when given (validation=, and the validation split of WISPSelect/WISPSearch); otherwise a group-wise hold-out of validation_size (default 0.125) of the training groups, drawn with GroupShuffleSplit(random_state=random_state) as in WISPSelect. Test data are never used.
  2. Rule. The same model, fitted on the training windows with an HMM smoother, decodes the validation windows twice: per sequence with the HMM and per window with argmax. The HMM is kept only if its validation macro-F1 (the benchmark scorer, wisp.metrics.score) is strictly higher; a tie gives "none".
  3. Final model. Fitted on all fitting data (training plus validation windows, or all of X) with the chosen decoder, so it is the same recipe's fixed-decoder model with that setting: for WISPClassifier, when the switch keeps the HMM the final model is bit-identical to decoder="hmm" (and to decoder="recipe" for a recipe that uses the HMM), and when it chooses argmax, to decoder="none" (tests in tests/test_adaptive_decoder.py). For WISPSelect/WISPSearch the selection itself is unchanged and the decision is made for the selected recipe; when the switch chooses the winner's own decoder, the result equals decoder="recipe". The winner's training fit is reused where the selector keeps it (WISPSelect: one extra prediction of the validation windows); otherwise the decision costs one extra training fit (decision_seconds_), and a change of decoder after an engine refit costs one more refit.
  4. Edge cases. No groups: the HMM is unavailable, decoder_ == "none" (reason "no groups"). No sequences, i.e. no training group has two or more windows: "none" (reason "no sequences", see below). Fewer than two groups, so no group-wise hold-out is possible: the recipe's own decoder, with a warning (reason "fewer than 2 groups").

Why data without sequences give "none". The Viterbi recursion starts with the class prior, delta_0(k) = log prior_k + log P_k. A one-window sequence is therefore decoded as argmax_k (prior_k * P_k), where prior_k is the (smoothed) frequency of class k in the training labels; there are no transitions to use. That is a prior reweighting of the scores, not sequence smoothing, so the switch does not count it as keeping the HMM. Under "adaptive", the same rule applies to how WISPSelect/WISPSearch score their candidates: on data without sequences, candidates whose recipe carries the HMM flag are scored and refitted with argmax decoding (decoder="none" scoring). An explicit decoder="recipe" or "hmm" keeps the earlier behaviour exactly.

Reproducing paper numbers. The paper used each recipe's own decoder: pass decoder="recipe" (or "hmm" for the fixed families), together with the default speed="exact". Outputs are then bit-identical to the paper code, as before.

WISPSelect and WISPSearch

Both are classifiers that choose a recipe on validation data and refit it once on train+validation. Neither accepts test data. Validation groups must not overlap training groups (checked).

wisp.WISPSelect(menu=5, *, decoder="adaptive", classes=None, layout="NTC", speed="exact", sequence="subject",
                n_jobs=1, random_state=42)
wisp.WISPSearch(strategy="random", *, controller="random", budget=329, population=24, sampler=None,
                decoder="adaptive", on_no_candidate="raise", classes=None, layout="NTC",
                speed="exact", sequence="subject", n_jobs=1, random_state=42,
                cost_weight=0.01, robustness_weight=0.1, output_dir=None)

est.fit(X, y, groups=g, time_index=t, validation=(X_val, y_val, g_val, t_val))  # explicit validation split (paper protocol)
est.fit(X, y, groups=g, time_index=t, validation=val_rows)                       # validation rows of X (indices or mask)
est.fit(X, y, groups=g, validation_size=0.125)                                   # or hold out a fraction of the groups
search.fit(..., sampling_rate_hz=25.0, study_setting="free_living")             # WISPSearch: recording descriptors
  • WISPSelect wraps wisp_release.selection.fit_selector (WISP-Select5/Select7). The rule is unchanged: higher validation macro-F1, then higher full-vocabulary worst-class F1, then smaller serialized model size, then the order SS, RC, SO, CSE, GIS, CIS, ESE. menu=5: SS, RC, SO, GIS, CIS; menu=7 adds CSE and ESE.
  • WISPSearch(strategy="random" | "evolution") runs WISP-Random/WISP-Evolution through the 0.2.0 search driver (wisp_fast.search.run_search): the paper's controller, proposal grammar, nine initial recipes, eleven mutations, stress views and validation utility, with population 24 and budget evaluations (paper: 329 = 9 + 20 generations x 16).
  • WISPSearch(strategy="optuna") proposes recipes with Optuna (default TPESampler(seed=random_state)) from the same grammar and scores each with the same cascade and validation utility. Needs the extra [optuna]. It has no paper results.
  • WISPSearch(strategy="funnel") is WISP-Funnel, the fast joint Random + Evolution search (below). It has no paper results; its benchmark record is in RECIPES.md.
  • WISPSearch.fit(..., sampling_rate_hz=None, study_setting=None): descriptors of the recordings for the search controllers' dataset fingerprint, which shapes their proposals (the window duration follows from the sampling rate; a study setting containing "free", "home", "natural" or "wild" marks free-living data). Without them the fingerprint assumes 50 Hz and an unknown setting, so proposals can differ from a run that passes them. The paper searches and the funnel benchmark record used the values of the WristHARBench exports; a wisp.datasets fold provides them as sampling_rate_hz and study_setting.
  • decoder sets the decoder of the final model (adaptive switch). "recipe" is the paper configuration (every candidate and the winner with its own decoder); "hmm"/"none" force that decoder for candidate scoring and the refit.
  • on_no_candidate: when no candidate passes validation (every candidate rejected or collapsed; RuntimeError from the search), "raise" (default) re-raises it and "default" fits the default CIS recipe (wisp.recipes.get("cis"), with the estimator's decoder) on all fitting data instead: training then validation windows for a validation tuple, all of X in its original order otherwise. fallback_ then records the reason (None otherwise).

Fitted attributes: best_recipe_, best_estimator_ (a fitted WISPClassifier), history_ (every candidate with its validation scores and fit time), selection_seconds_ and final_fit_seconds_ (selection cost and final-model cost, kept separate), decision_seconds_ (extra cost of the adaptive decision), decoder_, decoder_scores_, decoder_reason_ (those of best_estimator_), has_paper_results_; WISPSelect also selection_report_; WISPSearch also best_seed_, best_validation_, fallback_, search_summary_ (random/evolution), study_ (Optuna), or the funnel attributes below. has_paper_results_ requires, in addition to the earlier conditions, that the final decoder is the winner's own (decoder="recipe" always satisfies this).

The search's validation utility depends on measured fit and prediction times (a cost term with weight cost_weight), so two runs can choose different winners on different machines.

WISP-Funnel (WISPSearch(strategy="funnel"))

search = wisp.WISPSearch("funnel", controller="random", n_jobs=2, random_state=42)
search.fit(X, y, groups=g, time_index=t, validation=(X_val, y_val, g_val, t_val),
           sampling_rate_hz=fs, study_setting="free_living")      # optional recording descriptors
search.predict(X_test, groups=g_test, time_index=t_test)          # the Random controller's model
search.funnel_estimators_["evolution"].predict(X_test, groups=g_test, time_index=t_test)

One run fits both controllers of the paper's search (Random and Evolution) on the CIS family (state_rocket_interval_hmm candidates) and keeps both models:

  1. Proxy. Each controller proposes budget candidates (default 329; population 24). They are ranked on a training-only proxy: class-stratified contiguous spans of at most 4,096 training and 1,024 validation windows, a shared random-feature dictionary on which every candidate fits a Ridge readout in its own column subspace, HMM decoding where the candidate has it, and the search's validation utility with cost weight 0. The two controllers share one dictionary and one dataset fingerprint.
  2. Verification. A diversified shortlist of 4 candidates per controller is fitted on the full training split and scored on the full validation split and its four perturbed copies (the paper's cascade, robustness weight 0.1), with the screened Ridge solver. If none of the 4 passes, the next 4 are verified.
  3. Refit. Each controller's best verified candidate is refitted on train+validation.

controller ("random" or "evolution") chooses which model predict/predict_proba use; funnel_estimators_ holds both, each a fitted WISPClassifier with its own decoder_. n_jobs is the number of controller threads (1: in series; 2 or more: in parallel); every candidate and BLAS call uses one thread, and the results do not depend on n_jobs. speed, cost_weight and robustness_weight do not apply (the protocol fixes them) and sequence must be "subject". Selection uses training and validation data only.

Inputs with more than 64 channels use a portable NumPy route for the proxy's feature dictionary (its compiled kernel accepts at most 64 channels); inputs with at most 64 channels take exactly the code path of the benchmark record.

Fitted attributes (besides the common ones): funnel_estimators_ ({"random": ..., "evolution": ...}), funnel_summary_ (per controller: winner id, recipe, seed, validation result, proposal and verification counts, and proxy_seconds, verification_seconds, refit_seconds), funnel_receipt_ (shared preparation, feature-cache statistics, total seconds) and funnel_seconds_ (wall time of the whole joint run, both controllers). selection_seconds_ is the chosen controller's proxy plus verification time; final_fit_seconds_ its final fit.

wisp.integrations.optuna

from wisp.integrations.optuna import suggest_recipe, evaluate_recipe, run_study, SEARCH_SPACE

def objective(trial):
    recipe = suggest_recipe(trial)                       # a wisp.Recipe from the grammar's space
    lr = trial.suggest_float("other_param", 1e-4, 1e-1, log=True)
    ...

suggest_recipe(trial, families=None, prefix="wisp") samples the family, readout, segment sizes, symbolic bins, kernels, intervals, shapelets, ESE weights, CIS block switches (the paper's CIS subsets) and the decoder; parameter names are conditional on the family. evaluate_recipe(recipe, train, valid, ...) scores one recipe with the frozen cascade (train/valid are wisp.core.data.HARData) and returns (status, result); the utility is result["predictive_utility"]. run_study(...) is what WISPSearch("optuna") calls. Repeated proposals of the same recipe reuse the earlier result and still count as trials.

wisp.recipes

wisp.recipes.list(source=None)      # table of the 25 catalog recipes (DataFrame if pandas is installed)
wisp.recipes.get("cis")             # fixed: "ss" "rc" "so" "gis" "cis" "cse" "ese"
wisp.recipes.get("cis:RS")          # CIS subsets: "cis:R" "cis:I" "cis:S" "cis:RI" "cis:RS" "cis:IS" ("cis:RIS" is "cis")
wisp.recipes.best("capture24")      # search best recipe of a stream, same as get("best:capture24")
wisp.recipes.search_runs()          # the 360 final recipes of the budget-329 searches (read-only)
wisp.recipes.dataset_id("adl")      # short name -> full dataset ID

Recipe(family, params, *, id=None, paper_name=None, source="custom", provenance=None) is immutable. to_dict() gives the canonical {"name", "params", "route"} format of results/search_selections.csv; from_dict, to_json, from_json, with_params(**changes) (a custom copy), describe(). Properties: params (a copy), provenance, use_hmm, single_readout, in_catalog. params never holds seed or n_jobs.

See RECIPES.md for what each recipe is, which results back it and how the search best recipes were chosen.

wisp.datasets

data = wisp.datasets.load_wristharbench("adl", fold=0, cache_dir=None, local_data=None)
data.train.X, data.train.y, data.train.groups, data.train.time_index
data.val, data.test, data.train_val, data.label_names, data.classes
data.sampling_rate_hz, data.study_setting      # recording descriptors (e.g. for WISPSearch.fit)

data = wisp.datasets.load_exported_fold(root, "adl", fold=0)      # already exported NPZ folds

X, y, groups, time_index = wisp.datasets.make_windows(
    signal, fs=50, window_s=5.0, step_s=2.5, labels=labels, group=participant,
    label_rule="majority", min_label_fraction=0.8)

load_wristharbench exports the official fold once from the Hugging Face dataset Zipeng365/WristHARBench at the pinned revision (the same procedure as scripts/export_benchmark.py) and caches the NPZ files ($WISP_DATA_DIR or ~/.cache/wisp-har/wristharbench). It needs the extra [hub]. Access follows that repository's terms.

make_windows requires the window and step lengths (no defaults: datasets differ). Windows never cross a change of group. Labels follow the WristHARBench export rules: "majority" keeps a window when its most frequent valid annotation covers at least min_label_fraction of the valid annotations (CAPTURE-24 and IUWDS use 0.8); "constant" keeps only single-label windows (datasets whose windows are built within each activity segment). time_index is the window start in seconds.

wisp.adapters

wisp.adapters.FunctionBlock(fn, kw_args=None)                         # any X -> (n, d) function as a block
wisp.adapters.TorchEncoderBlock(module, batch_size=256, device="cpu", layout="NTC")   # frozen PyTorch encoder as a block
wisp.adapters.to_torch_dataset(Z, y=None)                             # features -> torch TensorDataset

PyTorch is imported only when a torch adapter is used. TorchEncoderBlock runs the module in eval() mode under torch.no_grad() in batches, passes (batch, C, T) float32 tensors (the usual PyTorch layout) and returns flattened numpy features; it does not train the module. A transformer that expects (n, C, T) (for example aeon's MiniRocket) can be wrapped with FunctionBlock(lambda X: t.transform(X.transpose(0, 2, 1))) after fitting it yourself.

Other modules

  • wisp.metrics.score(y_true, y_pred, n_classes) — the frozen four-metric definitions (macro-F1 over classes present in truth or prediction, accuracy, balanced accuracy, full-vocabulary worst-class F1) plus the confusion matrix.
  • wisp.hub.load_pretrained(...) — planned for a later version; raises NotImplementedError in this version. Retained checkpoints load with wisp_release.load_checkpoint (CHECKPOINTS.md).
  • Command line wisp: the 0.2.0 commands (list, inventory, predict, evaluate, family-fit, select-fit, search) plus wisp recipes [--source ...].

scikit-learn compatibility

Tested (tests/test_api_sklearn.py): clone/get_params/set_params round trips (also nested readout__* parameters), WISPRepresentation inside Pipeline, cross_val_score without groups, GridSearchCV over recipe, metadata routing of groups/time_index (set_fit_request(groups=True, time_index=True), set_predict_request(...)) end to end through a Pipeline and through cross_val_score(..., params=...), and joblib round trips.

With metadata routing, validation is a fit parameter like groups (request it with set_fit_request(validation=True) to route it through a Pipeline).

check_estimator runs on WISPClassifier("so", decoder="none"); it treats a 2-D input as single-channel windows. The checks listed in EXPECTED_FAILED_CHECKS in tests/test_api_sklearn.py are exempt, each with its reason (they assume tabular rows, not time windows). Kernel calls run with metadata routing switched off locally, because the kernel passes clf__sample_weight to its own pipelines.

Earlier interfaces (still available)

wisp_release.build_family, wisp_release.fit_selector, wisp_release.load_checkpoint, wisp_release.predict_checkpoint, wisp_fast.engine.* and every frozen kernel module (wisp.cpu.*, wisp.cis_algorithms, wisp.registry, wisp.ablations, wisp.search.*, wisp.core.*) keep their 0.2.0 paths and behaviour. The funnel's engine is a separate subpackage, wisp_fast.funnel (entry point wisp_fast.funnel.joint.fit_joint_funnel), which shares no module with wisp_fast.