NSSDNResult#

class ns_sdn.spectral_decomposition.NSSDNResult(*, endog, time, exog, k, state_dim, alignment, transition, ordered_frequency, gating, objective, scaling, scale, emission, fittedvalues, resid, llf, nobs, n_params, sigma2, trend, amplitude_raw, amplitude, frequency, phase, phase_offset, gate, state, mix, history, predictor)[source]#

A fitted spectral decomposition network.

The complete decomposition the network emitted over the sample, the one-step conditional fit derived from it, the concentrated Gaussian likelihood of the one-step residuals, and the trained network as a callable predictor. Composes rendering (summary, which is what a bare result prints), frame interop (to_pandas, to_dict with every path as a column) and criterion-named comparison (information_criteria, compare).

Rows and alignment. Every path has \(r\) rows. Under the filtered alignment \(r = n\), and row \(t\) is the emission that reconstructs \(y_t\) from the state after \(y_t\),

\[\hat y_t = \hat y\bigl(h_t\bigr), \qquad h_t = F_\psi(h_{t-1}, y_t), \qquad t = 0, \ldots, n - 1.\]

Under the predicted alignment \(r = n - 1\), and row \(i\) is the emission that predicts \(y_{i+1}\) from the state after \(y_i\),

\[\hat y_{i+1} = \hat y\bigl(h_{i}\bigr), \qquad h_i = F_\psi(h_{i-1}, y_i), \qquad i = 0, \ldots, n - 2.\]

observed is the slice of endog the rows align with. fittedvalues always has \(n - 1\) rows aligned with endog[1:] and is the one-step conditional prediction of each observation: the emission rows under the predicted alignment, the emissions through \(n - 2\) under the filtered one (the paper’s yhat[split - 1 : -1] against y[split:]).

Likelihood. With \(e_t = y_t - \hat y_{t \mid t-1}\) the one-step residuals over the effective sample of \(m = n - 1\) observations, the reported likelihood is the Gaussian likelihood concentrated at the residual variance,

\[\hat\sigma^2 = \frac{1}{m}\sum_{t=1}^{n-1} e_t^2, \qquad \ell = -\frac{m}{2}\bigl(\log 2\pi + \log \hat\sigma^2 + 1\bigr),\]

which is what the information criteria are formed from.

Variables:

  • endog – (n,) the full observed series on its original scale.

  • time – (n,) the time grid, the integers unless one was given.

  • exog – (n, p) the covariates used, or None.

  • k – Number of components \(K\).

  • state_dim – Latent dimension \(d\).

  • alignment – "filtered" or "predicted".

  • transition – Transition kind, "gru" or "timeaware".

  • ordered_frequency – Whether frequencies are strictly increasing in \(k\) at every step.

  • gating – Whether a gate head was fitted; when not, gate is ones.

  • objective – Prediction loss, "mse" or "huber".

  • scaling – Scaling choice, "minmax" or "none".

  • scale – The affine map between training units and the original scale.

  • emission – (r,) the synthesized series \(\hat y_t\), equal to trend + components.sum(axis=1).

  • fittedvalues – (n - 1,) one-step conditional predictions of endog[1:].

  • resid – (n - 1,) endog[1:] - fittedvalues.

  • llf – Concentrated Gaussian log-likelihood \(\ell\) of resid.

  • nobs – Effective sample size \(m = n - 1\).

  • n_params – Trainable parameter count of the network.

  • sigma2 – Residual variance \(\hat\sigma^2\).

  • trend – (r,) trend head \(B_t\) (Fig. 3).

  • amplitude_raw – (r, k) softplus amplitude \(A_{t,k}\) before the gate.

  • amplitude – (r, k) gated amplitude \(g_{t,k} A_{t,k}\) (Fig. 4).

  • frequency – (r, k) instantaneous angular frequency \(\omega_{t,k}\), radians per unit of time (Fig. 5).

  • phase – (r, k) cumulative phase \(\theta_{t,k}\).

  • phase_offset – (r, k) phase offset \(\phi_{t,k}\).

  • gate – (r, k) gate \(g_{t,k} \in (0, 1)\) (Fig. 6); ones when gating is off.

  • state – (r, state_dim) latent state \(h_t\).

  • mix – (k,) learned mixing weights \(w_k\).

  • history – Training losses by stage and step, each a record with the total and its unweighted parts.

  • predictor – The trained network behind a numpy interface.

Note

Under the filtered alignment the emission at \(t\) has seen \(y_t\), so emission is a reconstruction and its error is not a forecast error; fittedvalues are the published one-step protocol and should be read against a random walk before being read as skill. llf is a concentrated Gaussian likelihood at a penalized fit and n_params the nominal weight count, which overstates the effective freedom of a weight-decayed network, so criteria compare \(K\) within one configuration only. Without ordered_frequency the components are identified only up to permutation: a refit with another seed may return the same decomposition with its columns reordered.

Warning

Amplitude-type paths (amplitude_raw, amplitude, components) are returned in the units of endog by scaling the training-unit paths by the slope of scale alone; the trend and emission also receive the offset. Phase, frequency, gate and state carry no units and are the same on both scales.

See also

Example

>>> import numpy as np
>>> y = np.sin(0.2 * np.arange(150.0)) + 0.01 * np.arange(150.0)
>>> res = NSSDN(y, k=2, state_dim=8, schedule=(Stage(1e-2, 25),), seed=0).fit()
>>> res.alignment, res.observed.shape, res.resid.shape
('filtered', (150,), (149,))
>>> bool(np.allclose(res.resid, res.endog[1:] - res.fittedvalues))
True
>>> bool(np.all((res.gate >= 0.0) & (res.gate <= 1.0)))
True

Attributes#

endog

time

exog

k

state_dim

alignment

transition

ordered_frequency

gating

objective

scaling

scale

emission

fittedvalues

resid

llf

nobs

n_params

sigma2

trend

amplitude_raw

amplitude

frequency

phase

phase_offset

gate

state

mix

history

predictor

aic

Akaike information criterion, \(-2\ell + 2p\).

bic

Bayesian information criterion, \(-2\ell + p\log m\).

components

(r, k) the contribution of each component to the emission.

effective_amplitude

(r, k) the amplitude of each contribution to the emission.

hqic

Hannan-Quinn information criterion, \(-2\ell + 2p\log\log m\).

information_criteria

AIC, BIC, and HQIC from llf, nobs, n_params, as one record.

observed

(r,) the slice of endog the path rows align with.

oscillation

(r,) the oscillatory part of the emission, \(\hat y_t - B_t\).

period

(r, k) instantaneous period \(2\pi / \omega_{t,k}\) in time units.

power_share

(k,) each component's share of mean contribution power over the sample.

r_squared

One minus the one-step residual share of variance over the effective sample.

reconstruction_resid

(r,) the same-row error observed - emission.

Methods#

compare(*others[, criterion])

Rank this result and others by one criterion, best first.

decompose([endog, exog, time, scaled])

Every path of the decomposition, for the fitted sample or a new one.

forecast([steps, exog, time])

Recursive multi-step forecast from the end of the fitted sample.

predict(endog, *[, exog, time])

One-step conditional predictions over a sample.

spectral_state(*[, active_threshold])

The decomposition read as a time-local spectral measure.

summary()

The estimation summary, renderable as text, HTML, or a dataframe.

to_dict()

The aligned outputs as plain arrays.

to_pandas(*[, index])

The aligned outputs as a pandas.DataFrame, one column per series.