feat: Store ICCS/MCCC quality metrics in database#230
Merged
Conversation
![github-code-quality[bot]](https://avatars.githubusercontent.com/u/9919?s=60&v=4){kind=small}
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## master #230 +/- ##
==========================================
+ Coverage 70.34% 71.29% +0.94%
==========================================
Files 55 58 +3
Lines 3386 4264 +878
==========================================
+ Hits 2382 3040 +658
- Misses 1004 1224 +220 ☔ View full report in Codecov by Sentry. |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces first-class “quality metrics” support across AIMBAT (models, DB triggers, snapshots, CLI/TUI, docs) and modernises a few utilities (table rendering, UUID resolution, maths helpers), with corresponding test updates.
Changes:
- Add event/seismogram quality models + snapshotting, and SQLite triggers to invalidate stale quality when parameters/picks change.
- Introduce a richer
json_to_tableimplementation (aimbat.utils._table) and migrate CLI/table output to it. - Add a new
aimbat quality ...CLI and TUI quality modal, plus expanded integration/unit/functional test coverage.
Reviewed changes
Copilot reviewed 82 out of 85 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| zensical.toml | Adds docs nav entries for help/quality/development pages. |
| tests/unit/utils/test_table.py | New unit tests for utils._table formatting and rendering. |
| tests/unit/utils/test_maths.py | New unit tests for mean/SEM helpers. |
| tests/unit/utils/test_json.py | Removes old JSON→table tests (module removed). |
| tests/unit/test_config.py | Updates settings table capture to patch new table module; renames min_cc tests. |
| tests/unit/io/test_sac.py | British English wording updates (“initialised”). |
| tests/integration/models/test_triggers.py | Adds integration tests validating quality invalidation triggers. |
| tests/integration/models/test_readers.py | Adds integration tests for Read-model short-id generation. |
| tests/integration/core/test_views.py | Adds integration tests for quality “view” behaviour across snapshots. |
| tests/integration/core/test_mccc.py | Adds integration tests ensuring MCCC writes quality metrics. |
| tests/integration/core/test_iccs.py | Adds integration tests for ICCS/MCCC quality interplay + nulling rules. |
| tests/integration/core/test_data.py | Updates tests for new dump API + NoResultFound behaviour + session fixture usage. |
| tests/functional/test_cli_snapshots.py | Updates expectations and semantics around snapshot dump/list output. |
| tests/functional/test_cli_parameters.py | Updates parameter names/JSON keys to new aliases (min_cc etc.). |
| tests/functional/test_cli_basic_ops.py | Adds CLI tests for data add JSON types and --use-* flags. |
| tests/conftest.py | Updates set_default_event call to pass event id. |
| src/aimbat/utils/_uuid.py | Adds debug logging for UUID prefix resolution and shortening. |
| src/aimbat/utils/_table.py | New rich table renderer + styling/formatting helpers. |
| src/aimbat/utils/_style.py | Removes old styling helper module (superseded by _table). |
| src/aimbat/utils/_sampledata.py | Adds extra logging around sample data extraction. |
| src/aimbat/utils/_pydantic.py | Adds cached helper to map Pydantic field names → titles. |
| src/aimbat/utils/_maths.py | Adds cached mean/SEM utilities (numeric + Timedelta). |
| src/aimbat/utils/_json.py | Removes old json_to_table implementation (migrated to _table). |
| src/aimbat/utils/init.py | Re-exports new utils modules (_table, _maths, _pydantic). |
| src/aimbat/plot/_seismograms.py | Adds logging around seismogram plotting paths. |
| src/aimbat/plot/_plot_utils.py | Adds logging around plot preprocessing/bandpass. |
| src/aimbat/plot/_iccs.py | Renames min_ccnorm→min_cc and routes parameter persistence via set_event_parameter. |
| src/aimbat/models/_quality.py | Introduces base SQLModel classes for quality metrics. |
| src/aimbat/models/_parameters.py | Adds ramp/min_cc/mccc_min_cc, plus ICCS validation hook. |
| src/aimbat/models/init.py | Re-exports quality module and updates model overview docstring. |
| src/aimbat/logger.py | Logging module docstring tweaks (code fence formatting). |
| src/aimbat/io/sac.py | Migrates SAC registration to decorator-based I/O plugin registration. |
| src/aimbat/io/json.py | Migrates JSON registration to decorator-based I/O plugin registration. |
| src/aimbat/io/_base.py | Adds decorator factories for I/O registration + extra debug logging. |
| src/aimbat/io/init.py | Updates module docstring to describe decorator-based plugin pattern. |
| src/aimbat/db.py | Adds logging, centralises SQLite PRAGMAs, updates docstring fences. |
| src/aimbat/core/_station.py | Refactors station APIs, adds dump options and quality helper. |
| src/aimbat/core/_project.py | Adds SQLite triggers for quality invalidation; minor log-level tweaks. |
| src/aimbat/core/_default_event.py | Refactors default-event setter to accept event id; updates exception behaviour. |
| src/aimbat/core/_data.py | Refactors data dumping APIs and event/station id validation errors. |
| src/aimbat/core/init.py | Re-exports quality module and updates package overview. |
| src/aimbat/app.py | Registers new quality CLI subcommand. |
| src/aimbat/_types/_sqlalchemy.py | Makes timestamp/timedelta bind handling null-safe via pd.isnull. |
| src/aimbat/_types/_seismogram.py | Removes old enum module (merged into _enums). |
| src/aimbat/_types/_pydantic.py | Adds parsing rule: bare numeric strings → Timedelta seconds. |
| src/aimbat/_types/_event.py | Removes old enum module (merged into _enums). |
| src/aimbat/_types/_enums.py | New unified enums for event/seismogram parameters. |
| src/aimbat/_types/init.py | Re-exports unified enums and expands module docs. |
| src/aimbat/_tui/modals.py | Adds Quality modal and updates event deletion + parameter setting paths. |
| src/aimbat/_tui/aimbat.tcss | Styles quality modal and table sizing adjustments. |
| src/aimbat/_config.py | Adds new settings fields + updates settings table rendering. |
| src/aimbat/_cli/utils/sampledata.py | Improves CLI help typing/parameter metadata. |
| src/aimbat/_cli/station.py | Updates station dump/list to new dump/table utilities. |
| src/aimbat/_cli/snapshot.py | Updates snapshot dump/list/details to new dump/table utilities. |
| src/aimbat/_cli/shell.py | Adds DebugParameter support to shell entrypoint. |
| src/aimbat/_cli/seismogram.py | Refactors seismogram commands, adds list, updates parameter handling. |
| src/aimbat/_cli/quality.py | New CLI surface for quality listing/dumping. |
| src/aimbat/_cli/project.py | Updates station/seismogram helper calls to new signatures. |
| src/aimbat/_cli/pick.py | Renames ccnorm → cc and updates plot hook. |
| src/aimbat/_cli/event.py | Refactors event commands, adds event list/dump, parameter list/dump changes. |
| src/aimbat/_cli/data.py | Refactors data list/dump to new dump/table utilities + better help. |
| src/aimbat/_cli/common.py | Adds new parameter factories/traits and JSON dump parameters. |
| src/aimbat/_cli/align.py | Refactors ICCS/MCCC CLI parameter handling; updates docs. |
| pyproject.toml | Formatting-only reshuffle + adds vulture dev dep. |
| docs/usage/snapshots.md | Documents quality metric snapshotting + rollback behaviour. |
| docs/usage/quality.md | New user guide for quality metrics and interpretation. |
| docs/development/quality-invalidation.md | New developer doc describing invalidation triggers/rules. |
| docs/development/database-models.md | New ERD-style model documentation. |
| baseline/tests.test_seismogram.TestSeismogramPlot.test_lib_plotseis_mpl.png | Updates/introduces MPL baseline image. |
| .gitignore | Removes some local-only ignores. |
| .github/copilot-instructions.md | Updates contributor guidance (Ruff formatting, quality lifecycle, triggers). |
Comment on lines
+14
to
+17
| ``bash | ||
| AIMBAT_LOG_LEVEL=DEBUG | ||
| AIMBAT_LOGFILE=/path/to/custom.log | ||
| ``` | ||
| `` |
Comment on lines
+7
to
+10
| ``bash | ||
| AIMBAT_PROJECT=/path/to/project.db # derives db_url automatically | ||
| AIMBAT_DB_URL=sqlite+pysqlite:///absolute/path/to/project.db # explicit override | ||
| ``` | ||
| `` |
Comment on lines
+8
to
+30
| @@ -15,19 +15,19 @@ | |||
| "longitude": -106.4572, | |||
| "elevation": 1820.0 | |||
| } | |||
| ``` | |||
| `` | |||
|
|
|||
| - `JSON_EVENT` (`DataType.JSON_EVENT`): a JSON file containing a single event | |||
| record. Field names match `AimbatEvent`: | |||
|
|
|||
| ```json | |||
| ``json | |||
| { | |||
| "time": "2020-01-01T00:00:00Z", | |||
| "latitude": 35.0, | |||
| "longitude": -120.0, | |||
| "depth": 10.0 | |||
| } | |||
| ``` | |||
| `` | |||
Comment on lines
8
to
+15
| - All event-level parameters: the time window, bandpass filter settings, and | ||
| minimum CC norm threshold | ||
| - Per-seismogram parameters for every seismogram in the event: the current `t1` | ||
| pick, `select` flag, and `flip` flag | ||
| - Quality metrics, if available at snapshot time: | ||
| - ICCS CC per seismogram (always present once the event has been opened) | ||
| - MCCC metrics per seismogram and the global RMSE (present only if MCCC has | ||
| been run) |
Comment on lines
+181
to
+186
| if event_id is not None: | ||
| statement = ( | ||
| select(AimbatStation) | ||
| .join(AimbatSeismogram) | ||
| .where(AimbatSeismogram.event_id == event_id) | ||
| ) |
Comment on lines
+43
to
+45
| new_default_event_id: Annotated[ | ||
| uuid.UUID, event_parameter(help="Event to set as default.") | ||
| ], |
Comment on lines
50
to
+58
| Raises: | ||
| ValueError: If an explicit event_id is given but not found. | ||
| NoResultFound: If no event_id is given and no default event is set. | ||
| """ | ||
| if event_id: | ||
| logger.debug(f"Resolving event by explicit ID: {event_id}") | ||
| event = session.get(AimbatEvent, event_id) | ||
| if event is None: | ||
| raise ValueError(f"No AimbatEvent found with id: {event_id}.") | ||
| raise NoResultFound(f"No AimbatEvent found with id: {event_id}.") |
Comment on lines
+51
to
+54
| cli("event parameter get min_cc") | ||
| output = capsys.readouterr().out.strip() | ||
| assert output, "Expected a non-empty output for min_ccnorm" | ||
| assert float(output) >= 0.0, "min_ccnorm should be a non-negative float" | ||
| assert output, "Expected a non-empty output for min_cc" | ||
| assert float(output) >= 0.0, "min_ccshould be a non-negative float" |
Adds live quality tables (`AimbatSeismogramQuality`, `AimbatEventQuality`) and snapshot counterparts that are written when a snapshot is taken. ICCS CC norm and MCCC outputs (CC mean, CC std, timing error, RMSE) are captured per-seismogram and per-event and exposed through a new `aimbat quality` CLI subcommand with `list` and `dump` variants at seismogram, event, and station scope. Also introduces `FieldSpec`/`FieldGroup` view-layer types consumed by the TUI, new `mean_and_sem`/`mean_and_sem_timedelta` utilities, an `AimbatQualityInvalidation` enum, and supporting docs and tests.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds live quality tables (
AimbatSeismogramQuality,AimbatEventQuality) and snapshot counterparts that are written when a snapshot is taken. ICCS CC norm and MCCC outputs (CC mean, CC std, timing error, RMSE) are captured per-seismogram and per-event and exposed through a newaimbat qualityCLI subcommand withlistanddumpvariants at seismogram, event, and station scope.Also introduces
FieldSpec/FieldGroupview-layer types consumed by the TUI, newmean_and_sem/mean_and_sem_timedeltautilities, anAimbatQualityInvalidationenum, and supporting docs and tests.📚 Documentation preview 📚: https://aimbat--230.org.readthedocs.build/en/230/