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](#data-conventions) · [WISPClassifier](#wispclassifier) ·
[WISPRepresentation](#wisprepresentation) · [wisp.blocks](#wispblocks) ·
[HMMSmoother](#hmmsmoother) · [The adaptive HMM switch](#the-adaptive-hmm-switch-decoderadaptive) ·
[WISPSelect and WISPSearch](#wispselect-and-wispsearch) · [WISP-Funnel](#wisp-funnel-wispsearchstrategyfunnel) ·
[wisp.integrations.optuna](#wispintegrationsoptuna) · [wisp.recipes](#wisprecipes) ·
[wisp.datasets](#wispdatasets) · [wisp.adapters](#wispadapters) · [wisp.metrics, wisp.hub, CLI](#other-modules) ·
[scikit-learn compatibility](#scikit-learn-compatibility) · [Earlier interfaces](#earlier-interfaces-still-available)
## 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.md#accuracy-record-of-the-fast-tier-and-all-cell-check)). `speed="fast"`
uses a different Ridge solver and is a practical workaround, without the paper guarantee.
## WISPClassifier
```python
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](#the-adaptive-hmm-switch-decoderadaptive)); `"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](SPEED.md) |
| `sequence` | `"subject"` (default) or `"recording"`, as in 0.2.0 (see [METHODS.md](METHODS.md#speed-and-hmm-smoothing-sequence)). `"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
```python
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.
```python
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
```python
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).
```python
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](#wisp-funnel-wispsearchstrategyfunnel)). It has no paper results; its benchmark
record is in [RECIPES.md](RECIPES.md#wisp-funnel-a-fast-search).
* `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](#the-adaptive-hmm-switch-decoderadaptive)).
`"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")`)
```python
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
```python
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
```python
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](RECIPES.md) for what each recipe is, which results back it and how the search
best recipes were chosen.
## wisp.datasets
```python
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
```python
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](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`.