get_waveform_summary

Science

Numeric descriptors of the recording around an origin or in an explicit window, computed on the server. No samples leave the process. The result is always catalogue_bearing: false: filter_band is Tier D even at its default.

Windows are defined, not guessed. In origin mode the noise window is P_pred − pre_s to P_pred − 1 s and the signal window is P_pred − 1 s to P_pred + max(10 s, S_pred − P_pred). In window mode the first 20 % is noise and the rest is signal. Predicted times come from the NonLinLoc grid internally.

Metric	Definition
snr_db	20·log10(RMS signal / RMS noise) after the filter
peak_amplitude_counts / _nm	max |x| in the signal window; _nm after response removal to displacement, else null
dominant_freq_hz	frequency of the maximum of the Welch spectrum of the signal window
onset_sharpness	max STA/LTA (0.5 s / 10 s) within ± 2 s of P_pred; null in window mode
ps_amplitude_ratio	peak in S_pred ± 1 s / peak in P_pred ± 1 s; null when S is not in the window
coda_duration_s	time after P_pred until the 1 s envelope stays below 2 × noise RMS for 3 s
spectral_ratio_high_low	energy 5–15 Hz / energy 1–5 Hz on the unfiltered signal window

These are summary statistics. A blast-like spectral ratio is a prior, not a verdict. Published explosion/earthquake discriminators typically use S onsets and a long-period S coda that a 30 s regional window may not contain.

References

• Welch, P. D. (1967). The use of fast Fourier transform for the estimation of power spectra. IEEE Transactions on Audio and Electroacoustics. doi:10.1109/TAU.1967.1161901
• Allen, R. V. (1978). Automatic earthquake recognition and timing from single traces. Bulletin of the Seismological Society of America. doi:10.1785/BSSA0680051521

Contract

Generated from the live registry (ToolSpec). Field names, types and defaults come from the input and payload models; they are not hand-typed.

Group	waveform
Class	3
Tool version	1.0.0
Highest declared tier	D
Timeout	30 s
Budget key	get_waveform_summary
readOnlyHint	true
idempotentHint	true

Input

Field	Type	Required	Notes
target	object (kind origin | window)	yes	discriminated on kind
stations	array[string] | null	no	default null
channel	string ∈ {Z, horizontals, all}	no	default "Z"
filter_band	string	no	default "none"
pre_s	number	no	default 5.0; ≥ 0; ≤ 60.0
post_s	number	no	default 30.0; ≥ 0; ≤ 120.0

Payload

Field	Type	Required	Notes
channels	array[object]	yes
channels[].channel_id	string	yes
channels[].sample_rate_hz	number	yes
channels[].window	object	yes
channels[].window.from_utc	string	yes
channels[].window.to_utc	string	yes
channels[].gaps_pct	number	yes
channels[].clipped	boolean	yes
channels[].snr_db	number | null	no	default null
channels[].peak_amplitude_counts	number | null	no	default null
channels[].peak_amplitude_nm	number | null	no	default null
channels[].peak_time_utc	string | null	no	default null
channels[].dominant_freq_hz	number | null	no	default null
channels[].onset_sharpness	number | null	no	default null
channels[].ps_amplitude_ratio	number | null	no	default null
channels[].coda_duration_s	number | null	no	default null
channels[].spectral_ratio_high_low	number | null	no	default null
definitions	object	yes

Example request

{
  "target": {
    "kind": "origin",
    "origin_ref": {
      "kind": "catalog",
      "event_id": 1001
    }
  },
  "stations": [
    "XX.STA1"
  ],
  "channel": "Z",
  "filter_band": "2-15",
  "pre_s": 5,
  "post_s": 30
}

Example payload

{
  "channels": [
    {
      "channel_id": "XX.STA1..HHZ",
      "sample_rate_hz": 100.0,
      "window": {
        "from_utc": "2024-06-15T08:12:02.000Z",
        "to_utc": "2024-06-15T08:12:40.000Z"
      },
      "gaps_pct": 0.0,
      "clipped": false,
      "snr_db": 14.2,
      "peak_amplitude_counts": 18234,
      "peak_amplitude_nm": 412.5,
      "peak_time_utc": "2024-06-15T08:12:11.200Z",
      "dominant_freq_hz": 6.8,
      "onset_sharpness": 9.4,
      "ps_amplitude_ratio": 0.61,
      "coda_duration_s": 21.5,
      "spectral_ratio_high_low": 1.9
    }
  ],
  "definitions": {
    "snr_db": "20·log10(RMS signal / RMS noise) after the filter"
  }
}

What this tool does not tell you

What this tool does not tell you: what the event is. These are summary statistics; a blast-like spectral ratio is a prior, not a verdict. Published discriminators rely on S onsets and long-period S coda that a 30 s window at regional distance may not contain.

Warnings named for this tool

Code	When
data_gap	the requested window is only partially covered
clipped_trace	amplitude reaches digitizer full scale
station_silent	a requested station is silent in the window
tier_d_parameter	always — filter_band is Tier D even at its default