Skip to content

refactor(core): re-arange core, move set_default_event and friends ou… #224

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(core): re-arange core, move set_default_event and friends ou… #224

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
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,3 +38,4 @@ aimbat_test*.log
GEMINI.md
CLAUDE.md
.claude/settings.local.json
scratch/
80 changes: 36 additions & 44 deletions docs/first-steps/data.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,17 @@
# Data

Because a lot of operations in AIMBAT involve adjusting parameters that do
*not* require reading entire seismograms, the time series components of the
seismograms are kept separate from the rest of the data. If this were not the
case, doing something like adjusting the time window for the cross-correlation
for an event with 200 seismograms, would require reading all 200 seismograms
from disk, even though their data are not actually used for that operation. Not
having to do this naturally benefits performance, but also means that an AIMBAT
project does not really use up much disk space at all. As this is true for any
amount of seismograms, we can include multiple events in a single project.
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.

## Data hierarchy

Moving away from storing all data in individual files means things are
organised differently. Most importantly, seismograms, after importing them into
a project, no longer each contain event and station information. Instead they
use (and share) separately stored events and stations. Thus a single event will
contain multiple seismograms. The same is true for a single station, while the
seismograms themselves use exactly one event, one station, and one data source
(containing the time series).
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.

```mermaid
---
Expand All @@ -32,21 +25,25 @@ erDiagram

```

While all of this happens transparently to the user, there are still some
things to be mindful of:
!!! 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.

## 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:

- Seismograms that are supposed to be processed together are no longer
identified e.g. by being stored in the same directory, but instead from using
the same event and station. Thus the files they are created from when adding
them to an AIMBAT project *must* contain identical station and event data.
- 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.
- After importing a seismogram into a project, it no longer accesses the
metadata stored in the source file. It does, however, still need to be able
to read the time series data from it.
- 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
Expand Down Expand Up @@ -88,18 +85,13 @@ processing:

### AIMBAT Defaults

AIMBAT defaults 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 found by running
`#!bash aimbat settings` in your terminal. As some settings are relevant before
a project is created, they cannot be stored in the project file. To override these
settings you can set the corresponding environment variable directly (e.g.
`export AIMBAT_PROJECT=different_project_name.db`) or place those settings in a
`.env`[^2] file. Note that if you set them in both places the environment
variable is used.

[^2]: The file must be named exactly `.env`, and not `SOMENAME.env`!
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

Expand All @@ -108,14 +100,14 @@ 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.lib.models.AimbatEventParametersBase]
[`AimbatEventParametersBase`][aimbat.models.AimbatEventParametersBase]
class.

### Seismogram Parameters

Seismogram parameters are also used during processing. Most notably the time
picks belong to this tier. These parameters are attributes of the
[`AimbatSeismogramParametersBase`][aimbat.lib.models.AimbatSeismogramParametersBase]
[`AimbatSeismogramParametersBase`][aimbat.models.AimbatSeismogramParametersBase]
class.

## Snapshots
Expand All @@ -138,7 +130,7 @@ Internally, the items in a project use
[UUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier) to
identify themselves. They look something like this:

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

Expand All @@ -149,7 +141,7 @@ 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:

```
```text
6a4acdf7-6c7b-4523-aaaa-0a674cdc5f2d
647568aa-8361-45ef-bfc8-61f873847f17
c980918d-106d-44d9-a3fa-5740f58edf4e
Expand All @@ -158,7 +150,7 @@ c980918d-106d-44d9-a3fa-5740f58edf4e

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

```
```text
6a
64
c9
Expand Down
109 changes: 34 additions & 75 deletions docs/first-steps/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,19 @@
# Installing AIMBAT

AIMBAT is built on top of standard [Python](https://www.python.org) and uses
some popular third party modules (e.g. [NumPy][numpy], [SciPy][scipy]). In
order to benefit from modern Python features and up to date modules, AIMBAT is
developed on the latest stable Python versions. Automatic tests are done on
version 3.12 and newer.

AIMBAT is available as a package from the
[Python Package Index](https://pypi.org/project/aimbat/). This means it can be
installed using the [`pip`](https://pip.pypa.io/en/stable/) module. However, as
AIMBAT is a standalone application (rather than a library), we recommend
installing it using [`uv`](https://docs.astral.sh/uv/) instead. `uv` is a
single binary that doesn't require any dependencies to be installed, and it
allows you to install and run AIMBAT in an isolated environment.
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/).

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`.

[^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

Expand All @@ -22,44 +23,21 @@ of using `uv` is that it can run applications without installing them:

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

AIMBAT command line interface entrypoint for all other commands.

This is the main command line interface for AIMBAT. It must be
executed with a command (as specified below) to actually do anything.
Help for individual commands is available by typing aimbat COMMAND
--help.

╭─ Commands ────────────────────────────────────────────────────────╮
│ data Manage seismogram files in an AIMBAT project. │
│ event View and manage events in the AIMBAT project. │
│ iccs ICCS processing tools. │
│ project Manage AIMBAT projects. │
│ seismogram View and manage seismograms in the AIMBAT project. │
│ settings Print a table with default settings used in AIMBAT. │
│ snapshot View and manage snapshots. │
│ station View and manage stations. │
│ utils Utilities for AIMBAT. │
│ --help -h Display this message and exit. │
│ --version Display application version. │
╰───────────────────────────────────────────────────────────────────╯
$ uv tool run aimbat --version
⠴ Resolving dependencies...
2.0.0
```

This will likely have taken a while, as `uv` has to download and install a lot
of dependencies. Subsequent runs will be much faster. `uv tool run` is such a
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`:

```bash
# 'uvx' is an alias for 'uv tool run':
$ uvx aimbat
Usage: aimbat COMMAND
$ uvx aimbat --version
2.0.0
...
```

Expand All @@ -82,17 +60,16 @@ To clean up after yourself, you can remove the `uv` cache:

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

## Installing AIMBAT locally
## Installing locally

After successfully test driving AIMBAT you may want to actually install it.
This is very simple with `uv`:
Permanent installation is just as easy. Just run `uv tool install`:

Comment on lines +68 to 71
Copy link

Copilot AI Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sentence “Permanent installation of is just as easy.” is missing the object (e.g. “Permanent installation of AIMBAT…”). This reads as a typo in the rendered docs.

Copilot uses AI. Check for mistakes.
```bash
# Again use uv tool, but this time with the 'install' command:
$ uv tool install aimbat
⠦ Resolving dependencies...
⠇ Preparing packages... (66/69)
Expand All @@ -110,12 +87,12 @@ 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`.

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

```bash
$ uv tool upgrade aimbat
Expand All @@ -124,26 +101,8 @@ $ uv tool uninstall aimbat
Uninstalled 1 executable: aimbat
```

## Demo

This demo shows what you can expect to see in your terminal when running
the commands above:

<div id="asciinema-installation-demo" style="z-index: 1; position: relative; "></div>

<script>
window.onload = function(){
const player = AsciinemaPlayer.create('../../images/asciinema/install-with-uv.cast', document.getElementById('asciinema-installation-demo'),
{poster: 'npt:0:18', idleTimeLimit: 2, markers: [
[3, 'Intro'],
[5, 'Foo'],
[9, 'Bar'],
] });

}
</script>

!!! tip

These kinds of recordings work just like normal videos, but you can also
select text and copy it to your clipboard!
[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