BPMF.spectrum

class BPMF.spectrum.Spectrum(event=None, frequency_bands=None)

Bases: object

Class for handling spectral data and calculations.$a

compute_correction_factor(rho_source, rho_receiver, vp_source, vp_receiver, vs_source, vs_receiver, radiation_S=0.6324555320336759, radiation_P=0.5163977794943222)

Compute the correction factor and attenuation factor for a seismic event.

Parameters:

• rho_source (float) – Density of the source medium, in kg/m3.

• rho_receiver (float) – Density of the receiver medium, in kg/m3.

• vp_source (float) – P-wave velocity of the source medium, in m/s.

• vp_receiver (float) – P-wave velocity of the receiver medium, in m/s.

• vs_source (float) – S-wave velocity of the source medium, in m/s.

• vs_receiver (float) – S-wave velocity of the receiver medium, in m/s.

• radiation_S (float, optional) – Radiation coefficient for S-wave. Default is sqrt(2/5).

• radiation_P (float, optional) – Radiation coefficient for P-wave. Default is sqrt(4/15).

Returns:

The correction factor and attenuation factor are stored in the object’s attributes correction_factor and attenuation_factor.

Return type:

None

Notes

This method requires the object to have an attached BPMF.dataset.Event instance and for the instance to have called the set_source_receiver_dist(network) method.

compute_multi_band_spectrum(traces, phase, buffer_seconds, **kwargs)

Compute spectrum from the maximum amplitude in multiple 1-octave frequency bands.

Parameters:

• traces (list) – List of seismic traces.

• phase (str) – Phase of the seismic event. Should be ‘noise’, ‘p’, or ‘s’.

• buffer_seconds (float) – Buffer duration in seconds to remove from the beginning and end of the trace.

• **kwargs – Additional keyword arguments for filtering.

Returns:

The computed spectrum is stored in the object’s attribute {phase}_spectrum.

Return type:

None

Notes

• The attribute frequency_bands is required for this method.

• The spectrum is computed by finding the maximum amplitude in each 1-octave frequency band.

• The resulting spectrum and frequency values are stored in the spectrum dictionary.

• The relative distance error percentage is calculated and stored for each trace.

• The attribute {phase.lower()}_spectrum is updated with the computed spectrum.

• If the attribute phases exists, the phase is appended to the list. Otherwise, a new list is created.

compute_network_average_spectrum(phase, snr_threshold, correct_propagation=True, average_log=True, min_num_valid_channels_per_freq_bin=0, max_relative_distance_err_pct=25.0, reduce='mean', verbose=0)

Compute the network average spectrum for a given phase.

Parameters:

• phase (str) – Phase of the seismic event. Should be either ‘p’ or ‘s’.

• snr_threshold (float) – Signal-to-noise ratio threshold for valid channels.

• correct_propagation (bool, optional) – Flag indicating whether to correct for propagation effects. Default is True.

• average_log (bool, optional) – Flag indicating whether to average the logarithm of the spectra. Default is True.

• min_num_valid_channels_per_freq_bin (int, optional) – Minimum number of valid channels required per frequency bin. Default is 0.

• max_relative_distance_err_pct (float, optional) – Maximum relative distance error percentage for a valid channel. Default is 25.0.

• verbose (int, optional) – Verbosity level. Set to 0 for no output. Default is 0.

Returns:

The average spectrum and related information are stored in the object’s attributes.

Return type:

None

Notes

This method requires the object to have already computed the spectrum for the specified phase and to have set the target frequencies using the set_target_frequencies method. If correct_propagation is set to True, the method also requires the object to have computed the correction factor using the compute_correction_factor method.

compute_signal_to_noise_ratio(phase)

Compute the signal-to-noise ratio (SNR) for the specified phase.

Parameters:

phase (str) – Phase of the seismic event. Should be ‘p’ or ‘s’.

Returns:

The computed SNR values are stored in the object’s attribute snr_{phase}_spectrum.

Return type:

None

Raises:

AssertionError –

• If phase is not ‘p’ or ‘s’. - If the {phase} spectrum has not been computed. - If the noise spectrum has not been computed.

Notes

• The SNR is calculated as the modulus of the signal spectrum divided by the modulus of the noise spectrum.

• The SNR values and corresponding frequencies are stored in the snr dictionary.

• The attribute snr_{phase}_spectrum is updated with the computed SNR values.

compute_spectrum(traces, phase, taper=None, **taper_kwargs)

Compute spectrum using the Fast Fourier Transform (FFT) on the input traces.

Parameters:

• traces (list) – List of seismic traces.

• phase (str) – Phase of the seismic event. Should be ‘noise’, ‘p’, or ‘s’.

• taper (callable or None, optional) – Tapering function to apply to the traces before computing the spectrum. Default is None.

• **taper_kwargs – Additional keyword arguments for the tapering function.

