phasorpy.filter

Filter signals and phasor coordinates.

The phasorpy.filter module provides functions to filter:

• phasor coordinates:

  • phasor_threshold()

  • phasor_filter_gaussian()

  • phasor_filter_median()

  • phasor_filter_pawflim()

• signals:

  • signal_filter_gaussian()

  • signal_filter_median()

  • signal_filter_ncpca() (noise-corrected principal component analysis)

  • signal_filter_svd() (spectral vector denoise)

phasorpy.filter.phasor_filter_gaussian(mean, real, imag, /, *, repeat=1, size=3, sigma=None, mode='nearest', skip_axis=None)

Return Gaussian-filtered phasor coordinates.

By default, apply a NaN-aware Gaussian filter independently to the real and imaginary components of phasor coordinates once, with a kernel of size 3 in each filtered dimension. NaN values in the input are preserved in the output and are excluded from the weighted average of their neighbors. Return the intensity unchanged.

Parameters:

• mean (array_like) – Intensity of phasor coordinates.

• real (array_like) – Real component of phasor coordinates to be filtered.

• imag (array_like) – Imaginary component of phasor coordinates to be filtered.

• repeat (int, optional, default: 1) – Number of times to apply Gaussian filter.

• size (int, optional, default: 3) – Size of the Gaussian kernel. Must be a positive odd integer.

• sigma (float or None, optional) – Standard deviation of Gaussian kernel. By default, sigma is computed from size using the OpenCV formula \(0.3 \cdot ((size - 1) \cdot 0.5 - 1) + 0.8\).

• mode (str, optional, default: 'nearest') – Border mode passed to scipy.ndimage.convolve1d(). Determines how the input is extended beyond its boundaries. Options include ‘nearest’, ‘reflect’, ‘mirror’, ‘wrap’, and ‘constant’.

• skip_axis (int or sequence of int or None, optional, default: None) – Axes in mean to exclude from filtering. By default, all axes of mean are filtered. The harmonics axis, if present, is always excluded.

Returns:

• mean (ndarray) – Unchanged intensity of phasor coordinates.

• real (ndarray) – Gaussian-filtered real component of phasor coordinates.

• imag (ndarray) – Gaussian-filtered imaginary component of phasor coordinates.

Raises:

• ValueError – If the array shapes of mean, real, and imag do not match. If repeat is less than 0. If sigma is not positive. If size is less than 1 or even.

• IndexError – If any skip_axis value is out of bounds.

See also

phasorpy.filter.signal_filter_gaussian, Filter phasor coordinates

Examples

Apply a Gaussian filter with sigma=1:

>>> mean, real, imag = phasor_filter_gaussian(
...     [[1, 2, 3], [4, 5, 6], [7, 8, 9]],
...     [[0.0, 0.0, 0.0], [0.5, 0.5, 0.5], [0.2, 0.2, 0.2]],
...     [[0.3, 0.3, 0.3], [0.6, math.nan, 0.6], [0.4, 0.4, 0.4]],
...     sigma=1,
... )
>>> mean
array([[1, 2, 3],
       [4, 5, 6],
       [7, 8, 9]])
>>> real
array([[0..., 0..., 0...],
       [0..., 0..., 0...],
       [0..., 0..., 0...]])
>>> imag
array([[0..., 0..., 0...],
       [0..., nan, 0...],
       [0..., 0..., 0...]])

phasorpy.filter.phasor_filter_median(mean, real, imag, /, *, repeat=1, size=3, skip_axis=None, use_scipy=False, num_threads=None, **kwargs)

Return median-filtered phasor coordinates.

By default, apply a NaN-aware median filter independently to the real and imaginary components of phasor coordinates once, with a kernel of size 3 in each filtered dimension. NaN values in the input are preserved in the output and are excluded from the median of their neighbors. Return the intensity unchanged.

Parameters:

• mean (array_like) – Intensity of phasor coordinates.

• real (array_like) – Real component of phasor coordinates to be filtered.

• imag (array_like) – Imaginary component of phasor coordinates to be filtered.

• repeat (int, optional, default: 1) – Number of times to apply median filter.

• size (int, optional, default: 3) – Size of median filter kernel.

• skip_axis (int or sequence of int or None, optional, default: None) – Axes in mean to exclude from filtering. By default, all axes except harmonics are included. If None, all axes are filtered.

• use_scipy (bool, optional, default: False) – Use scipy.ndimage.median_filter(). This function has undefined behavior if the input arrays contain NaN values, but is faster when filtering more than two dimensions. See issue #87.

