render_spectrogram

Science

One channel's display trace and short-time Fourier spectrogram around an origin or in an explicit window (at most 120 s), with picks and predicted arrivals marked. The spectrogram is scipy.signal.spectrogram on the detrended, tapered, unfiltered trace; colour is relative dB (10·log10(PSD)). The display trace is filtered 1–20 Hz. The PSD matrix never leaves the server.

This is the figure a person uses to see frequency content and coda that get_waveform_summary summarises as dominant_freq_hz, spectral_ratio_high_low and coda_duration_s. A bright high-frequency onset is not a blast; a long low-frequency coda is not a teleseism. Colour is relative on a trace that is not response-corrected, not an absolute spectral level.

Every call is catalogue_bearing: false with warning tier_d_parameter. Cite the summary tool for the numbers.

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

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	visual
Class	3
Tool version	1.0.0
Highest declared tier	D
Timeout	30 s
Budget key	render
readOnlyHint	true
idempotentHint	true

Input

Field	Type	Required	Notes
station_id	string	yes
channel	string ∈ {Z, horizontals}	no	default "Z"
target	object (kind origin | window)	yes	discriminated on kind
pre_s	number	no	default 10.0; ≥ 0; ≤ 30.0
post_s	number	no	default 50.0; ≥ 0; ≤ 110.0
fmax_hz	number | null	no	default null
log_freq	boolean	no	default false
window_s	number	no	default 2.0; > 0
db_range	object | null	no	default null
db_range.min_db	number	yes
db_range.max_db	number	yes
picks_from	array[string]	no
width_px	integer ∈ {800, 1200, 1600}	no	default 1200

Payload

Field	Type	Required	Notes
figure	object	yes	payload.figure fragment every render tool returns (docs/12).
figure.width_px	integer	yes
figure.height_px	integer	yes
figure.digest	string	yes
figure.caption	string	yes
figure.series	array[string]	no
figure.url	string	yes
channel	object	yes
channel.channel_id	string	yes
channel.sample_rate_hz	number	yes
channel.window	object	yes
channel.window.from_utc	string	yes
channel.window.to_utc	string	yes
channel.gaps_pct	number	yes
channel.clipped	boolean	yes
spectrogram	object	yes
spectrogram.window_s	number	yes
spectrogram.overlap_pct	number	yes
spectrogram.fmax_hz	number	yes
spectrogram.freq_bins	integer	yes
spectrogram.time_bins	integer	yes

Example request

{
  "station_id": "XX.STA1",
  "channel": "Z",
  "target": {
    "kind": "origin",
    "origin_ref": {
      "kind": "catalog",
      "event_id": 1001
    }
  },
  "pre_s": 10,
  "post_s": 50,
  "fmax_hz": 25,
  "log_freq": false,
  "window_s": 2,
  "picks_from": [
    "catalog"
  ],
  "width_px": 1200
}

Example payload

{
  "figure": {
    "width_px": 1200,
    "height_px": 800,
    "digest": "sha256:789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456",
    "caption": "XX.STA1 HHZ, 1–20 Hz display trace, relative dB spectrogram",
    "series": [
      "tc-0118"
    ],
    "url": "/mcp/figures/tc-0024.png"
  },
  "channel": {
    "channel_id": "XX.STA1..HHZ",
    "sample_rate_hz": 100.0,
    "window": {
      "from_utc": "2024-06-15T08:11:53.417Z",
      "to_utc": "2024-06-15T08:12:53.417Z"
    },
    "gaps_pct": 0.0,
    "clipped": false
  },
  "spectrogram": {
    "window_s": 2.0,
    "overlap_pct": 90.0,
    "fmax_hz": 25.0,
    "freq_bins": 80,
    "time_bins": 400
  }
}

What this tool does not tell you

What this tool does not tell you: that a bright high-frequency onset is a blast, or that a long low-frequency coda is a teleseism. Cite get_waveform_summary for dominant_freq_hz, spectral_ratio_high_low and coda_duration_s; the picture illustrates those numbers, it is not a measurement. Colour is relative dB on a trace that is not response-corrected, not an absolute spectral level.

Warnings named for this tool

Code	When
tier_d_parameter	always — the call is evidence only

Errors named for this tool

Code	When
E_WINDOW_TOO_LARGE	the explicit window is longer than 120 s
E_DATA_UNAVAILABLE	reason is station_absent or no_waveform