Models

Models#

class NeuralFieldManifold.models.AR[source]#

Bases: object

Classical Autoregressive (AR) model fitted via ordinary least squares.

static acf(sig, nlags=60)[source]#

Compute the normalized autocorrelation function.

Parameters:

  • sig (np.ndarray) – Input signal.

  • nlags (int, optional) – Number of lags to return. Default is 60.

Returns:

ac – Autocorrelation values from lag 0 to nlags, inclusive.

Return type:

np.ndarray

static aic_bic(y, yhat, k)[source]#

Compute AIC and BIC for an AR model.

Parameters:

  • y (np.ndarray) – Observed values.

  • yhat (np.ndarray) – Predicted values.

  • k (int) – Number of estimated parameters (including intercept).

Returns:

  • aic (float) – Akaike Information Criterion.

  • bic (float) – Bayesian Information Criterion.

static fit(X, y)[source]#

Fit AR coefficients via OLS with an intercept term.

Parameters:

  • X (np.ndarray) – Lag matrix of shape (N, p).

  • y (np.ndarray) – Target vector of shape (N,).

Returns:

w – Coefficient vector [c, a1, …, ap] of shape (p + 1,) where c is the intercept.

Return type:

np.ndarray

static hybrid_predict(series, w, p, start_idx, n_steps, refresh_every=1)[source]#

Multi-step ahead prediction with periodic history refresh.

Runs a free-running AR forecast but resets the lag buffer to the true signal every refresh_every steps, blending open-loop and closed-loop prediction.

Parameters:

  • series (np.ndarray) – Full observed time series.

  • w (np.ndarray) – AR coefficient vector [c, a1, …, ap].

  • p (int) – Autoregressive order.

  • start_idx (int) – Index in series at which prediction begins.

  • n_steps (int) – Number of steps to forecast.

  • refresh_every (int, optional) – Re-anchor the lag buffer to the true signal every this many steps. Default is 1 (teacher-forced).

Returns:

preds – Predicted values of shape (n_steps,).

Return type:

np.ndarray

static lag_matrix(x, p)[source]#

Construct the lag (design) matrix and target vector for AR(p).

Parameters:

  • x (np.ndarray) – 1-D time series of length N.

  • p (int) – Autoregressive order.

Returns:

  • X (np.ndarray) – Lag matrix of shape (N - p, p) where column i contains the lag-(i+1) values.

  • y (np.ndarray) – Target vector of shape (N - p,).

static metrics(y_true, y_pred)[source]#

Compute regression metrics between true and predicted signals.

Parameters:

  • y_true (np.ndarray) – Ground-truth values.

  • y_pred (np.ndarray) – Predicted values.

Returns:

  • mse (float) – Mean squared error.

  • mae (float) – Mean absolute error.

  • r (float) – Pearson correlation coefficient.

static predict_from_params(X, w)[source]#

Predict target values from lag matrix and fitted parameters.

Parameters:

  • X (np.ndarray) – Lag matrix of shape (N, p).

  • w (np.ndarray) – Coefficient vector [c, a1, …, ap] of shape (p + 1,).

Returns:

y_hat – Predicted values of shape (N,).

Return type:

np.ndarray

class NeuralFieldManifold.models.TAR[source]#

Bases: object

Threshold AutoRegressive (TAR) model with 2 regimes.

static aic_bic(y, yhat, k)[source]#

Compute the BIC for a single TAR regime.

Parameters:

  • y (np.ndarray) – Observed values.

  • yhat (np.ndarray) – Predicted values.

  • k (int) – Number of estimated parameters.

Returns:

bic – Bayesian Information Criterion.

Return type:

float

static fit(x, p=8, d=1, thresh=0.0, train_frac=0.8)[source]#

Fit a two-regime TAR model to a time series.

Splits the lag matrix into two regimes based on the threshold variable z_t = x_{t-d} and fits separate OLS models for each.

Parameters:

  • x (np.ndarray) – 1-D time series.

  • p (int, optional) – Autoregressive order. Default is 8.

  • d (int, optional) – Delay for the threshold variable. Default is 1.

  • thresh (float, optional) – Threshold value separating the two regimes. Default is 0.0.

  • train_frac (float, optional) – Fraction of samples used for fitting. Default is 0.8.

Returns:

info – Dictionary containing fitted parameters (w1, w2), residuals (r1, r2), BIC values, and bookkeeping metadata needed for simulation.

Return type:

