Metadata-Version: 2.4
Name: requake
Version: 0.7.2
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@b6498527a861637124bae1b49943b83f9ca4a7d2/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.

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

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

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

    requake build_families

## Performances

- `requake scan_catalog` took 53 minutes on my 2.7 GHz i7 MacBook Pro to
process 14,100,705 earthquake pairs.
Dowloaded traces are cached in memory to speed up execution. Processing is not
yet parallel: some improvements might come in future versions, when
parallelization will be implemented.

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