spectral_connectivity.minimum_phase_decomposition.minimum_phase_reconstruction_error#

minimum_phase_reconstruction_error(cross_spectral_matrix: ndarray[tuple[int, ...], dtype[complexfloating]], minimum_phase_factor: ndarray[tuple[int, ...], dtype[complexfloating]] | None = None, *, tolerance: float = 1e-08, max_iterations: int = 500) → ndarray[tuple[int, ...], dtype[floating]][source]#

Relative reconstruction error of a Wilson factorization, per sub-spectrum.

The Wilson iteration’s convergence test only measures the change between successive iterates; a stable iterate does not guarantee G Gᴴ ≈ S. When the cross-spectrum is under-resolved in frequency (its autocovariance has not decayed within the window, so the periodic factorization aliases), the iteration can “converge” to a factor that reconstructs S poorly, silently biasing every directed-connectivity measure built on it (spectral Granger, DTF, PDC). This is an opt-in diagnostic: it returns max |G Gᴴ - S| / max |S| for each sub-spectrum – the entrywise maximum absolute residual over every frequency and matrix entry, relative to the entrywise maximum magnitude of S – so callers can check factorization quality explicitly.

cross_spectral_matrix must be a full two-sided spectrum in standard FFT order, as required by the factorization itself. This module-level function cannot verify that from the array alone (a one-sided spectrum has the same shape); the Connectivity.minimum_phase_reconstruction_error method enforces it from the transform’s declared sidedness.

A relative error near machine precision indicates a faithful factorization; values of a few percent are typical for finite-resolution estimated spectra; tens of percent or more indicate the spectrum is too coarsely resolved to trust the directed measures – use a longer FFT (larger n_fft_samples / n_time_samples_per_window). The error is deliberately not raised as a warning during factorization: it does not cleanly separate an under-resolved spectrum from a merely short or noisy one, so an always-on threshold would either cry wolf on ordinary short-window analyses or miss real problems.

Parameters:

  • cross_spectral_matrix (NDArray[complexfloating],) – shape (…, n_fft_samples, n_signals, n_signals) The two-sided cross-spectral matrix (standard FFT order, positive and negative frequencies) that was (or will be) factored.

  • minimum_phase_factor (NDArray[complexfloating], optional) – A precomputed factor from minimum_phase_decomposition(). If omitted, the factorization is computed here with tolerance / max_iterations.

  • tolerance – Passed to minimum_phase_decomposition() when it must be computed.

  • max_iterations – Passed to minimum_phase_decomposition() when it must be computed.

Returns:

relative_error – Entrywise max-abs relative reconstruction error per sub-spectrum (the leading batch dimensions cross_spectral_matrix.shape[:-3]). NaN where the factor is non-finite (the factorization did not converge).

Return type:

NDArray[floating], shape (…,)