smlmlp.locs_individual_splinefit module

smlmlp.locs_individual_splinefit(crops, X0, Y0, /, ch=None, *, optimizer='lm', estimator='mle', distribution='poisson', channels_pixels_nm=1.0, channels_gains=1.0, channels_QE=1.0, cuda=False, parallel=False, channels_psf_3d_xtangents=None, channels_psf_3d_ytangents=None, channels_psf_3d_ztangents=None, channels_psf_3d_spline_coeffs=None)[source]

Fit each crop independently with a 3D spline PSF model.

The function loops through channels, initializes a funclp.Spline3D model per event, runs the selected optimizer/estimator combination, and returns localized coordinates with fitted photometric values.

Parameters:

  • crops (sequence of array-like) – Sequence of crop stacks, one per channel, shaped (N, Y, X).

  • X0 (array-like) – Detection-aligned 1D vector of x-origin pixel indices.

  • Y0 (array-like) – Detection-aligned 1D vector of y-origin pixel indices.

  • ch (array-like or None, optional) – One-based channel index for each detection. Required when crops has several channels.

  • optimizer (str, optional) – Optimizer key.

  • estimator (str, optional) – Estimator key.

  • distribution (str, optional) – Distribution key used by the estimator.

  • channels_pixels_nm (float or sequence, optional) – Pixel size specification per channel.

  • channels_gains (float or sequence, optional) – Gain value(s) used to convert fitted amplitudes.

  • channels_QE (float or sequence, optional) – Quantum efficiency value(s) used to convert fitted amplitudes.

  • cuda (bool, optional) – Whether to run the fit on GPU.

  • parallel (bool, optional) – Whether to enable CPU parallelization.

  • channels_psf_3d_xtangents (sequence) – Spline x tangents, one set per channel.

  • channels_psf_3d_ytangents (sequence) – Spline y tangents, one set per channel.

  • channels_psf_3d_ztangents (sequence) – Spline z tangents, one set per channel.

  • channels_psf_3d_spline_coeffs (sequence) – Spline coefficients, one set per channel.

Returns:

A tuple (mux, muy, muz, info) where:

  • mux is the detection-aligned x localization array in nanometers,

  • muy is the detection-aligned y localization array in nanometers,

  • muz is the detection-aligned z localization array,

  • info is a dictionary with fitted parameter arrays.

info contains:

'amp'

Detection-aligned converted amplitudes.

'offset'

Detection-aligned converted offsets.

Return type:

tuple

Notes

  1. X0 and Y0 are split by ch so each origin vector follows the crop order inside its channel stack.

  2. A local x/y grid and zero z grid are built for each channel, and spline models are initialized at the crop center with zero z.

  3. The optimizer updates local spline parameters, local coordinates are shifted by crop origins, and all outputs are remapped to detection order.

Examples

>>> import numpy as np
>>> crops = [np.random.rand(2, 7, 7).astype(np.float32)]
>>> x0 = np.array([10, 20], dtype=np.float32)
>>> y0 = np.array([30, 40], dtype=np.float32)
>>> tx = [np.linspace(-1.0, 1.0, 5, dtype=np.float32)]
>>> ty = [np.linspace(-1.0, 1.0, 5, dtype=np.float32)]
>>> tz = [np.linspace(-0.5, 0.5, 5, dtype=np.float32)]
>>> coeffs = [np.ones((4, 4, 4), dtype=np.float32)]
>>> mux, muy, muz, info = locs_individual_splinefit(
...     crops,
...     x0,
...     y0,
...     channels_pixels_nm=[(100.0, 100.0)],
...     channels_psf_3d_xtangents=tx,
...     channels_psf_3d_ytangents=ty,
...     channels_psf_3d_ztangents=tz,
...     channels_psf_3d_spline_coeffs=coeffs,
... )
>>> mux.shape == muy.shape == muz.shape
True
>>> sorted(info)
['amp', 'offset']

>>> mux, muy, muz, info = locs_individual_splinefit(
...     crops,
...     x0,
...     y0,
...     channels_pixels_nm=[(100.0, 120.0)],
...     channels_psf_3d_xtangents=tx,
...     channels_psf_3d_ytangents=ty,
...     channels_psf_3d_ztangents=tz,
...     channels_psf_3d_spline_coeffs=coeffs,
... )
>>> info['amp'].ndim
1