Class PSD

Contains the definition of SAUL’s PSD class.

class saul.spectral.psd.PSD[source]

A class for calculating and plotting PSDs of one or more waveforms.

Attributes

method

See __init__()

Type:

str

win_dur

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

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

st

Input waveforms (single Trace input is converted to SAUL Stream)

Type:

SAUL Stream

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 waveforms

Type:

str or None

psd

List of PSDs (in dB) calculated from input waveforms; of the form [(f1, pxx_db1), (f2, pxx_db2), ...] given a Stream consisting of Trace entries [tr1, tr2, ...]

Type:

list

Methods

__init__(tr_or_st, method='welch', win_dur=60, time_bandwidth_product=4, number_of_tapers=7, units='infer')[source]

Create a PSD object.

The PSDs of the input waveforms are estimated in this method. Two spectral estimation approaches are supported: Welch’s method (scipy.signal.welch()) and the multitaper method (mtspec.MTSpec). The input arguments (below) relevant for each method are marked with a [W] for Welch’s method and an [M] for the multitaper method. Arguments corresponding to the non-selected method are ignored.

Parameters:

  • tr_or_st (Trace or Stream) – Input waveforms

  • method (str) – Either 'welch' [W] or 'multitaper' [M]

  • win_dur (int or float) – [W] Segment length in seconds. This usually must be tweaked to obtain the cleanest-looking plot and 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

  • units (str or None) – Units of the input waveforms; 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) — all input waveforms must have the same units!

plot(db_lim='smart', use_period=False, log_x=True, show_noise_models=False, infra_noise_model='ak')[source]

Plot the calculated PSDs.

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, x-axis will be period [s] instead of frequency [Hz]

  • log_x (bool) – If True, use log scaling for x-axis

  • show_noise_models (bool) – Whether to plot reference noise models

  • infra_noise_model (str) – Which infrasound noise model to use (only used if show_noise_models is True and self.data_kind is 'infrasound'), one of 'ak' (Alaska noise model) or 'idc' (IMS array noise model)

smooth(bandwidth)[source]

Smooth the calculated PSDs via the Konno–Ohmachi method.

The Konno–Ohmachi method smooths PSDs using fixed-bandwith windows. The C code used by this method is here. The ObsPy documentation for a similar function may also be helpful.

For more information, see equation 4 in Konno and Ohmachi (1998) — the \(b\) in that equation is the bandwidth parameter here.

Konno, K., & Ohmachi, T. (1998). Ground-motion characteristics estimated from spectral ratio between horizontal and vertical components of microtremor. Bulletin of the Seismological Society of America, 88(1), 228–241. https://doi.org/10.1785/BSSA0880010228

Note

The smoothing is performed in-place on the existing spectra in this object!

Parameters:

bandwidth (int or float) – Bandwidth for smoothing — lower values produce a broader smoothing effect

copy()[source]

Return a deep copy of the PSD object.