Smoothers

Bases: ABC

Abstract base class for all smoothers.

Mixin implementing the delayed-output queue used by fixed-lag smoothers.

Subclasses should call :meth:_initialize_delayed_state_outputs during initialization. The mixin also initializes lazily, which keeps it usable in lightweight test doubles and with classes restored through __new__.

The public convention is intentionally simple: ready outputs are returned as (step_index, state) tuples. The state object can be a backend array, NumPy array, dataclass, tracker state, or any other payload selected by the concrete smoother.

Bases: FixedLagMEMQKFSmoother

Full fixed-interval RTS smoother for MEMQKFTracker posterior sequences.

Bases: AbstractSmoother

Fixed-lag RTS smoother for MEMQKFTracker posterior sequences.

The kinematic state is smoothed with the standard finite-window RTS recursion. The MEM-QKF shape state [orientation, semi_axis_1, semi_axis_2] can either be smoothed with a separate RTS recursion or be passed through unchanged. Orientation residuals are treated as axial, pi-periodic ellipse-orientation differences.

Bases: FixedLagMEMQKFSmoother

Full-interval MEM-QKF smoother with conditional alternating passes.

The pass order is forward-filtered input, backward RTS kinematics, forward MEM-QKF shape updates conditioned on the smoothed kinematic centers, and a final backward RTS pass for orientation and semi-axis lengths. Setting n_iterations > 1 alternates this with kinematic re-filtering conditioned on the improved shape trajectory before smoothing kinematics and shape again.

If no initial shape prior is supplied, the first scan's original filtered shape posterior is kept as the conditional forward pass initial state to avoid double-counting the first measurement set. Supplying initial_shape_state and initial_shape_covariance lets the smoother reprocess every scan. Kinematic re-filtering follows the same convention unless initial_kinematic_state and initial_kinematic_covariance are supplied to :meth:smooth.

Smoother gains for one MEM-QKF backward recursion step.

Detached snapshot of a :class:MEMQKFTracker state.

Detached snapshot of a factorized GIW random-matrix tracker state.

Bases: AbstractSmoother

Fixed-lag smoother for factorized GIW random-matrix tracker states.

This class applies the factorized Gaussian inverse-Wishart backward recursion of Granstrom and Bramstang, IEEE TSP 2019, Table VII. Unlike :class:FixedLagRandomMatrixSmoother, it keeps the inverse-Wishart parameters v and V explicit and therefore implements the paper's finite-transition-dof correction terms directly.

Bases: AbstractSmoother

Fixed-lag smoother for RandomMatrixTracker posterior sequences.

The kinematic state is smoothed with a finite-window RTS recursion. The default random-matrix extent smoother follows the constant-extent-dynamics factorized GIW backward recursion of Granstrom and Bramstang, "Bayesian Smoothing for the Extended Object Random Matrix Model", IEEE TSP 2019, Table VII. Since :class:RandomMatrixTrackerState stores only the extent mean and an effective information scalar alpha, the implementation reconstructs the inverse-Wishart natural parameter as V = alpha * X and treats alpha as v - 2d - 2. Set extent_smoothing='information' for the earlier SPD-preserving alpha-weighted average, or extent_smoothing='none' to smooth only the kinematic component. Provide extent_transition_dof to include the paper's finite-transition-dof correction terms; the default omits those corrections.

Detached snapshot of a :class:RandomMatrixTracker state.

Bases: AbstractSmoother

Fixed-lag smoother for VelocityLockedMEMQKFTracker posterior sequences.

Kinematics are smoothed by a finite-window RTS recursion. The MEM-QKF shape state can either be passed through unchanged or smoothed by a separate RTS recursion in [orientation, semi_axis_1, semi_axis_2] space. Every output state is then projected back to the decoupled MEM-QKF covariance convention, and moving states are relocked to the smoothed kinematic velocity.

Smoother gains for one VL-MEM-QKF backward recursion step.

Detached snapshot of a :class:VelocityLockedMEMQKFTracker state.

Bases: AbstractSmoother

Fixed-interval Rao-Blackwellized FFBSi smoother for MEM-RBPF records.

The MEM-RBPF representation consists of one global kinematic Gaussian and a weighted orientation-particle approximation with conditional Gaussian semi-axis states. This smoother runs RTS smoothing for the global kinematic Gaussian and backward-simulates orientation/semi-axis trajectories.

Weighted filtering approximation at one MEM-RBPF measurement time.

Output of :class:MEMRBPFFFBSiSmoother.

Bases: AbstractSmoother

