docs/METHODS.md

# WISP names and method roles

WISP means **Wrist-Informed Space of Predictive Representations**. The public method names follow the current manuscript. Historical source code may use `tsevolve` package paths or fixed-family identifiers; those identifiers are provenance, not additional public methods. The series comprises seven fixed core models and four validation-selection/search variants. Multiple dataset/fold/seed checkpoints are fitted instances, not additional model types.

| Public name | Stable release ID | Role |
| --- | --- | --- |
| WISP-SS | `wisp_ss` | Fixed statistics/spectral/symbolic representation and classifier. |
| WISP-RC | `wisp_rc` | Fixed random-convolution representation and classifier. |
| WISP-SO | `wisp_so` | Fixed symbolic/interval representation and classifier. |
| WISP-CSE | `wisp_cse` | Score-level ensemble of statistics, random-convolution and symbolic members. |
| WISP-GIS | `wisp_gis` | Fixed geometry/interval/local-shape representation and classifier. |
| WISP-CIS | `wisp_cis` | Fixed convolution, interval and within-window state representation and classifier. |
| WISP-ESE | `wisp_ese` | Weighted score-level ensemble of fixed CIS, GIS and symbolic members. |
| WISP-Select5 | `wisp_select5` | Validation selection among the five fixed base families. |
| WISP-Select7 | `wisp_select7` | Validation selection among all seven fixed families, including two ensembles. |
| WISP-Random | `wisp_random` | Random search over candidate programs, followed by validation selection and final fitting. |
| WISP-Evolution | `wisp_evolution` | Evolutionary search over candidate programs, followed by validation selection and final fitting. |

Within-window state features and across-window HMM sequence decoding are different operations. Fixed-family paper configurations use the optional HMM decoder. Random/Evolution checkpoints carry their selected candidate's actual decoder setting; do not infer it from the search method name.

The fitted object produced by Select5/Select7 is the selected family's model, while a Random/Evolution fitted object is the selected candidate program. Keeping only that fitted object loses how it was selected, so publish the selector/candidate record alongside it. The model's semantic identity is established by its release metadata, not merely by its Python class name or filename.

Implementation coverage, retained checkpoint coverage and verified inference coverage are separate facts. `wisp list` describes method scope. The model inventory and release audit describe retained files and validation. No baseline family or baseline checkpoint is part of this method-only release.

## Validation-only selectors

`wisp select-fit` implements Select5 and Select7 using separate training and validation NPZ inputs. Select5 considers SS, RC, SO, GIS and CIS. Select7 additionally considers CSE and ESE. The participant/sequence groups must be disjoint between the two inputs, with compatible shape, chronological metadata and global class vocabulary.

Each candidate is fitted on training only and scored on validation. Selection uses, in order, higher macro-F1, higher full-vocabulary worst-class F1, smaller serialized model size using the preserved `estimate_pickle_size_mb` helper with Python's default pickle protocol (protocol 4 in the pinned Python 3.12 runtime), then the canonical order SS, RC, SO, CSE, GIS, CIS, ESE. A fresh winning model is fitted on train+validation once. Test data are not accepted or used by this command.

The selector's size measurement and the new fitted output's serialization protocol are separate: newly saved models use the highest protocol, while the historical size tie-break uses the default protocol. Renaming Python namespaces can itself affect serialized byte counts. The wrapper preserves the helper and ordering, but does not claim byte-identical model sizes or guarantee that an exact size-only tie remains unchanged across renamed namespaces/environments.

With `--execute`, the command saves the fitted output model, `<output_stem>.metadata.json` and `<output_stem>.selection.json`. Without `--execute`, it describes the requested plan only. A newly fitted selector model is a new artifact; it does not fill an original missing paper checkpoint without being labelled as a refit.