| # Input contract |
|
|
| The release interface consumes NumPy NPZ files containing already windowed time series. It does not infer the original wearable's sampling rate, convert raw sensor units, resample data, choose a wrist or map activity labels automatically. Use the exact preprocessing recorded for the checkpoint. |
|
|
| ## Arrays |
|
|
| | Field | Meaning | |
| | --- | --- | |
| | `X` | Finite numeric array shaped `(n_windows, n_timepoints, n_channels)`, in the checkpoint's channel order. A two-dimensional single-channel array must be exported explicitly as `(n_windows, n_timepoints, 1)`. | |
| | `y` | Integer encoded labels, shaped `(n_windows,)`; needed for fitting and evaluation, not ordinary inference. | |
| | `label_names` | Ordered global class vocabulary as a one-dimensional Unicode/string array; encoded label `k` refers to `label_names[k]`. | |
| | `subject` | Per-window sequence/group identifiers. Required for HMM-decoded inference. For frozen paper data, preserve the original subject/group IDs. | |
| | `time_index` | Per-window chronological positions within groups. Required for HMM-decoded inference. | |
| | `sampling_rate_hz` | Optional numeric rate metadata. Recording a value does not resample `X` or automatically establish rate compatibility with the checkpoint. | |
|
|
| Use non-object arrays: the release loader reads NPZ with `allow_pickle=False`. Do not store Python dictionaries, object arrays or pickled pandas objects in the NPZ. Represent ancillary dataset/preprocessing information in checkpoint JSON metadata instead. |
|
|
| Labels must use a common global integer axis `0, ..., K-1` across training, validation and test. A class can be absent from one partition without being removed from the axis. Do not independently re-encode each split, sort the vocabulary differently, or recover a new label map from the predicted classes. For fitting without `label_names`, provide the global class count through the documented CLI option; evaluation still needs the checkpoint's class axis. |
|
|
| Search accepts separate training, validation and test NPZ files. All three must preserve the shared global vocabulary and include `subject` and `time_index`, because a candidate can use sequence decoding. Paper comparisons require participant-disjoint splits; copying test participants into the train or validation input is not permitted by the frozen contract. |
|
|
| ## Preprocessing identity |
|
|
| The checkpoint metadata or its original effective dataset manifest must record: |
|
|
| - Dataset view and selected wearable/device/sensor channels, including axis order. |
| - Sampling rate, window length, stride/overlap, sample ordering and any padding/resampling rule. |
| - Units and upstream preprocessing, including missing-value handling and label/window assignment. |
| - Ordered label names and any mapping from original source labels. |
| - Participant/session boundaries and the chronological indexing used by sequence decoding. |
| - Frozen split identity and the training-data scope for this fitted model. |
|
|
| Matching only the number of channels is insufficient: swapping axes, gyroscope/accelerometer order or units can change predictions without causing a shape error. Fixed random intervals and local-shape representations can also depend on window length. |
|
|
| Optional JSON metadata supplied through `--metadata` can record `input_shape` as `[n_timepoints, n_channels]` and `label_names` as the ordered class vocabulary. These fields are used for shape/class checks. Extra descriptive fields such as channel names, physical units and sampling rate are important provenance but are not automatically checked or converted by the current inference wrapper; the caller is responsible for matching them. |
|
|
| The implementation performs its own configured per-window normalization and feature construction. Do not add new global standardization before inference unless that transformation was part of the checkpoint's original preprocessing. Some fitted classifiers additionally contain a learned feature scaler inside the serialized model; that scaler must not be refitted on the evaluation data. |
|
|
| ## Sequence decoding |
|
|
| For HMM-enabled models, the checkpoint contains a fitted transition matrix and class prior, but the caller must provide correct groups and chronological order. The decoder operates separately for each group and orders its windows by `time_index`. For exact paper evaluation, keep the frozen grouping/indexing unchanged. |
|
|
| For new recordings, group identifiers should distinguish independent recording sequences. Do not connect different participants, unrelated sessions or discontinuous recordings into one artificial sequence. Do not shuffle windows, batch a chronological sequence into unrelated chunks or omit metadata and still claim the same HMM prediction protocol. Offline sequence decoding can depend on later windows within a sequence; it is not presented as a causal, streaming recognizer. |
|
|
| A direct/argmax model can be run without sequence metadata where supported by its recorded configuration. Disabling HMM or omitting groups is a protocol change, not an equivalent reproduction of an HMM checkpoint. |
|
|
| ## Example schema |
|
|
| The following illustrates a valid object-free NPZ layout, not a replacement for checkpoint-specific windowing or class metadata: |
|
|
| ```python |
| import numpy as np |
| |
| # X already follows the chosen checkpoint's windowing and channel contract. |
| # Use the same global vocabulary that was used when fitting that model. |
| np.savez_compressed( |
| "input.npz", |
| X=np.asarray(X, dtype=np.float64), |
| y=np.asarray(y, dtype=np.int64), # omit for prediction without labels |
| label_names=np.asarray(label_names, dtype=str), |
| subject=np.asarray(sequence_ids, dtype=str), |
| time_index=np.asarray(window_positions, dtype=np.int64), |
| ) |
| ``` |
|
|
| Generating, preprocessing or validating input data on the cluster belongs on an allocated compute node, not a login node. |
|
|
