Magnitudes¶

Qseek calculates magnitudes for every detection. magnitudes is a list, so you can calculate several magnitudes at once, e.g. a local magnitude and a moment magnitude.

Local and moment magnitude

"magnitudes": [
  {"magnitude": "LocalMagnitude", "model": "iceland-reykjanes"},
  {"magnitude": "MomentMagnitude", "gf_store_dirs": ["gf-stores/"]}
]

Both measure peak amplitudes on restituted waveforms, so the stations need instrument responses from StationXML. A station magnitude needs a signal-to-noise ratio above min_signal_noise_ratio; the network magnitude needs at least min_stations station magnitudes.

Local magnitude¶

The local magnitude (ML) uses a regional attenuation model. Choose the model of your region:

Model	Reference	Distance range	Amplitude
`webnet-western-bohemia`	Horálek et al. (2000)	0–100 km hypocentral	velocity
`iaspei-southern-california`	Hutton and Boore (1987)	10–700 km hypocentral	wood-anderson-old
`southern-california`	Hutton and Boore (1987)	10–700 km hypocentral	wood-anderson-old
`central-california`	Bakun and Joyner (1984)	0–400 km epicentral	wood-anderson-old
`california-integrated-seismic-network`	Urhammer et. al (2011)	0–450 km epicentral	wood-anderson-old
`eastern-north-america`	Kim (1998)	100–800 km epicentral	wood-anderson
`argentiere-glacier`	Roux et al. (2008)	0–100 km hypocentral	wood-anderson-2800
`albania`	Muco and Minga (1991)	10–600 km epicentral	wood-anderson
`south-west-germany`	Stange (2006)	10–1000 km hypocentral	wood-anderson
`south-australia`	Greenhalgh and Singh (1986)	40–700 km epicentral	wood-anderson
`norway-fennoscandia`	Alsaker et al. (1991)	0–1500 km hypocentral	wood-anderson
`iceland-askja`	Greenfield et al. (2020)	0–150 km hypocentral	wood-anderson
`iceland-bardabunga`	Greenfield et al. (2020)	0–150 km hypocentral	wood-anderson
`iceland-askja-bardabunga-combined`	Greenfield et al. (2020)	0–150 km hypocentral	wood-anderson
`iceland-reykjanes`	Greenfield et al. (2022)	0–40 km hypocentral	wood-anderson
`azores`	Gongora et al. (2004)	10–800 km epicentral	wood-anderson
`argentina-volcanoes`	Montenegro et al. (2021)	0–100 km epicentral	wood-anderson
`netherlands-groningen`	Dost et al. (2018)	0–80 km epicentral	wood-anderson
`campi-flegrei`	Petrosino et al. (2008)	0.2–8 km epicentral	wood-anderson-2800

If no model fits, define your own attenuation with a CustomLocalMagnitudeModel as model. For each station, matched by its station code with wildcards, an attenuation model gives

\[ M_L = \log_{10} A + a \log_{10} r + b\,r + c \]

with the amplitude \(A\) (Wood-Anderson amplitude in mm) and the epicentral or hypocentral distance \(r\) in km. This example writes the relation of Hutton and Boore (1987) for all stations:

Custom local magnitude model

"magnitudes": [
  {
    "magnitude": "LocalMagnitude",
    "model": {
      "distance": "hypocentral",
      "max_amplitude": "wood-anderson",
      "attenuation_models": {
        "*": {"a": 1.11, "b": 0.00189, "c": 0.591}
      }
    }
  }
]

LocalMagnitude

{
  "magnitude": "LocalMagnitude",
  "min_stations": 3,
  "exclude_stations": [],
  "noise_window": 5.0,
  "seconds_after": 4.0,
  "taper_seconds": 10.0,
  "min_signal_noise_ratio": 3.0,
  "max_station_std": 3.0,
  "model": "iaspei-southern-california",
  "use_mean": false,
  "export_mseed": null
}

