Scikit-learn
human-activity-recognition
wearable
wrist
time-series
cpu
scikit-learn
File size: 28,263 Bytes
93a9282
4731b11
 
 
 
 
 
 
 
93a9282
 
4731b11
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
93a9282
4731b11
 
 
 
 
 
93a9282
4731b11
 
 
 
 
 
 
 
 
 
93a9282
4731b11
 
 
 
 
 
93a9282
 
 
4731b11
 
93a9282
 
 
 
 
 
 
4731b11
 
93a9282
 
 
 
 
 
4731b11
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
93a9282
 
 
4731b11
 
 
 
 
 
 
 
 
 
 
93a9282
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4731b11
 
 
 
 
 
 
93a9282
 
 
 
4731b11
 
 
 
93a9282
4731b11
93a9282
4731b11
 
 
 
 
 
 
 
 
 
 
 
 
93a9282
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4731b11
 
 
93a9282
 
 
 
 
 
 
4731b11
 
 
 
93a9282
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4731b11
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
93a9282
4731b11
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
93a9282
4731b11
 
 
 
 
 
 
 
 
 
 
 
93a9282
 
 
4731b11
 
 
 
 
 
 
 
 
 
 
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
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
# 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`.