smlmlp.registrate_solve_redundant_shift module

smlmlp.registrate_solve_redundant_shift(shiftx, shifty, /, sigma_thresh=3.0, max_outliers=None, *, cuda=False, parallel=False)[source]

Solve absolute channel shifts from redundant pairwise measurements.

This function reconstructs absolute x and y channel shifts from redundant pairwise shift measurements using a two-pass least-squares procedure. A first fit is used to estimate residuals and detect outliers, and a second fit is then computed after removing the detected outlier pairs.

Parameters:

  • shiftx (array-like) – Pairwise shifts along x.

  • shifty (array-like) – Pairwise shifts along y. Must have the same length as shiftx.

  • sigma_thresh (float, optional) – Threshold multiplier applied to the robust residual dispersion for outlier rejection in the second pass.

  • max_outliers (int or None, optional) – Maximum number of outlier pairs to reject. If None, all detected outliers are removed.

  • cuda (bool, optional) – Unused in this function. It is kept for API consistency.

  • parallel (bool, optional) – Unused in this function. It is kept for API consistency.

Returns:

A tuple (abs_shiftx, abs_shifty, info) where:

  • abs_shiftx is the solved absolute shift along x for each channel,

  • abs_shifty is the solved absolute shift along y for each channel,

  • info is a dictionary containing reusable intermediate results.

The dictionary contains the following keys:

'pairs'

List of channel pairs corresponding to the input pairwise shifts.

'mask_keep_first_pass'

Boolean mask of pairs kept in the first pass.

'mask_keep_second_pass'

Boolean mask of pairs kept in the second pass.

'outlier_idx'

Indices of rejected outlier pairs.

'outlier_pairs'

Channel pairs corresponding to the rejected outliers.

'residx_first_pass'

Residuals along x after the first pass.

'residy_first_pass'

Residuals along y after the first pass.

'resid_first_pass'

Euclidean residual norm after the first pass.

'residx_second_pass'

Residuals along x after the second pass.

'residy_second_pass'

Residuals along y after the second pass.

'resid_second_pass'

Euclidean residual norm after the second pass.

'median_resid_first_pass'

Median residual norm after the first pass.

'robust_sigma_first_pass'

Robust residual dispersion estimate after the first pass.

Return type:

tuple

Notes

Channel 0 is used as the reference channel, so its absolute shift is fixed to zero. The remaining channel shifts are solved by least squares.

The robust residual dispersion is estimated from the median absolute deviation:

\[\sigma_\mathrm{robust} = 1.4826 \times \mathrm{MAD}\]

Examples

Solve a simple 3-channel system:

>>> shiftx = [1.0, 2.0, 1.0]
>>> shifty = [0.0, 1.0, 1.0]
>>> abs_shiftx, abs_shifty, info = registrate_solve_redundant(shiftx, shifty)
>>> abs_shiftx.shape[0]
3
>>> abs_shifty.shape[0]
3
>>> len(info["pairs"])
3

Limit the number of rejected outliers:

>>> shiftx = [1.0, 2.0, 10.0]
>>> shifty = [0.0, 1.0, 8.0]
>>> abs_shiftx, abs_shifty, info = registrate_solve_redundant(
...     shiftx,
...     shifty,
...     sigma_thresh=2.0,
...     max_outliers=1,
... )
>>> info["outlier_idx"].ndim
1