docs/INPUTS.md

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:

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.