• num_threads (int, optional) – Number of OpenMP threads to use for parallelization. Applies to filtering in two dimensions when not using scipy. By default, multithreading is disabled. If zero, up to half of logical CPUs are used. OpenMP may not be available on all platforms.

• **kwargs – Optional arguments passed to scipy.ndimage.median_filter() when use_scipy is True.

Returns:

• mean (ndarray) – Unchanged intensity of phasor coordinates.

• real (ndarray) – Median-filtered real component of phasor coordinates.

• imag (ndarray) – Median-filtered imaginary component of phasor coordinates.

Raises:

• ValueError – If the array shapes of mean, real, and imag do not match. If repeat is less than 0. If size is less than 1.

• IndexError – If any skip_axis value is out of bounds.

See also

phasorpy.filter.signal_filter_median, Filter phasor coordinates

Examples

Apply three times a median filter with a kernel size of three:

>>> mean, real, imag = phasor_filter_median(
...     [[1, 2, 3], [4, 5, 6], [7, 8, 9]],
...     [[0.0, 0.0, 0.0], [0.5, 0.5, 0.5], [0.2, 0.2, 0.2]],
...     [[0.3, 0.3, 0.3], [0.6, math.nan, 0.6], [0.4, 0.4, 0.4]],
...     size=3,
...     repeat=3,
... )
>>> mean
array([[1, 2, 3],
       [4, 5, 6],
       [7, 8, 9]])
>>> real
array([[0, 0, 0],
       [0.2, 0.2, 0.2],
       [0.2, 0.2, 0.2]])
>>> imag
array([[0.3, 0.3, 0.3],
       [0.4, nan, 0.4],
       [0.4, 0.4, 0.4]])

phasorpy.filter.phasor_filter_pawflim(mean, real, imag, /, *, sigma=2.0, levels=1, harmonic=None, skip_axis=None)

Return pawFLIM wavelet-filtered phasor coordinates.

This function must only be used with calibrated, unprocessed phasor coordinates obtained from FLIM data. The coordinates must not be filtered, thresholded, or otherwise pre-processed. Return the intensity unchanged.

The pawFLIM wavelet filter is described in [1].

Parameters:

• mean (array_like) – Intensity of phasor coordinates.

• real (array_like) – Real component of phasor coordinates to be filtered. Must have at least two harmonics in the first axis.

• imag (array_like) – Imaginary component of phasor coordinates to be filtered. Must have at least two harmonics in the first axis.

• sigma (float, optional, default: 2) – Significance level to test difference between two phasors. Given in terms of the equivalent 1D standard deviations. sigma=2 corresponds to ~95% significance.

• levels (int, optional, default: 1) – Number of levels for wavelet decomposition. Controls the maximum averaging area, which has a length of \(2^{levels}\).

• harmonic (sequence of int or None, optional) – Harmonics included in first axis of real and imag. By default, the first axis of real and imag contains lower harmonics starting at one and increasing by one. All harmonics must have a corresponding half or double harmonic.

• skip_axis (int or sequence of int or None, optional, default: None) – Axes in mean to exclude from filtering. By default, all axes except harmonics are included. If None, all axes are filtered.

Returns:

• mean (ndarray) – Unchanged intensity of phasor coordinates.

• real (ndarray) – Filtered real component of phasor coordinates.

• imag (ndarray) – Filtered imaginary component of phasor coordinates.

Raises:

• ValueError – If sigma is negative. If levels is negative. If the array shapes of mean, real, and imag do not match. If real and imag have no harmonic axis. If the number of harmonics in harmonic is less than 2 or does not match the first axis of real and imag. If not all harmonics in harmonic have a corresponding half or double harmonic.

• IndexError – If any skip_axis value is out of bounds.

See also

Filter phasor coordinates

References

[1]

Silberberg M, and Grecco H. pawFLIM: reducing bias and uncertainty to enable lower photon count in FLIM experiments. Methods Appl Fluoresc, 5(2): 024016 (2017)

Examples

Apply a pawFLIM wavelet filter with four significance levels (sigma) and three decomposition levels:

>>> mean, real, imag = phasor_filter_pawflim(
...     [[1, 1], [1, 1]],
...     [[[0.5, 0.8], [0.5, 0.8]], [[0.2, 0.4], [0.2, 0.4]]],
...     [[[0.5, 0.4], [0.5, 0.4]], [[0.4, 0.5], [0.4, 0.5]]],
...     sigma=4,
...     levels=3,
...     harmonic=[1, 2],
... )
>>> mean
array([[1, 1],
       [1, 1]])
