Skip to content

feat(criteria): activate seismic criterion (v1.8 — 8 of 8 criteria live) - #4

Merged
Alex0420W merged 1 commit into
mainfrom
feature/v18-seismic-criterion
May 1, 2026
Merged

Alex0420W merged 1 commit into
mainfrom
feature/v18-seismic-criterion

Conversation

@Alex0420W

Copy link
Copy Markdown
Owner

Adds distance-to-nearest-scarp criterion using Mishra & Kumar 2022's 704 south-polar lunar scarp catalog (Geophysical Research Letters, CC-BY 4.0) as the primary data source, with the LROC SOC POLAR_SCARP_LOCATIONS shapefile (NASA-hosted, citing Watters 2015 verbatim) bundled alongside as an attribution anchor.

Eight of eight selene-base criteria now contribute to the aggregate score: slope, illumination, thermal, ice, hazard, coupling, LOS-to-Earth, and seismic. Default seismic weight 0.10 (slightly below slope, reflecting that scarp distance is one of multiple safety factors most relevant on long habitat-occupation timescales); the other seven weights scaled by 0.928 so the simplex still sums to 1.00.

Result on the v1.5 20 m catalog (same per-region tiled HLS filters, same NMS, only the aggregator's input set + weights change):

metric v1.5 (7) v1.8 (8) Δ
selene sites 69 69 0
selene matched within 5 km 56 (81%) 56 (81%) identical
Wueller matched within 5 km 44 (60%) 46 (63%) +2, +2.7 pp
median matched-pair distance 1.76 km 1.69 km -0.07 km

Same 69 sites, same top-3 in every region; 13 sites in HW/MMP/N1/N2 reshuffle within ranks 4-10 because seismic at 0.10 weight lifts the aggregate of slightly-further-from-scarp cells just enough to flip a few interior orderings. Two of those reshuffled cells now pair within 5 km of a Wueller target where their v1.5 predecessor didn't, lifting bidirectional from 44/73 to 46/73.

Scoring shape: logistic 1/(1+exp(-(d-25)/8)) — d=5 km → 0.08, d=25 km → 0.50, d=50 km → 0.96. The transition is centred on Civilini et al. 2023's documented Apollo-era shallow-moonquake-to-scarp clustering distance; logistic shape preferred over hard linear ramp because Civilini's distance estimates are themselves noisy with epicentral uncertainty of order 10 km.

Bundled data:

  • src/selene_base/criteria/data/scarps_mishra_kumar_2022/ main_segments.{shp,shx,dbf,prj} (~1.4 MB) — 704 LineString / MultiLineString features, polar-stereo Moon CRS matching selene's analysis CRS exactly. License: CC-BY 4.0 (Mishra & Kumar 2022, doi:10.1029/2022GL098505, Zenodo doi:10.5281/zenodo.6624114).
  • src/selene_base/criteria/data/scarps_watters_2015_polar/ polar_scarp_locations.{shp,shx,dbf,prj} (~25 KB) — 48 named-scarp Points in IAU Moon 2000 geographic. NASA public, attribution required. Cites Watters et al. 2015 verbatim as data citation; bundled as attribution anchor + sanity reference, not consumed by the criterion (sparse for selene's polar-grid scope).

Both bundles ship full-text README.md with citation, license, source URL, and rename provenance.

Code:

  • src/selene_base/criteria/seismic.py: replaces the v1.4-era linear- ramp compute() with a logistic; adds load_bundled_catalog() pointing at the in-repo Mishra & Kumar primary file plus BUNDLED_MISHRA_KUMAR_2022 / BUNDLED_WATTERS_2015_POLAR path constants for downstream consumers.
  • src/selene_base/pipeline/score.py: extends the seismic-score candidate list to fall back to the bundled Mishra & Kumar shapefile when no user-supplied override at data/raw/scarps/ is present, so the criterion fires out of the box without any download step.
  • config/weights_default.yaml: rebalanced 8-criterion vector; documents the 0.928 scaling and the 0.03 → 0.10 seismic bump.
  • tests/test_seismic.py: rewritten for the logistic + new load_bundled_catalog API; 19 tests including hand-verified logistic values, monotonicity, range, NaN/inf handling, parameter validation, and an end-to-end smoke test that runs the criterion chain on the bundled catalog over a coarse polar-stereo grid.

README + docs:

  • New "Seismic criterion (v1.8)" Methodology subsection with the Civilini-derived logistic parameters and the v1.5-vs-v1.8 result comparison.
  • v1.8 Roadmap entry with the headline numbers.
  • Default-weights paragraph rewritten with the new 8-criterion vector.
  • Mapping-to-NASA-FOM table: seismic row updated from "catalog TODO (planned)" to "Mishra & Kumar 2022 + Watters 2015 (consistent; bundled in-repo since v1.8)".
  • References: Civilini 2023 entry expanded with the v1.8 logistic- parameter justification; Mishra & Kumar 2022 added as a citation; the LROC SOC bundling location noted.
  • docs/v1.5_catalog_report.md §8 honest-limitations: the seismic- criterion limitation is now resolved; v1.8 update note added in place. The v1.5 report's headline numbers (81.2 % / 1.76 km) remain valid as the v1.5 7-criterion baseline; v1.8's 56/69 selene-matched count is identical and the median tightens to 1.69 km.

Tests: 372 passed (+10 over v1.7), 9 skipped (LEND + Robbins, expected). Lint + format clean.

Summary

What this PR does, in 1–3 sentences.

Motivation

Why this change is worth making (link the issue if there is one).

Checklist

  • ruff check . passes
  • ruff format --check . passes
  • pytest passes locally
  • New behaviour has a test (or an explicit # noqa reason if not)
  • Public-facing changes (CLI flags, criterion math, file layout) are
    reflected in the README or the relevant module docstring
  • No real-data fixtures were committed; new tests run in CI without
    downloaded data (or are guarded with pytest.mark.skipif)

Scope notes

  • Things this PR explicitly does not address (so reviewers know what
    to expect in follow-ups).

Adds distance-to-nearest-scarp criterion using Mishra & Kumar 2022's
704 south-polar lunar scarp catalog (Geophysical Research Letters,
CC-BY 4.0) as the primary data source, with the LROC SOC
POLAR_SCARP_LOCATIONS shapefile (NASA-hosted, citing Watters 2015
verbatim) bundled alongside as an attribution anchor.

Eight of eight selene-base criteria now contribute to the aggregate
score: slope, illumination, thermal, ice, hazard, coupling,
LOS-to-Earth, and seismic. Default seismic weight 0.10 (slightly below
slope, reflecting that scarp distance is one of multiple safety
factors most relevant on long habitat-occupation timescales); the
other seven weights scaled by 0.928 so the simplex still sums to 1.00.

Result on the v1.5 20 m catalog (same per-region tiled HLS filters,
same NMS, only the aggregator's input set + weights change):

| metric                          | v1.5 (7) | v1.8 (8) | Δ           |
|---------------------------------|---------:|---------:|-------------|
| selene sites                    |       69 |       69 | 0           |
| selene matched within 5 km      | 56 (81%) | 56 (81%) | identical   |
| Wueller matched within 5 km     | 44 (60%) | 46 (63%) | +2, +2.7 pp |
| median matched-pair distance    | 1.76 km  | 1.69 km  | -0.07 km    |

Same 69 sites, same top-3 in every region; 13 sites in HW/MMP/N1/N2
reshuffle within ranks 4-10 because seismic at 0.10 weight lifts the
aggregate of slightly-further-from-scarp cells just enough to flip a
few interior orderings. Two of those reshuffled cells now pair within
5 km of a Wueller target where their v1.5 predecessor didn't, lifting
bidirectional from 44/73 to 46/73.

Scoring shape: logistic 1/(1+exp(-(d-25)/8)) — d=5 km → 0.08, d=25 km
→ 0.50, d=50 km → 0.96. The transition is centred on Civilini et al.
2023's documented Apollo-era shallow-moonquake-to-scarp clustering
distance; logistic shape preferred over hard linear ramp because
Civilini's distance estimates are themselves noisy with epicentral
uncertainty of order 10 km.

Bundled data:
- src/selene_base/criteria/data/scarps_mishra_kumar_2022/
  main_segments.{shp,shx,dbf,prj} (~1.4 MB) — 704 LineString /
  MultiLineString features, polar-stereo Moon CRS matching selene's
  analysis CRS exactly. License: CC-BY 4.0 (Mishra & Kumar 2022,
  doi:10.1029/2022GL098505, Zenodo doi:10.5281/zenodo.6624114).
- src/selene_base/criteria/data/scarps_watters_2015_polar/
  polar_scarp_locations.{shp,shx,dbf,prj} (~25 KB) — 48 named-scarp
  Points in IAU Moon 2000 geographic. NASA public, attribution
  required. Cites Watters et al. 2015 verbatim as data citation;
  bundled as attribution anchor + sanity reference, not consumed by
  the criterion (sparse for selene's polar-grid scope).

Both bundles ship full-text README.md with citation, license, source
URL, and rename provenance.

Code:
- src/selene_base/criteria/seismic.py: replaces the v1.4-era linear-
  ramp `compute()` with a logistic; adds `load_bundled_catalog()`
  pointing at the in-repo Mishra & Kumar primary file plus
  `BUNDLED_MISHRA_KUMAR_2022` / `BUNDLED_WATTERS_2015_POLAR` path
  constants for downstream consumers.
- src/selene_base/pipeline/score.py: extends the seismic-score
  candidate list to fall back to the bundled Mishra & Kumar shapefile
  when no user-supplied override at data/raw/scarps/ is present, so
  the criterion fires out of the box without any download step.
- config/weights_default.yaml: rebalanced 8-criterion vector;
  documents the 0.928 scaling and the 0.03 → 0.10 seismic bump.
- tests/test_seismic.py: rewritten for the logistic + new
  `load_bundled_catalog` API; 19 tests including hand-verified
  logistic values, monotonicity, range, NaN/inf handling, parameter
  validation, and an end-to-end smoke test that runs the criterion
  chain on the bundled catalog over a coarse polar-stereo grid.

README + docs:
- New "Seismic criterion (v1.8)" Methodology subsection with the
  Civilini-derived logistic parameters and the v1.5-vs-v1.8 result
  comparison.
- v1.8 Roadmap entry with the headline numbers.
- Default-weights paragraph rewritten with the new 8-criterion vector.
- Mapping-to-NASA-FOM table: seismic row updated from "catalog TODO
  (planned)" to "Mishra & Kumar 2022 + Watters 2015 (consistent;
  bundled in-repo since v1.8)".
- References: Civilini 2023 entry expanded with the v1.8 logistic-
  parameter justification; Mishra & Kumar 2022 added as a citation;
  the LROC SOC bundling location noted.
- docs/v1.5_catalog_report.md §8 honest-limitations: the seismic-
  criterion limitation is now resolved; v1.8 update note added in
  place. The v1.5 report's headline numbers (81.2 % / 1.76 km) remain
  valid as the v1.5 7-criterion baseline; v1.8's 56/69 selene-matched
  count is identical and the median tightens to 1.69 km.

Tests: 372 passed (+10 over v1.7), 9 skipped (LEND + Robbins,
expected). Lint + format clean.
@Alex0420W
Alex0420W merged commit 57bde96 into main May 1, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant