Metadata-Version: 2.1
Name: noisepy-seis
Version: 0.9.78
Summary: A High-performance Computing Python Package for Ambient Noise Analysis
Project-URL: Homepage, https://github.com/noisepy/NoisePy
Author-email: Marine Denolle <mdenolle@uw.edu>, Chengxin Jiang <Chengxin.Jiang1@anu.edu.au>, Yiyu Ni <niyiyu@uw.edu>
License: MIT License
        
        Copyright (c) 2019 Marine Denolle & Chengxin Jiang
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ambient,change,cross-correlation,dispersion,monitoring,noise,seismic,surface,velocity,wave
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Requires-Python: <3.11,>=3.9
Requires-Dist: aiobotocore==2.5.2
Requires-Dist: datetimerange<3.0.0,>=2.0.0
Requires-Dist: diskcache<6.0.0,>=5.6.1
Requires-Dist: fsspec<2024.0.0,>=2023.4.0
Requires-Dist: h5py<4.0.0,>=3.8.0
Requires-Dist: numba<1.0.0,>=0.57.0
Requires-Dist: numpy<2.0.0,>=1.22.0
Requires-Dist: pandas<2.0.0,>=1.5.3
Requires-Dist: psutil<6.0.0,>=5.9.5
Requires-Dist: pyasdf<1.0.0,>=0.7.5
Requires-Dist: pycwt<1.0.0,>=0.3.0a22
Requires-Dist: pydantic-yaml==1.0
Requires-Dist: pydantic==2.3.0
Requires-Dist: pyyaml==6.0
Requires-Dist: s3fs<2024.0.0,==2023.4.0
Requires-Dist: zarr==2.14.2
Provides-Extra: aws
Requires-Dist: boto3<2.0.0,>=1.26.0; extra == 'aws'
Provides-Extra: dev
Requires-Dist: memory-profiler==0.61; extra == 'dev'
Requires-Dist: pre-commit==3.3.3; extra == 'dev'
Requires-Dist: pytest-cov==4.1.0; extra == 'dev'
Requires-Dist: pytest==7.2.2; extra == 'dev'
Provides-Extra: mpi
Requires-Dist: mpi4py<4.0.0,>=3.1.4; extra == 'mpi'
Provides-Extra: sql
Requires-Dist: sqlite3-0611; extra == 'sql'
Description-Content-Type: text/markdown

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

[![Documentation Status](https://readthedocs.org/projects/noisepy/badge/?version=latest)](https://noisepy.readthedocs.io/en/latest/?badge=latest)
[![Build Status](https://github.com/noisepy/NoisePy/actions/workflows/test.yaml/badge.svg)](https://github.com/noisepy/NoisePy/actions/workflows/test.yaml)
[![Codecov](https://codecov.io/gh/noisepy/NoisePy/branch/main/graph/badge.svg)](https://codecov.io/gh/noisepy/NoisePy)

<img src="https://raw.githubusercontent.com/noisepy/NoisePy/main/docs/figures/logo.png" width="800" height="400">

## 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](CONTRIBUTING.md).

# 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](https://docs.conda.io/en/latest/) or [pip](https://pypi.org/project/pip/) to install.

### Note the order of the command lines below matters ###

## With Conda and pip:
```bash
conda create -n noisepy python=3.10 pip
conda activate noisepy
pip install noisepy-seis
```

## With Conda and pip and MPI support:
```bash
conda create -n noisepy python=3.10 pip
conda activate noisepy
conda install -c conda-forge openmpi
pip install noisepy-seis[mpi]
```

## With virtual environment:
```bash
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](https://brew.sh/) :
```bash
brew install open-mpi
```

```bash
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](https://docs.obspy.org/packages/autogen/obspy.clients.fdsn.client.Client.get_stations.html) and [get_waveforms](https://docs.obspy.org/packages/autogen/obspy.clients.fdsn.client.Client.get_waveforms.html)
   + on AWS S3 bucket calls, with a test on the SCEDC AWS Open Dataset.
* save seismic data in [ASDF](https://asdf-definition.readthedocs.io/en/latest/) format, which convinently assembles meta, wavefrom and auxililary data into one single file ([Tutorials](https://github.com/SeismicData/pyasdf/blob/master/doc/tutorial.rst) 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](https://en.wikipedia.org/wiki/Message_Passing_Interface)
* **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](https://docs.docker.com/engine/security/rootless/#install).
```bash
docker pull  ghcr.io/noisepy/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](https://noisepy.github.io/NoisePy/noisepy_scedc_tutorial.html) or [Jupyter notebook](https://github.com/noisepy/NoisePy/blob/main/tutorials/noisepy_scedc_tutorial.ipynb) and can be
[run directly in Colab](https://colab.research.google.com/github/noisepy/NoisePy/blob/main/tutorials/noisepy_scedc_tutorial.ipynb).


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 (chengxinjiang@gmail.com)
Marine Denolle (mdenolle@uw.edu).

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

## Contributing

Thanks to our contributors so far!

[![Contributors](https://contrib.rocks/image?repo=noisepy/NoisePy)](https://github.com/noisepy/NoisePy/graphs/contributors)

## 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.](https://doi.org/10.1785/0220190364) _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.](https://doi.org/10.1111/j.1365-246X.2011.05263.x) _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.](https://doi.org/10.1093/gji/ggab140) _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/](https://doi.org/10.1093/gji/ggac410) _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](https://escience.washington.edu/software-engineering/ssec/)) supported by Schmidt Futures, as part of the Virtual Institute for Scientific Software (VISS). We would like to acknowledge [Carlos Garcia Jurado Suarez](https://github.com/carlosgjs) and [Nicholas Rich](https://github.com/nrich20) for their collaboration and contributions to the software.