Returns:

The computed spectrum is stored in the object’s attribute {phase}_spectrum.

Return type:

None

Notes

• The spectrum is computed using the FFT on the input traces.

• The computed spectrum and frequency values are stored in the spectrum dictionary.

• The relative distance error percentage is calculated and stored for each trace.

• The attribute {phase.lower()}_spectrum is updated with the computed spectrum.

• If the attribute phases exists, the phase is appended to the list. Otherwise, a new list is created.

differentiate(phase, average=True)

Apply differentiation to the spectrum of the specified phase.

Parameters:

• phase (str) – Phase of the seismic event. Should be ‘p’ or ‘s’.

• average (bool, optional) – Flag indicating whether to differentiate the average spectrum (True) or individual spectra (False). Defaults to True.

Returns:

The spectrum is modified in-place by multiplying it with the corresponding frequency values.

Return type:

None

Raises:

AssertionError –

• If average is True and the average {phase} spectrum has not been computed. - If average is False and the {phase} spectrum has not been computed.

fit_average_spectrum(phase, model='brune', log=True, min_fraction_valid_points_below_fc=0.1, min_fraction_valid_points=0.5, weighted=False, **kwargs)

Fit the average displacement spectrum with a specified model.

Parameters:

• phase (str) – Phase of the seismic event. Should be ‘p’ or ‘s’.

• model (str, optional) – Model to use for fitting the spectrum. Default is ‘brune’.

• log (bool, optional) – Flag indicating whether to fit the logarithm of the spectrum. Default is True.

• min_fraction_valid_points_below_fc (float, optional) – Minimum fraction of valid points required below the corner frequency. Default is 0.10.

• min_fraction_valid_points (float, optional) – Minimum fraction of valid points required overall. Default is 0.50.

• weighted (bool, optional) – Flag indicating whether to apply weighted fitting using sigmoid weights. Default is False.

• **kwargs – Additional keyword arguments to be passed to the curve fitting function.

Returns:

The fitting results are stored as attributes of the object.

Return type:

None

Raises:

AssertionError – If the average {phase} spectrum has not been computed.

Notes

• If the spectrum is below the SNR threshold everywhere, the fitting cannot be performed.

• If there are not enough valid points or valid points below the corner frequency, the fitting is considered unsuccessful.

integrate(phase, average=True)

Integrate the spectrum for a specific phase.

Parameters:

• phase (str) – Phase name. Should be ‘p’ or ‘s’.

• average (bool, optional) – Specifies whether to integrate the average spectrum (if True) or individual spectra (if False). Default is True.

Returns:

The spectrum is integrated in-place.

Return type:

None

Raises:

AssertionError – If the specified phase spectrum has not been computed.

plot_average_spectrum(phase, figname='spectrum', figtitle='', figsize=(10, 10), colors={'noise': 'dimgrey', 'p': 'C3', 's': 'black'}, linestyle={'noise': '--', 'p': '-', 's': '-'}, plot_fit=False, plot_std=False, plot_num_valid_channels=False)

Plot the average spectrum for a given phase.

Parameters:

• phase (str or list of str) – The phase(s) for which to plot the average spectrum.

• figname (str, optional) – The name of the figure. Default is “spectrum”.

• figtitle (str, optional) – The title of the figure. Default is an empty string.

• figsize (tuple, optional) – The size of the figure in inches. Default is (10, 10).

• colors (dict, optional) – A dictionary specifying the colors for different phases. Default is {“noise”: “dimgrey”, “s”: “black”, “p”: “C3”}.

• linestyle (dict, optional) – A dictionary specifying the line styles for different phases. Default is {“noise”: “–”, “s”: “-”, “p”: “-“}.

• plot_fit (bool, optional) – Whether to plot the fitted model spectrum. Default is False.

• plot_std (bool, optional) – Whether to plot the standard deviation range of the average spectrum. Default is False.

• plot_num_valid_channels (bool, optional) – Whether to plot the number of channels above the signal-to-noise ratio (SNR) threshold. Default is False.

Returns:

The generated figure.

Return type:

matplotlib.figure.Figure

plot_spectrum(phase, station=None, component=None, figname='spectrum', figsize=(10, 10), correct_propagation=False, plot_snr=False, colors={'noise': 'dimgrey', 'p': 'C3', 's': 'black'}, linestyle={'noise': '--', 'p': '-', 's': '-'})

Plot the spectrum for the specified phase(s) and trace(s).

Parameters:

• phase (str or list of str) – The phase(s) for which to plot the spectrum.

• station (str or None, optional) – The station code. If None, all stations will be plotted. Default is None.

• component (str or None, optional) – The component code. If None, all components will be plotted. Default is None.

• figname (str, optional) – The name of the figure. Default is “spectrum”.

• figsize (tuple, optional) – The size of the figure in inches. Default is (10, 10).

