Skip to content

aimbat

AIMBAT (Automated and Interactive Measurement of Body wave Arrival Times) is an open-source software package for efficiently measuring teleseismic body wave arrival times for large seismic arrays (Lou et al., 2012). It is based on a widely used method called MCCC (Multi-Channel Cross-Correlation) developed by VanDecar and Crosson (1990). The package is automated in the sense of initially aligning seismograms for MCCC which is achieved by an ICCS (Iterative Cross Correlation and Stack) algorithm. Meanwhile, a graphical user interface is built to perform seismogram quality control interactively. Therefore, user processing time is reduced while valuable input from a user's expertise is retained. As a byproduct, SAC (Goldstein et al., 2003) plotting and phase picking functionalities are replicated and enhanced.

config

Global configuration options for the AIMBAT application.

Settings

Bases: EventParametersValidatorMixin, BaseSettings

Source code in src/aimbat/config.py
class Settings(EventParametersValidatorMixin, BaseSettings):
    model_config = SettingsConfigDict(env_prefix="aimbat_", env_file=".env")

    project: Path = Field(
        default=Path("aimbat.db"),
        description="AIMBAT project file location (ignored if `db_url` is specified).",
    )
    """AIMBAT project file location."""

    db_url: str = Field(
        default="",
        description="AIMBAT database url (default value is derived from `project`).",
    )
    """AIMBAT database url (default is derived from `project`)."""

    logfile: Path = Field(default=Path("aimbat.log"), description="Log file location.")
    """Log file location."""

    debug: bool = Field(default=False, description="Enable debug logging.")
    """Enable debug logging."""

    window_pre: timedelta = Field(
        default=ICCS_DEFAULTS.window_pre,
        lt=0,
        description="Initial relative begin time of window.",
    )
    """Initial relative begin time of window."""

    window_post: timedelta = Field(
        default=ICCS_DEFAULTS.window_post,
        ge=0,
        description="Initial relative end time of window.",
    )
    """Initial relative end time of window."""

    context_width: timedelta = Field(
        default=ICCS_DEFAULTS.context_width,
        gt=0,
        description="Context padding to apply before and after the time window.",
    )
    """Context padding to apply before and after the time window."""

    min_ccnorm: float | np.floating = Field(
        default=ICCS_DEFAULTS.min_ccnorm,
        ge=0,
        le=1,
        description="Initial minimum cross correlation coefficient.",
    )
    """Initial minimum cross correlation coefficient."""

    bandpass_apply: bool = Field(
        default=ICCS_DEFAULTS.bandpass_apply,
        description="Whether to apply bandpass filter to seismograms.",
    )
    """Whether to apply bandpass filter to seismograms."""

    bandpass_fmin: float = Field(
        default=ICCS_DEFAULTS.bandpass_fmin,
        ge=0,
        description="Minimum frequency for bandpass filter (ignored if `bandpass_apply` is False).",
    )
    """Minimum frequency for bandpass filter (ignored if `bandpass_apply` is False)."""

    bandpass_fmax: float = Field(
        default=ICCS_DEFAULTS.bandpass_fmax,
        gt=0,
        description="Maximum frequency for bandpass filter (ignored if `bandpass_apply` is False).",
    )
    """Maximum frequency for bandpass filter (ignored if `bandpass_apply` is False)."""

    sac_pick_header: str = Field(
        default="t0", description="SAC header field where initial pick is stored."
    )
    """SAC header field where initial pick is stored."""

    sampledata_src: str = Field(
        default="https://github.com/pysmo/data-example/archive/refs/heads/aimbat_v2.zip",
        description="URL where sample data is downloaded from.",
    )
    """URL where sample data is downloaded from."""

    sampledata_dir: Path = Field(
        default=Path("sample-data"),
        description="Directory to store downloaded sample data.",
    )
    """Directory to store downloaded sample data."""

    min_id_length: int = Field(
        default=2, ge=1, description="Minimum length of ID string."
    )
    """Minimum length of truncated UUID string."""

    @model_validator(mode="after")
    def set_computed_defaults(self) -> Self:
        """Sets defaults that depend on other fields."""
        # 1. Handle db_url dependency on project
        if self.db_url == "":
            self.db_url = f"sqlite+pysqlite:///{self.project}"
        return self

bandpass_apply class-attribute instance-attribute

bandpass_apply: bool = Field(
    default=bandpass_apply,
    description="Whether to apply bandpass filter to seismograms.",
)

Whether to apply bandpass filter to seismograms.

bandpass_fmax class-attribute instance-attribute

bandpass_fmax: float = Field(
    default=bandpass_fmax,
    gt=0,
    description="Maximum frequency for bandpass filter (ignored if `bandpass_apply` is False).",
)

Maximum frequency for bandpass filter (ignored if bandpass_apply is False).

bandpass_fmin class-attribute instance-attribute

bandpass_fmin: float = Field(
    default=bandpass_fmin,
    ge=0,
    description="Minimum frequency for bandpass filter (ignored if `bandpass_apply` is False).",
)

