Julia-based seismic noise correlations on AWS

This repository contains source code for a Julia-based AWS application to do seismic noise correlations. The AWS application is built using JavaScript and can be found here.

This project was funded through Earth Science Information Partners (ESIP).

The AWS application is split into three parts. Each part has its own tab in the ESIP XCor App.

1) Map
2) XCor
3) Stacking

You can find the app at http://esip-julia-aws..... This application is hosted on a static Amazon S3 bucket.

1) Map

The first step when doing seismic noise crosscorrelations is to select the data. We use the IRIS DMC Web Services request tools to access data. Using Esir's Leaflet, we provide the user with a map, as well as the ability to filter data based on common fields used in seismic station naming: network, station name, location, channel, start date, end date. The user can also select data geographically using the bounding box drawing tool in the upper left corner of the map, just below the zoom buttons.

NOTE: Wildcard characters "*" and "?" are valid text for the IRIS search. For example, using TA for the network and *I* for the station will return all TA stations with the letter I in the name.

After the user has set these optional filters, hitting the Query button will query the IRIS FDSNWS and return a list of stations satisfying these requirements. The stations are plotted in their respective geographic locations on the map. Each station's metadata can quickly be access by clicking on a station on the map. In addition, a table in the lower half of the browser window is populated with the relevant metadata, one row per station. The total number of station found that meet the filter criteria will be stated below the Save Selected button beneath the filter parameters.

NOTE: Refreshing the webpage will clear the station information and the user will have to restart the process.

Station Selection

The user then needs to select which stations/channels are going to be processed for noise crosscorrelation. Selection is done using the check mark button in each row of the table. Selection can be done on an individual basis, or all stations/channels can be selected with the Select All button. Once stations/channels have been selected, the user needs to click Save Selected. The number of saved channels will indicated just above the Download button.

NOTE: The user can clear the saved channels using the Clear button. This way one can redo the station/channel selection if needed.

The save channels are the data that will be further processed for noise crosscorrelation.

The user can also download a CSV file (stations.csv) that contains the metadata for the selected channel. Each channel will be a row in the CSV file. This can useful to keep a record of the selected stations, etc.

2) XCor

Step 2 requires the user to move to the XCor tab. In this step, the user needs to choose the processing parameters that going into the noise crosscorrelations. Prior to that discussion though, we introduce the underlying Julia packages that are used under the hood in this AWS app.

a) To download data from IRIS and do the instrument deconvolution, we use SeisIO.jl. For anyone looking to start with Julia-based seismic data processing, this is the package we recommend. See the SeisIO docs. There is a also a recent publication about this code, which contains comparisons to other seismic data processing tools (e.g. Obspy) that highlights the speed of SeisIO.jl.

Joshua P. Jones, Kurama Okubo, Tim Clements, Marine A. Denolle; SeisIO: A Fast, Efficient Geophysical Data Architecture for the Julia Language. Seismological Research Letters doi: https://doi.org/10.1785/0220190295

b) To do the actual seismic noise preprocessing and crosscorrelation, we use SeisNoise.jl from Tim Clements and Marine Denolle. The XCor Filter parameters are used by this code.

c) We have written some Julia code SeisNoiseAWS.jl that uses these two packages. We then distribute the correlations over an AWS EC2 instance and return the completed the correlations to the user.

XCor Filter parameters

• Resample Frequency (Hz): In order to make the correlation process as fast as possible, the user can resample the data from the original sample rate of the downloaded data. The default frequency is 10 Hz, which gives a Nyquist frequency of 5 Hz.
• Minimum Frequency (Hz): This is the minimum frequency over which to compute the crosscorrelations. NOTE: the Instrument deconvolution is done at half of this minimum frequency.
• Maximum Frequency (Hz): This is the maximum frequency over which to compute the crosscorrelations. NOTE: This cannot be higher than the Nyquist frequency.
• Correlation Step (sec): This is step size over which to move the crosscorrelation window. Other crosscorrelation tools often report this as a percentage of the window length. We do not do that here.
• Correlation Length (sec): This is the length of the crosscorrelation window.
• Maximum Correlation Lag Time (sec): This is the length of the crosscorrelation that is saved as ouput. NOTE: This is usually much smaller than the correlation length parameter.

Launching the crosscorrelations

After the correlation filter parameters are entered, the user should hit the Save and Launch button. This will save the filter parameters and then launch the crosscorrelations.

NOTE: The user can download the correlation parameters to a CSV file (xcor_params.csv) after pushing the Save and Launch button.

What happens next?

This part of the code is still a work in progress.

When a user pushes the Save and Launch button, a random integer id is generated for a new folder name. This folder contains the station CSV file and the XCor parameter CSV file. This folder is stored in the S3 bucket in s3://esip-julia-aws/incoming.

For example, you might find the following on S3.

esip-julia-aws
    incoming
        41808
            stations.csv
            params.csv

There is an EC2 instance, also through esip-julia-aws, that has a cron job running every second. This cron job is syncing the S3 incoming folder with a incoming folder on the EC2 instance using the following command

aws s3 sync s3://esip-julia-aws/incoming incoming

If new files have arrived in the EC2 incoming folder, then a series of actions are taken.

First, the incoming folder is copied to a new folder that is named based on the data and time.

$(date +%Y%m%d_%H%M%S)

Second, a Docker image that contains Julia 1.3 and all of the necessary Julia libraries is launched. A Julia script (run_correlation.jl) is then launched. This script will read the station CSV and xcor parameter CSV and do the correlations.

The crosscorrelations between all possible stations pairs is performed. Rather than using a double FOR loop, Combinatorics.jl is used to create a list of all necessary pairs. The pmap() function from Disbributed.jl is then used to do the station pair correlations in parallel. This is done on a day-by-day basis, so there is still one FOR loop over all of the days of data.

Once a correlation for a single station pair, for a given day is complete the correlations are written to JLD2 files. The docker is then closed and the folder containing all of the JLD2 files is synced back to S3 to the folder processed.

3) Stacking

Eventually we will have a third tab that allows the user to stack the resulting crosscorrelations in the JLD2 files using the stacking capabilities in SeisNoise.jl. This includes linear, phase-weighted, and robust stacking. These are all methods that have been published in the seismic noise correlation literature.

In addition, the code will make images that can also be downloaded from the S3 bucket that show crosscorrelograms and virutal shot records.