Rauch--Tung--Striebel smoother for linear Gaussian models.

This class intentionally does not depend on pyrecest.filters.KalmanFilter. The current filter classes do not retain the full forward-pass history that an RTS smoother requires, so this implementation provides its own forward pass for sequences of linear Gaussian models.

The accepted model inputs can each either be a single matrix/vector reused for the whole sequence or a sequence with one entry per time step.

Parameters

initial_state Initial prior state as GaussianDistribution or (mean, covariance). measurements Sequence of measurements. A one-dimensional array is interpreted as a sequence of scalar measurements. For vector measurements, pass a list/tuple of one-dimensional arrays or a two-dimensional array of shape (T, dim_z). measurement_matrices Measurement matrix H or sequence H_t. Defaults to identity. meas_noise_covariances Measurement noise covariance R or sequence R_t. system_matrices Transition matrix F or sequence F_t used between consecutive time steps. Defaults to identity. sys_noise_covariances Process noise covariance Q or sequence Q_t. Defaults to zero. sys_inputs Optional control/input vector u or sequence u_t added in the prediction step. Defaults to zero.

Configuration for :func:smooth_records.

Parameters

method: "rts" runs a full Rauch--Tung--Striebel backward pass. "fixed-lag" applies the same backward recursion only over future records within lag seconds. "none" returns copied records. lag: Finite nonnegative fixed-lag horizon in seconds. Required for "fixed-lag". time_key, state_key, covariance_key: Keys used to extract timestamp, filtered state, and filtered covariance. output_state_key, output_covariance_key: Keys used for the smoothed posterior in returned records. filtered_state_key, filtered_covariance_key: Keys used to preserve the original filtered posterior in returned records. metadata: Extra key/value pairs appended to every returned record.

Bases: AbstractSmoother

Smooth state estimates by replacing each entry with a local manifold mean.

The smoother extracts a representative point from each input state. For PyRecEst distributions this is state.mean(); raw arrays are used directly. Each sliding window is then represented as a Dirac distribution on the same manifold, and the Dirac distribution's mean() defines the smoothed value.

Parameters

window_size Number of sequence entries considered for each smoothed state. Edge windows are truncated to the available samples. dirac_distribution_factory Optional callable factory(points, weights) used to construct the window Dirac distribution. This is useful for raw samples on non-linear manifolds. If omitted, the smoother infers a factory from distribution inputs and falls back to a Euclidean Dirac distribution for raw arrays. window_weights Optional non-negative weights with length window_size. Truncated edge windows use the corresponding weight slice and are renormalized by the Dirac distribution. alignment "center" uses past and future estimates around each state, "trailing" uses the current and previous estimates, and "leading" uses the current and following estimates.

Bases: AbstractSmoother

Smooth SO(3) rotation sequences with local weighted chordal means.

Rotations are represented as 3-by-3 rotation matrices. The chordal mean is computed by averaging rotation matrices in the ambient Euclidean space and projecting the result back onto SO(3) with the orthogonal Procrustes solution.

Parameters

window_size Number of neighboring rotations used per local mean. The window is centered as far as possible around each time index and clipped at the sequence boundaries. kernel_weights Optional nonnegative weights for positions inside the local window. If provided, its length must match window_size.

Bases: AbstractSmoother

Smooth SO(3) sequences with local tangent-space polynomial fits.

This smoother is a manifold-valued Savitzky-Golay-style baseline. For each time index, visible rotations in a centered local window are mapped to the tangent space of the nearest visible rotation. A weighted local polynomial is fitted against time offsets, the intercept is evaluated at the current time, and the result is mapped back to SO(3).

Rotations are represented as 3-by-3 rotation matrices. The optional mask marks reliable observations; masked samples are skipped rather than treated as identity rotations. smooth_product applies the same per-component smoother to product states with shape (n, k, 3, 3).

Bases: AbstractSmoother

Unscented fixed-interval smoother for nonlinear Gaussian state-space models.

This implements the unscented Rauch--Tung--Striebel (URTS) smoother for Euclidean state spaces. It mirrors the current :class:UnscentedKalmanFilter scope in PyRecEst and therefore only supports the NumPy backend.

The smoother provides a complete forward pass (filter) and the backward pass (smooth). For the nonlinear case the smoother gain depends on the predicted cross-covariance between x_t and x_{t+1}, so the forward pass stores those cross-covariances explicitly.

Parameters

points Optional sigma-point object compatible with MerweScaledSigmaPoints. If omitted, standard Merwe scaled sigma points are used. alpha, beta, kappa Default sigma-point parameters used when points is omitted.