Metadata-Version: 2.4
Name: requake
Version: 0.8.3
Summary: Repeating earthquakes search and analysis
Author-email: Claudio Satriano <satriano@ipgp.fr>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://requake.seismicsource.org
Project-URL: Source, https://github.com/SeismicSource/requake
Project-URL: Documentation, https://requake.readthedocs.io
Platform: OS
Platform: Independent
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: scipy>=1.5.0
Requires-Dist: obspy>=1.2.0
Requires-Dist: cartopy
Requires-Dist: argcomplete
Requires-Dist: tqdm
Requires-Dist: tabulate
Requires-Dist: pygments
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file

<img src="https://cdn.jsdelivr.net/gh/SeismicSource/requake@407e6c96ec3574f6e3743741763ca5b7c4daf914/imgs/Requake_logo.svg" width="400">

# Requake

Repeating earthquakes search and analysis.

[![changelog-badge]][changelog-link]
[![PyPI-badge]][PyPI-link]
[![license-badge]][license-link]
[![docs-badge]][docs-link]
[![DOI-badge]][DOI-link]

Copyright (c) 2021-2026 Claudio Satriano <satriano@ipgp.fr>

## Description

Requake is a command line tool to search and analyse repeating earthquakes.

It can either scan an existing earthquake catalog to search for similar events,
or perform template matching on a continuous waveform stream.

Catalogs and waveforms can be read from local files or downloaded using
standard [FDSN web services].

Requake is written in Python and uses [ObsPy] as backend.

## Installation

### Installing the latest release

#### Using Anaconda

The following command will automatically create an [Anaconda] environment
named `requake`, install the required packages and install the latest
version of SourceSpec via `pip`:

    conda env create --file https://raw.githubusercontent.com/SeismicSource/requake/main/requake_conda_env.yml

If you want a different name for your environment, use:

    conda env create -n YOUR_ENV_NAME --file https://raw.githubusercontent.com/SeismicSource/requake/main/requake_conda_env.yml

Activate the environment with:

    conda activate requake

(or `conda activate YOUR_ENV_NAME`)

To keep Requake updated run the following command from within the environment:

    pip install --upgrade requake

Or, to switch to a development snapshot, run:

    pip install git+https://github.com/SeismicSource/requake.git

#### Using pip and PyPI

The latest release of Requake is available on the [Python Package Index].

You can install it easily through `pip`:

    pip install requake

### Installing a development snapshot

If you need a recent feature that is not in the latest release (see the
`unreleased` section in [CHANGELOG][changelog-link]), you want to use the more
recent development snapshot from the [Requake GitHub repository].

#### Using pip

The easiest way to install the most recent development snapshot is to download
and install it through `pip`, using its builtin `git` client:

    pip install git+https://github.com/SeismicSource/requake.git

Run this command again, from times to times, to keep Requake updated with
the development version.

#### Cloning the Requake GitHub repository

If you want to take a look at the source code (and possibly modify it 😉),
clone the project using `git`:

    git clone https://github.com/SeismicSource/requake.git

or, using SSH:

    git clone git@github.com:SeismicSource/requake.git

(avoid using the "Download ZIP" option from the green "Code" button, since
version number is lost).

Then, go into the `requake` main directory and install the code in "editable
mode" by running:

    pip install -e .

You can keep your local Requake repository updated by running `git pull`
from times to times. Thanks to `pip`'s "editable mode", you don't need to
reinstall Requake after each update.

If you want the repository style rules to run locally before each commit,
enable the included git hook once per clone:

    scripts/setup_local_hooks.sh

You can also run the local style checks manually with:

    scripts/check_style.sh

## Running

### Command line arguments

Requake is based on a single executable, aptly named `requake` 😉.

To get help, use:

    requake -h

Different commands are available:

    sample_config       write sample config file to current directory and exit
    update_config       update an existing config file to the latest version
    read_catalog        read an event catalog from web services or from a file
    print_catalog       print the event catalog to screen
    scan_catalog        scan an existing catalog for earthquake pairs
    print_pairs         print pairs to screen
    plot_pair           plot traces for a given event pair
    build_families      build families of repeating earthquakes from a catalog
                        of pairs
    print_families      print families to screen
    plot_families       plot traces for one ore more event families
    plot_timespans      plot family timespans
    plot_cumulative     cumulative plot for one or more families
    map_families        plot families on a map
    flag_family         flag a family of repeating earthquakes as valid or not
                        valid.
    build_templates     build waveform templates for one or more event
                        families
    scan_templates      scan a continuous waveform stream using one or more
                        templates
    wfcache             manage persistent waveform cache (prefetch, print,
                        inspect, extract, reset_failures)

