feat: add JSON export functionality for snapshot results

CHANGELOG.md

@@ -92,6 +92,7 @@ All notable changes to the **AIMBAT** project will be documented in this file.
 - Update plot seismograms.
 - Remove dead code ([#231](https://github.com/pysmo/aimbat/issues/231))
 - Quality stats integrated into read models and tui
+- Quality stats integrated into read models and tui ([#232](https://github.com/pysmo/aimbat/issues/232))
 
 ### 🚀 New Features
 

README.md

@@ -40,23 +40,27 @@ arrival times.
 ## Version 2
 
 AIMBAT v2 is a complete rewrite. It shares the same goal as v1 but none of the
-code.
-
-- **Complete rewrite.** The algorithms are optimised and projects are stored in
-  a SQLite database (via [SQLModel](https://sqlmodel.tiangolo.com)), making them
-  persistent, portable, and inspectable.
-- **Focused scope.** Much of the underlying code has moved into the
-  [pysmo](https://github.com/pysmo/pysmo) library, leaving AIMBAT to focus on
-  the user-facing ICCS → quality-control → MCCC workflow rather than
-  reimplementing general seismogram utilities.
-- **Flexible data storage.** A single project can hold any number of seismic
-  events. Files from different events can live anywhere on disk — no need to
-  keep them in separate directories or follow a particular layout.
-- **Maintainable.** v2 is built on modern, typed Python with a comprehensive
-  test suite and strict dependency management, so it keeps working as the
-  ecosystem evolves.
+code. The main improvements for users are:
+
+- **Flexible workflow.** Snapshots save the complete processing state at any
+  point, making it straightforward to roll back, compare parameter sets, or
+  try a different approach without losing prior work. ICCS and MCCC can be run
+  in any order and as many times as needed; results can be exported from any
+  snapshot, not only after a final MCCC pass.
+- **Multi-event projects.** A single project database holds any number of
+  seismic events. Waveform files can live anywhere on disk — no prescribed
+  directory layout and no need to manage separate directories per event.
+- **Structured output for downstream analysis.** Each snapshot can be exported
+  as a structured JSON document containing per-station arrival times, ICCS
+  correlation coefficients, and — if MCCC has been run — formal timing standard
+  errors. This makes AIMBAT useful as a data source beyond tomographic
+  inversion: station quality assessment, delay patterns as a function of
+  back-azimuth, or any workflow that requires picks and quality metrics in a
+  machine-readable format.
 - **Multiple interfaces.** AIMBAT can be used via a CLI, an interactive shell,
-  a terminal UI, or directly as a Python library.
+  a terminal UI, or directly as a Python library. All functionality is
+  accessible through the Python API, making it straightforward to script any
+  part of the workflow.
 
 ## Quick Start
 

docs/first-steps/workflow.md

@@ -28,8 +28,12 @@ flowchart TD
 
 AIMBAT[^2] stacks all seismograms aligned on an initial pick, then
 cross-correlates each seismogram against that stack to refine arrivals
-simultaneously across the array. Parameters and picks are improved iteratively
-before a final MCCC run.
+simultaneously across the array. The diagram below reflects the original
+AIMBAT workflow. In modern AIMBAT, snapshots provide save points throughout the
+process, making the workflow more flexible: MCCC can be run at any point, not
+only as a final step, and ICCS and MCCC runs may alternate as parameters are
+refined. Results can be exported from any snapshot; running MCCC before the
+final export is usual but not required.
 
 [^2]:
   Lou, X., et al. "AIMBAT: A Python/Matplotlib Tool for Measuring
@@ -56,9 +60,13 @@ flowchart TD
 1. Change one parameter at a time and run ICCS to observe the effect before
    making further adjustments.
 2. Take snapshots often, with a comment describing the current state. They are
-   lightweight and easy to roll back to.
+   lightweight and easy to roll back to. There is no limit on how many
+   snapshots an event can have — use them as freely as version-control commits.
 3. Do not focus too much on individual poorly-aligned seismograms — use
    autoflip and autoselect to let the algorithm handle them.
+4. Export picks whenever the dataset is in a useful state — not only at the
+   end. ICCS picks are directly usable, and a snapshot taken at any stage is
+   sufficient to produce output.
 
 ### ICCS running modes
 
@@ -82,3 +90,17 @@ automatically if parameter changes bring it into alignment.
     and revised pick across iterations), consider deleting it from the project.
     Rogue seismograms can distort the valid ranges used when updating picks and
     time windows.
+
+### MCCC running modes
+
+MCCC has one optional flag:
+
+- **`--all`**: includes deselected seismograms in the inversion. By default,
+  only seismograms with `select=True` participate. Passing `--all` computes
+  picks and quality metrics for every seismogram, regardless of selection
+  state, which is useful when you want timing estimates for all stations even
+  if some were excluded from the ICCS stack.
+
+Use `--all` with care: deselected seismograms are typically excluded because
+they are noisy or misaligned, and including them may degrade the inversion
+for the rest of the array.

docs/usage/alignment.md

@@ -5,8 +5,8 @@
 ICCS alignment is inherently exploratory. There is no fixed sequence of steps
 that works for every dataset — it is a feedback loop between adjusting
 parameters, running the algorithm, and examining the results. The goal is a
-stack that is coherent across the array and CC norms that are high enough to
-give MCCC a clean dataset to work with.
+stack that is coherent across the array and correlation coefficients that are
+high across most of the array.
 
 Parameters interact: a filter that sharpens the waveform may allow a narrower
 time window, which in turn changes which seismograms align well. It is
@@ -93,58 +93,64 @@ refinement.
 
 ### Minimum CC norm
 
-`min_ccnorm` is the threshold used by autoselect to deselect seismograms
+`min_cc` is the threshold used by autoselect to deselect seismograms
 automatically. It does not affect the cross-correlation itself — only which
 seismograms are excluded from contributing to the stack in subsequent
 iterations.
 
 Setting this too high early on may exclude seismograms that would align well
 once the stack improves. It is usually more effective to start with a
-permissive threshold and tighten it as alignment converges.
+permissive threshold and tighten it as alignment converges. The threshold can
+be adjusted interactively with `aimbat tool cc`.
 
 ---
 
 ## Interactive adjustment
 
-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.
+In addition to setting parameters directly, four interactive tools let you
+adjust values by interacting with the plot — clicking or scrolling in a
+waveform display rather than typing numbers. They are the most convenient way
+to explore parameters, but the same values can also be set directly via CLI
+arguments or the Python API.
 
 === "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
+    aimbat tool phase <ID>    # adjust t1 by clicking on the stack
+    aimbat tool window <ID>   # set window_pre / window_post by clicking
+    aimbat tool cc <ID>       # set min_cc by scrolling the matrix image
+    aimbat tool bandpass <ID> # adjust bandpass filter settings interactively
     ```
 
 === "Shell"
 
     ```bash
-    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
+    tool phase    # adjust t1 by clicking on the stack
+    tool window   # set window_pre / window_post by clicking
+    tool cc       # set min_cc by scrolling the matrix image
+    tool bandpass # adjust bandpass filter settings interactively
     ```
 
-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) to set the value,
+then close the window to save it.
 
-All three accept `--no-context` and `--all` (include deselected seismograms).
+All four accept `--no-context` and `--all` (include deselected seismograms).
 
 === "TUI"
 
     Press `t` to open the **Tools** menu, then choose from:
 
     - **Phase arrival (t1)** — click in the stack to shift all picks globally
     - **Time window** — click to place the window boundaries
-    - **Min CC norm** — scroll the matrix image to set the threshold
+    - **Min CC** — scroll the matrix image to set the threshold
+    - **Bandpass filter** — toggle the filter and adjust frequency bounds
 
     Before launching, toggle **Context** (`c`) and **All seismograms** (`a`)
     as needed. The TUI suspends while the matplotlib window is open and
     resumes when you close it.
 
-The pick and window tools open the **stack view**; the CC norm tool opens the
-**matrix image**. The behaviour of each is described in [The ICCS
+The `phase`, `window`, and `bandpass` tools open the **stack view**; `cc`
+opens the **matrix image**. The behaviour of each is described in [The ICCS
 Stack](iccs-stack.md#use-in-interactive-adjustment).
 
 ---
@@ -174,7 +180,7 @@ throughout. It is safe to run repeatedly.
 
 ### Autoselect
 
-With autoselect enabled, seismograms whose CC norm falls below `min_ccnorm`
+With autoselect enabled, seismograms whose CC norm falls below `min_cc`
 are automatically set to `select = False` and excluded from the stack in
 subsequent iterations. Importantly, they are still cross-correlated against
 the stack — so if parameters improve and they start to align better, they can
@@ -200,25 +206,29 @@ automatically; there is no need to monitor it. Running ICCS again from
 AIMBAT's interface always starts a fresh run from the current picks.
 
 What matters is the convergence of the *overall process*: across multiple
-runs with adjusted parameters, do the stack and CC norms keep improving, or
-have they plateaued? When further adjustments produce no visible improvement
-in the stack, alignment is as good as it is going to get with ICCS, and it is
-time to move to MCCC.
+runs with adjusted parameters, do the stack and correlation coefficients keep
+improving, or have they plateaued? When further adjustments produce no visible
+improvement in the stack, the data is ready — either for direct export, or as
+input to MCCC for formal timing uncertainties.
 
 ---
 
 ## Knowing when to stop
 
 There is no objective criterion for when ICCS alignment is "done". Practical
-signals that the dataset is ready for MCCC:
+signals that the dataset is ready:
 
 - The stack is visually coherent — individual traces closely follow its shape
-- CC norms are high across most of the array
+- Correlation coefficients are high across most of the array
 - The time window highlights a clean, well-defined arrival
 - Running ICCS again with or without autoflip/autoselect produces no
   meaningful change
 
-It is worth taking a snapshot at this point before running MCCC.
+At this point the ICCS picks can be exported directly from a snapshot — see
+[Exporting Results](results.md). If formal per-station timing standard errors
+are needed (for example, as input to tomographic inversion), continue to
+[MCCC alignment](mccc.md) before taking the final snapshot. Either way, it is
+worth taking a snapshot now before making any further changes.
 
 ---
 
@@ -228,9 +238,11 @@ It is worth taking a snapshot at this point before running MCCC.
   an improvement or regression if multiple things change at once.
 - **Take snapshots liberally.** They are lightweight and make it easy to
   backtrack to a promising state.
-- **Don't over-optimise.** MCCC is more precise than ICCS and will further
-  refine picks. The job of ICCS is to get the data to a state where MCCC can
-  succeed — not to produce perfect picks itself.
+- **ICCS picks are directly usable.** For workflows that do not require formal
+  timing uncertainties, ICCS picks exported from a snapshot are suitable for
+  further analysis as-is. MCCC adds formal standard errors and a more rigorous
+  pairwise solution — run it when those are needed, but there is no obligation
+  to do so.
 - **Outlier seismograms.** If a seismogram consistently has a poor CC norm
   across many runs and parameter combinations, it may be worth deleting it
   from the project rather than letting it drag down the stack.

docs/usage/index.md

@@ -53,7 +53,12 @@ aimbat data add *.sac
 export DEFAULT_EVENT_ID=$(aimbat event dump | jq -r '.[0].id')
 aimbat snapshot create "initial import"
 aimbat align iccs --autoflip --autoselect
+aimbat snapshot create "post-ICCS"
+aimbat snapshot results <SNAPSHOT_ID> --output results.json  # export ICCS picks
+# or continue to MCCC for formal timing uncertainties:
 aimbat align mccc
+aimbat snapshot create "post-MCCC"
+aimbat snapshot results <SNAPSHOT_ID> --output results.json
 ```
 
 ---
@@ -96,7 +101,9 @@ Exit with `exit`, `quit`, `q`, or **Ctrl+D**.
 ### Terminal UI (TUI)
 
 ```bash
-aimbat tui
+aimbat tui           # via main CLI
+aimbat-tui           # standalone entry point (same app)
+aimbat tui --debug   # enable verbose logging
 ```
 
 The TUI is a full-screen, keyboard-driven interface built for efficient
@@ -174,13 +181,29 @@ Pressing `Enter` on any table row opens a context menu. Available actions depend
 | Reset parameters | Restore all per-seismogram parameters to their defaults |
 | Delete seismogram | Remove the seismogram from the project |
 
+**Snapshots — Snapshots table:**
+
+| Action | Description |
+|--------|-------------|
+| Show details | Display the event-level parameters saved in the snapshot |
+| Preview stack | Open the ICCS stack plot built from the snapshot's parameters |
+| Preview matrix image | Open the matrix image built from the snapshot's parameters |
+| Save results to JSON | Export per-seismogram picks and MCCC metrics to a JSON file |
+| Rollback to this snapshot | Restore the snapshot's parameters as the current live values |
+| Delete snapshot | Permanently remove the snapshot |
+
+Both preview options support `c` (toggle context waveforms) and `a` (include
+all seismograms) key bindings inside the action menu before the plot opens.
+See [Snapshots](snapshots.md) for a description of each action and the format
+of the exported results file.
+
 #### Global key bindings
 
 | Key | Action |
 |-----|--------|
 | `e` | Open event switcher |
 | `a` | Run alignment (ICCS or MCCC) |
-| `t` | Open interactive tools (matplotlib picking) |
+| `t` | Open interactive parameter tools (phase pick, time window, min CC, bandpass filter) |
 | `p` | Edit processing parameters |
 | `n` | Create a new snapshot |
 | `d` | Add data files to the project |
@@ -288,10 +311,12 @@ alignment and interactive tools are unavailable until the problem is resolved.
 
 AIMBAT writes a log to `aimbat.log` in the current directory. By default only
 `INFO`-level messages and above are recorded. To get more detail, pass
-`--debug` to any CLI command:
+`--debug` to any CLI command or TUI entry point:
 
 ```bash
-aimbat align iccs --debug
+aimbat align iccs --debug   # any CLI command
+aimbat tui --debug           # TUI via main CLI
+aimbat-tui --debug           # TUI standalone entry point
 ```
 
 This sets the log level to `DEBUG` for that invocation and writes verbose