Wave dispersion curve calculator

A function to calculate and plot the dispersion curve (group velocity as a function of wave period) of a wave packet.

This function numerically calculates and plots the dispersion curve (group velocity as a function of wave period) of a wave packet by applying the FTAN (Frequency-Time Analysis) method proposed by Levshin et al in a 1972 entitled "On a frequency-time analysis of oscillations" for applications such as the analysis of seismic surface waves.

INPUT PARAMETERS:

x: One-dimensional column array containing the signal with the wave.

fs: Signal sampling frequency (Hz).

alpha: A parameter that determines the time-frequency resolution of the filtering. Higher values for higher frequency resolution, lower values for higher time resolution.

fini: The lowest filtering central frequency. It determines the upper bound of the curve's period (horizontal) axis.

fend: The highest filtering central frequency. It determines the lower bound of the curve's period (horizontal) axis.

df: The spacing between two consecutive filtering central frequencies.

dist: The distance (usually, in km) between the wave source and the signal's measurement point

Ulim: The upper limit of the group velocity for plotting (vertical axis)

levels: The number of contour level curves in the figure showing the dispersion curve and the FTAN output function

OUTPUTS:

Ug: One-dimensional array that contains the dispersion curve representing the wave group velocities (in units of distance/s).

F: Vector containing the wave frequency (in Hz) that corresponds to each value of the dispersion curve array Ug.

T: Vector containing the wave period (in s) that corresponds to each value of the dispersion curve array Ug.

U: The vector of wave group velocities for plotting (vertical axis).

y: Two-dimensional array containing the FTAN output function (it represents the log-scale instantaneous amplitude of the filtered signal for each filtering central frequency in time domain).