LocalMagnitude `pydantic-model` ¶

Bases: EventMagnitudeCalculator

Local magnitude (ML) from peak amplitudes.

The station magnitudes are calculated with a regional attenuation model from the peak amplitudes of the restituted waveforms. The network magnitude combines the station magnitudes.

Fields:

min_stations (PositiveInt)
exclude_stations (list[NSL])
magnitude (Literal['LocalMagnitude'])
noise_window (PositiveFloat)
seconds_after (PositiveFloat)
taper_seconds (PositiveFloat)
min_signal_noise_ratio (float)
max_station_std (float)
model (ModelName | CustomLocalMagnitudeModel)
use_mean (bool)
export_mseed (Path | None)

Validators:

validate_model

noise_window `pydantic-field` ¶

noise_window: PositiveFloat = 5.0

Length in seconds of the waveform before the P arrival. The noise amplitude is measured in this window, up to 1 s before the P arrival.

seconds_after `pydantic-field` ¶

seconds_after: PositiveFloat = 4.0

Length in seconds of the waveform after the S arrival.

taper_seconds `pydantic-field` ¶

taper_seconds: PositiveFloat = 10.0

Length in seconds of the taper before and after the waveform. The taper stabilizes the restitution and is cut off before the analysis.

min_signal_noise_ratio `pydantic-field` ¶

min_signal_noise_ratio: float = 3.0

Minimum signal-to-noise ratio of a station magnitude. The noise amplitude is measured in the noise_window, up to 1 s before the P arrival.

max_station_std `pydantic-field` ¶

max_station_std: float = 3.0

Station magnitudes that deviate from the network magnitude by more than this many standard deviations are disregarded.

model `pydantic-field` ¶

model: ModelName | CustomLocalMagnitudeModel = (
    "iaspei-southern-california"
)

The amplitude attenuation model to use for calculating the local magnitude, or a custom local magnitude model.

use_mean `pydantic-field` ¶

use_mean: bool = False

Whether to use the mean or median of the station magnitudes for the network magnitude. The median is more robust to outliers, but the mean is more accurate if the station magnitudes are normally distributed.

export_mseed `pydantic-field` ¶

export_mseed: Path | None = None

Path to export the processed mseed traces to.

min_stations `pydantic-field` ¶

min_stations: PositiveInt = 3

Minimum number of station magnitudes required to calculate the network magnitude.

exclude_stations `pydantic-field` ¶

exclude_stations: list[NSL] = []

List of station NSLs to exclude from magnitude calculation.

get_magnitude `async` ¶

get_magnitude(
    waveform_provider: WaveformProvider,
    stations: StationInventory,
    event: EventDetection,
) -> EventLocalMagnitude

Calculate the local magnitude for the given event.

The local magnitude is calculated by extracting the restituted waveforms for the event, applying the appropriate transfer function for the model, and then calculating the station magnitudes and average magnitude using the model.

Parameters:

Name	Type	Description	Default
`waveform_provider`	`WaveformProvider`	The waveform provider to use for extracting the waveforms.	required
`stations`	`StationInventory`	The station inventory to use for calculating the station magnitudes.	required
`event`	`EventDetection`	The event for which to calculate the local magnitude.	required

get_station_magnitude ¶

get_station_magnitude(
    model: LocalMagnitudeModel,
    event: EventDetection,
    receiver: Receiver,
    traces: list[Trace],
) -> StationLocalMagnitude

Calculate the local magnitude for a given event and receiver.

Parameters:

Name	Type	Description	Default
`model`	`LocalMagnitudeModel`	The local magnitude model to use for the calculation.	required
`event`	`EventDetection`	The event to calculate the magnitude for.	required
`receiver`	`Receiver`	The seismic station to calculate the magnitude for.	required
`traces`	`list[Trace]`	The traces to calculate the magnitude for.	required

Returns:

Name	Type	Description
`StationLocalMagnitude`	`StationLocalMagnitude`	The calculated magnitude or None if the magnitude could not be determined.

