render_residuals

Science

Residual versus epicentral distance and versus azimuth for one to four solutions, with the pattern statistics as numbers in the payload. The statistics are descriptive. There is no verdict field and no inference about the event.

A catalog origin's residuals are predict_arrivals on the catalogue picks (nll_grid), computed in-process. A solution origin uses the stored residuals[] of a relocate. A jackknife id means its reference. value origins are not accepted.

trend_s_per_100km is the least-squares slope of residual versus distance; trend_p_value is null when n < 5. The first azimuthal harmonic is a least-squares fit of a cos φ + b sin φ; amplitude is √(a² + b²). bimodality is the largest gap in the sorted residuals when that gap exceeds three times the median gap. outliers are phases with |residual| > 2σ.

A trend with azimuth is not itself an epicentre offset. A trend with distance is not itself a wrong velocity model or a wrong depth. Two clusters are not themselves two events.

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	20 s
Budget key	render
readOnlyHint	true
idempotentHint	true

Input

Field	Type	Required	Notes
solutions	array[object (kind catalog | solution)]	yes	minItems 1; maxItems 4
phases	array[string ∈ {P, S}]	no	minItems 1
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
stats	array[object]	yes
stats[].origin	object (kind catalog | solution)	yes	discriminated on kind
stats[].n_p	integer	yes
stats[].n_s	integer	yes
stats[].mean_s	number | null	yes
stats[].std_s	number | null	yes
stats[].rms_s	number | null	yes
stats[].trend_s_per_100km	number | null	yes
stats[].trend_p_value	number | null	yes
stats[].azimuth_harmonic_amplitude_s	number | null	yes
stats[].azimuth_of_max_deg	number | null	yes
stats[].bimodality	object | null	no	default null
stats[].bimodality.split_s	number	yes
stats[].bimodality.n_low	integer	yes
stats[].bimodality.n_high	integer	yes
stats[].outliers	array[object]	yes
stats[].outliers[].station_id	string	yes
stats[].outliers[].phase	string	yes
stats[].outliers[].residual_s	number	yes

Example request

{
  "solutions": [
    {
      "kind": "catalog",
      "event_id": 1001
    },
    {
      "kind": "solution",
      "tool_call_id": "tc-0011"
    }
  ],
  "phases": [
    "P",
    "S"
  ],
  "width_px": 1200
}

Example payload

{
  "figure": {
    "width_px": 1200,
    "height_px": 800,
    "digest": "sha256:6789abcdef0123456789abcdef0123456789abcdef0123456789abcdef012345",
    "caption": "residual vs distance and azimuth, catalogue vs relocated",
    "series": [
      "tc-0011"
    ],
    "url": "/mcp/figures/tc-0023.png"
  },
  "stats": [
    {
      "origin": {
        "kind": "catalog",
        "event_id": 1001
      },
      "n_p": 6,
      "n_s": 3,
      "mean_s": 0.02,
      "std_s": 0.31,
      "rms_s": 0.31,
      "trend_s_per_100km": 0.12,
      "trend_p_value": 0.04,
      "azimuth_harmonic_amplitude_s": 0.18,
      "azimuth_of_max_deg": 212.0,
      "bimodality": {
        "split_s": 0.4,
        "n_low": 5,
        "n_high": 4
      },
      "outliers": [
        {
          "station_id": "XX.STA1",
          "phase": "P",
          "residual_s": 1.21
        }
      ]
    }
  ]
}

What this tool does not tell you

What this tool does not tell you: whether a solution is right. Trend, azimuthal harmonic, bimodality and outliers describe the residual pattern; they are not a verdict. A trend with azimuth is not itself an epicentre offset; a trend with distance is not itself a wrong velocity model or depth; two clusters are not themselves two events.

Errors named for this tool

Code	When
E_UNKNOWN_REF	a solution ref is unknown, failed, or the wrong kind (value is not accepted)
E_DATA_UNAVAILABLE	a catalogue origin is missing travel-time grids