retreat

RETREAT - REal-time TREmor Analysis Tool

||| |—|—| |RETREAT is a REal-time TREmor Analysis Tool written in python, making use of the ObsPy framework. It performs beamforming on real-time (or optionally archive) seismic array data to calculate the back azimuth and slowness values in a given time window, with the aim of aiding in the location of volcanic tremor signals.|logo| DOI

Background

The EUROVOLC project aims to promote an integrated and harmonised European volcanological community, and one of its main themes focuses on understanding sub-surface processes. Early identification of magma moving towards the surface is very important for mitigation of volcanic hazards, and joint research activities within the project aim to develop volcano pre-eruptive detection schemes.

Volcanic tremor is a sustained seismic signal associated with eruptions and is often linked to movement of magmatic fluids in the subsurface. However, it can occur pre-, syn- and post-eruption, and signals with similar spectral content can be generated by several other processes (e.g. flooding, rockfalls). Hence one of the best ways of distinguishing between the processes underlying tremor generation is its 3D location. As tremor cannot be located using classical seismological methods, its source must be determined using alternatives such as amplitude-based techniques or seismic array analysis.

Dense, small-aperture arrays are particularly suited for analyzing volcanic tremor, yet costs associated with installation and maintenance have meant few long-term or permanent seismic arrays in use for routine monitoring. Therefore, to facilitate greater use of arrays in tracking volcanic tremor sources, we present RETREAT - a REal-time TREmor Analysis Tool.

This software tool uses seismic array data and array processing techniques to help detect, quantify and locate volcanic tremor signals. It is a python-based tool that utilises existing routines from the open-source ObsPy framework to carry out analysis of seismic array data in real-time. The tool performs beamforming using f-k (frequency-wavenumber) analysis, or a Least-squares inversion, to calculate the back azimuth and slowness in overlapping time windows, which can be used to detect and track the location of volcanic tremor sources. While primarily intended as a tool for utilizing seismic array data to locate and track volcanic tremor, RETREAT also has the capability to analyze infrasonic array data to track acoustic sources.

Version 2.x of RETREAT now also has the ability to analyse data from multiple arrays.

Installation

Download

If you wish to use git you can download the latest version of the software by cloning the repository to a suitable location by typing:

git clone --recursive https://git.dias.ie/paddy/retreat

Or alternatively click on the download button (at the top of the page, below the project description) to download the source code as a zip, tar or compressed archive file:

Setup

After you have cloned or downloaded the software, navigate to the repository directory, or unzip/untar the source code to a suitable directory. The contents of the repository should look something like this:

