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.

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 command is wisp and its release API package is wisp_release. 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.

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. 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

Only NumPy, SciPy, scikit-learn and its runtime dependencies are installed. No PyTorch/CUDA, aeon, Mamba or baseline source download is needed. The recorded software gate passed 55 tests and verified wheel installation/import from outside the source tree using Python 3.12.13. 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.

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.

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.