Skip to content

refactor: active event -> default event #225

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
smlloyd merged 1 commit into from
Mar 5, 2026
Merged

refactor: active event -> default event #225

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 32 additions & 41 deletions docs/first-steps/core-concepts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,34 @@
# Core concepts

## Motivation

Precise phase arrival picks are the foundation of travel time tomography —
the accuracy of the resulting images of Earth's interior depends directly on
the quality of these measurements. Obtaining them requires picking the phase
arrival and assessing data quality for every seismogram, across every event
in the dataset. With modern seismic arrays recording each earthquake on
increasingly large numbers of seismometers, doing this seismogram by seismogram
quickly becomes impractical.

AIMBAT addresses this by shifting the focus from individual seismograms to the
dataset as a whole. Rather than assessing and processing each trace in
isolation, the focus is at the array level — where data quality and phase
arrivals can be judged in the context of all seismograms at once. Decisions
about filter settings, time windows, and which seismograms to include apply to
the entire dataset, and picks are refined across all traces simultaneously.
Everything is processed in bulk.

## Semi-automatic

This bulk processing happens in a semi-automatic way, whereby initial picks
surrounded by large time windows are iteratively refined into accurate phase
arrival picks with narrow time windows. Selecting high quality seismograms and
updating picks (for all stations simultaneously) are either performed manually,
or automatically by the ICCS algorithm. The automatically refined picks depend
on user-adjustable parameters, which are typically tuned between iterations to
achieve the best results. Once satisfied with the picks and parameter settings,
MCCC is run to produce the final relative arrival time measurements.

## Snapshots and rollback

The iterative nature of the workflow means exploring different parameter
combinations is central to the process. This is safe to do because the
seismogram data themselves are never modified — AIMBAT only stores and updates
processing parameters separately from the data.

To support this further, snapshots of the current parameter state can be saved
at any point during processing — including before any changes are made.
Rolling back to a snapshot restores the parameters exactly as they were, but
does not delete any other snapshots, so it is possible to switch freely between
saved states.
## The problem

Teleseismic travel time tomography requires accurate phase arrival picks across
large seismic arrays. Picking each trace individually does not scale — and
doing so in isolation discards the most useful information available: the
coherence of the wavefield across the array.

AIMBAT works at the array level. Filter settings, time windows, and data
quality decisions apply to the whole dataset, and picks are refined across all
traces simultaneously using cross-correlation.

## Workflow

Processing follows a standard pattern:

1. **Initial picks** — broad time windows are placed around approximate phase
arrivals, typically from a reference model.
2. **ICCS** — the Iterative Cross-Correlation and Stack algorithm refines picks
and windows across all seismograms simultaneously. Parameters controlling
the algorithm are adjusted between iterations until the results are
satisfactory.
3. **Quality control** — seismograms can be selected or deselected manually, or
automatically by ICCS based on cross-correlation quality.
4. **MCCC** — Multi-Channel Cross-Correlation produces the final relative
arrival time measurements from the refined picks.

## Snapshots

Because tuning parameters is an inherently iterative process, AIMBAT supports
snapshots — named saves of the current parameter state. Rolling back to a
snapshot restores parameters exactly, without removing other snapshots. This
makes it safe to explore parameter space without losing previous results.
147 changes: 47 additions & 100 deletions docs/first-steps/data.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,14 @@
# Data

AIMBAT treats input data as read-only. Processing parameters and results are
stored separately from the data in a database. Once imported into a project,
the data sources (e.g. SAC files) are only used to read the waveforms. All
metadata (e.g. event and station information) is stored in the database.
stored separately in a database. Once imported, data sources (e.g. SAC files)
are only read for waveform data — all metadata (event and station information)
is stored in the database.

## Data hierarchy

Moving away from storing all data in individual files means things are
organised differently. For example, a seismogram in AIMBAT is no longer a file;
it is an object in the database that links to a data source, station and event.
Stations and events are also objects in the database, and they are shared
between seismograms.
A seismogram in AIMBAT is a database object that links a data source, a
station, and an event. Stations and events are shared across seismograms.

```mermaid
---
Expand All @@ -25,121 +22,71 @@ erDiagram

```

!!! Tip
Seismograms that are supposed to be processed together are identified only
by their shared event and station in the database. You can therefore be
quite flexible in how you organise your data on disk, but you must make
sure they reference the exact same station and event information — small
differences in the metadata (e.g. a different number of decimal places) may
lead to AIMBAT treating seismograms as belonging to different events or
stations.
!!! tip
Seismograms that belong together are identified solely by shared event and
station records in the database. You can organise data files freely on disk,
but the metadata must match exactly — small differences (e.g. rounding in
coordinates) may cause AIMBAT to treat seismograms as belonging to different
events or stations.

## Deleting items

All of the above happens transparently to the user, but there are some things to
be mindful of when it comes to deleting items from a project:

- Deleting[^1] an event or station from a project will remove all related
seismograms.
- Conversely, deleting a seismogram will *not* remove the event or station.
This remains true even if an event or station end up not being used by any
seismograms in the project.

!!! Tip
If this all seems overly complicated to you, remember that often parameters
that apply to all seismograms of an event need to be changed to
the same value. Organising the data like this means we only need to change
the parameters in one place. And there are some additional
[benefits](#snapshots) when setting things up this way!
- Deleting[^1] an event or station removes all associated seismograms.
- Deleting a seismogram does *not* remove the event or station, even if they
are no longer referenced by any seismogram.

[^1]:
Deleting items from a project simply drops them from the project. AIMBAT
will *never* delete (or modify) any files.
Deleting items from a project drops them from the database only. AIMBAT
will *never* delete or modify any files.

## Project file

If the above section sounded a bit "databasey" to you, that is because you are
spot on! AIMBAT projects consist of a single
[sqlite](https://www.sqlite.org){ target="_blank" } file (which is
automatically generated when a new project is created). This file contains a
database to manage all aspects of an AIMBAT project. Understanding the
internals of this file (or all the tables used in the database) is not
particularly important for normal usage, though it might be useful to look at
the data directly in cases where AIMBAT behaves in unexpected ways (e.g. due to
inconsistencies in the seismogram files used as input). To do this we suggest
viewing the database in tools such as
[DB Browser for SQLite](https://sqlitebrowser.org){ target="_blank" }.
An AIMBAT project is a single [SQLite](https://www.sqlite.org){ target="_blank" }
file, created automatically when a new project is initialised. All project
state lives in this file. You do not need to understand the database schema for
normal use, but tools like
[DB Browser for SQLite](https://sqlitebrowser.org){ target="_blank" } are
useful for inspecting the raw data when debugging unexpected behaviour.

![DB Browser](../images/sqlbrowser.png){ loading=lazy }

## Parameters

As alluded to above, there is a hierarchy to how data are structured in AIMBAT,
and a major benefit of this is that parameters can be applied at different
levels. Thus there are three tiers of parameters that control behaviour and
processing:

1. AIMBAT defaults: shared across all events and seismograms in a project.
2. Event parameters: specific to an event (or shared across all seismograms
of that event).
3. Seismogram parameters: specific to a single seismogram.

### AIMBAT Defaults

AIMBAT [defaults](../usage/defaults.md) are global settings that control how
the application itself behaves, as well as defaults for
[event](#event-parameters) and [seismogram](#seismogram-parameters) parameters
when they are instantiated. The currently used values for these parameters can
be listed by running `#!bash aimbat utils settings` in the terminal. As some
settings are relevant before a project is created, they cannot be stored in
the project file.

### Event Parameters

Event parameters are used during processing. They are parameters that are
specific to an event (e.g. if an event should be marked as completed), or
parameters that are shared across all seismograms of that event (e.g. time
window for the cross-correlation, filter parameters, etc.).
These parameters are attributes of the
[`AimbatEventParametersBase`][aimbat.models.AimbatEventParametersBase]
class.

### Seismogram Parameters
Parameters are organised in three tiers:

Seismogram parameters are also used during processing. Most notably the time
picks belong to this tier. These parameters are attributes of the
[`AimbatSeismogramParametersBase`][aimbat.models.AimbatSeismogramParametersBase]
class.
1. **AIMBAT defaults** — global settings that control application behaviour and
provide initial values for event and seismogram parameters. Listed with
`#!bash aimbat utils settings`. Stored outside the project file, since some
settings are needed before a project exists.
2. **Event parameters** — shared across all seismograms of an event (e.g. time
window, filter settings, completed flag). Attributes of
[`AimbatEventParametersBase`][aimbat.models.AimbatEventParametersBase].
3. **Seismogram parameters** — specific to a single seismogram (e.g. arrival
time pick, select/deselect flag). Attributes of
[`AimbatSeismogramParametersBase`][aimbat.models.AimbatSeismogramParametersBase].

## Snapshots

The event and seismogram parameters are stored separately from the events and
seismograms (much like the seismograms link to an event and station instead of
saving them in the same object). This opens up the possibility to save an
arbitrary number of copies of these parameters that capture the current state
of processing. This allows for risk-free experimentation with different
parameters - if something goes wrong, you can always roll back to the last (or
any other) snapshot.
Event and seismogram parameters can be snapshot at any point during processing.
Snapshots are independent copies of the parameter state — rolling back to one
restores parameters exactly without affecting other snapshots.

!!! tip
It is always a good idea to create a snapshot right after importing new
data!
Create a snapshot immediately after importing data, before any processing
has been done.

## UUID (Universally Unique Identifiers)
## UUIDs

Internally, the items in a project use
[UUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier) to
identify themselves. They look something like this:
All items in a project are identified internally by
[UUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier):

```text
37a8245f-c508-46a7-9bbc-d1c601e42983
```

The length and randomness of these identifiers guarantee no two items will ever
have the same ID (even if generated on two separate computers, in different
databases etc.), but they are a bit unwieldy to use directly. To make things
easier, they are typically presented in a truncated form to the user (but
always long enough to be unique). For example, if there are only four
seismograms and they have these UUIDS:
Full UUIDs are unwieldy to type, so AIMBAT presents truncated forms — using
only as many characters as needed to be unambiguous within the project. For
example, four seismograms with these IDs:

```text
6a4acdf7-6c7b-4523-aaaa-0a674cdc5f2d
Expand All @@ -148,7 +95,7 @@ c980918d-106d-44d9-a3fa-5740f58edf4e
5dcb5c4b-b416-4a7b-870f-9a8da42a7dd2
```

they can still be unambiguously identified using only the first two characters:
can be unambiguously referenced as:

```text
6a
Expand All @@ -157,4 +104,4 @@ c9
5d
```

If two characters are insufficient, then three will be used, and so on.
If two characters are insufficient, three are used, and so on.
78 changes: 14 additions & 64 deletions docs/first-steps/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,108 +1,58 @@
# Installing AIMBAT

AIMBAT is built on top of standard [Python](https://www.python.org), combined
with a number of popular third party modules such as [NumPy][numpy] and
[SciPy][scipy]. It is available as a package from the
[Python Package Index][pypi], and can therefore be
installed using Python's standard package manager,
[`pip`](https://pip.pypa.io/en/stable/).
AIMBAT is available on [PyPI][pypi] and can be installed with any standard
Python package manager. We recommend [`uv`][uv] or [`pipx`][pipx], which
isolate the installation from the rest of your Python environment.

However, as AIMBAT is a standalone application, we recommend installing it
using tools like [`uv`][uv] or [`pipx`][pipx] instead[^1]. Here we show how to
install and run AIMBAT using `uv`.
## Running without installing

[^1]: If you want to get really fancy you can also use tools like
[MISE-EN-PLACE](https://mise.jdx.dev), which use `uv` or `pipx` under the
hood.

## Running AIMBAT without installing

Running applications with `uv` is very simple. It manages all dependencies and
even installs a compatible Python version if needed. A very convenient feature
of using `uv` is that it can run applications without installing them:

```bash
$ # First check that uv is available:
$ uv self version
uv 0.10.6
$ # Next run AIMBAT using uv tool:
$ uv tool run aimbat --version
⠴ Resolving dependencies...
2.0.0
```

The initial run may take a while to download AIMBAT and its dependencies, but
once that is done subsequent runs will be much faster. `uv tool run` is such a
useful command that it has its own alias, `uvx`:
`uv` can run AIMBAT directly without a permanent installation:

```bash
$ uvx aimbat --version
2.0.0
...
```

## Running the development version
The first run downloads AIMBAT and its dependencies; subsequent runs use the
cache and start immediately.

Running AIMBAT without installing it is particularly useful for trying out the
latest development version:
## Running the development version

```
```bash
$ uvx git+https://github.com/pysmo/aimbat --version
Updating https://github.com/pysmo/aimbat (HEAD)
⠇ Resolving dependencies...
⠦ Preparing packages... (66/69)
---> 100%
---> 100%
2.1.0.dev0
```

To clean up after yourself, you can remove the `uv` cache:
To clear the cache afterwards:

```bash
$ uv clean
Clearing cache at: /home/bob/.cache/uv
Cleaning [==================> ] 91%
Removed 26702 files (2.1GiB)
```

## Installing locally

Permanent installation is just as easy. Just run `uv tool install`:
## Installing permanently

```bash
$ uv tool install aimbat
⠦ Resolving dependencies...
⠇ Preparing packages... (66/69)
+ aimbat==2.0.0
...
Installed 1 executable: aimbat
```

You can now run AIMBAT using the `aimbat` command directly:

```bash
$ aimbat
Usage: aimbat COMMAND
...
```

!!! tip
If the above command fails (because your shell can't find the `aimbat`
command), you may need to add `~/.local/bin` to your `PATH`. This can be
done automatically by running `#!bash uv tool update-shell`.
If your shell cannot find the `aimbat` command, add `~/.local/bin` to your
`PATH` by running `#!bash uv tool update-shell`.

Upgrading or uninstalling is just as easy with `uv tool upgrade` and `uv tool
uninstall`:
Upgrade or uninstall with:

```bash
$ uv tool upgrade aimbat
Nothing to upgrade
$ uv tool uninstall aimbat
Uninstalled 1 executable: aimbat
```

[numpy]: https://numpy.org
[scipy]: https://scipy.org
[pypi]: https://pypi.org/project/aimbat/
[uv]: https://docs.astral.sh/uv/
[pipx]: https://pipx.pypa.io
Loading