>>> real
array([[[0.65, 0.65],
        [0.65, 0.65]],
       [[0.3, 0.3],
        [0.3, 0.3]]])
>>> imag
array([[[0.45, 0.45],
        [0.45, 0.45]],
       [[0.45, 0.45],
        [0.45, 0.45]]])

phasorpy.filter.phasor_threshold(mean, real, imag, /, mean_min=None, mean_max=None, *, real_min=None, real_max=None, imag_min=None, imag_max=None, phase_min=None, phase_max=None, modulation_min=None, modulation_max=None, open_interval=False, detect_harmonics=True, **kwargs)

Return phasor coordinates with values outside interval replaced by NaN.

Interval thresholds can be set for mean intensity, real and imaginary coordinates, and phase and modulation. Phasor coordinates smaller than minimum thresholds or larger than maximum thresholds are replaced with NaN. No threshold is applied by default. NaNs in mean or any real and imag harmonic are propagated to mean and all harmonics in real and imag.

Parameters:

• mean (array_like) – Intensity of phasor coordinates.

• real (array_like) – Real component of phasor coordinates.

• imag (array_like) – Imaginary component of phasor coordinates.

• mean_min (array_like, optional) – Lower threshold for mean intensity.

• mean_max (array_like, optional) – Upper threshold for mean intensity.

• real_min (array_like, optional) – Lower threshold for real coordinates.

• real_max (array_like, optional) – Upper threshold for real coordinates.

• imag_min (array_like, optional) – Lower threshold for imaginary coordinates.

• imag_max (array_like, optional) – Upper threshold for imaginary coordinates.

• phase_min (array_like, optional) – Lower threshold for phase angle.

• phase_max (array_like, optional) – Upper threshold for phase angle.

• modulation_min (array_like, optional) – Lower threshold for modulation.

• modulation_max (array_like, optional) – Upper threshold for modulation.

• open_interval (bool, optional, default: False) – Exclude threshold values from the interval. By default, the interval is closed and includes the threshold values.

• detect_harmonics (bool, optional, default: True) – Detect presence of multiple harmonics from array shapes. Otherwise, no harmonics are assumed to be present, and the function behaves like a numpy universal function.

• **kwargs – Optional arguments passed to numpy universal functions.

Returns:

• mean (ndarray) – Thresholded intensity of phasor coordinates.

• real (ndarray) – Thresholded real component of phasor coordinates.

• imag (ndarray) – Thresholded imaginary component of phasor coordinates.

See also

Filter phasor coordinates

Examples

Set phasor coordinates to NaN if mean intensity is smaller than 1.1:

>>> phasor_threshold([1, 2, 3], [0.1, 0.2, 0.3], [0.4, 0.5, 0.6], 1.1)
(array([nan, 2, 3]), array([nan, 0.2, 0.3]), array([nan, 0.5, 0.6]))

Set phasor coordinates to NaN if real component is smaller than 0.15 or larger than 0.25:

>>> phasor_threshold(
...     [1.0, 2.0, 3.0],
...     [0.1, 0.2, 0.3],
...     [0.4, 0.5, 0.6],
...     real_min=0.15,
...     real_max=0.25,
... )
(array([nan, 2, nan]), array([nan, 0.2, nan]), array([nan, 0.5, nan]))

Propagate NaNs to other input arrays:

>>> phasor_threshold(
...     [numpy.nan, 2, 3], [0.1, 0.2, 0.3], [0.4, 0.5, numpy.nan]
... )
(array([nan, 2, nan]), array([nan, 0.2, nan]), array([nan, 0.5, nan]))

phasorpy.filter.signal_filter_gaussian(signal, /, *, repeat=1, size=3, sigma=None, mode='nearest', skip_axis=-1)

Return Gaussian-filtered signal.

By default, apply a NaN-aware Gaussian filter over all axes except the last once, with a kernel of size 3 in each filtered dimension. NaN values in the input are preserved in the output and are excluded from the weighted average of their neighbors.

Parameters:

• signal (array_like) – Signal to be filtered.

• repeat (int, optional, default: 1) – Number of times to apply Gaussian filter.

• size (int, optional, default: 3) – Size of the Gaussian kernel. Must be a positive odd integer.

