MuRAT is a Matlab Package for seismic Attenuation, Scattering and Absorption Tomography using Body and Coda Waves at multiple frequencies.
MuRAT measures seismic attenuation, scattering, and absorption from passive and active data and models 3D variations of these parameters in space.
The group of active users (providing questions, feedback, and snippets of code) is the Volcano Earth Imaging group.
The file Documentation.pdf in this folder serves as complete documentation for MuRAT3.0. This README file and the Input_.mlx files in this folder act as additional documentation.
The Wiki for MuRAT is under construction, but you can already check a bit of the history of the code.
The program works on Mac, Linux and Windows systems with Matlab version R2017a or higher.
Necessary Toolboxes: Signal Processing, Curve Fitting, Image Processing and Mapping. The Parallel Computing Toolbox is recommended for speed.
Custom toolboxes not included in standard Matlab installations are also provided with the package. These are:
- Routines to read SAC files created by Zhigang Peng and available from his SAC tutorial page.
- The Regularization Toolbox was created by Per Christian Hansen and available from Matlab File Exchange.
- The IRTools, included in MuRAT as a zipped folder.
- Functions from the Geometry and Image-Based Bioengineering add-On for MATLAB.
Three sample datasets (Mount St. Helens, Romania, and Toba) are included and allow the user to obtain sample models. The datasets work with the three corresponding input.mlx files that show examples of what the user can get with the code.
The current version works following these steps:
-
Download or clone the package at https://github.com/LucaDeSiena/MuRAT.
-
Work in the downloaded folder after moving it to an appropriate location on your system.
-
Check that the IRTools have been downloaded as a zipped folder in the corresponding folder in the working directory. Otherwise, download them from https://github.com/jnagy1/IRtools/tree/ebd70d4036c3cd8c82fc1e17033351491fddf11f.
-
Open one of the three input .mlx files, providing a step-by-step explanation of all inputs (Murat_inputMSH.mlx, Murat_inputRomania.mlx, or Murat_inputToba.mlx) and create your own.
-
Use a velocity model, storing it in the corresponding folder. The format is [Latitude, Longitude, Altitude (meters)]
-
MuRAT works with SAC files that must be stored in a single folder and corrected for the instrument function. The files must have populated headers. Your SAC headers get tested anyway; the result is shown in an Excel file. The code takes from the header the following fields: a) The P-wave picking in the reference time of the waveform (in seconds); b) The coordinates of the event in degrees - beware, the earthquake depth must be in kilometers; c) The coordinates of the station - beware, the station elevation must be in meters; d) The origin time of the event (optional) in seconds.
-
Run MuRAT3 and select the name of the input file desired.
A. Start from the Murat_input..mlx files
The input files are self-explanatory and provide detailed descriptions of every input and references to papers you can use to set them. If you have a 3D velocity model, use MuRAT_InputMSH.mlx otherwise start from either MuRAT_InputRomania.mlx or MuRAT_InputToba.mlx, the examples for 3-component data.
B. Read the Documentation
The Documentation includes a summary of the theory underlying attenuation imaging: read it to understand the approximations used to process data, forward model kernels, and invert observations.
C. Understand the output text files
All the output files (.mat, .txt and .xlsx) and figures are stored in the TXT sub-directories in the Label folder, created in the working directory. A list of the output files and what they contain is provided in the following. Ascii files contain the models in degrees and UTM. We strongly suggest imaging the TXT files using the GeophysicalModelGenerator.
D. Understand the output figure files
Beware, .fig figures are created with the invisible option in Matlab. There are two ways to open them:
(1) Use the function openfig(..,'visible') to open them from the command window.
(2) Click twice on the figure file and write shg in the command window.
All the figures are stored in subdirectories in the Label folder, created in the working directory:
- TXT directory
peakdelay__.txt, Qc__.txt and Q__.txt: The 3D models of the parameters at different frequencies. The first three columns of all text files correspond to Latitude, Longitude, and altitude. The fourth column is the mapped parameter. They contain a minimum of five columns (for Peak Delay) that can be imported to show the locations of the anomalies in a simple (x,y,z) reference system. The fifth column shows blocks hit by at least one ray. Qc and Q are solved with an inversion and thus have (1) the sixth and seventh columns that correspond to the input and output of the checkerboard test; (2) the eighth and ninth columns that correspond to the input and output of the spike test.
Murat.mat: A Matlab structure containing all inputs and data the code produces.
DataHeaders.xls: A file containing all header variables of the SAC files used for the mapping, useful for data selection.
- Checkerboard directory
Qc subdirectory
Qc-Checkerboard__.tif and Qc-Checkerboard__.fig: These figures show the input and output of the Qc checkerboard test in the 3D space (.fig) and through cross-sections (.tif).
Q subdirectory
Q-Checkerboard__.tif and Q-Checkerboard__.fig: These figures show the input and output of the Q checkerboard test in the 3D space (.fig) and through cross-sections (.tif).
- RaysKernels directory
Clustering.tif: This figure shows all rays used on the map (black, discarded) with those after declustering (red).
Rays__.tif: These figures show how rays develop in 3D for the Peak Delay and Q measurements. It plots them on three slices (WE, SN, Z). The fourth panel shows the location of the area on the Earth.
Kernel__.tif and Kernel__.fig: Each .fig figure has two panels showing the sensitivity kernels in the entire 3D space (left) and the normalised kernels in the chosen inversion grid (right). This reduction implies several hypotheses: the most important is that most energy is still in the grid (the difference is generally < 1% if all sources and stations are in the inversion grid). The .tif figures are sections in the WE, SN, and Z directions. Figures are produced for all frequencies.
- Results directory
Parameter subdirectory
Parameter__.tif and Parameter__.fig: Parameter maps in 3D (.fig) and across sections (.tif).
PeakDelay subdirectory
Peak-Delay__.tif and Peak-Delay__.fig: Peak delay maps in 3D (.fig) and across sections (.tif).
Q subdirectory
Q__.tif and Q__.fig: Total attenuation maps in 3D (.fig) and across sections (.tif).
Qc subdirectory
Qc__.tif and Qc__.fig: Coda attenuation maps in 3D (.fig) and across sections (.tif).
- Spike directory
Qc subdirectory
Qc-Spike__.tif and Qc-Spike__.fig: These figures show the input and output of the Qc spike test in the 3D space (.fig) and through cross sections (.tif).
Q subdirectory
Q-Spike__.tif and Q-Spike__.fig: These figures show the input and output of the Q spike test in the 3D space (.fig) and through cross sections (.tif).
- Tests directory
Qc_Analysis__.tif, PD_Analysis__.tif, and CN_Analysis__.tif
Three figures to evaluate the appropriate peak-delay and coda inputs. Read the documentation for further clarifications.
L_curve__.fig: L-curves and cost functions (depending on the inversion method) for the Qc and Q inversions necessary to set the damping parameters. The user can ask for a prompt or set the damping parameters.
Qc_analysis__: Relationship between coda attenuation and frequency.
Velocity_model.fig: The 3D velocity model is also available as a figure in Matlab format. They can be loaded in Matlab and show the vertical and horizontal slices defined in Figures Sections.
If you use MuRAT for your research and publications, please consider mentioning the GitHub internet site and citing the following papers, depending on the techniques you are going to use
Q (Total attenuation):
-
De Siena, L., C. Thomas, and R. Aster. "Multi-scale reasonable attenuation tomography analysis (MuRAT): An imaging algorithm designed for volcanic regions." Journal of Volcanology and Geothermal Research 277 (2014): 22-35. - Older release that discusses the code for coda-normalisation, also used in the early works of Prudencio et al. 2015, a,b, GJI
-
De Siena, L., G. Chiodini, G. Vilardo, E. Del Pezzo, M. Castellano, S. Colombelli, N. Tisato, and G. Ventura, 2017. Source and dynamics of a volcanic caldera unrest: Campi Flegrei, 1983–84. Scientific reports: Nature Journals 7, 8099. - Recent implementation of the Coda Normalization method with correction for coda attenuation variations
-
Sketsiou P., L. De Siena, S. Gabrielli, F. Napolitano, 2021. 3-D attenuation image of fluid storage and tectonic interactions across the Pollino fault network. Geophysical Journal International, 226(1), 536-547. - Most recent application of Q imaging with MuRAT
Qc and Peak Delay (Absorption and scattering):
-
De Siena L., Calvet, M., Watson, K.J., Jonkers, A.R.T. and Thomas, C., 2016. Seismic scattering and absorption mapping of debris flows, feeding paths, and tectonic units at Mount St. Helens volcano. Earth and Planetary Science Letters, 442, pp.21-31. - Implementation of the older peak delay and Qc technique, both with regionalisation
-
De Siena L., A. Amoruso, E. Del Pezzo, Z. Wakeford, M. Castellano, L. Crescentini, 2017. Space-weighted seismic attenuation mapping of the aseismic source of Campi Flegrei 1983–84 unrest. Geophysical Research Letters, 44.4 pp. 1740-1748. - First implementation with kernels for Qc
-
Del Pezzo, E., De La Torre, A., Bianco, F., Ibanez, J., Gabrielli, S., and De Siena, L. (2018). Numerically Calculated 3D Space-Weighting Functions to Image Crustal Volcanic Structures Using Diffuse Coda Waves. - Numerical implementation of kernel functions
-
Sketsiou P., F. Napolitano, A. Zenonos, L. De Siena, (2020). New insights into seismic absorption imaging. Physics of the Earth and Planetary Interiors, 298, 106337. - Comprehensive review of the method and future outlooks
Although we have cross-checked the whole code, we cannot warranty it is exempt from bugs. The package is provided as-is; we will neither be held responsible for any use you make of it nor for the results and conclusions you may derive using MuRAT.
MuRAT is released under EUPL v1.1
Some developments of this software package were funded by the Deutsche Forshungsgemeinshaft under grant number SI 1748/4-1.