About NoisePy

NoisePy is a Python package designed for fast and easy computation of ambient noise cross-correlation functions. It provides additional functionality for noise monitoring and surface wave dispersion analysis.

Disclaimer: this code should not be used "as-is" and not run like a blackbox. The user is expected to change local paths and parameters. Submit an issue to github with information such as the scripts+error messages to debug.

Detailed documentation can be found at https://noisepy.readthedocs.io/en/latest/

Major updates coming

NoisePy is going through a major refactoring to make this package easier to develop and deploy. Submit an issue, fork the repository and create pull requests to contribute.

Installation

The nature of NoisePy being composed of python scripts allows flexible package installation, which is essentially to build dependent libraries the scripts and related functions live upon. We recommend using conda or pip to install.

Note the order of the command lines below matters

With Conda and pip:

conda create -n noisepy python=3.8 pip
conda activate noisepy
pip install noisepy-seis

With Conda and pip and MPI support:

conda create -n noisepy python=3.8 pip
conda activate noisepy
conda install -c conda-forge openmpi
pip install noisepy-seis[mpi]

With virtual environment:

python -m venv noisepy
source noisepy/bin/activate
pip install noisepy-seis

With virtual environment and MPI support:

An MPI installation is required. E.g. for macOS using brew :

brew install open-mpi

python -m venv noisepy
source noisepy/bin/activate
pip install noisepy-seis[mpi]

Functionality

Here is a list of features of the package:

• download continous noise data based:

  • on webservices using obspy's core functions of get_station and get_waveforms
  • on AWS S3 bucket calls, with a test on the SCEDC AWS Open Dataset.

• save seismic data in ASDF format, which convinently assembles meta, wavefrom and auxililary data into one single file (Tutorials on reading/writing ASDF files)

• offers scripts to precondition data sets before cross correlations. This involves working with gappy data from various formats (SAC/miniSEED) and storing it on local in ASDF.

• performs fast and easy cross-correlation with functionality to run in parallel through MPI

• Applications module:

  • Ambient noise monitoring: measure dv/v using a wide variety of techniques in time, fourier, and wavelet domain (Yuan et al., 2021)
  • Surface wave dispersion: construct dispersion images using conventional techniques.

Usage

To run the code on a single core, open the terminal and activate the noisepy environment before run following commands. To run on institutional clusters, see installation notes for individual packages on the module list of the cluster.

Deploy using Docker

We use I/O on disk, so users need root access to the file system. To install rootless docker, see instructions here.

docker pull  ghcr.io/mdenolle/noisepy:latest
docker run -v ~/tmp:/tmp cross_correlate --path /tmp

Tutorials

A short tutorial on how to use NoisePy-seis can be is available as a web page or Jupyter notebook and can be run directly in Colab.

This tutorial presents one simple example of how NoisePy might work! We strongly encourage you to download the NoisePy package and play it on your own! If you have any comments and/or suggestions during running the codes, please do not hesitate to contact us through email or open an issue in this github page!

Chengxin Jiang ([email protected]) Marine Denolle ([email protected]).

Taxonomy

Taxonomy of the NoisePy variables.

• station refers to the site that has the seismic instruments that records ground shaking.

• channel refers to the direction of ground motion investigated for 3 component seismometers. For DAS project, it may refers to the single channel sensors.

• ista is the index name for looping over stations

• cc_len correlation length, basic window length in seconds

• step is the window that get skipped when sliding windows in seconds

• smooth_N number of points for smoothing the time or frequency domain discrete arrays.

• maxlag maximum length in seconds saved in files in each side of the correlation (save on storage)

• substack,substack_len boolean, window length over which to substack the correlation (to save storage or do monitoring), it has to be a multiple of cc_len.

• time_chunk, nchunk refers to the time unit that defined a single job. for instace, cc_len is the correlation length (e.g., 1 hour, 30 min), the overall duration of the experiment is the total length (1 month, 1 year, ...). The time chunk could be 1 day: the code would loop through each cc_len window in a for loop. But each day will be sent as a thread.

Acknowledgements

Use this reference when publishing on your work with noisepy

Main code:

• Jiang, C. and Denolle, M. NoisePy: a new high-performance python tool for seismic ambient noise seismology. Seismological Research Letter 91, no. 3 (2020): 1853–1866. https://doi.org/10.1785/0220190364

Algorithms used:

• (data pre-processing) Seats, K. J., Jesse F. L., and German A. P. Improved ambient noise correlation functions using Welch′ s method. Geophysical Journal International 188, no. 2 (2012): 513-523. https://doi.org/10.1111/j.1365-246X.2011.05263.x

• (dv/v in wavelet domain) Yuan, C., Bryan, J. T., and Denolle, M. Numerical comparison of time-, frequency- and wavelet-domain methods for coda wave interferometry. Geophysical Journal International 226, no. 2 (2021): 828-846. https://doi.org/10.1093/gji/ggab140

• (optimal stacking) Yang X, Bryan J, Okubo K, Jiang C, Clements T, Denolle MA. Optimal stacking of noise cross-correlation functions/ Geophysical Journal International. 2023 Mar;232(3):1600-18. https://doi.org/10.1093/gji/ggac410

This research received software engineering support from the University of Washington’s Scientific Software Engineering Center (SSEC) supported by Schmidt Futures, as part of the Virtual Institute for Scientific Software (VISS). We would like to acknowledge Carlos Garcia Jurado Suarez and Nicholas Rich for their collaboration and contributions to the software.