retreat
├── CONTRIBUTORS.md
├── doc
│   ├── DIAS_logo.jpg
│   ├── Eurovolc-header-1.jpg
│   ├── EUROVOLC-logo-32.png
│   ├── EUROVOLC-logo.jpg
│   ├── IRIS-NORSAR1.jpg
│   ├── IRIS-NORSAR2.jpg
│   ├── retreat_trans128.png
│   ├── retreat_trans192.png
│   ├── retreat_trans48.png
│   ├── retreat_trans96.png
│   ├── screenshots
│   │   ├── retreat-buttons.jpg
│   │   ├── retreat-gitlab-download.png
│   │   ├── retreat_GUI_2arrays_common.jpg
│   │   ├── retreat_GUI_2arrays.jpg
│   │   ├── retreat_GUI_figwindow.jpg
│   │   ├── retreat_GUI.jpg
│   │   ├── retreat_GUI_output.jpg
│   │   ├── retreat_timeline_2arrays_arraysep.png
│   │   ├── retreat_timeline_2arrays.png
│   │   ├── retreat_WEB_bottom.jpg
│   │   ├── retreat_WEB_figwindow.jpg
│   │   ├── retreat_WEB_output.jpg
│   │   └── retreat_WEB_top.jpg
│   └── UR-array-map.png
├── LICENSE.txt
├── README.md
├── requirements.txt
└── retreat
    ├── data
    │   ├── array_preproc.py
    │   ├── beamforming_lsqr.py
    │   ├── check_for_gaps.py
    │   ├── ew2st.py
    │   ├── fdsn2st.py
    │   ├── fdsn2st3.py    
    │   ├── fix_times.py
    │   ├── get_array_response.py
    │   ├── get_meta.py
    │   ├── get_nth.py
    │   ├── __init__.py
    │   ├── sds2st3.py
    │   ├── slink2st3.py
    │   └── stack.py
    ├── defaults
    │   ├── default_input_values_narrays.py
    │   ├── default_input_values.py
    │   ├── default_input_values.py.NO
    │   ├── default_input_values.py.UR
    │   └── __init__.py
    ├── example_data
    │   ├── dataless.seed.UR
    │   ├── NO.xml
    │   ├── NO.scnl
    │   ├── UR.scnl
    │   ├── VI.URA..HHZ.2014.246.00.00.mseed
    │   ├── VI.URB..HHZ.2014.246.00.00.mseed
    │   ├── VI.URD..HHZ.2014.246.00.00.mseed
    │   ├── VI.URE..HHZ.2014.246.00.00.mseed
    │   ├── VI.URF..HHZ.2014.246.00.00.mseed
    │   ├── VI.URG..HHZ.2014.246.00.00.mseed
    │   └── VI.URH..HHZ.2014.246.00.00.mseed
    ├── gui
    │   ├── get_param_gui.py
    │   ├── gui_layout.py
    │   ├── gui_layout_two.py                
    │   ├── gui_sizes.py
    │   └── __init__.py
    ├── __init__.py
    ├── __main__.py
    ├── output
    ├── plot
    │   ├── add_logos.py
    │   ├── __init__.py
    │   ├── mapping.py
    │   ├── rms_rmes.py
    │   ├── set_font_sizes.py
    │   ├── shiftedColorMap.py
    │   ├── update_plot2.py
    │   └── update_plot.py
    ├── realtime.py
    ├── start.py
    ├── tools
    │   ├── __init__.py
    │   ├── KThread.py
    │   ├── monitoring_routines.py
    │   ├── processpool.py
    │   └── time_to_wait.py
    ├── update2.py
    └── update.py

Next, check and install all the required software and packages by following the instructions in the next section.

Requirements

This software requires python3. A list of required python modules is contained in the requirements.txt file.

These are:

More information on obspy and PySimpleGUI is available from:

https://www.obspy.org/ and https://pysimplegui.readthedocs.io/en/latest/#install

Ubuntu/Debian package names are shown in brackets where available, and can be installed via:

sudo apt-get install *packagename*

To install the required modules using pip, you can type the following:

pip3 install -r /path/to/requirements.txt

Finally, to start the software follow the instructions below.

Starting the software

The RETREAT package can be run in 3 modes:

  1. With a GUI interface, running in its own window - this is the default mode.
  2. With a web interface, where the input and output are displayed in a browser window
  3. (From the command line with no GUI or web interface)

GUI window

This the default mode. In a terminal window navigate to the directory you cloned or downloaded to and type:

python3 -m retreat

This will start the software and open a GUI window that should look something like this:

GUI

with the Input Parameters in the left hand pane, and the Control Buttons and Output Pane on the right hand side. Figures will appear in a new window.

Web interface

To run the software with a web interface in a browser, do the same as above, but simply give the -w command line flag, i.e. :

python3 -m retreat -w

This will start the software and open a new tab in your browser and should look something like this:

GUI

with the Input Parameters listed at the top of the page,

GUI

and the Control Buttons and Output Pane visible below if you scroll down the page. Figures will appear below the Output Pane.

Command-line interface (optional/advanced)

Although specifically designed as a GUI tool, a command-line mode allowing RETREAT to run from a shell or terminal without either a GUI or web interface, has now been implemented. This may be useful in certain circumstances, such as analysis of existing archive data and/or use in scripts.

Input options will be read from the default_input_values.py file in the retreat/defaults directory (see default values section) or other supplied defaults file. Output messages in the log file will be displayed in the terminal window, and saved output figures will NOT be displayed in the GUI (unless the figure output is specified)

To run the software in command-line mode, do the same as above, but give the -c flag or argument, i.e.

python3 -m retreat -c

Other command line options (optional/advanced)

As well as the options to specify a GUI, web or command line interface, RETREAT has several other command line options - including the ability to analyse mutiple arrays.

Figure output destination

When running in command line mode (see above), there is also the option to still display the figure output in either a GUI window or web interface, with the output remaining in your terminal. To do this use the -f argument as specify the destination as “gui” for a GUI window or “web” to display in a browser window, i.e.:

