Class Spectrogram

Contains the definition of SAUL’s Spectrogram class.

class saul.spectral.spectrogram.Spectrogram[source]

A class for calculating and plotting spectrograms of waveforms.

Attributes

method

See __init__()

Type:

str

win_dur

See __init__(); only defined if method='scipy' or method='multitaper'

Type:

int or float

time_bandwidth_product

See __init__(); only defined if method='multitaper'

Type:

float

number_of_tapers

See __init__(); only defined if method='multitaper'

Type:

int

gamma

See __init__(); only defined if method='s_transform'

Type:

float

max_fs

See __init__(); only defined if method='s_transform'

Type:

int or float

tr

Input waveform

Type:

Trace

data_kind

Input waveform data kind; e.g., 'infrasound' or 'seismic' (inferred from channel code)

Type:

str

db_ref_val

dB reference value for PSD (data kind dependent)

Type:

int, float, or None

waveform_units

Units of the input waveform

Type:

str or None

spectrogram

Spectrogram (in dB) calculated from the input waveform; of the form (f, t, sxx_db) where f and t are 1D arrays and sxx_db is a 2D array with shape (f.size, t.size)

Type:

tuple

Methods

__init__(tr_or_st, method='scipy', win_dur=8, time_bandwidth_product=4, number_of_tapers=7, gamma=1, max_fs=10, units='infer')[source]

Create a Spectrogram object.

The spectrogram of the input waveform is estimated in this method (only a single waveform may be provided). Three spectral estimation approaches are supported: The method implemented by SciPy (scipy.signal.spectrogram()), the multitaper method (mtspec.spectrogram()), and the \(S\) transform (implemented in the Stockwell package). The input arguments (below) relevant for each method are marked with a [P] for the SciPy method, an [M] for the multitaper method, and an [S] for the \(S\) transform. Arguments corresponding to the non-selected method are ignored.

Parameters:

  • tr_or_st (Trace or Stream) – Input waveform

  • method (str) – Either 'scipy' [P], 'multitaper' [M], or 's_transform' [S]

  • win_dur (int or float) – [P] [M] Segment length in seconds. This usually must be adjusted, within the constraints of the total signal duration, to ensure that the longest-period signals of interest are included

  • time_bandwidth_product (float) – [M] Time-bandwidth product

  • number_of_tapers (int) – [M] Number of tapers to use

  • gamma (float) – [S] Gamma parameter, see here for more info

  • max_fs (int or float) – [S] Maximum allowed sampling rate in hertz. If an input signal has a sampling rate higher than this, it will be downsampled before the \(S\) transform is computed (this saves computation time and memory)

  • units (str or None) – Units of the input waveform; either 'infer' to guess from input response information, a string explicitly defining the units (see _VALID_UNIT_OPTIONS in saul.waveform.units for supported options), or None for unknown units (e.g., counts)

plot(db_lim='smart', use_period=False, log_y=False)[source]

Plot the calculated spectrogram.

Parameters:

  • db_lim (tuple, str, or None) – Tuple defining min and max dB cutoffs, 'smart' for a sensible automatic choice, or None for no clipping

  • use_period (bool) – If True, spectrogram y-axis will be period [s] instead of frequency [Hz]

  • log_y (bool) – If True, use log scaling for spectrogram y-axis

copy()[source]

Return a deep copy of the Spectrogram object.