smlmlp.locs_individual_fit module

smlmlp.locs_individual_fit(crops, X0, Y0, /, ch=None, *, channels_fit_models='isogauss', 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_sigmas_nm=93.8, channels_psf_xsigmas_nm=93.8, channels_psf_ysigmas_nm=93.8, channels_psf_thetas_deg=0.0, channels_fit_thetas=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 stack with a channel-specific localization model.

Parameters:

  • crops (sequence of array-like) – Crop stacks to fit, one stack per channel. Each stack must be shaped (N, Y, X) where N is the number of events in that channel.

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

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

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

  • channels_fit_models (str or sequence of str, default="isogauss") – Model used for each channel crop stack. Accepted values are "isogauss", "gauss", and "spline".

  • optimizer ({"lm"}, default="lm") – Optimizer used to fit each model.

  • estimator ({"mle", "lse"}, default="mle") – Estimator used by the optimizer.

  • distribution ({"poisson", "normal"}, default="poisson") – Noise distribution used by maximum-likelihood estimators.

  • channels_pixels_nm (float, tuple, or sequence, default=1.0) – Pixel size specification. A scalar is used for both axes and all channels, a (py, px) tuple is broadcast to all channels, and a sequence provides one (py, px) pair per channel.

  • channels_gains (float or sequence, default=1.0) – Gain values used to convert fitted amplitudes and offsets.

  • channels_QE (float or sequence, default=1.0) – Quantum efficiencies used to convert fitted amplitudes and offsets.

  • cuda (bool, default=False) – Whether to run fits on CUDA when supported.

  • parallel (bool, default=False) – Whether to use threaded CPU execution.

  • channels_psf_sigmas_nm (float or sequence, default=SIGMA) – Initial isotropic sigma values for "isogauss" channels.

  • channels_psf_xsigmas_nm (float or sequence, default=SIGMA) – Initial x sigma values for "gauss" channels.

  • channels_psf_ysigmas_nm (float or sequence, default=SIGMA) – Initial y sigma values for "gauss" channels.

  • channels_psf_thetas_deg (float or sequence, default=0.0) – Initial theta values, in degrees, for "gauss" channels.

  • channels_fit_thetas (bool or sequence, default=False) – Whether to fit theta for "gauss" channels.

  • channels_psf_3d_xtangents (sequence, optional) – Spline x tangents for "spline" channels.

  • channels_psf_3d_ytangents (sequence, optional) – Spline y tangents for "spline" channels.

  • channels_psf_3d_ztangents (sequence, optional) – Spline z tangents for "spline" channels.

  • channels_psf_3d_spline_coeffs (sequence, optional) – Spline coefficients for "spline" channels.

Returns:

A tuple (mux, muy, muz, info) where mux and muy are detection-aligned fitted coordinates in nanometers and muz contains fitted spline z coordinates or np.nan for 2D models. info contains detection-aligned "amp", "offset", optional "sigma", optional "sigmax", optional "sigmay" arrays, plus a "models" list. "sigma" is None when no channel uses "isogauss"; "sigmax"/"sigmay" are None when no channel uses "gauss". Present sigma arrays match localization length and contain np.nan where a quantity does not apply to a given channel model.

Return type:

tuple

Raises:

  • ValueError – If per-channel inputs have incompatible lengths or a model name is not one of "isogauss", "gauss", and "spline".

  • SyntaxError – If the optimizer, estimator, distribution, or required spline metadata is missing or unsupported.

Notes

  1. Channel model names and per-channel parameters are normalized to match the crop list length.

  2. X0 and Y0 are split by ch so origins match each crop stack.

  3. Each channel selects IsoGaussian, Gaussian2D, or Spline3D and initializes local coordinates at the crop center.

  4. The selected optimizer updates model parameters in local nanometer coordinates before crop origins are added back.

  5. Coordinates and fitted parameter arrays 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)
>>> mux, muy, muz, info = locs_individual_fit(
...     crops,
...     x0,
...     y0,
...     channels_fit_models=["isogauss"],
...     channels_pixels_nm=[(100.0, 100.0)],
... )
>>> mux.shape == muy.shape
True

>>> tx = [np.linspace(-300.0, 300.0, 8, dtype=np.float32)]
>>> ty = [np.linspace(-300.0, 300.0, 8, dtype=np.float32)]
>>> tz = [np.linspace(-300.0, 300.0, 8, dtype=np.float32)]
>>> coeffs = [np.ones((4, 4, 4), dtype=np.float32)]
>>> mux, muy, muz, info = locs_individual_fit(
...     crops,
...     x0,
...     y0,
...     channels_fit_models=["spline"],
...     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,
... )
>>> info["models"]
['spline']