smlmlp.integrate_crop module

smlmlp.integrate_crop(crops, X0=None, Y0=None, /, ch=None, *, x_fit=None, y_fit=None, z_fit=None, os_fit=None, sigma_fit=None, sigma_x_fit=None, sigma_y_fit=None, sigma_angle=None, channels_weighted_integrations=True, channels_fit_models='isogauss', channels_pixels_nm=1.0, channels_gains=1.0, channels_QE=1.0, 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_psf_3d_xtangents=None, channels_psf_3d_ytangents=None, channels_psf_3d_ztangents=None, channels_psf_3d_spline_coeffs=None, cuda=False, parallel=False)[source]

Integrate photon counts from per-channel crop stacks.

Parameters:

  • crops (sequence of array-like) – Crop stacks, one stack per channel, shaped (N, Y, X). The order inside each channel must match the detections where ch == channel.

  • X0 (array-like or sequence of array-like, optional) – Crop x/y origins in pixels. Detection-aligned arrays are split with ch. Per-channel arrays are also accepted. These origins are required for weighted channels because fitted coordinates are stored globally.

  • Y0 (array-like or sequence of array-like, optional) – Crop x/y origins in pixels. Detection-aligned arrays are split with ch. Per-channel arrays are also accepted. These origins are required for weighted channels because fitted coordinates are stored globally.

  • ch (array-like or None, optional) – One-based channel index for each detection. When provided, integrated values are remapped to this detection order.

  • x_fit (array-like, optional) – Fitted x/y coordinates in nanometers. Required for weighted channels.

  • y_fit (array-like, optional) – Fitted x/y coordinates in nanometers. Required for weighted channels.

  • z_fit (array-like, optional) – Fitted z coordinates for spline channels. Missing values default to zero.

  • os_fit (array-like, optional) – Fitted offset in photons per pixel. Required for weighted channels and converted back to raw crop units before subtraction.

  • sigma_fit (array-like, optional) – Fitted isotropic sigma in nanometers for "isogauss" channels.

  • sigma_x_fit (array-like, optional) – Fitted x/y sigmas in nanometers for "gauss" channels.

  • sigma_y_fit (array-like, optional) – Fitted x/y sigmas in nanometers for "gauss" channels.

  • sigma_angle (array-like, optional) – Per-detection Gaussian angle. If omitted, channels_psf_thetas_deg is used for each channel.

  • channels_weighted_integrations (bool or sequence of bool, optional) – Per-channel switch selecting weighted PSF projection when true and border-background summation when false.

  • channels_fit_models (str or sequence of str, optional) – Per-channel fit model used to reconstruct weighted PSFs. Supported values are "isogauss", "gauss", and "spline".

  • channels_pixels_nm (float, tuple, or sequence, optional) – Pixel sizes in (y, x) nanometers. A scalar or one tuple is broadcast to all channels.

  • channels_gains (float or sequence, optional) – Gain values used to convert raw crop counts to photons.

  • channels_QE (float or sequence, optional) – Quantum efficiencies used to convert raw crop counts to photons.

  • channels_psf_sigmas_nm (float or sequence, optional) – Channel PSF defaults used when fitted sigma columns are not supplied.

  • channels_psf_xsigmas_nm (float or sequence, optional) – Channel PSF defaults used when fitted sigma columns are not supplied.

  • channels_psf_ysigmas_nm (float or sequence, optional) – Channel PSF defaults used when fitted sigma columns are not supplied.

  • channels_psf_thetas_deg (float or sequence, optional) – Channel Gaussian angle defaults.

  • channels_psf_3d_xtangents (sequence, optional) – Spline tangents used by weighted "spline" channels.

  • channels_psf_3d_ytangents (sequence, optional) – Spline tangents used by weighted "spline" channels.

  • channels_psf_3d_ztangents (sequence, optional) – Spline tangents used by weighted "spline" channels.

  • channels_psf_3d_spline_coeffs (sequence, optional) – Spline coefficients used by weighted "spline" channels.

  • cuda (bool, optional) – Whether to run array operations on CUDA-compatible arrays.

  • parallel (bool, optional) – Whether to parallelize the background-removal step for unweighted channels.

Returns:

A tuple (intensity, info) where intensity is a one-dimensional detection-aligned photon count array. info contains normalized channel settings, intermediate weighted denominators, and the background vectors applied to each crop.

Return type:

tuple

Raises:

  • ValueError – If channel lengths are inconsistent, channel indices are invalid, or a weighted channel is missing required fitted coordinates or offsets.

  • SyntaxError – If spline metadata is required but missing.

Notes

Unweighted channels subtract the border-median background with crop_remove_bkgd(), sum all corrected pixels, and convert raw counts as raw * gain / QE.

Weighted channels reconstruct the fitted PSF shape with the matching funclp function and zero offset. The fitted offset is subtracted from the raw crop after conversion back to raw units. The normalized PSF p = psf_model / psf_model.sum() is then used as a matched filter: N = sum(p * crop_no_bkgd) / sum(p**2). The resulting raw count is converted with the same gain / QE factor.

Examples

>>> import numpy as np
>>> crops = [np.ones((2, 3, 3), dtype=np.float32)]
>>> crops[0][:, 1, 1] = [11.0, 21.0]
>>> intensity, info = integrate_crop(crops, channels_weighted_integrations=False)
>>> intensity.shape
(2,)

>>> ch = np.array([2, 1], dtype=np.uint8)
>>> crops = [np.ones((1, 3, 3), dtype=np.float32), np.ones((1, 3, 3), dtype=np.float32)]
>>> crops[1][0, 1, 1] = 6.0
>>> intensity, info = integrate_crop(
...     crops,
...     np.array([0, 0]),
...     np.array([0, 0]),
...     ch=ch,
...     x_fit=np.array([np.nan, 1.0], dtype=np.float32),
...     y_fit=np.array([np.nan, 1.0], dtype=np.float32),
...     os_fit=np.array([0.0, 1.0], dtype=np.float32),
...     channels_weighted_integrations=[True, False],
... )
>>> intensity.ndim
1