Certain commands (e.g., `plot_pair`) require further arguments (use, e.g.,
`requake plot_pair -h` to get help).

Requake supports command line tab completion for commands and arguments, thanks
to [argcomplete].
To enable command line tab completion run:

    activate-global-python-argcomplete

(This is a one-time command that needs to be run only once).

Or, alternatively, add the following line to your `.bashrc` or `.zshrc`:

    eval "$(register-python-argcomplete requake)"

### Typical workflow

The first thing you will want to do is to generate a sample config file:

    requake sample_config

Edit the config file according to your needs, then read or download the event
catalog:

    requake read_catalog

or

    requake read_catalog CATALOG_FILE

Now, build the catalog of event pairs with:

    requake scan_catalog

When relying on FDSN web services for waveform data, it is strongly
recommended to prefetch all waveform windows before running the scan.
This downloads every required waveform once and stores it in a local
SQLite cache, avoiding repeated downloads and dramatically reducing
overall runtime for large catalogs:

    requake wfcache prefetch

Once done ([it will take time!](#performances)), you are ready to build
repeating earthquake families:

    requake build_families

## Performances

- `requake scan_catalog` is designed to fully utilize available CPU cores by
  processing earthquake pairs in parallel. On an M2 MacBook Air, scanning
  95,034 earthquake pairs downloaded via FDSNWS took approximately 5 minutes
  using 7 worker processes, yielding ~19,000 pairs per minute. When repeating
  the same scan with a fully cached set of waveforms, runtime dropped to 84
  seconds (~68,000 pairs per minute). These results indicate that overall
  performance is typically dominated by waveform download latency rather than
  computation.

- For large FDSN-based runs, use `requake wfcache prefetch` before
  `requake scan_catalog` to download all waveforms upfront into a local
  SQLite cache.  This eliminates repeated downloads, lets the scan read
  exclusively from disk, and is the single most effective way to speed up
  catalog scanning.

- `requake build_families` is fast™.

## How to Cite

If you used Requake for a scientific paper, please cite it as:

> Satriano, C. (2026). Requake: Repeating earthquakes search and analysis (X.Y).
> [doi: 10.5281/ZENODO.10832203]

Please replace `X.Y` with the Requake version number you used.

You can also cite the following abstract presented at the
2021 AGU Fall Meeting:

> Satriano, C., Doucet, A. & Bouin, M.-P. (2021).
> Probing the creep rate along the Lesser Antilles Subduction Zone through repeating earthquakes.
> In AGU Fall Meeting Abstracts
> (Vol. 2021, pp. T25A-0167), [bibcode: 2021AGUFM.T25A0167S]

<!-- Badges and project links -->
[PyPI-badge]: http://img.shields.io/pypi/v/requake.svg
[PyPI-link]: https://pypi.python.org/pypi/requake
[license-badge]: https://img.shields.io/badge/license-GPLv3-green
[license-link]: https://www.gnu.org/licenses/gpl-3.0.html
[docs-badge]: https://readthedocs.org/projects/requake/badge/?version=latest
[docs-link]: https://requake.readthedocs.io/en/latest/?badge=latest
[changelog-badge]: https://img.shields.io/badge/Changelog-136CB6.svg
[changelog-link]: https://github.com/SeismicSource/requake/blob/main/CHANGELOG.md
[DOI-badge]: https://zenodo.org/badge/DOI/10.5281/zenodo.10832203.svg
[DOI-link]: https://doi.org/10.5281/zenodo.10832203
[Requake GitHub repository]: https://github.com/SeismicSource/requake

<!-- External links -->
[FDSN web services]: https://www.fdsn.org/webservices/
[ObsPy]: https://obspy.org
[Anaconda]: https://www.anaconda.com/download
[Python Package Index]: https://pypi.org/project/requake/
[argcomplete]: https://kislyuk.github.io/argcomplete/

<!-- References -->
[doi: 10.5281/ZENODO.10832203]: https://doi.org/10.5281/ZENODO.10832203
[bibcode: 2021AGUFM.T25A0167S]: https://ui.adsabs.harvard.edu/abs/2021AGUFM.T25A0167S