Minimum frequency for bandpass filter (ignored if bandpass_apply is False).

context_width class-attribute instance-attribute

context_width: timedelta = Field(
    default=context_width,
    gt=0,
    description="Context padding to apply before and after the time window.",
)

Context padding to apply before and after the time window.

db_url class-attribute instance-attribute

db_url: str = Field(
    default="",
    description="AIMBAT database url (default value is derived from `project`).",
)

AIMBAT database url (default is derived from project).

debug class-attribute instance-attribute

debug: bool = Field(
    default=False, description="Enable debug logging."
)

Enable debug logging.

logfile class-attribute instance-attribute

logfile: Path = Field(
    default=Path("aimbat.log"),
    description="Log file location.",
)

Log file location.

min_ccnorm class-attribute instance-attribute

min_ccnorm: float | floating = Field(
    default=min_ccnorm,
    ge=0,
    le=1,
    description="Initial minimum cross correlation coefficient.",
)

Initial minimum cross correlation coefficient.

min_id_length class-attribute instance-attribute

min_id_length: int = Field(
    default=2,
    ge=1,
    description="Minimum length of ID string.",
)

Minimum length of truncated UUID string.

project class-attribute instance-attribute

project: Path = Field(
    default=Path("aimbat.db"),
    description="AIMBAT project file location (ignored if `db_url` is specified).",
)

AIMBAT project file location.

sac_pick_header class-attribute instance-attribute

sac_pick_header: str = Field(
    default="t0",
    description="SAC header field where initial pick is stored.",
)

SAC header field where initial pick is stored.

sampledata_dir class-attribute instance-attribute

sampledata_dir: Path = Field(
    default=Path("sample-data"),
    description="Directory to store downloaded sample data.",
)

Directory to store downloaded sample data.

sampledata_src class-attribute instance-attribute

sampledata_src: str = Field(
    default="https://github.com/pysmo/data-example/archive/refs/heads/aimbat_v2.zip",
    description="URL where sample data is downloaded from.",
)

URL where sample data is downloaded from.

window_post class-attribute instance-attribute

window_post: timedelta = Field(
    default=window_post,
    ge=0,
    description="Initial relative end time of window.",
)

Initial relative end time of window.

window_pre class-attribute instance-attribute

window_pre: timedelta = Field(
    default=window_pre,
    lt=0,
    description="Initial relative begin time of window.",
)

Initial relative begin time of window.

set_computed_defaults

set_computed_defaults() -> Self

Sets defaults that depend on other fields.

Source code in src/aimbat/config.py
@model_validator(mode="after")
def set_computed_defaults(self) -> Self:
    """Sets defaults that depend on other fields."""
    # 1. Handle db_url dependency on project
    if self.db_url == "":
        self.db_url = f"sqlite+pysqlite:///{self.project}"
    return self

cli_settings_list

cli_settings_list(*, pretty: bool = True) -> None

Print a table with default settings used in AIMBAT.

These defaults control the default behavior of AIMBAT within a project. They can be changed using environment variables of the same name, or by adding a .env file to the current working directory.

Parameters:

Name Type Description Default
pretty bool

Print the table in a pretty format.

True
Source code in src/aimbat/config.py
def cli_settings_list(
    *,
    pretty: bool = True,
) -> None:
    """Print a table with default settings used in AIMBAT.

    These defaults control the default behavior of AIMBAT within a project.
    They can be changed using environment variables of the same name, or by
    adding a `.env` file to the current working directory.

    Args:
        pretty: Print the table in a pretty format.
    """
    print_settings_table(pretty)

print_settings_table

print_settings_table(pretty: bool) -> None

Print a pretty table with AIMBAT configuration options.

Source code in src/aimbat/config.py
def print_settings_table(pretty: bool) -> None:
    """Print a pretty table with AIMBAT configuration options."""
    from aimbat.lib.common import make_table, TABLE_STYLING
    from rich.console import Console

    env_prefix = Settings.model_config.get("env_prefix")

    if not pretty:
        for k in Settings.model_fields:
            print(
                f'{(env_prefix + k).upper() if env_prefix else k}="{getattr(settings, k)}"'
            )
        return

    table = make_table(title="AIMBAT settings")
    table.add_column("Name", justify="left", style=TABLE_STYLING.id, no_wrap=True)
    table.add_column("Value", justify="center", style=TABLE_STYLING.mine)
    table.add_column("Description", justify="left", style=TABLE_STYLING.linked)

    for k, v in Settings.model_fields.items():
        env_var = (
            f"Environment variable: {env_prefix.upper()}{str(k).upper()}"
            if env_prefix
            else ""
        )
        description_with_env_var = (
            f"{v.description} " if v.description else ""
        ) + env_var
        table.add_row(k, str(getattr(settings, k)), description_with_env_var)

    console = Console()
    console.print(table)

logger

Logging setup.

aimbat.cli

Modules:

Name Description
common

Common parameters and functions for the AIMBAT CLI.

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.

snapshot

View and manage snapshots.

station

View and manage stations.

utils

Utilities for AIMBAT.