Frequency_Spectrum#

class PySeismoSoil.class_frequency_spectrum.Frequency_Spectrum(data: str | numpy.ndarray, *, df: float = None, interpolate: bool = False, fmin: float = 0.1, fmax: float = 30, n_pts: int = 1000, log_scale: bool = True, sep: str = '\t')[source]#

Bases: object

Class implementation of a frequency spectrum object. The user-supplied frequency spectrum is internally interpolated onto a reference frequency array. (If frequency range implied in data and/or df goes beyond fmin and/or fmax, then the interpolation algorithm automatically use the 0th and the last point in the extrapolated parts.)

Parameters:

  • data (str | np.ndarray) – If str: the full file name on the hard drive containing the data. If np.ndarray: the numpy array containing the data. The data can have one column (which contains the spectrum) or two columns (0st column: freq; 1st column: spectrum). If only one column is supplied, another input parameter df must also be supplied.

  • df (float) – Frequency interval. Not necessary if data has two columns (with the 0th column being the frequency information). If data has one column, it is assumed that the values in data correspond to a linear frequency array.

  • interpolate (bool) – Whether to use the interpolated spectra in place of the raw data.

  • fmin (float) – Minimum frequency of the manuall constructed frequency array for interpolation. It has no effect if interpolate is False.

  • fmax (float) – Maximum frequency of the manually constructed frequency array for interpolation. It has no effect if interpolate is False.

  • n_pts (int) – Number of points in the manualy constructed frequency array for interpolation. It has no effect if interpolate is False.

  • log_scale (bool) – Whether the manually constructed frequency (for interpolation) array is in log scale (or linear scale). It has no effect if interpolate is False.

  • sep (str) – Delimiter identifier, only useful if data is a file name.

raw_df#

Original frequency interval as entered.

Type:

float

raw_data#

Raw frequency spectrum (before interpolation) that the user provided.

Type:

np.ndarray

n_pts#

Same as the input parameter.

Type:

int

freq#

The reference frequency array for interpolation.

Type:

np.ndarray

fmin#

Same as the input parameter.

Type:

float

fmax#

Same as the input parameter.

Type:

float

spectrum_2col#

A two-column numpy array (frequency and spectrum).

Type:

np.ndarray

spectrum#

Just the spectrum values.

Type:

np.ndarray

amplitude#

The amplitude (or “magnitude”) of spectrum. Note that spectrum can already be all real numbers.

Type:

np.ndarray

amplitude_2col#

A two-column numpy array (frequency and amplitude).

Type:

np.ndarray

phase#

The phase angle of spectrum. If spectrum has all real values, phase is all zeros.

Type:

np.ndarray

phase_2col#

A two-column numpy array (frequency and phase).

Type:

np.ndarray

iscomplex#

Is spectrum complex or already real?

Type:

bool

Methods Summary

get_f0()

Get the "fundamental frequency" of the amplitude spectrum, which is the frequency of the first amplitude peak.

get_smoothed([win_len, show_fig])

Smooth the spectrum by calculating the convolution of the raw signal and the smoothing window.

get_unwrapped_phase([robust])

Unwrpped the phase component of the spectrum.

plot([fig, ax, figsize, dpi, logx, logy, ...])

Plot the shape of the interpolated spectrum.

Methods Documentation

get_f0() → float[source]#

Get the “fundamental frequency” of the amplitude spectrum, which is the frequency of the first amplitude peak.

Returns:

f0 – The fundamental frequency.

Return type:

float

get_smoothed(win_len: int = 15, show_fig: bool = False, *, log_scale: bool, **kwargs: dict[Any, Any]) → tuple[numpy.ndarray | None, matplotlib.figure.Figure, matplotlib.axes._axes.Axes][source]#

Smooth the spectrum by calculating the convolution of the raw signal and the smoothing window.

Parameters:

  • win_len (int) – Length of the smoothing window. Larget numbers means more smoothing.

  • show_fig (bool) – Whether to show a before/after figure.

  • log_scale (bool) – Whether the frequency spacing of this frequency spectrum is in log scale (otherwise, linear scale). If this argument is incorrect, it could lead to strange smoothing results.

  • **kwargs (dict[Any, Any]) – Extra keyword arguments get passed to the function helper_signal_processing.log_smooth().

Returns:

  • sm (np.ndarray | None) – The smoothed signal. 1D numpy array.

  • fig (Figure) – The figure object being created or being passed into this function.

  • ax (Axes) – The axes object being created or being passed into this function.

get_unwrapped_phase(robust: bool = True) → Frequency_Spectrum[source]#

Unwrpped the phase component of the spectrum.

Parameters:

robust (bool) – When unwrapping, whether to use the robust adjustment or not. Turning this option on can help mitigate some issues associated with incomplete unwrapping due to discretization errors.

Returns:

unwrapped – A frequency spectrum with unwrapped phase component.

Return type:

Frequency_Spectrum

plot(fig: matplotlib.figure.Figure | None = None, ax: matplotlib.axes._axes.Axes | None = None, figsize: tuple[float, float] = None, dpi: float = 100, logx: bool = True, logy: bool = False, plot_abs: bool = False, **kwargs_plot: dict[Any, Any]) → tuple[matplotlib.figure.Figure, matplotlib.axes._axes.Axes][source]#

Plot the shape of the interpolated spectrum.

Parameters:

  • fig (Figure | None) – Figure object. If None, a new figure will be created.

  • ax (Axes | None) – Axes object. If None, a new axes will be created.

  • figsize (tuple[float, float]) – Figure size in inches, as a tuple of two numbers. The figure size of fig (if not None) will override this parameter.

  • dpi (float) – Figure resolution. The dpi of fig (if not None) will override this parameter.

  • logx (bool) – Whether to show x scale as log.

  • logy (bool) – Whether to show y scale as log.

  • plot_abs (bool) – Whether to plot the absolute values of the spectrum.

  • **kwargs_plot (dict[Any, Any]) – Extra keyword arguments are passed to matplotlib.pyplot.plot().

Returns:

  • fig (Figure) – The figure object being created or being passed into this function.

  • ax (Axes) – The axes object being created or being passed into this function.