refactor: quality stats integrated into read models and tui

CHANGELOG.md

@@ -90,6 +90,8 @@ All notable changes to the **AIMBAT** project will be documented in this file.
 - Active event -> default event
 - Use default event concept only for cli commands
 - Update plot seismograms.
+- Remove dead code ([#231](https://github.com/pysmo/aimbat/issues/231))
+- Quality stats integrated into read models and tui
 
 ### 🚀 New Features
 

docs/development/database-models.md

@@ -34,7 +34,6 @@ erDiagram
 
     AimbatEvent {
         uuid id PK
-        bool is_default UK
         timestamp time UK
         float latitude
         float longitude
@@ -81,7 +80,7 @@ erDiagram
 
     AimbatSnapshot {
         uuid id PK
-        timestamp date UK
+        timestamp time UK
         string comment
         string parameters_hash
         uuid event_id FK

docs/usage/alignment.md

@@ -17,13 +17,22 @@ making further adjustments.
 
 ## Running ICCS
 
-=== "CLI / Shell"
+=== "CLI"
 
     ```bash
-    aimbat align iccs                          # basic run
-    aimbat align iccs --autoflip               # flip inverted polarity automatically
-    aimbat align iccs --autoselect             # deselect poor-quality seismograms automatically
-    aimbat align iccs --autoflip --autoselect  # both
+    aimbat align iccs <ID>                          # basic run
+    aimbat align iccs <ID> --autoflip               # flip inverted polarity automatically
+    aimbat align iccs <ID> --autoselect             # deselect poor-quality seismograms automatically
+    aimbat align iccs <ID> --autoflip --autoselect  # both
+    ```
+
+=== "Shell"
+
+    ```bash
+    align iccs                          # basic run
+    align iccs --autoflip               # flip inverted polarity automatically
+    align iccs --autoselect             # deselect poor-quality seismograms automatically
+    align iccs --autoflip --autoselect  # both
     ```
 
 === "TUI"
@@ -101,19 +110,26 @@ In addition to setting parameters directly, three tools let you adjust values
 by interacting with the plot — clicking or scrolling in a waveform display
 rather than typing numbers.
 
-=== "CLI / Shell"
+=== "CLI"
+
+    ```bash
+    aimbat pick phase <ID>    # adjust t1 by clicking on the stack
+    aimbat pick window <ID>   # set window_pre / window_post by clicking
+    aimbat pick ccnorm <ID>   # set min_ccnorm by scrolling the matrix image
+    ```
+
+=== "Shell"
 
     ```bash
-    aimbat pick phase    # adjust t1 by clicking on the stack
-    aimbat pick window   # set window_pre / window_post by clicking
-    aimbat pick ccnorm   # set min_ccnorm by scrolling the matrix image
+    pick phase    # adjust t1 by clicking on the stack
+    pick window   # set window_pre / window_post by clicking
+    pick ccnorm   # set min_ccnorm by scrolling the matrix image
     ```
 
-    Each command opens a matplotlib window. Click (or scroll, for ccnorm) to
-    set the value, then close the window to save it.
+Each command opens a matplotlib window. Click (or scroll, for ccnorm) to
+set the value, then close the window to save it.
 
-    All three accept `--no-context` and `--all` (include deselected
-    seismograms).
+All three accept `--no-context` and `--all` (include deselected seismograms).
 
 === "TUI"
 

docs/usage/api.md

@@ -1,9 +1,16 @@
 # Python API
 
-The CLI, shell, TUI, and GUI all use the same underlying Python library. You
-can use it directly for custom scripts, automation, or workflows that go beyond
-what the other interfaces expose. See the full [API reference](../api/aimbat.md)
-for a complete listing.
+After running ICCS and MCCC alignment across many events, the accumulated
+quality metrics span stations and events in ways that are natural to analyse
+with pandas and matplotlib but impossible from the CLI or TUI. The Python API
+is the primary interface for that kind of post-processing quality analysis: you
+query `AimbatSeismogram`, `AimbatStation`, and `AimbatEvent` records directly,
+build DataFrames, and apply whatever aggregation or visualisation you need.
+
+The same API also drives the CLI and TUI internally, so it covers the full
+workflow — data ingestion, parameter management, alignment, snapshots — not
+just quality analysis. See the full [API reference](../api/aimbat.md) for a
+complete listing.
 
 !!! note "Writing seismogram data"
     [`AimbatSeismogram.data`][aimbat.models.AimbatSeismogram.data] is backed by
@@ -149,6 +156,116 @@ with Session(engine) as session:
     )
 ```
 
+## Quality Analysis
+
+After alignment has been run across a set of events, each seismogram carries
+quality metrics that can be queried directly from the database. The sections
+below show the most common patterns.
+
+### Quality data model
+
+Per-seismogram metrics are stored in `AimbatSeismogramQuality` and accessed via
+`seismogram.quality`:
+
+| Attribute | Description |
+|---|---|
+| `iccs_cc` | ICCS cross-correlation with the stack |
+| `mccc_cc_mean` | MCCC waveform quality — mean CC across seismogram pairs |
+| `mccc_cc_std` | MCCC waveform consistency — std of CC across pairs |
+| `mccc_error` | MCCC timing precision (`pd.Timedelta`, SEM from covariance matrix) |
+
+The per-event MCCC global array fit is stored in `AimbatEventQuality` and
+accessed via `event.quality`:
+
+| Attribute | Description |
+|---|---|
+| `mccc_rmse` | Global array fit (`pd.Timedelta`) |
+
+### Build a per-seismogram DataFrame across all events
+
+The most flexible starting point is a flat DataFrame with one row per
+seismogram:
+
+```python
+from sqlalchemy.orm import selectinload
+from sqlmodel import Session, select
+import pandas as pd
+
+from aimbat.db import engine
+from aimbat.models import AimbatSeismogram
+from aimbat.utils import rel
+
+with Session(engine) as session:
+    seismograms = session.exec(
+        select(AimbatSeismogram).options(
+            selectinload(rel(AimbatSeismogram.station)),
+            selectinload(rel(AimbatSeismogram.event)),
+            selectinload(rel(AimbatSeismogram.quality)),
+        )
+    ).all()
+
+    rows = []
+    for seis in seismograms:
+        q = seis.quality
+        rows.append({
+            "station": f"{seis.station.network}.{seis.station.name}",
+            "event_time": seis.event.time,
+            "iccs_cc": q.iccs_cc if q else None,
+            "mccc_cc_mean": q.mccc_cc_mean if q else None,
+            "mccc_error_s": q.mccc_error.total_seconds() if (q and q.mccc_error) else None,
+        })
+
+df = pd.DataFrame(rows)
+```
+
+From here you can groupby station, pivot on event, filter by quality threshold,
+or feed the result directly into matplotlib.
+
+### Station-level quality summary
+
+`SeismogramQualityStats.from_station` aggregates all per-seismogram metrics
+across every event recorded at a station:
+
+```python
+from aimbat.models import AimbatSeismogram, AimbatStation, SeismogramQualityStats
+
+with Session(engine) as session:
+    stations = session.exec(
+        select(AimbatStation).options(
+            selectinload(rel(AimbatStation.seismograms)).selectinload(
+                rel(AimbatSeismogram.quality)
+            )
+        )
+    ).all()
+    stats = [SeismogramQualityStats.from_station(s) for s in stations]
+```
+
+Each `stats` item exposes `cc_mean`, `mccc_cc_mean`, and `mccc_error` as
+(mean, SEM) pairs aggregated across all events at that station.
+
+### Event-level quality summary
+
+`SeismogramQualityStats.from_event` aggregates per-seismogram metrics for a
+single event and also carries the global `mccc_rmse` array-fit value:
+
+```python
+from aimbat.models import AimbatEvent, AimbatSeismogram, SeismogramQualityStats
+
+with Session(engine) as session:
+    events = session.exec(
+        select(AimbatEvent).options(
+            selectinload(rel(AimbatEvent.seismograms)).selectinload(
+                rel(AimbatSeismogram.quality)
+            ),
+            selectinload(rel(AimbatEvent.quality)),
+        )
+    ).all()
+    stats = [SeismogramQualityStats.from_event(e) for e in events]
+```
+
+`mccc_rmse` on each stats object is the global array fit for that event —
+useful for comparing event difficulty across a dataset.
+
 ## Worked Example
 
 The script below builds a complete project from scratch. It loads **3 events**,

docs/usage/event-selection.md

@@ -6,15 +6,21 @@ one event at a time.
 
 ## Listing events
 
-=== "CLI / Shell"
+=== "CLI"
 
     ```bash
     aimbat event list
     ```
 
-    The table shows each event's ID, time, and location. IDs are displayed in
-    their shortest unambiguous form — use any unique prefix when passing an
-    ID to other commands.
+=== "Shell"
+
+    ```bash
+    event list
+    ```
+
+The table shows each event's ID, time, and location. IDs are displayed in
+their shortest unambiguous form — use any unique prefix when passing an
+ID to other commands.
 
 === "TUI"
 
@@ -26,35 +32,48 @@ one event at a time.
 
 ---
 
-## Selecting an Event for CLI / Shell
+## Selecting an Event for the CLI and Shell
 
 Most processing commands (like `aimbat align iccs` or `aimbat snapshot create`)
 operate on a single event. You can specify the target event in two ways:
 
-### 1. The `--event-id` flag (or `--event`)
+### 1. Positional argument
 
-Pass the ID directly to any command. You can use the full UUID or any unique
-prefix:
+Pass the ID directly as the first argument. You can use the full UUID or any
+unique prefix:
 
 ```bash
-aimbat align iccs --event-id 6a4a
+aimbat align iccs 6a4a
+```
+
+The named forms `--event` and `--event-id` are also accepted and behave
+identically:
+
+```bash
+aimbat align iccs --event 6a4a
 ```
 
 ### 2. The `DEFAULT_EVENT_ID` environment variable
 
-If you are working on the same event for multiple commands, you can set the
-`DEFAULT_EVENT_ID` environment variable in your shell. This tells AIMBAT to
-use that event whenever the `--event-id` flag is omitted:
+If you are working on the same event for multiple commands, set the
+`DEFAULT_EVENT_ID` environment variable in your shell. AIMBAT uses it
+whenever no explicit ID is provided:
 
 ```bash
 export DEFAULT_EVENT_ID=6a4a
 aimbat align iccs
 aimbat snapshot create "post-ICCS"
 ```
 
-The shell prompt also reflects this ID when set. To clear it, simply unset the
+The shell prompt also reflects this ID when set. To clear it, unset the
 variable: `unset DEFAULT_EVENT_ID`.
 
+!!! note
+    `DEFAULT_EVENT_ID` is a plain shell environment variable consumed directly
+    by the CLI argument parser. It is **not** an AIMBAT setting: it has no
+    `AIMBAT_` prefix, cannot be set in `.env`, and does not appear in
+    `aimbat settings list`.
+
 ---
 
 ## Selecting an event for processing (TUI / GUI)