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
WISP: Composable Representations for Wrist-Worn Activity Recognition
WISP (Wrist-Informed Space of Predictive Representations) is a CPU method family for wrist-worn human activity recognition. This method-only repository provides the authors' implementation, a small inference/training interface, a pinned CPU environment, and retained method checkpoints with an explicit inventory. Author: ZipengWu.
Version 0.4.0 adds WISP-Funnel, a fast joint Random + Evolution search (WISPSearch(strategy="funnel")), and makes the adaptive HMM switch (decoder="adaptive", which decides on validation data whether HMM decoding is used) the default decoder of every WISP estimator. The paper numbers on this page use each recipe's own decoder; decoder="recipe" reproduces them exactly (what changed). Version 0.3.0 added the scikit-learn interface to the same frozen method code: wisp.WISPClassifier, wisp.WISPRepresentation, wisp.HMMSmoother, wisp.WISPSelect, wisp.WISPSearch and a catalog of recipes that have saved results. The 0.2.0 interfaces (wisp_release, wisp_fast, the wisp command) and all kernel module paths are unchanged, so the retained checkpoints still load.
Why WISP
WISP is accurate, fast and small, and it plugs into the tools you already use. Each figure below
places every method by one score against one resource, so the further up and to the left a
point sits, the better. A method is Pareto-dominated when another method needs no more of the
resource and scores higher; every point beneath the dashed gold line (the WISP Pareto frontier)
is dominated by a WISP method. WISP points and numbers in this section are results with each
recipe's own decoder (the paper protocol); decoder="recipe" with speed="exact" reproduces them
(the 0.4.0 default decoder is described below).
WISP-Random is Pareto-optimal in all eight figures (four metrics, each against final-model cost and against memory): no method is both cheaper, or smaller, and more accurate. It dominates most baselines outright:
| Resource (same result for all four metrics) | Overall Pareto frontier | Baselines Pareto-dominated by WISP |
|---|---|---|
| Final-model cost | WISP-Random, Balanced-RF | 14 of 15 by WISP-Random and by WISP-Evolution; 11 by WISP-CIS, which needs no search |
| Peak memory | WISP-Random, QUANT, Balanced-RF | 4 of 6 by each of WISP-Random, WISP-Evolution and WISP-CIS |
The baselines that stay on the frontier do so only by being cheaper or smaller, not by being more accurate: Balanced-RF scores 22.3 macro-F1 points below WISP-Random, and QUANT 14.9.
1. Accurate and fast
Macro-F1 (nine primary datasets, all splits, three seeds) against the cost of the final model:
fitting the selected configuration on training+validation data plus predicting the test data,
in core-hours summed over ten streams (fold 0, seed 42; log scale). Configuration selection
(the WISP searches, the baselines' tuning grids) is not on this axis; fixed WISP-CIS needs no
selection at all. One NVIDIA A100 hour counts as 64 core-hours. Every plotted value is in
docs/figures/cost_accuracy_plotted_values.csv.
- Most accurate. WISP-Random reaches 70.20 macro-F1, WISP-Evolution 69.59 and WISP-CIS 66.14; the best baseline is tuned RDST at 67.07. WISP-Random is the highest on all four metrics: macro-F1, balanced accuracy, accuracy (77.28; best baseline 74.93) and worst-class F1 (28.25; 27.82, tuned MR-Hydra).
- Fast. The final model costs 0.311 core-hours for WISP-Random, 0.347 for WISP-CIS and 0.712 for WISP-Evolution. The final models of tuned RDST, MR-Hydra, MultiRocket and MiniRocket cost 34.15, 45.52, 84.63 and 15.53 core-hours, 50–272 times WISP-Random's. WISP runs on CPUs only; no GPU is needed.
- Pareto-dominant. WISP-Random and WISP-Evolution are both cheaper and more accurate than 14 of the 15 baselines, including every tuned baseline, HC2 and all four deep models. Fixed WISP-CIS, with no search at all, dominates 11 of them; only Balanced-RF and the three strongest tuned baselines (RDST, MR-Hydra, MultiRocket) escape it. Balanced-RF's final model (0.22 core-hours, 47.85 macro-F1) is the only one cheaper than every WISP point.
- What the axis leaves out. Configuration selection is not on it; a full WISP search is expensive there (cost notes), while fixed WISP-CIS has no selection cost.
- Fast search: WISP-Funnel (new in 0.4.0).
WISPSearch(strategy="funnel")runs the Random and Evolution controllers in one pass, ranks their proposals on a training-only proxy and verifies only a shortlist on the full splits. One run, which yields both a Random and an Evolution model, costs about 1/47 of the candidate-fitting time of one paper WISP-Random search (1/70 of one WISP-Evolution search), and its two models reach 69.22 and 69.30 macro-F1, within one point of the full searches (70.20 and 69.59) and 3.1 points above fixed WISP-CIS (66.14). The cost comparison sets the funnel's total CPU time for the whole run (both controllers' proposals, verification and both refits on train+validation) against the paper searches' recorded single-core time for their 329 candidate fits alone (sums of the per-stream medians over the ten primary streams: 7.76 against 365.6 and 541.4 core-hours); the paper figure leaves out the searches' validation scoring and refit. This is the package's own benchmark on the 150 paper cells, not a paper result (record and per-stream costs).
2. Good on every class, at a fraction of the time
Balanced accuracy (the mean recall over classes, so rare activities count as much as common ones) against the same final-model cost axis.
Wearable activity data are imbalanced: a few activities fill most of the day. Balanced accuracy rewards a model only if it recognises the rare activities too. WISP-Random (70.88) and WISP-Evolution (70.17) are the two most balanced methods in the comparison, and both Pareto-dominate 14 of the 15 baselines on this figure too. The best baseline, tuned RDST, reaches 68.21 with a final model that costs 110 times WISP-Random's (34.15 against 0.311 core-hours).
3. Small memory
Peak host memory of one final model (fit plus test prediction), the largest of the ten primary
streams (fold 0, seed 42), one thread, log scale. WISP: this package's measurement
(benchmarks/memory_final_models.py), fitting on
training+validation data; each search's selected recipe was refitted with the seed of its
retained model and reproduced the saved scores exactly. Baselines (default parameters): the
paper's single-thread efficiency benchmark, fitting on the training split only, which slightly
favours the baselines. Scores are those of the figures above. Not on this axis: the tuned
baselines (their final refits were recorded with 1–8 threads, which is not comparable with
these single-thread peaks), HC2 (32 threads) and the deep models (GPU memory). Values:
docs/figures/memory_plotted_values.csv.
WISP-Random is again Pareto-optimal, and every WISP method Pareto-dominates RDST, MR-Hydra, MultiRocket and MiniRocket on all four metrics. The final model of WISP-Random peaks at 4.7 GiB, WISP-Evolution at 8.0 GiB and WISP-CIS at 8.9 GiB, so all three fit on a laptop with 16 GB of memory. RDST, MR-Hydra and MultiRocket needed 104–114 GiB, about 22–24 times WISP-Random, and MiniRocket 21.8 GiB, while scoring 10–11 points lower in macro-F1. QUANT (4.4 GiB) and Balanced-RF (2.3 GiB) use less memory than WISP-Random, at 14.9 and 22.3 points lower macro-F1.
4. Extensible
The representation drops into any scikit-learn pipeline (WISPRepresentation); the readout can
be swapped for any scikit-learn classifier, including neural networks through skorch; external
encoders, such as a frozen PyTorch network, join as extra representation blocks; the HMM
decoder smooths the scores of any model (HMMSmoother); and recipe search runs through Optuna
(WISPSearch(strategy="optuna"), wisp.integrations.optuna.suggest_recipe). These are
capabilities, not performance claims: the package reports no numbers for user-assembled
combinations. In this package's own benchmark, Optuna search matched WISP-Random's test
macro-F1 (+0.27 points on average over 36 paired runs) in 0.39 times the selection time
(benchmarks/results/optuna_vs_random.md).
Adaptive HMM switch (default)
The switch chooses per dataset whether sequence decoding helps, on validation data only: the same
model, fitted on training windows, decodes the validation windows with and without the HMM, and
the HMM is kept only if its validation macro-F1 is strictly higher. Data without sequences (no
training group with two or more windows) give "none". It is the default decoder of every WISP
estimator since 0.4.0 (decoder="adaptive"); the paper numbers above use each recipe's own
decoder and are reproduced with decoder="recipe" and speed="exact"
(API.md).
This package's benchmark, not a paper result. The 150 cells of the ten primary streams (5 folds x 3 seeds), the paper's validation split as decision data, the test split scored once; nine-view averages, adaptive with the method's own recipe-decoder result in brackets. "HMM kept" counts the cells whose final model decodes with the HMM; the extra cost is the decision fit summed over the cells, with its share of the final fits' time.
| Method | HMM kept | Macro-F1 | Balanced acc. | Accuracy | Worst-class F1 | Extra decision cost |
|---|---|---|---|---|---|---|
| WISP-SS | 77/150 | 61.45 (58.54) | 61.97 (59.04) | 73.47 (73.36) | 25.94 (21.70) | 1.11 h (88%) |
| WISP-RC | 105/150 | 65.41 (63.44) | 66.78 (63.59) | 72.66 (71.46) | 23.67 (22.87) | 0.68 h (91%) |
| WISP-SO | 79/150 | 55.70 (53.59) | 56.44 (54.19) | 69.15 (69.31) | 21.00 (16.75) | 1.10 h (88%) |
| WISP-GIS | 76/150 | 58.10 (55.16) | 58.42 (55.95) | 70.56 (70.66) | 24.11 (19.49) | 1.53 h (88%) |
| WISP-CIS | 111/150 | 68.54 (66.14) | 69.37 (66.04) | 75.41 (74.07) | 26.78 (24.78) | 2.24 h (90%) |
| WISP-CSE | 75/150 | 62.44 (58.74) | 62.94 (59.10) | 73.43 (72.86) | 25.75 (21.22) | 2.58 h (88%) |
| WISP-ESE | 70/150 | 60.77 (57.38) | 61.01 (57.71) | 71.91 (71.73) | 24.52 (19.78) | 3.93 h (89%) |
| WISP-Select5 | 112/150 | 69.27 (67.10) | 69.81 (66.94) | 76.39 (75.21) | 26.80 (24.93) | 0.64 h (31%) |
| WISP-Select7 | 112/150 | 68.86 (66.69) | 69.52 (66.65) | 76.18 (75.01) | 26.51 (24.65) | 0.65 h (29%) |
| WISP-Funnel, Random | 116/150 | 69.20 (69.22) | 70.18 (70.01) | 76.37 (76.11) | 26.18 (26.27) | 6.26 h (78%) |
| WISP-Funnel, Evolution | 119/150 | 69.76 (69.30) | 70.10 (69.97) | 76.16 (75.93) | 26.77 (26.99) | 7.14 h (85%) |
| WISP-Random (saved winner) | 120/150 | 70.20 (70.20) | 70.88 (70.88) | 77.28 (77.28) | 28.25 (28.25) | 2.38 h (89%) |
| WISP-Evolution (saved winner) | 120/150 | 69.59 (69.59) | 70.17 (70.17) | 76.84 (76.84) | 27.96 (27.96) | 2.06 h (89%) |
For WISP-Random and WISP-Evolution the switch was applied to the recipe each paper search
selected (the searches were not rerun); WISPSelect reuses its candidates' training fits, so its
decision costs one validation prediction plus a refit where the decoder changes. In every cell
where the switch keeps the recipe's decoder, the final model is identical to the model with the
recipe's decoder: the paper model for the fixed families, WISPSelect and the saved winners, the
benchmark record's model for WISP-Funnel (identical test metrics in all such cells). Per-stream
counts and the changed cells: benchmarks/results/adaptive_decoder.md.
Quick start
import wisp # pip install ".[hub]" for the dataset download
d = wisp.datasets.load_wristharbench("adl", fold=0) # official participant-disjoint fold
fit = d.train_val # paper protocol: fit on train+validation
clf = wisp.WISPClassifier("cis", decoder="recipe", classes=d.classes) # WISP-CIS as in the paper
clf.fit(fit.X, fit.y, groups=fit.groups, time_index=fit.time_index)
pred = clf.predict(d.test.X, groups=d.test.groups, time_index=d.test.time_index)
print(wisp.metrics.score(d.test.y, pred, len(d.label_names))["macro_f1"]) # 0.58054..., as in results/run_results.csv
random_state=42 is the default; seeds 43 and 44 give the other two saved results of this cell.
decoder="recipe" keeps the recipe's own decoder, as in the paper. Without it, the default
decoder="adaptive" decides on validation data whether to keep the HMM decoder: pass
validation=(X_val, y_val, groups_val, time_val) to fit (then the final model is fitted on
training plus validation windows), or let it hold out 12.5% of the training groups
(adaptive switch).
examples/01_benchmark_quickstart.py does the same for
any stream, fold, seed and catalog recipe and prints the saved result next to it.
What else is in the package:
| Need | Use |
|---|---|
| A result-backed configuration | wisp.recipes.list(), wisp.recipes.get("cis:RS"), wisp.recipes.best("capture24") |
| Features for your own model | WISPRepresentation("cis") in any sklearn.pipeline.Pipeline; block_slices_ names the R, I and S columns |
| Your own readout | WISPClassifier("cis", readout=LogisticRegression()) (any classifier, also skorch networks) |
| Your own encoder as a block | WISPRepresentation("cis:RS", extra_blocks=[wisp.adapters.TorchEncoderBlock(net)]) |
| HMM decoding of any model's scores | wisp.HMMSmoother().fit(y_train, groups=g_train).decode(scores, groups=g_test) |
| Validation selection / search | WISPSelect(menu=5), WISPSearch("random" | "evolution" | "optuna") |
| A fast search (both controllers in one run) | WISPSearch("funnel", controller="random" | "evolution"); funnel_estimators_ holds both models |
| HMM decoding only where it helps | decoder="adaptive" (the default): decided on validation data, for any WISP estimator |
| Your own recordings | wisp.datasets.make_windows(signal, fs=..., window_s=..., step_s=..., labels=..., group=...) |
Guides: API reference · Which recipe, and when to search · Speed tiers · examples/ · failure log.
More metrics
The other two metrics against final-model cost and against memory (values in the same CSVs):
About this release
Release contents: code, configurations, environments, documented results and all 360 retained search checkpoints are provided together. The inventory distinguishes these available files from fixed-family and selection checkpoints that were not retained.
The local Python distribution is named wisp-har; its import name is wisp, its command is wisp and its 0.2.0 release API package wisp_release remains available. This repository installation is not a claim that a package has been published to PyPI.
The seven fixed models are WISP-SS, WISP-RC, WISP-SO, WISP-GIS, WISP-CIS, WISP-CSE and WISP-ESE. WISP-Select5 and WISP-Select7 provide validation-based selection; WISP-Random and WISP-Evolution provide search strategies. These are seven core models plus four selection/search variants, not hundreds of distinct model types. Method names and roles explain the distinction. This is a method release, not a baseline platform: third-party baseline training code, environments, pretrained weights and checkpoint files are excluded.
Benchmark data remain in WristHARBench on Hugging Face. Access follows that repository's visibility and source-specific dataset terms. This method repository does not duplicate the benchmark data or change its licenses. The local input interface described below uses exported NPZ windows, not raw source archives or arbitrary Hub Parquet rows.
Video overview / 中英文科研动画
Two independently narrated animations explain WristHARBench, how WISP representations read wrist-motion signals, how complementary information is combined, and the experimental findings.
Narration updated on 28 October 2026: Chinese uses MiMo's 茉莉 voice; English uses Chloe. Both are AI-generated voices. Subtitles and scene timing have been rebuilt for the new narration.
| Language | Video | Audio | Subtitles | Script |
|---|---|---|---|---|
| English · 3:46 | Watch / 下载 MP4 | WAV | SRT · VTT | English script |
| 中文 · 3:47 | Watch / 下载 MP4 | WAV | SRT · VTT | 中文脚本 |
English
中文
The research story and graphics are retained from the 18 October 2026 production. Signal landscapes include illustrative synthetic inputs, distinguished from experimental results in the videos. This update changes narration and subtitle timing; it does not introduce new experimental results.
Reproducible project · Reproduction instructions and sources · Paper (Pure)
Original system-voice edition and subtitles. Previously shared system_voice.mp4 URLs now serve the refreshed editions.
Install
Use Python 3.12.13, the interpreter selected and tested for this release. The historical virtual-environment creation record also names 3.12.13, but does not prove the runtime patch version of every historical fit. Other Python patch versions are not automatically covered by the model-validation claim. Version 0.3.0 also passed its full test suite, including the equivalence checks against the saved results, on Python 3.11.14 with the same pinned packages, so the package metadata accepts Python 3.11 and 3.12; Python 3.10 cannot install the pinned NumPy 2.3.5. The commands below assume python3.12 resolves to 3.12.13; otherwise select that interpreter explicitly. On the cluster, installation, inference, tests and training must run on allocated compute nodes, not login nodes. From this repository root:
python3.12 -c 'import sys; assert sys.version_info[:3] == (3, 12, 13), sys.version'
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r environments/cpu.lock.txt
python -m pip install --no-deps .
wisp list
Optional extras: [hub] (dataset download for wisp.datasets.load_wristharbench), [optuna] (WISPSearch(strategy="optuna")), [torch] (PyTorch adapters), [dev] (pytest), e.g. python -m pip install ".[hub,optuna]". Without them the rest of the package works; the corresponding tests are skipped.
Only NumPy, SciPy, scikit-learn and its runtime dependencies are installed. No PyTorch/CUDA, aeon, Mamba or baseline source download is needed. Installing from source compiles small optional C kernels when a C compiler is available; without one, the same code runs on slower pure-Python/NumPy paths. A prebuilt wheel for CPython 3.12 on Linux x86_64 is in dist/. The software gate recorded for the first release passed 55 tests and verified wheel installation/import from outside the source tree using Python 3.12.13. The 0.3.0 test suite was run the same way, with and without the C kernels compiled; see the 0.3.0 validation record. See environment notes and the release audit for the exact resolved environment and final regression checks.
Export a benchmark fold (optional)
If the NPZ inputs are not already available, install the optional data-export dependencies and export a frozen fold from an existing local WristHARBench snapshot:
python -m pip install -r environments/data.lock.txt
python scripts/export_benchmark.py \
--dataset adl_wrist_accel_v1 \
--output inputs \
--fold 0 \
--local-data /path/to/WristHARBench
Omit --local-data to read the pinned Hugging Face repository/configuration/revision instead. You must have access to that repository and authenticate your own account when its access controls require it. This is not an anonymous-public-download claim. Keep tokens out of scripts, published metadata and command logs. Export must run on an allocated compute node. The root release audit identifies which exports were actually checked; the script's presence does not imply that every dataset export has passed validation.
This creates inputs/adl_wrist_accel_v1/fold0/train.npz, valid.npz and test.npz. The verified fold has 3,035 training, 446 validation and 861 test windows, 14 global activity classes, and participant-disjoint partitions. The example below uses its test.npz; no training/search is needed to use a retained checkpoint.
The exporter reconstructs the paper view and fold contract, rather than treating the complete source collection as identical to the paper's experimental subset. In particular, the full benchmark collection and the paper's CAPTURE-24 view have different window coverage. Preserve the export's effective dataset/split metadata alongside a checkpoint; do not infer that they are interchangeable because the dataset name matches.
Use a retained checkpoint
First inspect the actual model inventory:
wisp inventory --root models
The first-release scope is code for all eleven variants and the 360 retained search checkpoints: 180 WISP-Random plus 180 WISP-Evolution, totaling 74,911,659,604 bytes (about 74.91 GB before auxiliary files). These are per-stream/fold/seed fitted instances of two search strategies, not 360 different method types. All 360 original copies have identical SHA256 to their source files and passed loading and small synthetic prediction checks in the validated environment.
| Method scope | Expected paper model cells | Retained source checkpoint files |
|---|---|---|
| WISP-Random | 180 | 180 |
| WISP-Evolution | 180 | 180 |
| Seven fixed families, including WISP-CIS | 1,260 | 0 |
| WISP-Select5 and WISP-Select7 | 360 | 0 |
The full inventory covers 1,980 keys: eleven methods × twelve physical streams × five folds × three seeds. 1,620 keys have no retained checkpoint, including all 180 WISP-CIS keys. Their implementation and historical results can be included, but no missing model is fabricated, substituted with a search-selected model, or silently retrained. No new training is performed merely to populate this release.
Having implementation code or a completed result for a method does not establish that its trained checkpoints were retained or validated. The model inventory and release audit are the authority for the files actually copied and checked.
models/model_inventory.csv enumerates the expected paper cells by method, physical source stream, fold and seed. Missing-cell rows are deliberate and do not represent downloadable model files. The 360 retained rows are load_and_smoke_verified; that status does not mean every full test split was rerun. Twelve physical streams include separate HARMES wrist streams, while the benchmark's reported dataset views number eleven.
After exporting ADL-Wrist fold 0 above, run the verified WISP-Random fold-0/seed-42 checkpoint:
wisp predict \
--checkpoint models/wisp_random/adl_wrist_accel_v1/fold0/seed42/model.pkl \
--input inputs/adl_wrist_accel_v1/fold0/test.npz \
--output outputs/adl_random_fold0_seed42_predictions.npz \
--sha256 874f0b547ea16f5520641d01894fc4836451d749795dec2e805544925b56944b \
--n-jobs 1 \
--trust-pickle
Evaluate the same fitted model without retraining:
wisp evaluate \
--checkpoint models/wisp_random/adl_wrist_accel_v1/fold0/seed42/model.pkl \
--input inputs/adl_wrist_accel_v1/fold0/test.npz \
--output outputs/adl_random_fold0_seed42_metrics.json \
--sha256 874f0b547ea16f5520641d01894fc4836451d749795dec2e805544925b56944b \
--n-jobs 1 \
--trust-pickle
Prediction writes NPZ; evaluation writes JSON metrics and the full-vocabulary confusion matrix. Existing output files are not overwritten. These commands use an existing fitted model; they do not run the search or retrain it. See evaluation definitions, especially the difference between corrected frozen results and original adjacent metric files.
What has been verified
The model validation report separates three evidence levels:
- 360/360: original-copy SHA256 identity, loading and small synthetic-input predictions passed.
- 360/360: rescoring the immutable saved test predictions matched the corrected four-metric paper catalogue; this is not 360 full inference reruns.
- 6/6 ADL-Wrist fold-0 models: Random/Evolution × seeds 42/43/44 each reproduced all 861 locked test predictions exactly, both on the original frozen NPZ and a fresh pinned benchmark export. The other 354 full test splits were not rerun in this gate.
For this ADL check, the original time_index uses seconds and the Hub export uses window ordinals. The raw coordinates differ, but participant/row labels, input signals and within-participant chronological order matched; the decoder uses order, not time-gap magnitudes. This difference is recorded in the report rather than concealed. Model regression and remote-publication receipts are tracked separately by the release audit.
Pickle checkpoints are executable serialized objects. Load only trusted releases, with compatible dependency versions. A checksum verifies byte identity, not whether an untrusted model is safe. Checkpoint notes cover fitted state, legacy tsevolve compatibility and model provenance.
Version 0.3.0 checks (record): the full test suite passes from an installed wheel with and without the C kernels; on ADL-Wrist fold 0 the new WISPClassifier, WISPRepresentation, WISPSelect and HMMSmoother reproduce the paper code and the saved results exactly (tables in benchmarks/results/); and refits of the catalog recipes on all paper cells are compared with the saved results in docs/SPEED.md.
Version 0.4.0 checks (record): the full test suite passes from an installed wheel with and without the C kernels, and the equivalence checks against the paper code and the saved results give the same report as in 0.3.0 (with decoder="recipe"); speed="exact" and speed="fast" reproduce the 0.3.0 outputs on a sample of saved cells (156 of 156; all 96 exact-tier results equal the saved four metrics); WISPSearch(strategy="funnel", decoder="recipe") reproduces the funnel benchmark record on all 150 cells (same winners, identical test class scores and labels; benchmarks/results/funnel_record_check.md); and the switch's final models equal the fixed-decoder models (tests/test_adaptive_decoder.py).
Train or search
wisp family-fit --help describes fitting a fixed WISP family. wisp select-fit --help describes WISP-Select5/Select7 validation selection and final refitting. wisp search --help describes WISP-Random and WISP-Evolution. All three commands require --execute to perform fitting; without it they print the requested plan. Seed and --n-jobs are required. Search population, generations and maximum candidate evaluations must also be supplied explicitly rather than borrowed from undocumented defaults.
select-fit fits candidates on training participants, selects using validation only, then fits a fresh selected model on train+validation once. It does not accept test input. See method roles and selection rule.
All three training commands accept the two options below. Both default to the original behaviour, so commands without them run as before.
Speed options
--speed exact(default) uses the original Ridge solver. Outputs are identical to the original implementation.--speed fastuses a screened Ridge solver: the regularisation strength is chosen on a 512-row subsample of the training data, then the classifier is fitted on all rows. It is faster, and results can change slightly. Only models with a Ridge classifier are affected (WISP-RC, WISP-CIS and the RC/CIS parts of the ensembles and search candidates).
In this package's own benchmark (all seven fixed families on the twelve streams, fold 0, seed 42, one thread, one CPU type), the exact engine reproduced the paper code's class scores bit for bit and took 5,108 s in total against 28,942 s for the paper code (5.7x); the fast mode's Ridge readouts were faster still. Cells, timings and the per-dataset accuracy changes of the fast mode are in docs/SPEED.md. The Python interface uses the same two options: WISPClassifier(..., speed="exact" | "fast").
HMM smoothing sequence
The optional HMM smoother decodes windows as sequences. There are two ways to form them:
--sequence subject(default): all windows of one participant form one chain, ordered bytime_index. This is the original behaviour and suits continuous, all-day wear.--sequence recording: each recording forms its own chain. A new recording starts whenevertime_indexgoes backwards within a participant's rows. This suits data collected as separately recorded clips. The confidence scaling of classifier scores is chosen on the validation split, and smoothing is skipped when most training recordings contain a single activity, because there are then no within-recording transitions to learn. Withfamily-fit, supply the validation split through--valid.
wisp family-fit --method wisp_cis \
--input inputs/adl_wrist_accel_v1/fold0/train.npz \
--valid inputs/adl_wrist_accel_v1/fold0/valid.npz \
--output outputs/adl_cis_fold0_seed42.pkl \
--seed 42 --n-jobs 1 --speed fast --sequence recording --execute
The same choices in Python:
from wisp_release import build_family
from wisp_release.data import as_har_data, read_npz
train, valid, test = (as_har_data(read_npz(f"inputs/adl_wrist_accel_v1/fold0/{part}.npz", require_y=True))
for part in ("train", "valid", "test"))
model = build_family("wisp_cis", seed=42, speed="fast", sequence="recording")
model.fit(train.X, train.y, groups=train.subject, time_index=train.time_index,
n_classes=train.n_classes)
model.fit_confidence_scale(valid.X, valid.y) # only used with sequence="recording"
labels = model.predict(test.X, groups=test.subject, time_index=test.time_index)
wisp_release.fit_selector(..., speed=..., sequence=...) takes the same options. Saved metadata records both choices. Retained checkpoints keep the decoder they were fitted with; these options apply when fitting new models. Details: method options.
These commands are separate from checkpoint inference. Paper fold checkpoints correspond to a specific dataset view, label vocabulary, fold and seed. They are not a universal cross-dataset recognizer. A new model fitted to all available participants would be a separate deployment artifact, not the original held-out evaluation checkpoint.
For a paper comparison, retain the frozen dataset view, participant-disjoint splits, window/channel ordering, class axis, validation-based selection rule and sequence-decoding contract. Never choose the advertised “best” fold/seed by its held-out test score and present that selection as unbiased. The source-level saving logic and actual retained checkpoint inventory are separate evidence; checkpoint notes explain this distinction.
Scope
This repository is method-only: our method code, retained method models, environment pins, input/output contracts and release audit. It is not a full copy of the historical experiment workspace and does not claim that any baseline run can be replayed here. Associated benchmark results or manuscript materials are evidence, not substitutes for fitted checkpoints or working inference examples. Model-use terms distinguish source-code licensing from dataset-derived checkpoint artifacts.
Original software is covered by the MIT source-code license, with its original author notices retained. Checkpoints follow their source-specific terms and are not globally relicensed as MIT. In particular, consult the GOTOV restrictions and training-derived prototype notes before reusing those models.
Citation
If you use WISP or WristHARBench in your research, please cite the WISP paper below. When using WristHARBench, please also cite the original datasets used in your experiments.
Zipeng Wu, Shiqiao Zhou, Fabian Spill, and James Andrews (2026). WISP: Composable Representations for Wrist-Worn Activity Recognition. Preprint, University of Birmingham. Paper on Pure.
@techreport{wu2026wisp,
title = {{WISP}: Composable Representations for Wrist-Worn Activity Recognition},
author = {Wu, Zipeng and Zhou, Shiqiao and Spill, Fabian and Andrews, James},
year = {2026},
institution = {University of Birmingham},
type = {Preprint},
url = {https://research.birmingham.ac.uk/en/publications/wisp-composable-representations-for-wrist-worn-activity-recogniti/}
}
A standalone BibTeX record is available in CITATION.bib.
- Downloads last month
- -







