robust_unwrap

PySeismoSoil.helper_site_response.robust_unwrap(signal: ndarray, discont: float | None = 3.141592653589793) → ndarray

Unwrap a phase signal in a robust way.

Sometimes, due to numerical discreteness, the “jump” in the signal does not happen immediately between two adjacent signal points, but rather over several points. For example:

[-2.98, -3.01, -3.03, -3.05, -3.08, -1.55, 0.34, 2.24, 3.11, 3.08, 3.06]
                             trough ------------------ peak

This would mess with numpy.unwrap() and tricks it to think that the points between the trough and peak (shown above) don’t need unwrapping.

This function deals with such situations by adjust the values underlined by “—-” into the range of (trough, -3.1415927], so that numpy.unwrap() can correctly identify the “jump”.

Parameters:

• signal (np.ndarray) – Input array. Only allows 1D arrays.

• discont (float | None) – Maximum discontinuity between values, default is pi. Refer to the documentation of numpy.unwrap().

Returns:

unwrapped – Unwrapped array.

Return type:

np.ndarray

Notes

An underlying assumption of this algorithm is that the phase angle (if correctly unwrapped) should be monotonically decreasing and all negative. This assumption is true for the transfer functions of 1D SH wave propagation, because the output waves always arrive later than the input waves.

Also, this algorithm only works for “clean” phase signals, not noisy ones, because this algorithm assumes that all “upward jumps” that are not achieved within “one step” (i.e., between two adjacent signal points) are artifacts. This assumption is not true for noisy phase signals, since some “upward jumps” are just noises, not artifacts.