digger.analyze.spectrogram

Module Contents

Functions

spectrogram

This function takes as arguments a single arrival time (t0) and eta array, both of which can be derived from gauge2ts output, as well as the total simulation length and the constant sample rate of the input data. It then calculates the frequency spectrum of the data and outputs frequency domain data as well as a spectrogram (window length can be modified if desired) of the full time series, including simulation time prior to wave arrival.

API

digger.analyze.spectrogram.spectrogram(t0, simlength, eta, samprate, gauge, window=1000, waterlevel=0, plot=False, plotname='spectrum', plotform='png', dpi=210, outdir=None)

This function takes as arguments a single arrival time (t0) and eta array, both of which can be derived from gauge2ts output, as well as the total simulation length and the constant sample rate of the input data. It then calculates the frequency spectrum of the data and outputs frequency domain data as well as a spectrogram (window length can be modified if desired) of the full time series, including simulation time prior to wave arrival.

Uses wave arrival time (t0) and amplitude array (eta) to generate a frequency series and spectrogram (using fast Fourier transform) for spectral analysis of wave data. A detrended (simple) time series is also output. The default values are tailored toward analysis of water wave data, but can be adapted for any wave type.

This analysis requires that input data be equally-spaced in time corresponding to the provided sample rate. The accompanying function, gauge2ts, can perform this task.

Any time between the start of the simulation (t=0) and the time of wave arrival (it is assumed that t[0] != 0) is padded with zeros at the defined sample rate. This enables an accurate depiction of the frequency domain from the start of the simulation.

Inputs:

t0:

float value for the time of wave arrival (i.e., time of first non-zero eta value in the simulation)

simlength:

total length (seconds) of simulation from initiation (t=0) to conclusion; this is independent of t0, i.e., if the simulation runs from 0 to 3600 seconds, even if the wave doesn’t arrive at a given gage until t0=t seconds, simlength will always be 3600 seconds

eta:

numpy 1-D array containing wave amplitudes

samprate:

sample rate (Hz) of input data

gauge:

number or name of source gage, used only for labels in plotting

window:

window length in seconds for fast Fourier transform (default: 1000)

waterlevel:

baseline amplitude, e.g., sea level (default: 0)

plot:

boolean, whether to output plots (default: False)

plotname:

name for output plot (without extension), required if plot=True

plotform:

format for output plot, required if plot=True

dpi:

dots per inch resolution of the output plot

outdir:

directory for output plot, if desired (default: None); if left as default, figures will output to current working directory

Outputs:

times:

numpy 1-D array containing sampling times (in seconds)

amps:

numpy 1-D array containing wave amplitudes for each instance of times

xf:

numpy 1-D array containing sampled frequencies in the FFT

yf:

numpy 1-D array containing normalized transformed amplitudes