python3 -m retreat -c -f gui

Note that this option is ONLY valid if also running in command line mode.

Specify defaults file

If you wish to use a different default values file other than the default location/filename (retreat/defaults/default_input_values.py) the -d can option can be used to specify the full path to the file, e.g:

python3 -m retreat -d /home/user/my_defaults.py

Multiple array mode

Version 2.x of RETREAT now has the ability to analyse multiple arrays. This option can be turned on by specifying the number of arrays with the command option -n, e.g.:

python3 -m retreat -n 2

See multiple arrays section for more details on using more than one array

Summary

All command line options are also summarised in the Table below:

Option alternative Purpose
-h –help Show help message and command line options [flag]
-w –web Run RETREAT using web interface in browser [flag]
-c –cmd Run RETREAT using command line interface (no GUI or web interface) [flag]
-f FIGS –figs FIGS Specify figure output destination. FIGS argument MUST be one of either “gui” or “web”. e.g. -f gui. ONLY valid in command line mode (-c, –cmd)
-d DEFAULTS –defaults DEFAULTS Specify path to defaults file if not using standard. DEFAULTS argument should be the full path to the file
-n NARRAYS –narrays NARRAYS Use multiple arrays. NARRAYS argument is the (integer) number of arrays, e.g. -n 2

Description of Input Parameters

Input Data

These parameters define the source and properties of the input data. The fields are:

Note that if ASCII format is selected then you are unable select the pre-processing option to remove the instrument response (as no response information was supplied in the inventory). See also this note on coordinate specification.

Pre-processing

These parameters define any pre-processing applied to the data before the array analysis is carried out. The fields are:

Timing

This set of parameters define the amount of data to be processed, by defining the length of the window and how often it is updated (real-time mode). The parameters are:

Array Processing parameters

Sets parameters for the array processing, using the standard array_analysis routines in obspy. See the obspy documentation here. The choice of these values will depend very much on the specific array being used.

The next 2 parameters define the bandpass filter limits:

To provide a timeseries output, the f-k analysis is performed by using shorter time windows and sliding these windows across the entire trace.

Other parameters:

Finally, there is also an option to use a Least-Squares beamforming method as an alternative to f-k, e.g. for infrasound data where lower velocity/higher slowness values mean a large slowness grid is required which can impact the computation time. This method is described in De Angelis et al. (2020), and allows for significantly faster computation. The python routine implementing the method in this software were adapted from the matlab code available here.

Note on coordinates: although the obspy array_processing module accepts coordinates as either Cartesian (xy) or latitude and longitude (lonlat), for convenience in plotting the array response function and map of the array, please note that latitude and longitude (lonlat) format is assumed. Therefore, please ensure your station coordinates are specified as latitude and longitude in your station metadata/inventory file.

Results and Plots

The parameters in this section define what you wish to plot as the output of the analysis as well as various settings for these figures. For more details and examples see the Figures section. The main timeseries figure can have up to 7 panels, with the desired output selected by the 7 checkboxes:

RMeS is the envelope of the seismogram calculated using a Root-Median-Square sliding window. The parameters than control this are:

The checkbox Polar plot creates a separate figure with the power from the beamforming analysis represented in Polar form as a histogram, with the Back azimuth on the angular axis, and the slowness on the radial axis. Note for Least-squares beamforming this is weighted by the MCCM rather than relative power.

The next set of parameters define the size of the output figures, as pairs of x and y values. The sizes are specified in pixels (resolution is set to 100 DPI):

Fixed y-axis limits for the various figures can also be set. If set to auto the figure will automatically scale the axes:

You can also define the resolution for the histogram in the polar representation of the results:

Other options include:

The next set of values control the (optional) plot of the array response function:

The wavenumber grid over which to evaluate the array response must also be defined:

see here for the obspy documentation and an example of plotting the array response function.

The final set of values control the (optional) map of the array, overlain by the calculated back azimuths:

The x- and y-axis limits of the map extent can also be manually specified. If the array at centre checkbox is NOT checked, these values MUST be given. Else, if set to auto the figure will automatically scale the axes.

If set to auto the figure will automatically scale the axes (for array at centre checked)

Spectrogram

A separate section contains the settings for controlling the spectrogram figure (if selected to plot):

The length and overlap of the FFT window used are controlled by:

The colormap and limits of the colour scale for the spectrogram are given by:

Output

These settings control where the output produced by the software is placed on your system. The parameters are:

Default values

All parameters that can be set using the GUI or web interface can also be defined in advance of runtime. This is controlled by the default_input_values.py file in the retreat/defaults directory, which contains a simple python dictionary comprising of pairs of parameters and their default values. e.g:

defaults = dict(
        #########################
        # DATA SOURCES - REALTIME
        myclient="IRIS",
        connection=['FDSN', 'seedlink'],
        ...
        ...
        ...
        arrayfigname="arrayresp",
        mapfigname="map",
        ########################
    )

This file can be easily edited to change the default values as desired.

The repository also contains two examples files containing default values that can be used to run the two examples described in the Examples section. These are:

default_input_values.py.NO

which contains values to run the real-time data example, using data from the SPITS/NORSAR (NO) array

and

default_input_values.py.UR

which contains values to run the archive data example, using data from the Bárðarbunga (UR) array.

Command line input

Note that the full path to an alternative defaults file (must have a .py extension), can be supplied using the -d command line option. For example:

python3 -m retreat -d /path/to/defaults_file.py

Control Buttons

There are 3 simple buttons to control the software:

Figures and Output

Output window

In both GUI and web mode, the interface displays an output pane that shows the output produced once the Start button is pressed. The text displayed on screen is the same as the messages that are written to the log file. Note that the logfile will be overwritten by default when the software is run, unless a different name is specified in the input parameters.

output-pane

Figure window

In both GUI and web mode, the interface also has a figure window that shows the output figures that are produced once the Start button is pressed.

In GUI mode this will open as a new window:

GUI-figwindow

whereas in web mode, figures are displayed in the same browser window, below the output pane:

web-figwindow

Examples

Two example configuration files are included with the source code to demonstrate how the tool can be used for both real-time and archive data.

1. Real-time mode using data from SPITS array

The first example uses real-time data from the small-aperture SPITS array in Spitsbergen, part of the larger NORSAR array:

IRIS-Norsar-info

Data is acquired in real-time from IRIS via the obspy FDSN client.

To run the example, simply copy the appropriate default values file (NO array) and overwrite the default values:

cd retreat/defaults/

cp default_input_values.py.NO default_input_values.py

and start the software. This should begin analysis of real-time data, with results similar to those shown here.

Seedink

Note: this example configuration should also work using the IRIS seedlink server (rtserve.iris.washington.edu:18000) rather than the FDSN client as the data source. In this case the Inventory file checkbox must be checked as metadata cannot be retrieved automatically. The default for this configuration example is the NO.xml file supplied in the retreat/example_data directory.

2. Archive mode using data from FUTUREVOLC

The second example uses archive data from the 2014 eruption at Bárðarbunga volcano/Holuhraun in Iceland, collected as part of the FUTUREVOLC project. Several hours of data from the UR array between 00:00 and 08:00 UTC on 03 September 2014 are included with the distribution in the example_data folder. This corresponds to part of the time period analysed in Eibl et al., (2017a). The map below shows the location of the seven station UR array in Iceland, relative to the erupted lava flow field in Holuhraun (red) and Bárdarbunga volcano (B, black dot) along with the approximate path of the intruded dyke in grey.

UR-array-map

Again, to run this example, simply copy the appropriate default values file (UR array) and overwrite the default values:

cd retreat/defaults/

cp default_input_values.py.UR default_input_values.py

and start the software. This should begin analysis of the archive data.

Multiple arrays

A new feature in version 2.x of RETREAT is the ability to process and analyse data from more than one array. If the -n command line option is selected, RETREAT is enabled in multiple array mode, with the number of arrays specified as an argument. This means RETREAT is now able to analyse input data from multiple arrays and display the results together in the output window. Note that in this configuration RETREAT does not (currently) jointly invert the data, but simply performs the beamforming separately for each array.

Format of defaults file

To accomodate the fact that there are now two (or more arrays), the format of the default_input_values.py file for multiple array mode is slightly different. Rather than a single dictionary of parameters, the file now contains a dictionary of common parameters that are common to all arrays:

    # default parameter values
    #############################
    ### Start with values/parameters common to all arrays
    defaults_common = dict(
        #########################
        # TIMING
        plot_window=3600,
        window_length=900,
        update_interval=900,
        ...
        savedata=False,
        datafile="array_output",
        ########################
        )