dict

static lag_matrix_with_threshold(x, p, d=1)[source]#

Build lag matrix, target vector, and threshold variable.

Parameters:

  • x (np.ndarray) – 1-D time series of length N.

  • p (int) – Autoregressive order.

  • d (int, optional) – Delay for the threshold variable z_t = x_{t-d}. Default is 1.

Returns:

  • X (np.ndarray) – Lag matrix of shape (N - p, p).

  • y (np.ndarray) – Target vector of shape (N - p,).

  • z (np.ndarray) – Threshold variable of shape (N - p,).

static ols_with_intercept(X, y)[source]#

Fit AR coefficients via OLS with an intercept column.

Parameters:

  • X (np.ndarray) – Lag matrix of shape (N, p).

  • y (np.ndarray) – Target vector of shape (N,).

Returns:

w – Coefficient vector [c, a1, …, ap] of shape (p + 1,).

Return type:

np.ndarray

static predict_from_params(X, w)[source]#

Predict target values from lag matrix and fitted parameters.

Parameters:

  • X (np.ndarray) – Lag matrix of shape (N, p).

  • w (np.ndarray) – Coefficient vector [c, a1, …, ap].

Returns:

y_hat – Predicted values of shape (N,).

Return type:

np.ndarray

static simulate_tar_free_run(info, init_lags, n_steps, seed=0, variance_match_to=None)[source]#

Free-run simulation from a fitted two-regime TAR model.

Generates a synthetic trajectory by recursively applying the regime-specific AR coefficients and bootstrap-resampled residuals.

Parameters:

  • info (dict) – Output of TAR.fit().

  • init_lags (array-like) – Initial lag values [x_{t-1}, …, x_{t-p}].

  • n_steps (int) – Number of time steps to simulate.

  • seed (int, optional) – Random seed. Default is 0.

  • variance_match_to (np.ndarray or None, optional) – If provided, the output is affine-rescaled to match the mean and standard deviation of this reference signal.

Returns:

out – Simulated trajectory of shape (n_steps,).

Return type:

np.ndarray

class NeuralFieldManifold.models.DeepLagEmbed(seq_len=600, n_classes=5, max_ar_order=6, hidden_dim=128)[source]#

Bases: Module

Deep Lag Embedding network for joint AR-order and coefficient estimation.

The architecture has two blocks:

  • P-Block — predicts the AR order class via Gumbel-Softmax, enabling discrete order selection that is differentiable during training.

  • D-Block — conditioned on the input series and the soft order prediction, outputs time-varying AR coefficients that are masked according to the predicted order.

__init__(seq_len=600, n_classes=5, max_ar_order=6, hidden_dim=128)[source]#

Initialise the DeepLagEmbed model.

Parameters:

  • seq_len (int, optional) – Length of each input time series. Default is 600.

  • n_classes (int, optional) – Number of AR-order classes (e.g., 5 for p ∈ {2, 3, 4, 5, 6}). Default is 5.

  • max_ar_order (int, optional) – Maximum AR order, i.e. number of coefficient channels. Default is 6.

  • hidden_dim (int, optional) – Hidden-layer width for both blocks. Default is 128.

forward(x, temperature=1.0)[source]#

Forward pass: predict AR order and time-varying coefficients.

Parameters:

  • x (torch.Tensor) – Input batch of shape (N, seq_len).

  • temperature (float, optional) – Temperature for Gumbel-Softmax sampling. Lower values make the order selection closer to argmax. Default is 1.0.

Returns:

  • coeffs (torch.Tensor) – Predicted time-varying AR coefficients of shape (N, seq_len, max_ar_order), masked by the predicted order.

  • p_logits (torch.Tensor) – Raw logits for the AR-order classifier of shape (N, n_classes).

  • p_hard (torch.Tensor) – Hard (argmax) predicted order class indices of shape (N,).

  • x_hat (torch.Tensor) – Reconstructed signal of shape (N, seq_len) obtained by applying the predicted coefficients to the lagged input.

class NeuralFieldManifold.models.ARMLP(seq_len=600, n_classes=5, max_ar_order=6, hidden_dim=128)[source]#

Bases: Module

Simple MLP baseline for time-varying AR coefficient estimation.

Maps an input sequence directly to seq_len × max_ar_order coefficient values through a three-layer feed-forward network. No AR-order classification is performed.

__init__(seq_len=600, n_classes=5, max_ar_order=6, hidden_dim=128)[source]#