• sigma (float or None, optional) – Standard deviation of Gaussian kernel. By default, sigma is computed from size using the OpenCV formula \(0.3 \cdot ((size - 1) \cdot 0.5 - 1) + 0.8\).

• mode (str, optional, default: 'nearest') – Border mode passed to scipy.ndimage.convolve1d(). Determines how the input is extended beyond its boundaries. Options include ‘nearest’, ‘reflect’, ‘mirror’, ‘wrap’, and ‘constant’.

• skip_axis (int or sequence of int or None, optional, default: -1) – Axes in signal to exclude from filtering. By default, the last axis is excluded. If None, all axes are filtered.

Returns:

Gaussian-filtered signal.

Return type:

ndarray

Raises:

• ValueError – If repeat is less than 0. If sigma is not positive. If size is less than 1 or even.

• IndexError – If any skip_axis value is out of bounds.

See also

phasorpy.filter.phasor_filter_gaussian, Filter phasor coordinates

Examples

Apply a Gaussian filter, skipping the first axis:

>>> signal_filter_gaussian(
...     [
...         [[0.0, 1.0, 0.0], [0.0, math.nan, 0.0]],
...         [[1.0, 1.0, 1.0], [1.0, 1.0, 1.0]],
...     ],
...     size=3,
...     skip_axis=0,
... )
array([[[0..., 0..., 0...],
        [0..., nan, 0...]],
       [[1..., 1..., 1...],
        [1..., 1..., 1...]]])

phasorpy.filter.signal_filter_median(signal, /, *, repeat=1, size=3, skip_axis=-1, use_scipy=False, num_threads=None, **kwargs)

Return median-filtered signal.

By default, apply a NaN-aware median filter over all axes except the last once, with a kernel of size 3 in each filtered dimension. NaN values in the input are preserved in the output and are excluded from the median of their neighbors.

Parameters:

• signal (array_like) – Signal to be filtered.

• repeat (int, optional, default: 1) – Number of times to apply median filter.

• size (int, optional, default: 3) – Size of median filter kernel.

• skip_axis (int or sequence of int or None, optional, default: -1) – Axes in signal to exclude from filtering. By default, the last axis is excluded. If None, all axes are filtered.

• use_scipy (bool, optional, default: False) –

  Use scipy.ndimage.median_filter(). This function has undefined behavior if the input array contains NaN values, but is faster when filtering more than two dimensions. See issue #87.

• num_threads (int, optional) – Number of OpenMP threads to use for parallelization. Applies to filtering in two dimensions when not using scipy. By default, multithreading is disabled. If zero, up to half of logical CPUs are used. OpenMP may not be available on all platforms.

• **kwargs – Optional arguments passed to scipy.ndimage.median_filter() when use_scipy is True.

Returns:

Median-filtered signal.

Return type:

ndarray

Raises:

• ValueError – If repeat is less than 0. If size is less than 1.

• IndexError – If any skip_axis value is out of bounds.

See also

phasorpy.filter.phasor_filter_median, Filter phasor coordinates

Notes

Signal-space filtering does not commute with the phasor transform. For heterogeneous data, the spatial median of neighboring signals does not produce a physically meaningful signal, causing the phasor coordinates to be displaced from the true distribution. Use phasorpy.filter.phasor_filter_median() instead.

Examples

Apply three times a median filter with a kernel size of three, skipping the first axis:

>>> signal_filter_median(
...     [
...         [[0.0, 1.0, 0.0], [0.0, math.nan, 0.0]],
...         [[1.0, 1.0, 1.0], [1.0, 1.0, 1.0]],
...     ],
...     size=3,
...     repeat=3,
...     skip_axis=0,
... )
array([[[0, 0, 0],
        [0, nan, 0]],
       [[1, 1, 1],
        [1, 1, 1]]])

phasorpy.filter.signal_filter_ncpca(signal, /, n_components=3, *, axis=-1, dtype=None, **kwargs)

Return signal filtered by noise-corrected principal component analysis.

Apply noise-corrected Principal Component Analysis (NC-PCA) to denoise a signal containing shot noise. The signal is Poisson-normalized, its dimensionality reduced by PCA with a specified number of components, and then reconstructed according to [3].

Parameters:

• signal (array_like) – Data containing Poisson noise to be filtered. Must have at least three samples along the specified axis.

