Listening for events…
← All Docs

Scope freeze — earthquake magnitude-band Eventdexes (complete-catalog tiers)

Frozen 2026-07-07. Four new Eventdex kinds that hold the earthquakes below the M4.5 notable eq spine, one magnitude band each. Built for the paper-data standardization campaign ([[project_paper_dex_repoint_campaign]]): swarm and aftershock papers need the complete local micro-catalog, which the notable spine (frozen M6+ global / M4.5+ US, docs/scope-earthquake-eventdex.md) deliberately does not hold. These tiers coexist alongside the spine; the spine is unchanged.

Mike's shape ruling 2026-07-07: "separate earthquake-magnitude eventdexes for < 1.0, < 2.0, < 3.0 etc." Implemented as disjoint bands so every quake lands in exactly one tier and no event is double-counted; a paper reconstructs any completeness threshold by unioning the bands it needs.

The four kinds (disjoint bands, union with the eq spine = complete catalog)

kind band distinct events at freeze time span at freeze
eq_mag_3_45 3.0 ≤ M < 4.5 42,486 2021-04-12 → 2026-07-07
eq_mag_2_3 2.0 ≤ M < 3.0 3,906 2026-03-16 → 2026-07-07
eq_mag_1_2 1.0 ≤ M < 2.0 11,920 2026-03-16 → 2026-07-07
eq_mag_lt1 M < 1.0 4,444 2026-03-16 → 2026-07-07

Total 62,756 sub-4.5 events. The existing eq kind (M ≥ 4.5 notable spine) sits on top unchanged.

What it is / measures

feedback_measured_reality_only. Each slot is one earthquake: the measured ground motion at a place and time (origin time, hypocenter lat/lon/depth, magnitude) as reported by USGS ComCat. Nothing modeled. Same measured source as the eq spine (usgs_earthquake); these tiers just organize the smaller quakes the spine's magnitude floor excludes.

Completeness — read this honestly (feedback_data_is_data_partial_coverage)

The sub-M4.5 events come from the platform's live USGS feed, not a deep historical backfill (the eq spine backfill was M4.5+ only). So:

  • eq_mag_3_45 has ~5-year depth (the moderate feed reaches back to 2021).
  • The sub-M3 bands are a shallow, recent window — only ~4 months (2026-03-16 → present) — and US-dense (the live feed's small-quake completeness is a US/dense-network property, sparse globally; the raw M3–4 dip vs M4–4.5 confirms the small tiers are regionally complete, not globally).

This is fine for the campaign: the target papers (cascadia swarm, kermadec doublet, sanriku foreshock) are all 2026 regional events that fall inside the covered window. Deeper historical and global micro-catalogs are a later backfill (take what exists, null the rest, backfill later); the tiers grow as the live feed accumulates and if we backfill ComCat at lower floors.

Slot = one earthquake (Eventdex, spine-parquet storage)

  • Slot id: the USGS ComCat event_id (always present in observations; deduped to one row per id, keeping the largest reported magnitude). Validator id field slot_id, must be unique + non-null.
  • Fields: slot_id, kind, magnitude, origin_utc, lat, lon, depth_km (nullable), place, status, net, mag_band, sources.
  • Storage: spine-parquet, one row per event, at data/event_storehouse/<kind>/<kind>_spine.parquet + a small <kind>_index.json. Deliberately NO per-slot JSON dossiers: 62,756 dossiers would bloat the shared storehouse index (the lightning precedent, [[project_storehouse_index_cost]]). This follows the severe-weather split's spine-parquet architecture, so these kinds stay OUT of the storehouse_index.json rebuild entirely.

Dedup

One slot per distinct USGS event_id. The append-only live feed re-inserts the same event every poll (207,178 rows → 114,229 distinct ids), so dedup is by event_id (the true USGS identity), keeping the largest reported magnitude, not the spatial-rounding rule (which would merge distinct nearby micro-quakes).

Provenance

KIND_SOURCES[<kind>] = ["usgs_earthquake"] for all four — the same registered measured source as the eq spine, resolved read-time via resolve_for_kind ([[feedback_provenance_every_datum]]).

Validation

Self-validates via the shared dex_validator.validate_spine_eventdex_or_raise (new 2026-07-07, the spine-parquet Eventdex analogue of validate_directorydex): spine rows == index n_events, slot_id unique + non-null, family == event_dex. pytest logic tests pin the band-partition and row-shaping in tests/test_monitor/test_earthquake_magnitude_bands.py.

Deferred

  • Multi-network (EMSC / GFZ / ISC). Kermadec's cross-network magnitude check needs the other agencies (already ingested: emsc_magnitude 33,847, isc_magnitude 3,242, gfz_magnitude 1,760). Registering/associating them to these events is the next sub-step of the earthquake build.
  • Historical + global backfill of the sub-M3 tiers (see completeness above).
  • The repoint itself. Papers are NOT switched to these dexes now — that is the campaign's final step ([[project_paper_dex_repoint_campaign]]).
Live Feed