Penalties#

class ns_sdn.spectral_decomposition.Penalties(amplitude=0.0002, frequency=0.0008, phase_curvature=0.0, trend=0.0, sparsity=0.0, spectrum=0.0)

Bases: object

Weights on the drift and sparsity penalties added to the prediction loss.

Each is a non-negative multiplier \(\lambda\) on a term evaluated on the scaled series over the \(r\) emission rows and \(K\) components; zero removes the term from the graph entirely. With \(\bar A_{t,k} = g_{t,k} A_{t,k}\) the gated amplitude, the terms are

\[\mathcal{P}_A = \frac{1}{(r-1)K}\sum_{t,k} (\bar A_{t,k} - \bar A_{t-1,k})^2, \qquad \mathcal{P}_\omega = \frac{1}{(r-1)K}\sum_{t,k} (\omega_{t,k} - \omega_{t-1,k})^2,\]
\[\mathcal{P}_\theta = \frac{1}{(r-2)K}\sum_{t,k} (\theta_{t,k} - 2\theta_{t-1,k} + \theta_{t-2,k})^2, \qquad \mathcal{P}_B = \frac{1}{r-1}\sum_{t} (B_t - B_{t-1})^2,\]
\[\mathcal{P}_{\mathrm{sp}} = \sum_{k}\Bigl(\frac{1}{r}\sum_t \bar A_{t,k}^2\Bigr)^{1/2}, \qquad \mathcal{P}_{\mathrm{spec}} = \frac{1}{F}\sum_{f} \Bigl(|\mathcal{F}\hat y|_f^2 - |\mathcal{F}y|_f^2\Bigr)^2,\]

and the total loss is the prediction term plus \(\lambda_A \mathcal{P}_A + \lambda_\omega \mathcal{P}_\omega + \lambda_\theta \mathcal{P}_\theta + \lambda_B \mathcal{P}_B + \lambda_{\mathrm{sp}} \mathcal{P}_{\mathrm{sp}} + \lambda_{\mathrm{spec}} \mathcal{P}_{\mathrm{spec}}\). The first two are the TVP-VAR intuition that spectral parameters move slowly and are the only ones the published run used; the defaults are its stage-A weights.

Variables:

  • amplitude – \(\lambda_A\), on the squared first differences of the gated amplitude paths.

  • frequency – \(\lambda_\omega\), on the squared first differences of the instantaneous frequencies.

  • phase_curvature – \(\lambda_\theta\), on the squared second differences of the cumulative phase; a smoothness prior on the frequency itself.

  • trend – \(\lambda_B\), on the squared first differences of the trend, which keeps the trend head from absorbing the oscillation.

  • sparsity – \(\lambda_{\mathrm{sp}}\), the group (\(\ell_{2,1}\)) penalty that silences whole components rather than shrinking all of them.

  • spectrum – \(\lambda_{\mathrm{spec}}\), on the mean squared difference between the rFFT power spectra of the target and the prediction over \(F\) frequency bins.

Raises:

SpecificationError – If any weight is negative, non-finite or not a number.

Example

>>> from ns_sdn.spectral_decomposition import Penalties
>>> Penalties(amplitude=3e-4, frequency=1.5e-3).sparsity
0.0
>>> Penalties()
Penalties(amplitude=0.0002, frequency=0.0008, phase_curvature=0.0, trend=0.0, ...)
>>> Penalties(trend=-1.0)
Traceback (most recent call last):
    ...
ns_sdn.exceptions.SpecificationError: trend must be non-negative and finite; got -1.0.