phasorpy.utils

Utility functions.

The phasorpy.utils module provides auxiliary and convenience functions that do not naturally fit into other modules.

phasorpy.utils.anscombe_transformation(data, /, **kwargs)

Return Anscombe variance-stabilizing transformation.

The Anscombe transformation normalizes the standard deviation of noisy, Poisson-distributed data. It can be used to transform un-normalized phasor coordinates to approximate standard Gaussian distributions.

Parameters:

• data (array_like) – Noisy Poisson-distributed data to be transformed.

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

Returns:

Anscombe-transformed data with variance of approximately 1.

Return type:

ndarray

Notes

The Anscombe transformation according to [1]:

\[z = 2 \cdot \sqrt{x + 3 / 8}\]

References

[1] (1,2)

Anscombe FJ. The transformation of Poisson, binomial and negative-binomial data. Biometrika, 35(3-4): 246-254 (1948)

Examples

>>> z = anscombe_transformation(numpy.random.poisson(10, 10000))
>>> numpy.allclose(numpy.std(z), 1.0, atol=0.1)
True

phasorpy.utils.anscombe_transformation_inverse(data, /, *, approx=False, **kwargs)

Return inverse Anscombe transformation.

Parameters:

• data (array_like) – Anscombe-transformed data.

• approx (bool, default: False) – If true, return approximation of exact unbiased inverse.

• **kwargs –

  Optional arguments passed to numpy universal functions.

Returns:

Inverse Anscombe-transformed data.

Return type:

ndarray

Notes

The inverse Anscombe transformation according to [1]:

\[x = (z / 2.0)^2 - 3 / 8\]

The approximate inverse Anscombe transformation according to [2] and [3]:

\[x = 1/4 \cdot z^2{2} + 1/4 \cdot \sqrt{3/2} \cdot z^{-1} - 11/8 \cdot z^{-2} + 5/8 \cdot \sqrt(3/2) \cdot z^{-3} - 1/8\]

References

[2]

Makitalo M, and Foi A. A closed-form approximation of the exact unbiased inverse of the Anscombe variance-stabilizing transformation. IEEE Trans Image Process, 20(9): 2697-8 (2011).

[3]

Makitalo M, and Foi A Optimal inversion of the generalized Anscombe transformation for Poisson-Gaussian noise, IEEE Trans Image Process, 22(1): 91-103 (2013)

Examples

>>> x = numpy.random.poisson(10, 100)
>>> x2 = anscombe_transformation_inverse(anscombe_transformation(x))
>>> numpy.allclose(x, x2, atol=1e-3)
True

phasorpy.utils.number_threads(num_threads=None, max_threads=None, /)

Return number of threads for parallel computations on CPU cores.

This function is used to parse num_threads parameters.

Parameters:

• num_threads (int, optional) – Number of threads to use for parallel computations on CPU cores. If None (default), return 1, disabling multi-threading. If greater than zero, return value up to max_threads if set. If zero, return the value of the PHASORPY_NUM_THREADS environment variable if set, else half the CPU cores up to max_threads or 32.

• max_threads (int, optional) – Maximum number of threads to return.

Examples

>>> number_threads()
1
>>> number_threads(0)  
8

phasorpy.utils.spectral_vector_denoise(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 [4].

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 be of same shape as signal with axis removed and axis containing spectral space appended. If None (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, default: 0.05) – Width of Gaussian filter in spectral vector space. Weighted averages are calculated using the spectra of signal items within an spectral vector Euclidean distance of 3 * sigma and intensity above vmin.

• vmin (float, optional) – Signal intensity along axis below which not to include in denoising.

• 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, multi-threading 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

References

[4]

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

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))
>>> spectral_vector_denoise(signal, axis=0, sigma=0.1, harmonic=[1, 2])
array([[[...]]])