NSSDNResult

class cultivars.experimental.spectral.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)

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).

Every path has r rows: r = n under the filtered alignment, where row t is the emission that reconstructs endog[t] from the state after endog[t]; r = n - 1 under the predicted alignment, where row i is the emission that predicts endog[i + 1] from the state after endog[i]. 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:]).

Variables:

• endog – The full observed series.

• time – The time grid.

• exog – The covariates used, or None.

• k – Number of components.

• state_dim – Latent dimension.

• alignment – "filtered" or "predicted".

• transition – Transition kind.

• ordered_frequency – Whether frequencies are strictly increasing in k.

• gating – Whether a gate head was fitted.

• objective – Prediction loss.

• scaling – Scaling choice.

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

• emission – (r,) the synthesized series, trend + components.sum(1).

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

• resid – endog[1:] - fittedvalues.

• llf – Concentrated Gaussian log-likelihood of resid.

• nobs – Effective sample size, n - 1.

• n_params – Trainable parameter count.

• sigma2 – Residual variance.

• 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 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.

• 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.

See also

• NSSDN – the specification that produces this.

• SpectralState – the measure-valued reading of the decomposition.

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.
bic	Bayesian information criterion.
components	(r, k) contributions w_k g_{t,k} A_{t,k} sin(theta_{t,k} + phi_{t,k}).
effective_amplitude	(r, k) the amplitude of each contribution, |w_k| g_{t,k} A_{t,k}.
hqic	Hannan-Quinn information criterion.
information_criteria	AIC, BIC, and HQIC from llf, nobs, n_params.
observed	(r,) the slice of endog the path rows align with.
oscillation	(r,) the oscillatory part of the emission, emission - trend.
period	(r, k) instantaneous period 2 pi / omega 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,) observed - emission; a same-step error under the filtered alignment.

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.