Initialise the AR-MLP model.

Parameters:

  • seq_len (int, optional) – Length of each input time series. Default is 600.

  • n_classes (int, optional) – Number of AR-order classes (unused; kept for API compatibility). Default is 5.

  • max_ar_order (int, optional) – Maximum AR order, i.e. number of coefficient channels. Default is 6.

  • hidden_dim (int, optional) – Hidden-layer width. Default is 128.

forward(x, temperature=1.0)[source]#

Forward pass: predict time-varying AR coefficients.

Parameters:

  • x (torch.Tensor) – Input batch of shape (N, seq_len).

  • temperature (float, optional) – Unused; kept for API compatibility. Default is 1.0.

Returns:

  • coeffs (torch.Tensor) – Predicted AR coefficients of shape (N, seq_len, max_ar_order).

  • p_logits (torch.Tensor) – Zeros of shape (N, n_classes) (no order prediction).

  • p_hard (torch.Tensor) – Zeros of shape (N,) (no order prediction).

  • x_hat (torch.Tensor) – Reconstructed signal of shape (N, seq_len).

class NeuralFieldManifold.models.ARTransformer(seq_len=600, n_classes=5, max_ar_order=6, d_model=64, nhead=4, num_layers=2)[source]#

Bases: Module

Transformer encoder baseline for time-varying AR coefficient estimation.

Projects each scalar time step to a d_model-dimensional embedding, adds learnable positional encodings, passes through a stack of Transformer encoder layers, and projects each position to max_ar_order coefficient values.

__init__(seq_len=600, n_classes=5, max_ar_order=6, d_model=64, nhead=4, num_layers=2)[source]#

Initialise the AR-Transformer model.

Parameters:

  • seq_len (int, optional) – Length of each input time series. Default is 600.

  • n_classes (int, optional) – Number of AR-order classes (unused; kept for API compatibility). Default is 5.

  • max_ar_order (int, optional) – Maximum AR order, i.e. number of coefficient channels. Default is 6.

  • d_model (int, optional) – Transformer hidden dimension. Default is 64.

  • nhead (int, optional) – Number of attention heads. Default is 4.

  • num_layers (int, optional) – Number of Transformer encoder layers. Default is 2.

forward(x, temperature=1.0)[source]#

Forward pass: predict time-varying AR coefficients.

Parameters:

  • x (torch.Tensor) – Input batch of shape (N, seq_len).

  • temperature (float, optional) – Unused; kept for API compatibility. Default is 1.0.

Returns:

  • coeffs (torch.Tensor) – Predicted AR coefficients of shape (N, seq_len, max_ar_order).

  • p_logits (torch.Tensor) – Zeros of shape (N, n_classes) (no order prediction).

  • p_hard (torch.Tensor) – Zeros of shape (N,) (no order prediction).

  • x_hat (torch.Tensor) – Reconstructed signal of shape (N, seq_len).

class NeuralFieldManifold.models.AnalyticalAR(seq_len=600, n_classes=5, max_ar_order=6)[source]#

Bases: Module

Non-learned AR baseline that solves least-squares per sample.

This module has no trainable parameters. For each input sequence it builds the lag matrix, solves the normal equations via torch.linalg.lstsq, and returns fixed (time-invariant) AR coefficients together with the reconstructed signal.

__init__(seq_len=600, n_classes=5, max_ar_order=6)[source]#

Initialise the analytical AR baseline.

Parameters:

  • seq_len (int, optional) – Length of each input time series. Default is 600.

  • n_classes (int, optional) – Number of AR-order classes (kept for API compatibility). Default is 5.

  • max_ar_order (int, optional) – Maximum autoregressive order used for the lag matrix. Default is 6.

forward(x, temperature=1.0)[source]#

Run the analytical AR fit on a batch of sequences.

Parameters:

  • x (torch.Tensor) – Input batch of shape (N, seq_len).

  • temperature (float, optional) – Unused; kept for API compatibility with learned models.

Returns:

  • coeffs (torch.Tensor) – Time-invariant AR coefficients broadcast to shape (N, seq_len, max_ar_order). The first max_ar_order time steps are zeroed out.

  • p_logits (torch.Tensor) – Zeros of shape (N, n_classes) (no order prediction).

  • p_hard (torch.Tensor) – Zeros of shape (N,) (no order prediction).

  • x_hat (torch.Tensor) – Reconstructed signal of shape (N, seq_len).

On this page