Analysis and visualisation code

This repository is home to analysis and visualisation code to support the manuscript:

Winder, T., Bacon, C.A., Smith, J.D., Hudson, T.S., and White, R.S.
QuakeMigrate: a Python Package for Automatic Earthquake Detection and Location
Using Waveform Migration and Stacking. (to be submitted to Seismica).

Open-access paper:

Supplementary datafiles:

Analysis and visualisation:

Steps to reproduce analysis and figures

1. Clone this repository and navigate to it:

git clone https://github.com/QuakeMigrate/manuscript
cd manuscript

2. Create a new virtual environment using a tool such as conda or uv and install QuakeMigrate. In order to recreate all of the steps used to create the figures in the main manuscript and the supplementary material, we recommend installing QuakeMigrate from PyPI with the optional argument manuscript, i.e.:

conda create -n qm_manuscript python=3.12 pip
conda activate qm_manuscript
pip install 'quakemigrate[manuscript]'

3. If you do not already have GMT installed on your system, install it in your virtual environment with e.g.:

conda activate qm_manuscript
conda install gmt

4. Optional: Add qm_manuscript.mplstyle (a matplotlib stylesheet) to your mpl_configdir (usually found at ~/.config/matplotlib)

5. Optional: Install Helvetica font for Matplotlib

6. Follow the instructions on the QuakeMigrate documentation to install NonLinloc, which is used as the backend for computing the traveltime lookup tables used in the migration and stacking stages.

7. Scripts for building each figure in the main manuscript and the supplementary material are found under sub-directories in the figures directory. In most cases, input data for the figures must first be generated by running the scripts (in order) found in the corresponding generate_results directories (more details below). However, in instances where these require extensive computation we have also included the necessary data files in order to minimise computational requirements. Figures can then be built by running the .gmt (as bash <script>.gmt) or .py (as python <script>.py) scripts.

Detailed instructions for individual figures

Figure 1; Figures 3-5; Supplementary Figures S1, S3

Code for these figures is found within the synthetic sub-directory. Users should first run through all scripts in synthetics/generate_synthetic_results in order, before running the scripts to build the individual figures. Note that the secondary <script>_p_only.py scripts run the example with only the P onset functions, in order to generate the event summary plot presented in Supplementary Figure S3.

Figures 6-7; Supplementary Figure S10

Code for these figures is found within the icequake_example sub-directory. Code to generate the input results for these figures is provided within icequake_example/generate_results, however this example is computationally expensive to run, so the relevant output files for constructing the figures are also provided within the repository. If the user chooses to re-generate the outputs themselves, they should run through the scripts within generate_results in order. They may also adjust the time windows in order to run a subset.

Note that Figure 7 requires GMT to be installed.

Figures 8-9

Code for these figures is found within the Askja_VT-DLP_example sub-directory. Users should first run through all scripts in Askja_VT-DLP_example/generate_results in order, before running the scripts to build the individual figures. This requires downloading 24h of waveform data from IRIS/EarthScope, which requires approximately 1 GB of disk space, and takes some time (depending on network connection, etc.).

Figure 10; Supplementary Figure S11

Code for these figures is found within the Askja_QM-manpick_comparison sub-directory. Code to generate the input results for these figures is provided within Askja_QM-manpick_comparison/generate_results, however this example is computationally expensive to run, so the relevant output files for constructing the figures are also provided within the repository. If the user chooses to re-generate the outputs themselves, they should run through the scripts within generate_results in order.

Note that there are two versions of the get_data script; the first uses the Zenodo API to automatically download, extract, and organise the input data from the accompanying Zenodo repository , and requires the user to have a Zenodo account & API access token (see here), while the second extracts and organises the zip files after they have been manually downloaded via the webpage. Manual download is the only option until the Zenodo repository is finalised and published (which will occur when the manuscript is hopefully accepted).

Supplementary Figure S2

Code to build this figure is found within the supplementary/synthetic sub-directory.

Supplementary Figures S4-S8

Code for these figures is found within the supplementary/profiling sub-directory. Code to profile the performance of QuakeMigrate on the user's system is provided in the generate-profiles.sh script. Note that this will run the Askja_VT-DLP example several times, sweeping across a range of timesteps, decimation factors, and number of threads. This requires that at least the Askja_VT-DLP_example/generate_results/0_get_data.py script has been run beforehand, in order to download the required input waveform data. Once the profiling is complete, users may run the individual build_figure scripts to plot the results.

Supplementary Figure S9

Code to build this figure is fond within the supplementary/icequake_example sub-directory.

Notes

These figures were prepared using macOS 15.5 and Ubuntu 22.04. A limited number were produced using Affinity Designer, a licensed piece of software for graphic design. .afdesign files are provided.