• correct_propagation (bool, optional) – Whether to correct the spectrum for propagation effects. Default is False.

• plot_snr (bool, optional) – Whether to plot the signal-to-noise ratio (SNR) spectrum if available. Default is False.

• colors (dict, optional) – A dictionary specifying the colors for different phases. Default is {“noise”: “dimgrey”, “s”: “black”, “p”: “C3”}.

• linestyle (dict, optional) – A dictionary specifying the line styles for different phases. Default is {“noise”: “–”, “s”: “-”, “p”: “-“}.

Returns:

The generated figure.

Return type:

matplotlib.figure.Figure

resample(new_frequencies, phase)

Resample the spectrum to new frequencies.

Parameters:

• new_frequencies (array-like) – New frequency values to resample the spectrum to.

• phase (str or list) – Phase(s) of the seismic event to resample. Can be a single phase or a list of phases.

Returns:

The spectrum is resampled and updated in-place.

Return type:

None

set_Q_model(Q, frequencies)

Set the attenuation Q model for P and S phases.

Parameters:

• Q (array-like) – Array of attenuation Q values.

• frequencies (array-like) – Array of corresponding frequencies. These are used to later keep track of which frequencies were used for the Q model.

Returns:

The Q model is stored in the Q0 attribute. The frequencies are stored in the Q0_frequencies attribute. These are later used to computed the Q-model and attenuation factor at arbitrary frequencies.

Return type:

None

set_frequency_bands(frequency_bands)

Set the frequency bands for spectrum analysis.

Parameters:

frequency_bands (dict) – Dictionary specifying the frequency bands. The keys are the names of the bands, and the values are tuples of the form (freqmin, freqmax). freqmin and freqmax represent the minimum and maximum frequencies of each band, respectively.

Returns:

The frequency bands are set and stored as an attribute in the object. The center frequencies of each band are also calculated and stored in the frequencies attribute.

Return type:

None

set_target_frequencies(freq_min, freq_max, num_points)

Set the target frequencies for spectrum analysis.

Parameters:

• freq_min (float) – Minimum frequency.

• freq_max (float) – Maximum frequency.

• num_points (int) – Number of target frequencies to generate.

Returns:

The target frequencies are set and stored as an attribute in the object.

Return type:

None

update_Q_model()

Interpolate the Q-model at the current self.frequencies.

update_attenuation_factor()

Compute attenuation factor at the current self.frequencies.

BPMF.spectrum.boatwright(freqs, omega0, fc, log=False)

Boatwright model.

BPMF.spectrum.brune(freqs, omega0, fc, log=False)

Brune model.

BPMF.spectrum.compute_moment_magnitude(event, mag_params, plot_above_Mw=100.0, plot_above_random=1.0, path_figures='', phases=['p', 's'], plot=False, figsize=(8, 8))

BPMF.spectrum.fc_circular_crack(Mw, stress_drop_Pa=1000000.0, phase='p', vs_m_per_s=3500.0, vr_vs_ratio=0.9)

Compute the corner frequency assuming a circular crack model (Eshelby).

Parameters:

• Mw (float) – Moment magnitude of the earthquake.

• stress_drop_Pa (float, optional) – Stress drop in Pascals. Default is 1.0e6.

• phase (str, optional) – Seismic phase. Valid values are ‘p’ for P-wave and ‘s’ for S-wave. Default is ‘p’.

• vs_m_per_s (float, optional) – Shear wave velocity in meters per second. Default is 3500.0.

• vr_vs_ratio (float, optional) – Ratio of rupture velocity to shear wave velocity. Default is 0.9.

Returns:

corner_frequency – Corner frequency in Hertz.

Return type:

float

Raises:

AssertionError – If phase is not ‘p’ or ‘s’.

BPMF.spectrum.magnitude_to_moment(Mw)

Convert moment magnitude to seismic moment [N.m].

BPMF.spectrum.moment_to_magnitude(M0)

Convert seismic moment [N.m] to moment magnitude.

BPMF.spectrum.stress_drop_circular_crack(Mw, fc, phase='p', vs_m_per_s=3500.0, vr_vs_ratio=0.9)

Compute the stress drop assuming a circular crack model (Eshelby).

Parameters:

• Mw (float) – Moment magnitude of the earthquake.

• fc (float) – Corner frequency in Hertz.

• phase (str, optional) – Seismic phase. Valid values are ‘p’ for P-wave and ‘s’ for S-wave. Default is ‘p’.

• vs_m_per_s (float, optional) – Shear wave velocity in meters per second. Default is 3500.0.

• vr_vs_ratio (float, optional) – Ratio of rupture velocity to shear wave velocity. Default is 0.9.

Returns:

stress_drop – Stress drop in Pascals.

Return type:

float

Raises:

AssertionError – If phase is not ‘p’ or ‘s’.