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
|
Download docs/API.md from Zipeng365/WISP: direct link, hf CLI and curl.
- Browser
- Download file 28.3 kB
-
https://huggingface.co/Zipeng365/WISP/resolve/main/docs/API.md
- Command line
-
hf download hf://Zipeng365/WISP/docs/API.md
-
curl -L -o API.md https://huggingface.co/Zipeng365/WISP/resolve/main/docs/API.md
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`. | |