• n_components (int, float, or str, optional, default: 3) – Number of principal components to retain. The default is 3, matching the reference implementation. If None, all components are kept (no denoising). If ‘mle’, use Minka’s MLE to guess the dimension. If 0 < n_components < 1 and svd_solver == ‘full’, select the number of components such that the amount of variance that needs to be explained is greater than the percentage specified by n_components. See sklearn.decomposition.PCA for more details.

• axis (int, optional, default: -1) – Axis containing PCA features (for example, FLIM histogram bins). The default is the last axis (-1). Other axes are flattened and used as PCA samples.

• dtype (dtype_like, optional) – Data type of computation and output arrays. Either float32 or float64. The default is float64 unless the input signal is float32.

• **kwargs – Optional arguments passed to sklearn.decomposition.PCA.

Returns:

Denoised signal of specified dtype. Values may be negative. Values, where the signal mean along axis is zero, are set to NaN.

Return type:

ndarray

Raises:

ValueError – If dtype is not a floating-point type. If signal has fewer than three samples along specified axis. If n_components is invalid for the data size.

References

[3]

Soltani S, Paulson J, Fong E, Mumenthaler S, and Armani A. Denoising of fluorescence lifetime imaging data via principal component analysis. Preprint, (2025)

Notes

Intensities of the reconstructed signal may be negative. Hence, the phasor coordinates calculated from the reconstructed signal may be outside the unit circle. Consider thresholding low intensities for further analysis.

Examples

Denoise FLIM data using three principal components:

>>> signal = numpy.random.poisson(100, (32, 32, 64))
>>> denoised = signal_filter_ncpca(signal, n_components=3)
>>> denoised.shape
(32, 32, 64)

phasorpy.filter.signal_filter_svd(signal, /, spectral_vector=None, *, axis=-1, harmonic=None, sigma=0.05, vmin=None, dtype=None, num_threads=None)

Return spectral-vector-denoised signal.

The spectral vector denoising algorithm is based on a Gaussian weighted average calculation, with weights obtained in n-dimensional Chebyshev or Fourier space [2].

Parameters:

• signal (array_like) – Hyperspectral data to be denoised. A minimum of three samples are required along axis. The samples must be uniformly spaced.

• spectral_vector (array_like, optional) – Spectral vector. For example, phasor coordinates, PCA-projected phasor coordinates, or Chebyshev coefficients. Must have the same shape as signal with axis removed and an axis containing spectral space appended. By default, phasor coordinates are calculated at specified harmonic.

• axis (int, optional, default: -1) – Axis over which spectral_vector is computed if not provided. The default is the last axis (-1).

• harmonic (int, sequence of int, or 'all', optional) – Harmonics to include in calculating spectral_vector. If ‘all’, include all harmonics for signal samples along axis. Else, harmonics must be at least one and no larger than half the number of signal samples along axis. The default is the first harmonic (fundamental frequency). A minimum of harmonic * 2 + 1 samples are required along axis to calculate correct phasor coordinates at harmonic.

• sigma (float, optional, default: 0.05) – Width of Gaussian filter in spectral vector space. Weighted averages are calculated using the spectra of signal items within a spectral vector Euclidean distance of 3 * sigma and intensity above vmin.

• vmin (float, optional) – Signal intensity along axis below which spectra are excluded from denoising. If None or negative, 0.0 is used.

• dtype (dtype_like, optional) – Data type of output arrays. Either float32 or float64. The default is float64 unless the signal is float32.

• num_threads (int, optional) – Number of OpenMP threads to use for parallelization. By default, multithreading is disabled. If zero, up to half of logical CPUs are used. OpenMP may not be available on all platforms.

Returns:

Denoised signal of dtype. Spectra with integrated intensity below vmin are unchanged.

Return type:

ndarray

Raises:

ValueError – If sigma is not positive. If signal has fewer than three samples along specified axis. If dtype is not a floating-point type. If spectral_vector shape does not match signal shape.

References

[2]

Harman RC, Lang RT, Kercher EM, Leven P, and Spring BQ. Denoising multiplexed microscopy images in n-dimensional spectral space. Biomed Opt Express, 13(8): 4298-4309 (2022)

Notes

This implementation is considered experimental. It is not validated against the reference implementation and may not be practical with real-world data. See discussion in issue #142.

Examples

Denoise a hyperspectral image with a Gaussian filter width of 0.1 in spectral vector space using first and second harmonic:

>>> signal = numpy.random.randint(0, 255, (8, 16, 16))
>>> signal_filter_svd(signal, axis=0, sigma=0.1, harmonic=[1, 2])
array([[[...]]])