NumPy unwrap()

The numpy.unwrap() function corrects phase angles in a signal by replacing abrupt jumps larger than a threshold with their 2π (or specified period) complement. This ensures continuity in phase data.

Syntax

</>
Copy
numpy.unwrap(p, discont=None, axis=-1, *, period=6.283185307179586)

Parameters

ParameterTypeDescription
parray_likeInput array containing phase values.
discontfloat, optionalMaximum discontinuity allowed between consecutive values before unwrapping occurs. Default is period/2.
axisint, optionalAxis along which unwrapping is performed. Default is the last axis (-1).
periodfloat, optionalDefines the range over which the phase wraps. Default is 2π (6.283).

Return Value

Returns an ndarray with phase values corrected for discontinuities, ensuring smooth transitions.

Examples

1. Basic Unwrapping of a Wrapped Phase Signal

Here, we apply numpy.unwrap() to a simple wrapped phase sequence.

</>
Copy
import numpy as np

# Simulated wrapped phase values in radians
wrapped_phase = np.array([0, np.pi/2, np.pi, -np.pi, -np.pi/2, 0])

# Unwrap the phase to remove discontinuities
unwrapped_phase = np.unwrap(wrapped_phase)

# Print results
print("Wrapped phase values:", wrapped_phase)
print("Unwrapped phase values:", unwrapped_phase)

Output:

Wrapped phase values: [ 0.          1.57079633  3.14159265 -3.14159265 -1.57079633  0.        ]
Unwrapped phase values: [0.         1.57079633 3.14159265 3.14159265 4.71238898 6.28318531]

The function corrects the sudden phase jump from -π to π by adjusting it to a continuous phase progression.

2. Unwrapping Along a Specified Axis

Unwrapping can be applied along a specific axis in multidimensional arrays.

</>
Copy
import numpy as np

# 2D array of wrapped phase values
wrapped_phase_2d = np.array([[0, np.pi/2, np.pi, -np.pi, -np.pi/2],
                             [0, -np.pi/2, -np.pi, np.pi, np.pi/2]])

# Unwrap along the last axis
unwrapped_phase_2d = np.unwrap(wrapped_phase_2d, axis=-1)

# Print results
print("Wrapped phase:\n", wrapped_phase_2d)
print("Unwrapped phase:\n", unwrapped_phase_2d)

Output:

Wrapped phase:
 [[ 0.          1.57079633  3.14159265 -3.14159265 -1.57079633]
 [ 0.         -1.57079633 -3.14159265  3.14159265  1.57079633]]
Unwrapped phase:
 [[ 0.          1.57079633  3.14159265  3.14159265  4.71238898]
 [ 0.         -1.57079633 -3.14159265 -3.14159265 -4.71238898]]

The function applies unwrapping along the specified axis, ensuring smooth phase transitions across the row.

3. Adjusting Discontinuity Threshold

By changing the discont parameter, we can control when unwrapping occurs.

</>
Copy
import numpy as np

# Wrapped phase values with large jumps
wrapped_phase_large_jump = np.array([0, np.pi/2, np.pi, 3*np.pi, -np.pi, -np.pi/2, 0])

# Unwrap with a custom discontinuity threshold
unwrapped_custom = np.unwrap(wrapped_phase_large_jump, discont=np.pi)

# Print results
print("Wrapped phase values:", wrapped_phase_large_jump)
print("Unwrapped phase values:", unwrapped_custom)

Output:

Wrapped phase values: [ 0.          1.57079633  3.14159265  9.42477796 -3.14159265 -1.57079633
  0.        ]
Unwrapped phase values: [0.         1.57079633 3.14159265 3.14159265 3.14159265 4.71238898
 6.28318531]

Since the discontinuity threshold is set to π, jumps greater than this value trigger unwrapping, while smaller jumps are ignored.

4. Changing the Period for Custom Unwrapping

We can specify a different period to unwrap signals wrapping over a different range than 2π.

</>
Copy
import numpy as np

# Define a wrapped phase signal with a different periodicity
wrapped_phase_custom = np.array([0, 3, 6, 9, 12, 15, -3, 0])

# Unwrap with a period of 6
unwrapped_custom_period = np.unwrap(wrapped_phase_custom, period=6)

# Print results
print("Wrapped phase values:", wrapped_phase_custom)
print("Unwrapped phase values with period 6:", unwrapped_custom_period)

Output:

Wrapped phase values: [ 0  3  6  9 12 15 -3  0]
Unwrapped phase values with period 6: [ 0  3  6  9 12 15 15 18]

By setting period=6, the function treats discontinuities larger than 6/2 as phase jumps, ensuring smooth transitions.