pysecs.KalmanSECS

class pysecs.KalmanSECS(secs: SECS, tau: float, prior_std: float | None = None, gate_sigma: float | None = None, smoother: bool = True, epsilon: float = 0.05, mode: str = 'relative')

Kalman filter / smoother for time series of SECS amplitudes.

Parameters:

• secs (SECS) – The elementary current system holding the SEC locations. Its transfer matrices are reused for the state-space model and the fitted amplitudes are stored back into it for predictions.

• tau (float) – Temporal correlation time of the amplitudes, in the same units as the spacing of the times passed to fit() (seconds if times is a datetime64 array). Amplitudes decorrelate as exp(-dt / tau); larger values produce smoother time series.

• prior_std (float, optional) – Stationary (a priori) standard deviation of each SEC amplitude in Amperes. This regularizes the spatial inversion the same way epsilon regularizes the snapshot fit: amplitudes the data do not constrain relax to zero with this uncertainty. When None, it is estimated from the RMS amplitude of an ordinary snapshot fit to the same observations. Default: None

• gate_sigma (float, optional) – Innovation gating threshold in standard deviations. At each time step, observations whose innovations (measurement minus model forecast) exceed gate_sigma standardized deviations have their errors inflated so they cannot dominate the update. This rejects impulsive single-station disturbances while leaving consistent large-scale changes alone. None disables gating. Default: None

• smoother (bool) – Whether to run the backward Rauch-Tung-Striebel smoother after the forward filter pass. The smoother uses future as well as past data at each time step (non-causal) and is recommended for post-processing; disable for a purely causal (real-time) filter. Default: True

• epsilon – Passed to the snapshot SECS.fit() used only to estimate prior_std when it is not given.

• mode – Passed to the snapshot SECS.fit() used only to estimate prior_std when it is not given.

Notes

The forward pass is the classic Kalman filter [1] and the backward pass the Rauch-Tung-Striebel smoother [2]; the temporal regularization approach follows the strategies reviewed by Laundal et al. [3].

The full amplitude covariance is stored for every time step in sec_amps_cov with shape (ntimes, nsec, nsec), which requires 8 * ntimes * nsec**2 bytes of memory (about 0.5 GB for 2000 time steps of 180 SECs). Keep the SEC grid and analysis windows sized accordingly.

References

[1]

Kalman, R. E. “A New Approach to Linear Filtering and Prediction Problems.” J. Basic Eng. 82.1 (1960): 35-45.

[2]

Rauch, H. E., F. Tung, and C. T. Striebel. “Maximum likelihood estimates of linear dynamic systems.” AIAA Journal 3.8 (1965).

[3]

Laundal, K. M., et al. “Next-Generation Data Assimilation Methods for Polar Ionospheric Electrodynamics.” Surveys in Geophysics (2025). doi:10.1007/s10712-025-09918-3

__init__(secs: SECS, tau: float, prior_std: float | None = None, gate_sigma: float | None = None, smoother: bool = True, epsilon: float = 0.05, mode: str = 'relative') → None

Methods

__init__(secs, tau[, prior_std, gate_sigma, ...])
fit(obs_loc, obs_B, times[, obs_std])	Run the filter (and smoother) over a time series of observations.
predict(pred_loc[, J, return_var])	Predict magnetic fields or currents from the estimated amplitudes.
predict_B(pred_loc[, return_var])	Predict magnetic fields; see predict().
predict_J(pred_loc[, return_var])	Predict currents; see predict().