as well as two (or more) separate dictionaries - one for each array - for parameters that can be different for each array:

## ARRAY 1    
defaults_array_one = dict(
    #########################
    # DATA SOURCES - REALTIME
    myclient="IRIS",
    ...
    clim_max=1.0,
    cmap="jet",
)

## ARRAY 2    
defaults_array_two = dict(
    #########################
    # DATA SOURCES - REALTIME
    myclient="GFZ",
    ...
    clim_max=2.0,
    cmap="jet",
)

An example input file for use with multiple arrays is included with the RETREAT distribution: retreat/defaults/default_input_values_narray.py that can be modified as required, such as adding additonal dictionaries for more arrays.

Extra parameter

Most of the input parameters in multiple array mode are identical to those used for single array processing. However there is one addtional input parameter that must be specified:

If unchecked, the default is to superimpose the output results into a single plot, as shown in the example below:

retreat_timeline_2arrays

If checked, each timeline variable selected to be plotted will have two separate panels - one for each array - as shown below:

retreat_timeline_2arrays_arraysep

GUI interface

Two arrays

If the narrays argument is equal to 2, then a GUI interface can be used. Starting retreat with the appropriate arguments:

python3 -m retreat -n 2 -d retreat/defaults/default_input_values_narrays.py

should start the GUI window and look something like this:

GUI_2arrays

Each of the two arrays has its own set of parameters that can be different for each array, including: connection, station/channel information, pre-processing, array processing and spectrogram parameters.

Common parameters that are the same for both arrays, e.g. timing, plotting and output options, are specified beneath these and can be accessed via the vertical scroll bar.

More than two arrays

To avoid the size of the GUI becoming too large and complicated, if more than two arrays are to be used, then RETREAT must be run in command line mode, specified with the -c option. Output figures can still be displayed in a GUI window or web browser if desired by setting the -f option and specifying gui or web. See: command line options for more details on these options.

References

De Angelis S, Haney MM, Lyons JJ, Wech A, Fee D, Diaz-Moreno A and Zuccarello L (2020). Uncertainty in Detection of Volcanic Activity Using Infrasound Arrays: Examples From Mt. Etna, Italy. Front. Earth Sci. 8:169. doi:10.3389/feart.2020.00169

Eibl, Eva P. S., Bean, C.J., Vogfjörd, K.S., Ying, Y., Lokmer, I., Möllhoff, M., O’Brien, G.S., & Pálsson, F. (2017a). Tremor-rich shallow dyke formation followed by silent magma flow at Bárðarbunga in Iceland. Nature Geoscience volume 10, pages 299–304, doi:10.1038/ngeo2906.

Eibl, E. P. S., Bean, C. J., Jónsdóttir, I., Höskuldsson, A., Thordarson, T., Coppola, D., Witt, T., and Walter, T. R. (2017b), Multiple coincident eruptive seismic tremor sources during the 2014–2015 eruption at Holuhraun, Iceland, J. Geophys. Res. Solid Earth, 122, 2972– 2987, doi:10.1002/2016JB013892.

Smith, P. J. and Bean, C. J., (2020), RETREAT: A REal-Time TREmor Analysis Tool for Seismic Arrays, With Applications for Volcano Monitoring. Front. Earth Sci. 8:586955. https://doi.org/10.3389/feart.2020.586955

Release History

Licensing

Copyright (c) 2021, Patrick Smith and all persons listed in CONTRIBUTORS.md. This project is licensed under the EUPL, v1.2. See LICENSE.txt for more information.

Meta

Patrick Smith – psmith@cp.dias.ie

DIAS_LOGO

https://git.dias.ie/paddy/retreat

This software was developed and made available as part of the EUROVOLC project.

For more information see https://eurovolc.cp.dias.ie/index.php

EUROVOLC_LOGO

Cite this code

DOI

Smith, P. J. and Bean, C. J., (2020), RETREAT: A REal-Time TREmor Analysis Tool for Seismic Arrays, With Applications for Volcano Monitoring. Front. Earth Sci. 8:586955. https://doi.org/10.3389/feart.2020.586955

Patrick Smith. (2020, May 11). RETREAT - a REal-time TREmor Analysis Tool (Version v1.0). Zenodo. http://doi.org/10.5281/zenodo.3820867

This site is open source. Improve this page.