get_subclasses `classmethod` ¶

get_subclasses() -> tuple[
    type[EventMagnitudeCalculator], ...
]

Get the subclasses of this class.

Returns:

Type	Description
`tuple[type[EventMagnitudeCalculator], ...]`	list[type]: The subclasses of this class.

prepare `async` ¶

prepare(octree: Octree, stations: StationInventory) -> None

Prepare the magnitudes calculation by initializing necessary data structures.

Parameters:

Name	Type	Description	Default
`octree`	`Octree`	The octree containing seismic event data.	required
`stations`	`Stations`	The stations containing seismic station data.	required

Raises:

Type	Description
`NotImplementedError`	This method must be implemented by subclasses.

Moment magnitude¶

The moment magnitude (Mw) compares the observed peak amplitudes with peak amplitudes modeled from Pyrocko GF stores, Green's function databases for your velocity model. The method is described in Dahm et al., 2024.

MomentMagnitude

{
  "magnitude": "MomentMagnitude",
  "min_stations": 3,
  "exclude_stations": [],
  "noise_window": 5.0,
  "seconds_after": 4.0,
  "taper_seconds": 10.0,
  "min_signal_noise_ratio": 1.5,
  "max_station_std": 3.0,
  "gf_store_dirs": [
    "."
  ],
  "export_mseed": null,
  "models": [
    {
      "gf_store_id": "moment_magnitude",
      "quantity": "displacement",
      "frequency_range": [
        2.0,
        20.0
      ],
      "max_distance": 100000.0,
      "source_depth_delta": 1000.0,
      "reference_magnitude": 1.0,
      "rupture_velocities": [
        0.8,
        0.9
      ],
      "stress_drop": [
        1000000.0,
        10000000.0
      ],
      "gf_interpolation": "multilinear",
      "nsl_id": null,
      "peak_amplitude": "absolute",
      "station_epicentral_range": [
        1000.0,
        100000.0
      ]
    }
  ]
}

MomentMagnitude `pydantic-model` ¶

Bases: EventMagnitudeCalculator

Moment magnitude (Mw) from peak amplitudes.

The peak amplitudes are compared to modeled peak amplitudes from Pyrocko GF stores (Dahm et al., 2024).

Fields:

min_stations (PositiveInt)
exclude_stations (list[NSL])
magnitude (Literal['MomentMagnitude'])
noise_window (PositiveFloat)
seconds_after (PositiveFloat)
taper_seconds (PositiveFloat)
min_signal_noise_ratio (float)
max_station_std (float)
gf_store_dirs (list[DirectoryPath])
export_mseed (Path | None)
models (list[PeakAmplitudeDefinition])

noise_window `pydantic-field` ¶

noise_window: PositiveFloat = 5.0

Length in seconds of the waveform before the P arrival. The noise amplitude is measured in this window, up to 0.5 s before the P arrival.

seconds_after `pydantic-field` ¶

seconds_after: PositiveFloat = 4.0

Length in seconds of the waveform after the S arrival.

taper_seconds `pydantic-field` ¶

taper_seconds: PositiveFloat = 10.0

Length in seconds of the taper before and after the waveform. The taper stabilizes the restitution and is cut off before the analysis.

min_signal_noise_ratio `pydantic-field` ¶

min_signal_noise_ratio: float = 1.5

Minimum signal-to-noise ratio of a station magnitude. The noise amplitude is measured in the noise_window, up to 0.5 s before the P arrival.

max_station_std `pydantic-field` ¶

max_station_std: float = 3.0

Station magnitudes that deviate from the network magnitude by more than this many standard deviations are disregarded.

gf_store_dirs `pydantic-field` ¶

gf_store_dirs: list[DirectoryPath] = [Path('.')]

Directories with the Pyrocko GF stores.

export_mseed `pydantic-field` ¶

export_mseed: Path | None = None

