pycsa.core.priors

Pluggable Tikhonov priors for the linear-fit step.

The default fit in pycsa.core.lin_reg.do() adds a scalar lmbda * trace(MᵀM)/N to the diagonal of the normal-equations matrix. That branch is preserved unchanged — it is what every existing call site hits and what the reproducibility fixtures pin down.

This module introduces a Prior protocol so spike scripts can experiment with structured (per-mode) regularization without touching the default code path. A prior is a callable that returns the diagonal vector to add to diag(E_tilda_lm).

IsotropicPrior is a parallel implementation of the existing scalar-trace branch. It is NOT routed through by default; passing prior=IsotropicPrior() to lin_reg.do should produce the same numerical result as prior=None, within floating-point re-association noise (the parallel path computes the same scalar but the assignment sequence is different). Unit-tested for parity on a synthetic E_tilda_lm.

SpectralPrior is the alternative under test in the spike: a per-mode prior whose diagonal grows with wavenumber norm.

Classes

IsotropicPrior()

Parallel implementation of the current scalar-trace diagonal.

Prior(*args, **kwargs)

Callable that returns the Tikhonov diagonal to add to diag(MᵀM).

SpectralPrior(alpha[, eps])

Per-mode prior with diagonal growing with wavenumber norm.
class pycsa.core.priors.Prior(*args, **kwargs)

Callable that returns the Tikhonov diagonal to add to diag(MᵀM).

Parameters:

  • fobj – The pycsa.core.fourier.f_trans instance used to build the design matrix. Carries the mode-index attributes (m_i, m_j, optional k_idx/l_idx) that structured priors need to compute per-mode weights.

  • E_tilda_lm – The dense normal-equations matrix (MᵀM), shape (N, N). Priors may use trace(E) for scale normalization.

  • lmbda – The overall regularization scale (the same scalar that the existing lin_reg.do accepts).

Returns:

diag – Non-negative diagonal to be added to diag(E_tilda_lm).

Return type:

np.ndarray, shape (N,)

__init__(*args, **kwargs)
class pycsa.core.priors.IsotropicPrior

Parallel implementation of the current scalar-trace diagonal.

Returns lmbda * trace(E) / N * ones(N). Equivalent to the inline scalar-trace branch in lin_reg.do (the dense and sparse prior is None paths), within reassociation noise — the inline branch computes one scalar and broadcasts; this returns an array. Provided so spike scripts can compose it as an explicit baseline alongside other priors.

Not the default path. lin_reg.do(prior=None) continues to use the inline branch and produces bit-identical fixture output.

__init__() → None
class pycsa.core.priors.SpectralPrior(alpha: float, eps: float = 0.001)

Per-mode prior with diagonal growing with wavenumber norm.

For each mode m with wavenumber pair (k_m, l_m):

\[\lambda_m = \lambda \cdot \frac{\mathrm{tr}(E)}{N} \cdot \left( \frac{\Vert k_m \Vert}{\Vert k \Vert_{\max}} + \varepsilon \right)^\alpha\]

Equivalent to a zero-mean Gaussian prior on the coefficients with variance proportional to ‖k_m‖^(-alpha). Implies an assumed topographic power spectrum behaving like ‖k‖^(-alpha), so alpha should be calibrated from the input fixture’s empirical power-law slope rather than picked from generic physics constants. alpha=0 recovers the isotropic baseline (modulo the + eps floor).

Parameters:

  • alpha (float) – Spectral decay exponent. alpha=0 reduces to isotropic (constant diagonal at (1 + eps)^0 == 1).

  • eps (float) – Small additive floor that keeps the DC mode (‖k‖ = 0) from receiving zero regularization. Documented knob, not a free hyperparameter.

alpha: float
eps: float = 0.001
__init__(alpha: float, eps: float = 0.001) → None