SpectralState#

class ns_sdn.spectral_state.SpectralState(*, time, frequency, weight, centroid, dispersion, entropy, effective_count, participation_ratio, velocity, velocity_frequency, velocity_mass, active, contribution_correlation, disentanglement_score, active_threshold)[source]#

The spectral-state coordinates of a fitted decomposition.

Rows follow the result’s path rows (\(r = n\) under the filtered alignment, \(n - 1\) under the predicted one). Velocities have one fewer row and sit between consecutive rows: velocity[i] is the distance from row \(i\) to row \(i + 1\) divided by the time between them.

The velocity split is two counterfactual distances rather than an additive decomposition,

\[v^{\omega}_t = \frac{1}{\Delta t_t}\, W_1\!\Bigl(\sum_k w_{t-1,k}\,\delta_{\omega_{t,k}},\; \mu_{t-1}\Bigr), \qquad v^{m}_t = \frac{1}{\Delta t_t}\, W_1\!\Bigl(\sum_k w_{t,k}\,\delta_{\omega_{t-1,k}},\; \mu_{t-1}\Bigr),\]

so \(v^{\omega}_t\) is what the measure would have moved had only the frequencies changed and \(v^{m}_t\) had only the weights changed. They need not sum to \(v_t\); read them as attributions.

The disentanglement score is formed from the correlation matrix \(\rho\) of the per-component contributions \(c_{t,k} = w_k g_{t,k} A_{t,k}\sin(\theta_{t,k} + \phi_{t,k})\) over the rows,

\[D = 1 - \frac{\sum_{j \neq k} \rho_{jk}^2}{\sum_{j,k} \rho_{jk}^2} \in [0, 1],\]

which is one when the contributions are mutually uncorrelated and falls toward zero as components duplicate one another. A component with no variance over the sample has its off-diagonal correlations set to zero.

Variables:

  • time – (nobs,) the times of the rows.

  • frequency – (nobs, k) instantaneous frequencies \(\omega_{t,k}\), radians per unit time.

  • weight – (nobs, k) normalized power \(w_{t,k}\), each row summing to one.

  • centroid – (nobs,) power-weighted mean frequency \(\bar\omega_t\).

  • dispersion – (nobs,) power-weighted frequency standard deviation \(s_t\).

  • entropy – (nobs,) spectral entropy \(H_t = -\sum_k w_{t,k}\log w_{t,k}\), in nats, in \([0, \log K]\).

  • effective_count – (nobs,) \(N_t = \exp H_t\), in \([1, K]\).

  • participation_ratio – (nobs,) inverse participation ratio \(P_t = 1 / \sum_k w_{t,k}^2\), in \([1, K]\).

  • velocity – (nobs - 1,) \(v_t = W_1(\mu_t, \mu_{t-1}) / \Delta t_t\).

  • velocity_frequency – (nobs - 1,) \(v^{\omega}_t\), the part from frequencies moving under frozen weights.

  • velocity_mass – (nobs - 1,) \(v^{m}_t\), the part from weights moving under frozen frequencies.

  • active – (nobs, k) whether \(w_{t,k} \geq\) active_threshold.

  • contribution_correlation – (k, k) correlation \(\rho\) of the component contributions over the rows, unit diagonal.

  • disentanglement_score – \(D\), one minus the off-diagonal share of squared correlation, in \([0, 1]\).

  • active_threshold – The weight floor used for active.

Note

Dispersion is reported in the units of frequency (radians per unit time), effective count and participation ratio in components, and velocity in radians per unit time per unit time. Entropy uses the natural logarithm, so effective_count is exp(entropy) exactly and reaches \(K\) only when the power is spread uniformly.

See also

Example

A single pure sinusoid fitted with one component has a degenerate measure: one atom, zero dispersion, effective count one:

>>> import numpy as np
>>> from ns_sdn.spectral_decomposition import NSSDN, Stage
>>> y = np.sin(0.3 * np.arange(160.0))
>>> res = NSSDN(y, k=1, state_dim=8, schedule=(Stage(1e-2, 20),), seed=0).fit()
>>> state = res.spectral_state()
>>> bool(np.allclose(state.weight, 1.0)), bool(np.allclose(state.dispersion, 0.0))
(True, True)
>>> bool(np.allclose(state.effective_count, 1.0)), state.disentanglement_score
(True, 1.0)

Attributes#

time

frequency

weight

centroid

dispersion

entropy

effective_count

participation_ratio

velocity

velocity_frequency

velocity_mass

active

contribution_correlation

disentanglement_score

active_threshold

k

the number of atoms in every \(\mu_t\).

nobs

the number of path rows the coordinates are computed at.

Methods#

from_result(result, *[, active_threshold])

Compute every coordinate from a fitted result.

summary()

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

to_dict()

The scalar coordinates as aligned arrays of nobs rows.

to_pandas(*[, index])

The scalar coordinates as a pandas.DataFrame.