Preprocessing

preprocessing

Preprocessing utilities for TNKM.

build_lagged_data

build_lagged_data(
    u_input: Array,
    y_output: Array,
    input_lags: tuple[int, ...] | None = None,
    output_lags: tuple[int, ...] | None = None,
) -> tuple[Array, Array]

Construct a supervised learning dataset using lagged input and output.

The returned feature matrix contains selected lagged values of the output signal and optional exogenous input signals, aligned so that every row corresponds to one prediction target. If no lags are provided, the function returns u_input and y_output unchanged.

Parameters:

• u_input (Array) –

  Input signal(s), shape (N,) or (N, m).

• y_output (Array) –

  Output signal, shape (N,).

• input_lags (tuple[int, ...], default: None ) –

  Input lags to include in the feature matrix. Input lags must be non-negative integers.

• output_lags (tuple[int, ...], default: None ) –

  Output lags to include in the feature matrix. Output lags must be strictly positive integers.

Returns:

• X ( Array ) –

  Feature matrix of shape (N - L, n_features), where L = max(max(input_lags), max(output_lags)).

• y ( Array ) –

  Target vector of shape (N - L,).

Notes

This function constructs a lagged regression dataset for time-series prediction. The construction is causal: each feature vector only depends on past values and never uses future information.

For each valid time index t >= L, the feature vector X[t] is constructed from:

• past output values y[t - lag]
• past input values u[t - lag]

The corresponding target is y[t].

Here L = max(max(input_lags), max(output_lags)), which defines the effective history length of the model.

Raises:

• ValueError –

  If input and output signals have different lengths, y_output is not a 1D array, u_input is not 1D or 2D, an input lag is negative, or an output lag is not strictly positive.

• RuntimeError –

  If the constructed features and target lengths do not match.

Examples:

>>> import jax.numpy as jnp
>>> from tnkm.preprocessing import build_lagged_data
>>> u, y = jnp.arange(5), jnp.arange(5) + 10
>>> build_lagged_data(u, y, input_lags=(0, 1), output_lags=(1, 2))
(Array([[11, 10,  2,  1],
        [12, 11,  3,  2],
        [13, 12,  4,  3]], dtype=int32),
 Array([12, 13, 14], dtype=int32))

build_lagged_feature

build_lagged_feature(
    u_input: Array,
    y_output: Array,
    input_lags: tuple[int, ...] | None = None,
    output_lags: tuple[int, ...] | None = None,
) -> Array

Construct a single lagged feature vector from input and output history.

This function is used for recursive prediction or simulation, where a single feature vector is built from the most recent available samples.

The feature vector is constructed using lagged values of:

• the output signal (autoregressive terms)
• the input signal (exogenous terms)

Output lags are placed before input lags in the final feature vector.

Lag convention:

• lag 0 corresponds to the most recent value
• lag 1 corresponds to the previous time step, etc.

Output lag 0 is disallowed to prevent target leakage.

Parameters:

• u_input (Array) –

  Input history of shape (N,) or (N, m).

• y_output (Array) –

  Output history of shape (N,).

• input_lags (tuple[int, ...], default: None ) –

  Input lags to include in the feature vector.

• output_lags (tuple[int, ...], default: None ) –

  Output lags to include in the feature vector.

Returns:

• Array –

  Feature vector of shape (1, n_features).

Notes

This function does not construct a dataset. It produces a single feature vector intended for one-step prediction in recursive models.

Raises:

• ValueError –

  If neither input_lags nor output_lags is provided, if an input lag is negative, or if an output lag is not strictly positive.

Examples:

>>> import jax.numpy as jnp
>>> from tnkm.preprocessing import build_lagged_feature
>>> u, y = jnp.arange(5), jnp.arange(5) + 10
>>> build_lagged_feature(u, y, input_lags=(0, 1), output_lags=(1, 2))
Array([[13, 12,  4,  3]], dtype=int32)