predict_detectability¶

Science¶

For a referenced origin, the fitted probability-based magnitude of completeness (PMC) model returns an expected SNR and a detection probability at each station. The inputs are hypocentral distance, the origin's network magnitude, and that station-week's noise p50_db.

A magnitude is required. If the PMC table is missing the tool errors E_DATA_UNAVAILABLE with reason: model_not_fitted. If the origin has no magnitude_ml, scoring is skipped (partial_result) and the rest of the payload still returns; a value origin may supply a magnitude.

detection_probability is a fitted probability from the host catalogue history, not a certainty that the station would or would not have seen the event. Treat “expected detection” as odds, not a fact. availability_stale means the daily availability table has no row for the origin's UTC day.

References¶

Schorlemmer, D. and Woessner, J. (2008). Probability of detecting an earthquake. Bulletin of the Seismological Society of America. doi:10.1785/0120070133

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	`forward`
Class	3
Tool version	`1.2.0`
Highest declared tier	F
Timeout	20 s
Budget key	`none`
`readOnlyHint`	true
`idempotentHint`	true

Input¶

Field	Type	Required	Notes
`origin_ref`	object (kind `catalog` \| `solution` \| `value`)	yes	discriminated on `kind`
`stations`	array[string] \| null	no	default `null`

Payload¶

Field	Type	Required	Notes
`stations`	array[object]	yes
`stations[].station_id`	string	yes
`stations[].distance_km`	number	yes
`stations[].r_hyp_km`	number \| null	no	default `null`
`stations[].state_in_window`	string	yes
`stations[].expected_snr_db`	number	yes
`stations[].detection_probability`	number	yes
`stations[].noise_p50_db_used`	number	yes
`model_version`	string	yes

Example request¶

{
  "origin_ref": {
    "kind": "catalog",
    "event_id": 1001
  },
  "stations": [
    "XX.STA1"
  ]
}

Example payload¶

{
  "stations": [
    {
      "station_id": "XX.STA1",
      "distance_km": 41.2,
      "r_hyp_km": 43.0,
      "state_in_window": "delivering",
      "expected_snr_db": 9.1,
      "detection_probability": 0.87,
      "noise_p50_db_used": -146.3
    }
  ],
  "model_version": "pmc-2024-06"
}

What this tool does not tell you¶

What this tool does not tell you: a certainty. The attenuation relation is regional; treat "expected detection" as a probability, not a fact.

Warnings named for this tool¶

Code	When
`partial_result`	scoring is skipped (no magnitude) or a requested station is not in `stations[]`
`availability_stale`	the availability table has no row for the origin's UTC day

Errors named for this tool¶

Code	When
`E_DATA_UNAVAILABLE`	`reason` is `model_not_fitted` — the PMC table is missing