clouddrift.kinematics.inertial_oscillation_from_position

clouddrift.kinematics.inertial_oscillation_from_position(longitude: ndarray, latitude: ndarray, relative_bandwidth: float | None = None, wavelet_duration: float | None = None, time_step: float | None = 3600.0, relative_vorticity: float | ndarray | None = 0.0) → ndarray

Extract inertial oscillations from consecutive geographical positions.

This function acts by performing a time-frequency analysis of horizontal displacements with analytic Morse wavelets. It extracts the portion of the wavelet transform signal that follows the inertial frequency (opposite of Coriolis frequency) as a function of time, potentially shifted in frequency by a measure of relative vorticity. The result is a pair of zonal and meridional relative displacements in meters.

This function is equivalent to a bandpass filtering of the horizontal displacements. The characteristics of the filter are defined by the relative bandwidth of the wavelet transform or by the duration of the wavelet, see the parameters below.

Parameters

longitudearray-like

Longitude sequence. Unidimensional array input.

latitudearray-like

Latitude sequence. Unidimensional array input.

relative_bandwidthfloat, optional

Bandwidth of the frequency-domain equivalent filter for the extraction of the inertial oscillations; a number less or equal to one which is a fraction of the inertial frequency. A value of 0.1 leads to a bandpass filter equivalent of +/- 10 percent of the inertial frequency.

wavelet_durationfloat, optional

Duration of the wavelet, or inverse of the relative bandwidth, which can be passed instead of the relative bandwidth.

time_stepfloat, optional

The constant time interval between data points in seconds. Default is 3600.

relative_vorticity: Optional, float or array-like

Relative vorticity adding to the local Coriolis frequency. If “f” is the Coriolis frequency then “f” + relative_vorticity will be the effective Coriolis frequency as defined by Kunze (1985). Positive values correspond to cyclonic vorticity, irrespectively of the latitudes of the data points.

Returns

xhatarray-like

Zonal relative displacement in meters from inertial oscillations.

yhatarray-like

Meridional relative displacement in meters from inertial oscillations.

Examples

To extract displacements from inertial oscillations from sequences of longitude and latitude values, equivalent to bandpass around 20 percent of the local inertial frequency:

>>> xhat, yhat = inertial_oscillation_from_position(longitude, latitude, relative_bandwidth=0.2)

The same result can be obtained by specifying the wavelet duration instead of the relative bandwidth:

>>> xhat, yhat = inertial_oscillation_from_position(longitude, latitude, wavelet_duration=5)

Next, the residual positions from the inertial displacements can be obtained with another function:

>>> residual_longitudes, residual_latitudes = residual_position_from_displacement(longitude, latitude, xhat, yhat)

Raises

ValueError

If longitude and latitude arrays do not have the same shape. If relative_vorticity is an array and does not have the same shape as longitude and latitude. If time_step is not a float. If both relative_bandwidth and wavelet_duration are specified. If neither relative_bandwidth nor wavelet_duration are specified. If the absolute value of relative_bandwidth is not in the range (0,1]. If the wavelet duration is not greater than or equal to 1.

See Also

residual_position_from_displacement(), wavelet_transform, morse_wavelet