phasorpy._utils#

Note

This module and its functions are not part of the public interface. They are intended to facilitate the development of the PhasorPy library.

Private auxiliary and convenience functions.

phasorpy._utils.chunk_iter(shape, chunk_shape, /, axes=None, *, pattern=None, squeeze=False, use_index=False)[source]#

Yield indices and labels of chunks from ndarray’s shape.

Parameters:

  • shape (tuple of int) – Shape of C-order ndarray to chunk.

  • chunk_shape (tuple of int) – Shape of chunks in the most significant dimensions.

  • axes (str or sequence of str, optional) – Labels for each axis in shape if pattern is None.

  • pattern (str, optional) – String to format chunk indices. If None, use _[{axes[index]}{chunk_index[index]}] for each axis.

  • squeeze (bool) – If true, do not include length-1 chunked dimensions in label unless dimensions are part of chunk_shape. Applies only if pattern is None.

  • use_index (bool) – If true, use indices of chunks in shape instead of chunk indices to format pattern.

Yields:

  • index (tuple of int or slice) – Indices of chunk in ndarray.

  • label (str) – Pattern formatted with chunk indices.

  • cropped (bool) – True if chunk exceeds any border of ndarray. Indexing ndarray with index will yield a slice smaller than chunk_shape.

Examples

>>> list(chunk_iter((2, 2), (2,), pattern='Y{}'))
[((0, slice(0, 2, 1)), 'Y0', False), ((1, slice(0, 2, 1)), 'Y1', False)]

Chunk a four-dimensional image stack into 2x2 sized image tiles:

>>> stack = numpy.zeros((2, 3, 4, 5))
>>> for index, label, cropped in chunk_iter(stack.shape, (2, 2)):
...     chunk = stack[index]
...
phasorpy._utils.dilate_coordinates(real, imag, offset, /)[source]#

Return dilated coordinates.

Parameters:

  • real (array_like) – Coordinates of convex hull, sorted by angle.

  • imag (array_like) – Coordinates of convex hull, sorted by angle.

  • offset (float) – Amount by which to dilate coordinates.

Returns:

real, imag – Coordinates dilated by offset.

Return type:

ndarray

Examples

>>> dilate_coordinates([2, 3, 1, 0], [-1, 0, 1, 0], 0.05)
(array([2.022, 3.05, 0.9776, -0.05]), array([-1.045, 0, 1.045, 0]))
phasorpy._utils.kwargs_notnone(**kwargs)[source]#

Return dict of kwargs which values are not None.

>>> kwargs_notnone(one=1, none=None)
{'one': 1}
phasorpy._utils.parse_harmonic(harmonic, harmonic_max=None, /)[source]#

Return parsed harmonic parameter.

This function performs common, but not necessarily all, verifications of user-provided harmonic parameter.

Parameters:

  • harmonic (int, list of int, 'all', or None) – Harmonic parameter to parse.

  • harmonic_max (int, optional) – Maximum value allowed in hamonic. Must be one or greater. To verify against known number of signal samples, pass samples // 2. If harmonic=’all’, a range of harmonics from one to harmonic_max (included) is returned.

Returns:

  • harmonic (list of int) – Parsed list of harmonics.

  • has_harmonic_axis (bool) – False if harmonic input parameter is a scalar integer.

Raises:

  • IndexError – Any element is out of range [1..harmonic_max].

  • ValueError – Elements are not unique. Harmonic is empty. String input is not ‘all’. harmonic_max is smaller than 1.

  • TypeError – Any element is not an integer. harmonic is ‘all’ and harmonic_max is None.

phasorpy._utils.parse_kwargs(kwargs, /, *keys, _del=True, **keyvalues)[source]#

Return dict with keys from keys|keyvals and values from kwargs|keyvals.

If _del is true (default), existing keys are deleted from kwargs.

>>> kwargs = {'one': 1, 'two': 2, 'four': 4}
>>> kwargs2 = parse_kwargs(kwargs, 'two', 'three', four=None, five=5)
>>> kwargs == {'one': 1}
True
>>> kwargs2 == {'two': 2, 'four': 4, 'five': 5}
True
phasorpy._utils.parse_signal_axis(signal, /, axis=None)[source]#

Return axis over which phasor coordinates are computed.

The axis parameter is not validated against the signal shape.

Parameters:

  • signal (array_like) – Image stack.

  • axis (int or str, optional) – Axis over which phasor coordinates are computed. By default, the ‘H’ or ‘C’ axes if signal contains such dimension names, else the last axis (-1).

Returns:

  • axis (int) – Axis over which phasor coordinates are computed.

  • axis_label (str) – Axis label from signal.dims if any.

Raises:

ValueError – Axis not found in signal.dims or invalid for signal type.

Examples

>>> parse_signal_axis([])
(-1, '')
>>> parse_signal_axis([], 1)
(1, '')
>>> class DataArray:
...     dims = ('C', 'H', 'Y', 'X')
...
>>> parse_signal_axis(DataArray())
(1, 'H')
>>> parse_signal_axis(DataArray(), 'C')
(0, 'C')
>>> parse_signal_axis(DataArray(), 1)
(1, 'H')
phasorpy._utils.phasor_from_polar_scalar(phase, modulation, /, *, degree=False, percent=False)[source]#

Return phasor from scalar polar coordinates.

>>> phasor_from_polar_scalar(0.0, 100.0, degree=True, percent=True)
(1.0, 0.0)
phasorpy._utils.phasor_to_polar_scalar(real, imag, /, *, degree=False, percent=False)[source]#

Return polar from scalar phasor coordinates.

>>> phasor_to_polar_scalar(1.0, 0.0, degree=True, percent=True)
(0.0, 100.0)
phasorpy._utils.scale_matrix(factor, origin)[source]#

Return matrix to scale homogeneous coordinates by factor around origin.

Parameters:

  • factor (float) – Scale factor.

  • origin ((float, float)) – Coordinates of point around which to scale.

Returns:

matrix – A 3x3 homogeneous transformation matrix.

Return type:

ndarray

Examples

>>> scale_matrix(1.1, (0.0, 0.5))
array([[1.1, 0, -0],
       [0, 1.1, -0.05],
       [0, 0, 1]])
phasorpy._utils.sort_coordinates(real, imag, /, origin=None)[source]#

Return cartesian coordinates sorted counterclockwise around origin.

Parameters:

  • real (array_like) – Coordinates to be sorted.

  • imag (array_like) – Coordinates to be sorted.

  • origin ((float, float)) – Coordinates around which to sort by angle.

Returns:

  • real, imag (ndarray) – Coordinates sorted by angle.

  • indices (ndarray) – Indices used to reorder coordinates.

Examples

>>> sort_coordinates([0, 1, 2, 3], [0, 1, -1, 0])
(array([2, 3, 1, 0]), array([-1,  0,  1,  0]), array([2, 3, 1, 0]...))
phasorpy._utils.update_kwargs(kwargs, /, **keyvalues)[source]#

Update dict with keys and values if keys do not already exist.

>>> kwargs = {'one': 1}
>>> update_kwargs(kwargs, one=None, two=2)
>>> kwargs == {'one': 1, 'two': 2}
True