mkvishesh / array_processing

Various array processing tools for infrasound and seismic data

array_processing

Various array processing tools for infrasound and seismic data. By default uses least-squares to determine the trace velocity and back-azimuth of a plane wave crossing an array in sliding time windows. More advanced processing (such as least-trimmed squares) is easily integrated. Also provides tools to characterize the array response, uncertainty, source-location of a spherical wave crossing the array, etc. See documentation and example.py for more info.

General References and Suggested Citations

Least squares and array uncertainty:

Szuberla, C. A. L., & Olson, J. V. (2004). Uncertainties associated with parameter estimation in atmospheric infrasound arrays, J. Acoust. Soc. Am., 115(1), 253–258. https://doi.org/doi:10.1121/1.1635407

Least-trimmed squares:

Bishop, J. W., Fee, D., & Szuberla, C. A. L. (2020). Improved infrasound array processing with robust estimators, Geophys. J. Int., 221 p. 2058-2074. https://doi.org/10.1093/gji/ggaa110

Installation

We recommend you install this package into a new conda environment. (Please install Anaconda or Miniconda before proceeding.) The environment must contain all of the packages listed in the Dependencies section. For ease of installation, we've provided an environment.yml file which specifies all of these dependencies as well as instructions for installing array_processing itself. To install array_processing in this manner, execute the following commands:

git clone https://github.com/uafgeotools/array_processing.git
cd array_processing
conda env create -f environment.yml

This creates a new conda environment named uafinfra and installs array_processing and all of its dependencies there.

The final line in the environment.yml file installs array_processing in "editable" mode, which means that you can update it with a simple git pull in your local repository. We recommend you do this often, since this code is still under rapid development.

For installation into a pre-existing conda environment, click here.

First ensure you have ObsPy and FastKML installed (conda install -c conda-forge obspy fastkml) and then download and install the uafgeotools dependencies and this package with:

pip install git+https://github.com/uafgeotools/waveform_collection.git
pip install git+https://github.com/uafgeotools/lts_array.git
pip install git+https://github.com/uafgeotools/array_processing.git

(Note that this option does not produce a local clone of the repository.)

Dependencies

uafgeotools packages:

• waveform_collection
• lts_array

Python packages:

• ObsPy
• FastKML

Usage

Import the package like any other Python package, ensuring the correct environment is active. For example,

$ conda activate uafinfra
$ python
>>> import array_processing

Documentation is available online here. For a usage example, see example.py.

Note: The array_plot() function does not allow both sigma_tau and dropped elements from least trimmed squares to be plotted.

The sigma_tau variable is an indicator of nonplanar propagation across an array (using all elements), and least trimmed squares drops element pairs that appear "too far" from planar. In this way, having a large sigma_tau value and having consistently dropped element pairs (while not the same) suggest a departure from the plane wave model.

sigma_tau is only calculated when ordinary least squares (ALPHA=1.0) is used. The ability to plot one or the other was intended as a safeguard against potentially conflicting processing assumptions. To maintain a consistent output data structure, the sigma_tau key returns a np.nan in the case that subset pairs are trimmed (0.5 <= ALPHA < 1.0).

If ALPHA=1.0, the dropped stations are not plotted since least trimmed squares is not used, and sigma_tau may be plotted if specified. If ALPHA < 1.0, then sigma_tau is not plotted or calculated.

Authors

(Alphabetical order by last name.)

Jordan Bishop
David Fee
Curt Szuberla
Liam Toney
Andrew Winkelman