smlmlp.signal_combination module

smlmlp.signal_combination(channels, /, channels_spatial_kernels=None, temporal_kernel=None, signals=None, bkgds=None, noise_corrections=None, *, do_spatial_filter=True, do_temporal_filter=False, cuda=False, parallel=False)[source]

Apply a sequence of signal-enhancement filters.

This function combines the spatial and temporal signal filters into a single processing pipeline. Each enabled step is applied in sequence, and the output of one step becomes the input of the next one.

Parameters:

  • channels (sequence of ndarray) – Sequence of input channel stacks, one per channel.

  • channels_spatial_kernels (sequence of ndarray or None, optional) – Spatial kernels forwarded to signal_spatial_filter().

  • temporal_kernel (array-like or None, optional) – Temporal kernel forwarded to signal_temporal_filter().

  • signals (sequence of ndarray or None, optional) – Optional preallocated output arrays reused across filtering steps.

  • bkgds (sequence of ndarray or None, optional) – Optional background arrays subtracted before the first enabled filtering step.

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

  • do_spatial_filter (bool, optional) – Whether to apply signal_spatial_filter().

  • do_temporal_filter (bool, optional) – Whether to apply signal_temporal_filter().

  • cuda (bool, optional) – Whether to enable CUDA processing.

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

Returns:

A tuple (signals, noise_corrections, info) where:

  • signals is the list of filtered signal stacks,

  • noise_corrections is the updated list of correction factors,

  • info is a dictionary aggregating intermediate results from all executed filtering 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 filtering:

'channels_spatial_kernels'

Spatial kernels used for the correlation, one per channel.

'kernel_factors'

Multiplicative noise-correction factors derived from the norm of each spatial kernel.

From temporal filtering:

'temporal_kernel'

Temporal kernel used for the correlation.

'kernel_factor'

Multiplicative noise-correction factor derived from the temporal kernel norm.

Return type:

tuple

Notes

After each enabled filtering step, the resulting signals are copied into internal buffers so they can safely be reused as input for the next step.

Examples

Apply only spatial filtering:

>>> import numpy as np
>>> channels = [np.random.rand(10, 8, 8).astype(np.float32)]
>>> spatial_kernels = [np.ones((3, 3), dtype=np.float32)]
>>> signals, noise_corr, info = signal_combination(
...     channels,
...     channels_spatial_kernels=spatial_kernels,
...     do_spatial_filter=True,
...     do_temporal_filter=False,
... )
>>> len(signals)
1
>>> "channels_spatial_kernels" in info
True

Apply spatial and temporal filtering in sequence:

>>> temporal_kernel = np.array([1.0, -1.0], dtype=np.float32)
>>> signals, noise_corr, info = signal_combination(
...     channels,
...     channels_spatial_kernels=spatial_kernels,
...     temporal_kernel=temporal_kernel,
...     do_spatial_filter=True,
...     do_temporal_filter=True,
... )
>>> "temporal_kernel" in info
True