numpy.ma.unwrap#

ma.unwrap(p, discont=None, axis=-1, *, period=6.283185307179586)[source]#

Unwrap by taking the complement of large deltas with respect to the period.

This unwraps a signal p by changing elements which have an absolute difference from their predecessor of more than max(discont, period/2) to their period-complementary values. Masked elements are skipped over, so the predecessor of an element is the closest preceding unmasked one, and the mask is preserved in the output.

For the default case where period is \(2\pi\) and discont is \(\pi\), this unwraps a radian phase p such that adjacent differences are never greater than \(\pi\) by adding \(2k\pi\) for some integer \(k\).

Parameters:
parray_like

Input array. Masked entries are not taken into account in the computation.

discontfloat, optional

Maximum discontinuity between values, default is period/2. Values below period/2 are treated as if they were period/2. To have an effect different from the default, discont should be larger than period/2.

axisint, optional

Axis along which unwrap will operate, default is the last axis.

periodfloat or int, optional

Size of the range over which the input wraps. By default, it is 2 pi.

Returns:
outMaskedArray

Output array, carrying the mask of p. Its dtype is numpy.result_type(p, period). In particular an integer array unwrapped with an integer period keeps its integer dtype, while any float period (including the default 2 pi) produces a floating-point result. The data underlying the masked elements is unspecified.

See also

numpy.unwrap

Equivalent function for ndarrays

Notes

If the discontinuity in p is smaller than period/2, but larger than discont, no unwrapping is done because taking the complement would only make the discontinuity larger.

Unwrapping assumes that the change between an element and its predecessor is less than half a period. Across a masked gap that assumption cannot be checked, so a gap hiding more than half a period of change is not recovered and leaves the elements after it offset by a multiple of period.

Examples

>>> import numpy as np

>>> phase = np.ma.masked_array([0., 1., 2., 2 + 2 * np.pi, 3 + 2 * np.pi],
...                            mask=[0, 0, 1, 0, 0])
>>> np.ma.unwrap(phase)
masked_array(data=[0.0, 1.0, --, 2.0, 3.0],
             mask=[False, False,  True, False, False],
       fill_value=1e+20)

The masked element is skipped over, so the fourth element is unwrapped against the second one.

>>> phase_deg = np.ma.masked_array([0., 170., 340., 150.],
...                                mask=[0, 1, 0, 0])
>>> np.ma.unwrap(phase_deg, period=360)
masked_array(data=[0.0, --, -20.0, 150.0],
             mask=[False,  True, False, False],
       fill_value=1e+20)
On this page