Path to export the processed mseed traces to.

models `pydantic-field` ¶

models: list[PeakAmplitudeDefinition] = [
    PeakAmplitudeDefinition()
]

The peak amplitude models to use.

min_stations `pydantic-field` ¶

min_stations: PositiveInt = 3

Minimum number of station magnitudes required to calculate the network magnitude.

exclude_stations `pydantic-field` ¶

exclude_stations: list[NSL] = []

List of station NSLs to exclude from magnitude calculation.

get_subclasses `classmethod` ¶

get_subclasses() -> tuple[
    type[EventMagnitudeCalculator], ...
]

Get the subclasses of this class.

Returns:

Type	Description
`tuple[type[EventMagnitudeCalculator], ...]`	list[type]: The subclasses of this class.

get_magnitude `async` ¶

get_magnitude(
    waveform_provider: WaveformProvider,
    stations: StationInventory,
    event: EventDetection,
) -> EventMagnitude

Calculates the magnitude for the given event.

Parameters:

Name	Type	Description	Default
`waveform_provider`	`WaveformProvider`	The waveform provider.	required
`stations`	`StationInventory`	The station inventory.	required
`event`	`EventDetection`	The event detection object.	required

Raises:

Type	Description
`NotImplementedError`	This method is not implemented in the base class.

csv_header ¶

csv_header() -> list[str]

Get the CSV header for the magnitude data.

Returns:

Type	Description
`list[str]`	list[str]: The CSV header as a list of column names.

Recalculate magnitudes¶

To calculate the magnitudes of an existing run again, e.g. after changing the magnitudes, see recalculate magnitudes and features.

Magnitudes¶

Local magnitude¶

LocalMagnitude pydantic-model ¶

noise_window pydantic-field ¶

seconds_after pydantic-field ¶

taper_seconds pydantic-field ¶

min_signal_noise_ratio pydantic-field ¶

max_station_std pydantic-field ¶

model pydantic-field ¶

use_mean pydantic-field ¶

export_mseed pydantic-field ¶

min_stations pydantic-field ¶

exclude_stations pydantic-field ¶

get_magnitude async ¶

get_station_magnitude ¶

get_subclasses classmethod ¶

prepare async ¶

Moment magnitude¶

MomentMagnitude pydantic-model ¶

noise_window pydantic-field ¶

seconds_after pydantic-field ¶

taper_seconds pydantic-field ¶

min_signal_noise_ratio pydantic-field ¶

max_station_std pydantic-field ¶

gf_store_dirs pydantic-field ¶

export_mseed pydantic-field ¶

models pydantic-field ¶

min_stations pydantic-field ¶

exclude_stations pydantic-field ¶

get_subclasses classmethod ¶

get_magnitude async ¶

csv_header ¶

Recalculate magnitudes¶

LocalMagnitude `pydantic-model` ¶

noise_window `pydantic-field` ¶

seconds_after `pydantic-field` ¶

taper_seconds `pydantic-field` ¶

min_signal_noise_ratio `pydantic-field` ¶

max_station_std `pydantic-field` ¶

model `pydantic-field` ¶

use_mean `pydantic-field` ¶

export_mseed `pydantic-field` ¶

min_stations `pydantic-field` ¶

exclude_stations `pydantic-field` ¶

get_magnitude `async` ¶

get_subclasses `classmethod` ¶

prepare `async` ¶

MomentMagnitude `pydantic-model` ¶

noise_window `pydantic-field` ¶

seconds_after `pydantic-field` ¶

taper_seconds `pydantic-field` ¶

min_signal_noise_ratio `pydantic-field` ¶

max_station_std `pydantic-field` ¶

gf_store_dirs `pydantic-field` ¶

export_mseed `pydantic-field` ¶

models `pydantic-field` ¶

min_stations `pydantic-field` ¶

exclude_stations `pydantic-field` ¶

get_subclasses `classmethod` ¶

get_magnitude `async` ¶