smlmlp.bkgd_combination module

smlmlp.bkgd_combination(channels, /, bkgds=None, noise_corrections=None, *, do_spatial_opening=False, channels_opening_radii_pix=3.0, do_temporal_median=True, median_window_fr=25, do_spatial_mean=True, channels_mean_radii_pix=7.0, cuda=False, parallel=False)[source]

Compute a background by combining several background estimation steps.

This function applies up to three background estimation methods in sequence:

  1. spatial opening,

  2. temporal median,

  3. spatial mean.

After each enabled step, the estimated background is subtracted from the current working channels. At the end of the pipeline, the final background is reconstructed from the difference between the original input channels and the final residual channels.

The function preserves the original computation logic. The returned info dictionary is built by updating a single dictionary with the intermediate info outputs returned by the sub-functions that were actually executed.

Parameters:

  • channels (sequence of ndarray) – Sequence of input channel stacks to process.

  • bkgds (sequence of ndarray or None, optional) – Optional output arrays used to store the background estimates.

  • noise_corrections (sequence of float or None, optional) – Optional per-channel noise correction factors propagated through the enabled background estimation steps.

  • do_spatial_opening (bool, optional) – Whether to apply bkgd_spatial_opening() first.

  • channels_opening_radii_pix (float or sequence, optional) – Opening radii parameter forwarded to bkgd_spatial_opening().

  • do_temporal_median (bool, optional) – Whether to apply bkgd_temporal_median().

  • median_window_fr (int, optional) – Temporal median window, in frames, forwarded to bkgd_temporal_median().

  • do_spatial_mean (bool, optional) – Whether to apply bkgd_spatial_mean().

  • channels_mean_radii_pix (float or sequence, optional) – Spatial mean radii parameter forwarded to bkgd_spatial_mean().

  • cuda (bool, optional) – Whether to use CUDA-enabled array operations when supported.

  • parallel (bool, optional) – Whether to enable parallel execution in the called sub-functions.

Returns:

A tuple (bkgds, noise_corrections, info) where:

  • bkgds is the final reconstructed background for each channel,

  • noise_corrections is the updated list of correction factors,

  • info is a dictionary aggregating intermediate results from all executed background estimation steps.

The dictionary is built by updating a single dictionary with the info outputs of each enabled step. Depending on the activated methods, it may contain:

From spatial opening:

'channels_opening_radii_pix'

Per-channel opening radii.

'footprints'

Structuring elements used for each channel.

From temporal median:

'median_window_fr'

Temporal window size used for the median filter.

From spatial mean:

'channels_mean_radii_pix'

Per-channel spatial radii.

'sigmas'

Gaussian standard deviations used for filtering.

'kernels'

1D kernels used for noise correction estimation.

Return type:

tuple

Notes

The working channels are updated in-place whenever possible through the backend returned by arrlp.get_xp().

If no background step is enabled:

  • bkgds is created as zeros if it was initially None,

  • otherwise the provided output backgrounds are filled with zeros.

Examples

Apply the default combination of temporal median and spatial mean:

>>> import numpy as np
>>> channels = [
...     np.random.rand(10, 16, 16).astype(np.float32),
...     np.random.rand(10, 16, 16).astype(np.float32),
... ]
>>> bkgds, noise_corr, info = bkgd_combination(channels)
>>> len(bkgds)
2
>>> len(noise_corr)
2
>>> isinstance(info, dict)
True

Apply only spatial opening:

>>> bkgds, noise_corr, info = bkgd_combination(
...     channels,
...     do_spatial_opening=True,
...     do_temporal_median=False,
...     do_spatial_mean=False,
...     channels_opening_radii_pix=4.0,
... )
>>> "footprints" in info
True

Disable all background estimation steps:

>>> bkgds, noise_corr, info = bkgd_combination(
...     channels,
...     do_spatial_opening=False,
...     do_temporal_median=False,
...     do_spatial_mean=False,
... )
>>> len(bkgds) == len(channels)
True