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)

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, /)

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)

Return dict of kwargs which values are not None.

>>> kwargs_notnone(one=1, none=None)
{'one': 1}

phasorpy._utils.parse_harmonic(harmonic, samples, /)

Return parsed harmonic parameter.

Parameters:

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

• samples (int) – Number of samples in signal. Used to verify harmonic values and set maximum harmonic value.

Returns:

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

• has_harmonic_axis (bool) – If true, harmonic input parameter is an integer, else a list.

Raises:

• IndexError – Any element is out of range [1..samples // 2].

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

• TypeError – Any element is not an integer.

phasorpy._utils.parse_kwargs(kwargs, /, *keys, _del=True, **keyvalues)

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.phasor_from_polar_scalar(phase, modulation, /, *, degree=False, percent=False)

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)

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)

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)

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)

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