rsqsim_api.catalogue.utilities

Utility functions for RSQSim catalogue statistics and seismological calculations.

Provides magnitude–moment conversions, b-value estimation, stress drop and scaling-parameter calculations, and helper functions for computing weighted circular statistics.

Functions

`calculate_b_value_kijko_smit`(magnitudes[, min_mw, max_mw])	Estimate the Gutenberg-Richter b-value using the Kijko and Smit (2012) method.
`calculate_scaling_c`(magnitudes, areas)	Calculate the Gutenberg-Richter scaling parameter c.
`calculate_stress_drop`(seismic_moments, areas[, stress_c])	Calculate stress drop from seismic moments and rupture areas.
`summary_statistics`(dataframe[, stress_c])	Compute summary statistics for a catalogue DataFrame.
`mw_to_m0`(magnitudes)	Convert moment magnitude to scalar seismic moment.
`m0_to_mw`(seismic_moment)	Convert scalar seismic moment to moment magnitude.
`weighted_circular_mean`(azimuths, weights)	Compute the weighted circular (angular) mean of a set of azimuths.
`median_cumulant`(m0_array, mw_array)	Compute the median cumulant magnitude for a set of events on a patch.
`jit_intersect`(l1, l2)	JIT-compiled intersection of two integer arrays.
`mw_from_area_and_scaling_c`(area, c)	Calculate moment magnitude from rupture area and scaling parameter c.
`slip_from_area_and_scaling_c`(area, c[, mu])	Calculate mean slip from rupture area and scaling parameter c.

Module Contents

rsqsim_api.catalogue.utilities.calculate_b_value_kijko_smit(magnitudes, min_mw=0.0, max_mw=10.0)[source]

Estimate the Gutenberg-Richter b-value using the Kijko and Smit (2012) method.

Parameters:

magnitudes (numpy.ndarray) – Array of moment magnitudes.
min_mw (float, optional) – Lower magnitude cutoff. Events below this are excluded. Defaults to 0.0.
max_mw (float, optional) – Upper magnitude cutoff. Events above this are excluded. Defaults to 10.0.

Returns:

Estimated b-value (log₁₀ base).

Return type:

float

rsqsim_api.catalogue.utilities.calculate_scaling_c(magnitudes, areas)[source]

Calculate the Gutenberg-Richter scaling parameter c.

The parameter c is defined as Mw - log10(area) + 6, where area is in m².

Parameters:

magnitudes (numpy.ndarray) – Array of moment magnitudes.
areas (numpy.ndarray) – Array of rupture areas in m².

Returns:

Scaling parameter c for each event.

Return type:

numpy.ndarray

rsqsim_api.catalogue.utilities.calculate_stress_drop(seismic_moments, areas, stress_c=2.44)[source]

Calculate stress drop from seismic moments and rupture areas.

Uses the relation Δσ = C * M0 / A^1.5. Typical values of C are 2.44 for a circular crack, and 2.53, 3.02, 5.21 for rectangular cracks with aspect ratios of 1, 4, and 16, respectively.

Parameters:

seismic_moments (numpy.ndarray) – Scalar seismic moments in N·m.
areas (numpy.ndarray) – Rupture areas in m².
stress_c (float, optional) – Shape constant. Defaults to 2.44 (circular crack).

Returns:

Stress drop in Pa for each event.

Return type:

numpy.ndarray

rsqsim_api.catalogue.utilities.summary_statistics(dataframe, stress_c=2.44)[source]

Compute summary statistics for a catalogue DataFrame.

Calculates the 5th, 50th, and 95th percentiles of the scaling parameter c and the stress drop, together with the maximum magnitude.

Parameters:

dataframe (pandas.DataFrame) – Catalogue DataFrame with columns "mw", "area" (m²), and "m0" (N·m).
stress_c (float, optional) – Shape constant passed to calculate_stress_drop(). Defaults to 2.44.

Returns:

Series with index ["Max Mw, 5th C, 50th C, 95th C, 5th SD, 50th SD, 95th SD"] where C is the scaling parameter and SD is the stress drop in MPa.

Return type:

pandas.Series

rsqsim_api.catalogue.utilities.mw_to_m0(magnitudes)[source]

Convert moment magnitude to scalar seismic moment.

Uses the relation M0 = 10^(1.5 * Mw + 9.05).

Parameters:: magnitudes (numpy.ndarray) – Array of moment magnitudes.
Returns:: Scalar seismic moments in N·m.
Return type:: numpy.ndarray

rsqsim_api.catalogue.utilities.m0_to_mw(seismic_moment)[source]

Convert scalar seismic moment to moment magnitude.

Uses the relation Mw = (log10(M0) - 9.05) / 1.5.

Parameters:: seismic_moment (float) – Scalar seismic moment in N·m.
Returns:: Moment magnitude.
Return type:: float

rsqsim_api.catalogue.utilities.weighted_circular_mean(azimuths, weights)[source]

Compute the weighted circular (angular) mean of a set of azimuths.

Parameters:

azimuths (numpy.ndarray) – Azimuth values in degrees.
weights (numpy.ndarray) – Weights for each azimuth (e.g. patch areas or seismic moments).

Returns:

Weighted circular mean azimuth in degrees.

Return type:

float

rsqsim_api.catalogue.utilities.median_cumulant(m0_array, mw_array)[source]

Compute the median cumulant magnitude for a set of events on a patch.

Sorts events by M0, forms the normalised cumulative sum of Mw, and returns the Mw at the index where the cumulative sum first reaches 0.5.

Parameters:

m0_array (numpy.ndarray) – Scalar seismic moments (N·m) for all events rupturing a patch.
mw_array (numpy.ndarray) – Corresponding moment magnitudes.

Returns:

Moment magnitude at the median of the cumulative M0 distribution.

Return type:

float

rsqsim_api.catalogue.utilities.jit_intersect(l1, l2)[source]

JIT-compiled intersection of two integer arrays.

Returns the unique values that appear in both l1 and l2.

Parameters:

l1 (numpy.ndarray of int32) – First integer array.
l2 (numpy.ndarray of int32) – Second integer array.

Returns:

Sorted unique values present in both arrays.

Return type:

numpy.ndarray of int32

rsqsim_api.catalogue.utilities.mw_from_area_and_scaling_c(area, c)[source]

Calculate moment magnitude from rupture area and scaling parameter c.

Uses the relation Mw = log10(area) - 6 + c.

Parameters:

area (float) – Rupture area in m².
c (float) – Scaling parameter (typically ~4.2 for New Zealand crustal faults).

Returns:

Moment magnitude.

Return type:

float

rsqsim_api.catalogue.utilities.slip_from_area_and_scaling_c(area, c, mu=30000000000.0)[source]

Calculate mean slip from rupture area and scaling parameter c.

Computes the seismic moment from the area and c, then divides by mu * area to give the average slip.

Parameters:

area (float) – Rupture area in m².
c (float) – Scaling parameter (typically ~4.2 for New Zealand crustal faults).
mu (float, optional) – Shear modulus in Pa. Defaults to 3×10¹⁰ Pa (30 GPa).

Returns:

Average slip in metres.

Return type:

float