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]

Bases: _SummaryMixin, _SeriesMixin, _ComparisonMixin

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

Private methods#

_comparison_label()

The row label compare prints for this result.

_from_fit(fit, model)

Assemble the public result from a raw fit and its specification.

_paths_to_dict(observed, paths, mix)

Lay a pass of the network out as the dictionary decompose returns.

_series()

Observed, emission, trend, and every per-component path as columns.

_summary_table()

Structured summary rendered by every display path.
On this page