Menu Close

Slider / MSATSI Library

MATLAB package for stress inversion from focal mechanisms

Version 1.0.10, Last update: 22.04.2015

Authors:

Patricia Martínez-Garzón <patricia@gfz-potsdam.de>
Grzegorz Kwiatek <kwiatek@gfz-potsdam.de>

Original SATSI library code by Jeanne Hardebeck and Andy Michael (website); see Hardebeck and Michael [2006] for details. MSATSI package uses MATLAB routine sh.m for appropriate calculation of the horizontal stresses, developed by Bjorn Lund and John Townend (website); see also Lund and Townend [2007] for details. The extensive description of the package together with examples is presented in Martínez-Garzón et al. [2014]. If you find the MSATSI useful in your research you can acknowledge our work by providing a reference to the following works:

Martínez-Garzón, P., Kwiatek, G., Ickrath, M. and M. Bohnhoff (2014). MSATSI: A MATLAB package for stress inversion combining solid classic methodology, a new simplified user-handling and a visualization tool. Seismol. Res. Lett., 85,4, doi: 10.1785/0220130189. Go to: Full article (web view); Download: Full article (pdf) through GeoScienceWorld.

Hardebeck, J. L., and Michael, A. J. (2006). Damped regional-scale stress inversions: Methodology and examples for southern California and the Coalinga aftershock sequence, J. Geophys. Res. Solid Earth 111, no. B11, B11310, doi 10.1029/2005JB004144.

Lund B. and Townend, J., (2007). Calculating horizontal stress orientations with full or partial knowledge of the tectonic stress tensor, Geophys. J. Int., 170, 1328-1335, doi: 10.1111/j.1365-246X.2007.03468.x.

Also, you can let us know on your publications using MSATSI packake. We are happy to advertise them at this website!

Download

The newest version of MSATSI package can requested by filling the following form. After submitting the form, the email message with download link will be sent to you. In case you don’t receive the letter after a couple of minutes, please firstly check your spam folder and then contact us!

    Your Name (required)

    Your Email (required)

    Affiliation (Optional)

    Changelog

    The current version of MSATSI package is 1.0.10:

    1.0.10 (Release data: 22.04.2015) Correction to path handling in Windows systems
    1.0.9 (Release data: 27.03.2015) Various corrections to account for path/file handling in Mac/Linux versions.
    1.0.8 (Release date: 04.02.2015) SilentMode and SaveImage options added. Small corrections to existing code. Correction to the best solution of satsi2d.
    1.0.7 (Release date: 02.06.2014) Correction to stereonet grid plotting routine in msatsi_plot.m
    1.0.6 (Release date: 01.06.2014) PDF/Word documentation added, binaries updated.
    1.0.5 (Release data: 22.10.2013) Correction to the small bug introduced in 1.0.4
    1.0.4 (Release date: 19.09.2013) Correction to the msatsi.m parameter FractionValidFaultPlanes.

    1.0.3 (Release date: 24.08.2013) Initial release.

    Table of contents

    1. Introduction
    2. Installation
      1. Installation for Microsoft Windows
      2. Installation for Linux / Mac
      3. Important notice to all MSATSI users
    3. Quick start guide
      1. Performing stress inversion
      2. Displaying stress inversion results
    4. Package documentation
      1. Content of the package
      2. Input data for msatsi routine
      3. Running the stress inversion with msatsi routine
      4. Properties of msatsi routine
      5. Stress inversion output
      6. Input data for msatsi_plot routine
      7. Running msatsi_plot
      8. msatsi_plot properties
    5. Examples
    6. Compilation of SATSI for different platforms
      1. Compilation for Linux platform
      2. Compilation for Windows platform
      3. Compilation for Mac platform
    7. References

    1. Introduction

    MSATSI is a MATLAB software package that allows performing the stress inversion using earthquake focal mechanisms. MSATSI is based on the C library SATSI created by Hardebeck and Michael (2006) (http://earthquake.usgs.gov/research/software/#SATSI). MSATSI provides a framework for calculating the deviatioric stress tensor together with its uncertainties using bootstrap resampling method. It also allows displaying the stress inversion results using a variety of plots.

    The MSATSI package is composed of two MATLAB functions. The first one msatsi.m performs actual stress inversion and the second one, msatsi_plot.m, provides the graphical visualization of stress inversion results calculated with MSATSI.

    Main features of MSATSI package are:

    • Simple and comprehensive handling of input and output stress inversion data.
    • Variety of graphical representations of the stress inversion results: stereonets, stereotraces, profiles, world stress map-alike plots, stereomaps and stereovolumes.
    • Versatile and adjustable graphical output
    • User friendly interface through the intensive use of MATLAB properties.

    The details of the software package are described in Martínez-Garzón et al. [2014].

    2. Installation

    In the first step, please use the form above to download the current version of the package.

    2.1 Installation for Microsoft Windows

    1. Unpack downloaded version of MSATSI to some directory.
    2. Add the root folder of the package (i.e. the location containing msatsi.m and msatsi_plot.m functions) to the MATLAB search path (File>Set Path option in MATLAB main menu). Alternatively, copy both m-files together with seven executable files (*.exe) to the directory already included in your MATLAB search path.
    3. Done!

    2.2 Installation for Linux / Mac users

    1. Unpack downloaded version of MSATSI to some directory.
    2. Add the root folder of the package (i.e. the location containing msatsi.m and msatsi_plot.m functions) to the MATLAB search path (File>Set Path in MATLAB main menu).
    3. Depending on your platform, proceed to the appropriate subfolder of ./bin directory and copy seven executable files into the place where you placed msatsi.m and msatsi_plot.m routines. You can delete the existing *.exe files, as these are executables for Microsoft Windows platform that are of no use for Linux / Mac users. Alternatively, copy both m-files together with executable files appropriate for your platform to the directory already included in your MATLAB search path.
    4. Done!

    2.3 Important notice to all MSATSI users

    Executable files appropriate for each platform (Microsoft Windows, Linux or Mac) must be located in the same directory where msatsi.m and msatsi_plot.m files are stored, otherwise msatsi function will not work properly.

    3. Quick start guide

    This quick start guide provides the basics of MSATSI package usage. For a detailed description of stress inversion using msatsi.m routine and parameters controlling the inversion procedure, the user is referred to sections 4.2-4.5. For the description of msatsi_plot.m funtion and parameters controlling the graphical output, the MSATSI user is referred to Sections 4.6-4.8 of this documentation.

    Obtaining the stress orientation from focal mechanisms using MSATSI basically consists of the three steps. In the first step we prepare (or as in the case of this quick start tutorial – simply load) the input data table containing information about focal mechanisms. In the second step we perform the actual stress tensor inversion using msatsi.m function. Finally, after successful completion of the stress inversion, we will display the obtained results using msatsi_plot.m function.

    3.1 Performing stress inversion

    When in MATLAB, change the current directory to ./examples/example1D. This folder contains example input focal mechanism data from the North Anatolian Fault Zone (dip direction, dip angle and rakes of numerous earthquakes that occurred along the fault zone. The input data table in a form of MATLAB matrix is stored in the INPUT_example1D.mat. This file contains focal mechanism data divided arbitrarily into 27 temporal divisions (in the formal documentation of MSATSI package presented in this documentation the term ‘division’ is referred as ‘grid point’) containing 70 seismic focal mechanisms. This division was made in order to display with the stress inversion the changes in the stress field orientation along the major fault plane.

    Once we are in the ./examples/example1D directory, type in MATLAB command prompt:

    load('INPUT_example1D.mat')

    This call will load the input data table containing focal mechanism data. New variable example1d should be now visible in MATLAB workspace. Alternatively, you can also load the text version of the table by calling:

    example1d = load('INPUT_example1D.txt)

    The loaded file is a matrix containing dip directions, dip angle and rakes of faults (columns 3-5 of the matrix). The first two columns contain the information on the segment number (grid point) the particular focal mechanism belongs to (in fact, the first column contains only zeros with the second column changing from 0 to 26). As you noticed, there is no direct information on location of specific seismic events, but only the information about the segment (grid point) the particular focal mechanism is attributed to. Fault plane solutions from each segment (grid point) will be inverted for the stress tensor, therefore we expect obtain a set of 27 stress tensors reflecting the direction of cardinal stress axes along the North Anatolian fault plane.

    Now let’s finally call the stress inversion by typing:

    OUT = msatsi('example1',example1D,'BootstrapResamplings',2000)

    This will perform a complete stress inversion together with bootstrap uncertainty assessment. The first input parameter is the project name. For each project, a separate project directory is created during inversion. This folder contains input and output data as well as additional intermediate graphical output if requested by the user. The second parameter is simply the input table we loaded with the load function. The last ParameterName-ParameterValue pair ‘BootstrapResamplings’ modifies the default number of bootstrap resampling by requesting to perform 2000 bootstrap resamplings of the original input data instead of (default) 500.

    The inversion procedure with MSATSI will take some time. The details of the inversion procedure are described in details in Martínez-Garzón et al. [2014]. In the first stage, the tradeoff parameter is calculated using an automated procedure. In the second step, the actual stress inversion is performed and the best stress tensors are found for each grid point. Finally, the input dataset is resampled using bootstrap procedure and the confidence intervals of stress tensor axes are found. The results of stress inversion and uncertainty assessment are stored in a project directory (in our case inside example1 folder) in MAT file called example1_OUT.mat (as you noticed, the name of MAT file depends on project name). However, the content of output MAT file is also returned directly by msatsi.m function as a structure array. We therefore grab the stress inversion result in OUT structure.

    There are a number of input inversion parameters possible to modify by providing additional property name-propery value pairs. For a comprehensive overview of all parameters we refer to Section 4.4 of this documentation.

    As example, consider the case when one wants to calculate the 68% confidence intervals, but by default msatsi calculates 95% confidence intervals. This can be easily modified by specifying additional parameter ‘ConfidenceLevel’:

    OUT = msatsi('example1',example1D,'BootstrapResamplings',2000,'ConfidenceLevel',68)

    3.2 Displaying stress inversion results

    The stress inversion results may be graphically represented in a variety of ways using msatsi_plot routine. Here, we present changes in the stress field orientation as a profile plot. In order to create a picture, we now call msatsi_plot routine:

    msatsi_plot('example1','profile','Title',{'Changes of S1-S3 along NAFZ'})

    where the first parameter is either the directory containing the solution (e.g. ‘example1’) or directly the output structure array from the call to msatsi.m function, i.e. the following syntax should give the same results, provided that OUT structure array is an outcome of the relevant stress inversion presented in Section 3.1:

    msatsi_plot(OUT,'profile','Title',{'Changes of S1-S3 along NAFZ'})

    The second parameter specifies the plot type to create. The ‘profile‘ option creates three pictures: one for variations of the trend angles , second analogous picture for variations in plunge, and a third one with variations in R (stress ratio coefficient). Bootstrap-aided 95% confidence intervals are represented by default with error bars. With the property ‘Title’, we have written the title we wished on top of each figure.

    Various, highly customizable plots can be created using msatsi_plot.m by specifying additional properties. We refer to Sections 4.6-4.8 of this document for details.

    The additional examples are presented in Section 5 of this document. Good luck!

    4. Package documentation

    This part contains the information on input and output formats as well as the description of the two core routines forming MSATSI package: msatsi.m and msatsi_plot.m.

    4.1 Content of the package

    The unzipped MSATSI package contains the following files and folders:

    LocationDescription
    ./ The root directory contains msatsi.m and msatsi_plot.m routines together with auxiliary SATSI executable files compiled for Microsoft Windows platform. Files for other platforms are located in the ./bin subfolder and MUST be copied to the root directory before using msatsi.m script when platform different the Microsoft Windows is used. Both m-files and executables should be kept together for a proper functioning of the package.
    ./binThis folder contains SATSI executables precompiled for Windows, Linux and Mac platforms. If MATLAB is running on other platform than Microsoft Windows, executable files in the root folder (./) should be replaced with appropriate executable files either from ./bin/linux or ./bin/mac for Linux and Mac, respectively. By default, the root directory (./) contains executables for Microsoft Windows platform (*.exe).
    ./examples This directory provides illustrations of the usage of MSATSI package. Examples 1D-3D cover the cases presented in the paper of Martínez-Garzón et al. (2014). Example 0D presents additional stress inversion together with graphical output not presented in the manuscript. Short descriptions are available in each subfolder of the ./examples directory as well as input and output data.
    ./srcContains modified C code from original SATSI package available at USGS website. Instructions on how to compile the package for different platforms is provided inside of the directory. For the user's convenience, the compiled programs for different platforms are available in ./bin directory.

    4.2 Input data for msatsi routine

    The input matrix for stress tensor inversion varies whether inversion using 0D/1D/2D grid or 3D/4D grid is performed. For 0D-2D case, the input matrix is of n-by-5 size where n is the number of input data (i.e. focal mechanisms). Each row of the input data matrix contains the following data:

    [X Y DIP_DIR DIP_ANGLE RAKE]

    where the columns are:

    Column nameColumn description
    X,YGrid point indexes (unsigned integer values)
    DIP_DIRDip direction (degrees)
    DIP_ANGLEDip angle (degrees)
    RAKERake (degrees)

    NOTE: Please note that the input parameters for the fault plane solution is dip direction, dip angle and rake and NOT the strike, dip angle and rake.

    An example of input data file for 0D/1D/2D cases can be found in ./examples/example1D/INPUT_example1D.txt or the corresponding MAT file located in the same directory. The input stress inversion data for 3D/4D case is slightly different as it has two additional columns:

    [X Y Z T DIP_DIR DIP_ANGLE RAKE]

    where Z and T are two additional grid point indexes. For an example of input file for 3D/4D, see ./examples/example3D/INPUT_example3D.txt.

    4.3 Running the stress inversion with msatsi routine

    Be sure that you are placed in the directory containing msatsi.m and the appropriate executable files.

    First, load or create your input file. For example, load the input data file from ./examples/example1D directory:

    load('INPUT_example1D.mat')

    Run the inversion editing the desirable initial parameters, for example:

    OUT = msatsi('example1',example1D,'BootstrapResamplings',2000)

    Now you have to wait a bit for inversion to finish.

    4.4 Properties of msatsi routine

    The initial parameters of the inversion with the msatsi.m routine can be modified using various PropertyName-PropertyValue pairs.

    The available properties of msatsi.m routine are gathered in a table below:

    Property NameConstraintsDefault ValueDescription
    BootstrapResamplingsScalar > 0500It defines number of bootstrap resamplings to be performed
    CaptionStringNULLAdditional comments to be included
    ConfidenceLevel0 < Scalar < 10095Percentage of confidence interval of the results
    Damping'on' | 'off''on'It switches on/off the calculation of damping parameter and tradeoff curve
    DampingCoeffScalar >= 00Value of the damping coefficient used (defined as 0 before calculation is activated, set automatically to 0 if damping is 'off')
    FractionValidFaultPlanes0 <= Scalar <= 10.5Fraction of valid fault planes from the input data. If fault plane is selected randomly from the two possible options (typical case for fault planes from seismic data), then = 0.5
    MinEventsNodeScalar > 020Minimum of events per grid point to perform stress inversion
    PTPlots'on' | 'off''off'Switches on/off the plotting of P and T axes for every grid point
    TimeSpaceDampingRatioScalar > 01Property used in 4D case: If there is no difference in treatment for columns Z and T of input data, then = 1

    4.5 Stress inversion output

    During call of msatsi routine, the folder is created in the current MATLAB directory containing input and output inversion files. This folder contains the following files:

    FilenameDescription
    .satContains the data from the input file.
    _tradeoff.pngOnly created if damping is activated for the stress inversion. The file contains tradeoff curve and selected damping parameter.
    .outContains the output of satsi2d.exe/satsi4d.exe. The first part reflects best solution data for each grid point: [X Y See Sen Seu Snn Snu Suu] where See Sen Seu Snn Snu Suu are the 6 independent components of deviatoric stress tensor (in case of 3D/4D problem, two columns more are present: [X Y Z T See Sen Seu Snn Snu Suu]). The second part gives for each input focal mechanism the magnitude of shear traction vector and deviation between predicted and calculated slip.
    .slboot_tensorThe file is an output of bootmech2d.exe/bootmech4d.exe. It contains the (deviatoric) stress tensor coordinates for each grid and each bootstrap performed. The columns are [X Y See Sen Seu Snn Snu Suu] for 0D/1D/2D problem, and [X Y Z T See Sen Seu Snn Snu Suu] for 3D/4D.
    .slboot_trplThis file is a second output of bootmech2d.exe/bootmech4d.exe. It contains trend and plunge of principal stress axes for each grid and each bootstrap performed. The columns are [X Y Phi Tr1 Pl1 Tr2 Pl2 Tr3 Pl3] for 0D/1D/2D and [X Y Z T Phi Tr1 Pl1 Tr2 Pl2 Tr3 Pl3] for 3D/4D.
    .summaryContains output from bootuncert.exe. It contains best, minimum and maximum values for PHI, and the principal stress axes for each grid point. The columns are: [PhiBest PhiMin PhiMax Tr1Best Tr1Min Tr1Max Pl1Best Pl1Min Pl1Max Tr2Best Tr2Min Tr2Max Pl2Best Pl2Min Pl2Max Tr3Best Tr3Min Tr3Max Pl3Best Pl3Min Pl3Max]
    .summary_extIt forms another output of bootuncert.exe. It contains for each grid point the bootstrap resamplings included within the specified confidence interval. Here, regardless of the dimensionality of the problem, the columns are: [X Y Z T PHI TR1 PL1 TR2 PL2 TR3 PL3].
    _OUT.matThis structure array contains input parameters for the stress inversion as well as the resulting output data together with bootstrap uncertainty assessment . The structure contains (sizes of matrices presented are only example, the actual size may change depending on performed inversion):
    Out.Damping: 1 (If damping is 'off', then = 0, if damping is 'on', then =1)
    Out.DampingCoeff: 2.8 Final damping coefficient used after calculation.
    Out.ConfidenceLevel: 95
    Out.FractionValidFaultPlanes: 0.5000
    Out.MinEventsNode: 20
    Out.BootstrapResamplings: 2000
    Out.Caption: '(example1)'
    Out.TimeSpaceDampingRatio: 1
    Out.PTPlot: 0
    Out.SLBOOT_TENSOR: [54000x8 double] Information and structure equal to 'example1.slboot_tensor'
    Out.SLBOOT_TRPL: [54000x9 double] Information and structure equal to 'example1.slboot_trpl'
    Out.BOOTST_EXT: [51289x11 double] Information and structure equal to 'example1.summary_ext'
    Out.INPUT_TABLE: [1890x5 double] Information and structure equal to 'example1.sat'
    Out.SUMMARY_TABLE: [27x21 double] Information and structure equal to 'example1.summary'
    Out.GRID: [[27x3 double] Contains the order of the grid-points in which the inversion results are sorted (for example, in .summary file). If SI is 0D/1D/2D, the columns are [X Y Nevents], where Nevents is the number of focal mechanisms included in each grid point. If SI is 3D/4D, the columns are: [X Y Z T Nevents].

    4.6 Input data for msatsi_plot routine

    By default, the msatsi_plot.m program is using the output data created by msatsi.m. Thus, no additional input file needs to be created for msatsi_plot.m routine.

    4.7 Running msatsi_plot

    There are two ways of calling the msatsi_plot.m. Firstly, one can specify the directory containing the stress inversion results. In this case, the folder must be located in the current MATLAB directory. The example call could look as follows:

    msatsi_plot('example1', plottype, 'PropertyName', PropertyValue, ...)

    where ‘example1’ is the directory located in the current MATLAB folder. The other way of producing the graphical output is to call the msatsi_plot.m routine with the output structure array derived by msatsi.m:

    msatsi_plot(Out, plottype, 'PropertyName', PropertyValue, ...)

    where Out is a structure array returned by the previous call to msatsi.m routine:

    Out = msatsi(...)

    The second obligatory parameter, plottype, is the type of the plot. There are five different plots available:

    PlotTypeDimensionsDescription
    'stereonet'0D-1DSuitable to represent the 0D-1D stress inversion results (e.g. temporal changes, changes of stress field orientation along the fault plane etc.). The direction of the principal stress axes is plotted using stereonet and lower hemisphere projection. R values for each grid point are plotted in a separate figure
    'profile'1DThis plot is composed of three figures showing changes in plunge and trend of the principal stress axes and R for each grid point.
    'stereomap'2DAppropriate for visualization of 2D stress inversion results (e.g. surface distribution). Directions of principal stress axes for each grid point forming a map are plotted using the stereonet. 2D distribution of R values is shown as a separate figure.
    'wsm'2DThis option creates a 2D plot compatible to those created by World Stress Map project (Heidbach et al., 2010). It shows the directions of the maximum horizontal stress according to the respective stress faulting regime classification criteria (Zoback, 1992)
    'stereovolume'3DIt is appropriate for 3D stress inversion data. The results are presented as 3D plot with cardinal stress axes directions pointing according to their trends and plunges. The idea is analogous to “stereomap” but extended to 3D

    To modify the graphical characteristics of obtained plots, the user may specify additional PropertyName-PropertyValue pairs to adjust the graphical output.

    4.8 msatsi_plot properties

    The design of the plots created with msatsi_plot.m can be significantly modified using a number of PropertyName-PropertyValue pairs. The available msatsi_plot.m properties are gathered in the table below.

    PropertyNameConstraintsDefault ValueDescription
    ArbitraryGridn-by-2 matrix[]It replaces the OUT.GRID with the values given in the matrix specified by the user. The first and second columns replace X and Y coordinates, respectively. This can be used to position the stress inversion results in arbitrary positions.
    ConfidenceIntervals'intervals' | 'off' | 'bootstraps''intervals'It specifies the confidence intervals to be plotted or switches them off. 'intervals' option creates patches covering the area enclosed by bootstrap resamplings (confidence intervals); 'bootstraps' option plots the bootstrap points; 'off' switches off plotting of the uncertainties.
    Grid'on' | 'off''on'Switches on/off plotting of the stereonet grid.
    GridColor1-by-3 matrix[0.5 0.5 0.5]Allows for modification of the stereonet grid color.
    GridStepAzimuthScalar > 015Separation between the consecutive grid lines along the azimuth in stereonet plot (degrees).
    GridStepPlungeScalar > 015Separation between the consecutive grid lines along the plunge in stereonet plot (degrees).
    Projection'schmidt' | 'wulff''wulff'Defines a type of lower hemisphere projection as 'schmidt' (Equal-area projection) or 'wulff' (Equal angle projection).
    RPlot'on' | 'off''on'Enables/disables creation of R plot.
    ScaleFactorScalar > 00.5Modifies the size of stress axes directions with respect to the grid points. Especially useful for cases with more than 1D or when ArbitraryGrid is used.
    SlicestringNULLReduces the number of dimensions / output data to be plotted by selecting only the stress inversion results that are in agreement with the specified condition, e.g. 'X==0', 'Y<10', etc. Example: To plot a stereomap from a 3D SI results, we should select the plot type stereomap, and then 'Slice' and the condition, for example 'X==0' will plot only the results that have X==0.
    Stereonet'on' | 'off''on'Switches on/off' plotting of the stereonet.
    S1Color1-by-3 matrix[1 0 0]Color of S1, specified by [r g b] triplet.
    S2Color1-by-3 matrix[0 1 0]Color of S2, specified by [r g b] triplet.
    S3Color1-by-3 matrix[0 0 1]Color of S3, specified by [r g b] triplet.
    S1PatchColor1-by-3 matrix[1.0 0.7 0.7]Edits the color in which S1 uncertainty patch is plotted, specified by [r g b] triplet.
    S2PatchColor1-by-3 matrix[0.7 1.0 0.7]Edits the color in which S2 uncertainty patch is plotted, specified by [r g b] triplet.
    S3PatchColor1-by-3 matrix[0.7 0.7 1.0]Edits the color in which S3 uncertainty patch is plotted, specified by [r g b] triplet.
    S1'on' | 'off''on'Switches plotting of the maximum principal stress S1
    S2'on' | 'off''on'Switches plotting of the intermediate principal stress S2
    S3'on' | 'off''on'Switches plotting of the minimum principal stress S3
    SymbolLineSpec'+'Determines the symbol used to mark the best solution in various plots
    SText'on' | 'off''off'Adds text of 's1','s2','s3' beside best solutions
    Titlestring'off'Adds a tittle to plots created.
    XGridLabelcell array with strings{}Modifies the grid labels for X axis.
    YGridLabelcell array with strings{}Modifies the grid labels for Y axis.
    ZGridLabelcell array with strings{}Modifies the grid labels for Z axis.
    XLabelstringNULLAdds a label to the X axis
    YLabelstringNULLAdds a label to the Y axis
    ZLabelstringNULLAdds a label to the Z axis

    5. Examples

    In this section we provide with examples of every dimension that can be plotted with msatsi_plot.m.

    0D example of stress inversion

    This example (not included in the paper) is composed of a set of 150 focal mechanisms describing normal faulting regime grouped in a single grid point [0 0]. Therefore, the problem is 0D.

    To run this inversion, type:

    load('INPUT_EXAMPLE0D.mat');
    [OUT] = msatsi('example0',example0D,'PTPlots','on','BootstrapResamplings',2000)

    Since it is only one grid point, a damped inversion cannot be performed (there are no neighboring grid points). Therefore, the ‘Damping’ is automatically settled to ‘off’ (no need to write it). As a consequence, there is no tradeoff curve output.

    In this case, we have activated the P and T axis for this grid point (‘PTPlots’). The plot is contained in the folder /example0. We calculate the uncertainty by 2000 bootstrap resamplings.

    Examples of plots

    1 By typing:

    [Hs, Hr] = msatsi_plot('example0','stereonet')

    We obtain two pictures, one representing the stress and one representing R values. Examples of these are saved as ‘example0_stereonet_S.png’ and ‘example0_stereonet_R.png’

    Example0_stereonet_S
    Example0_stereonet_S
    Example0_stereonet_R
    Example0_stereonet_R

     

    2 By typing:

     [Hs, Hr] = msatsi_plot('example0','stereonet','ConfidenceIntervals','bootstraps')

    We obtain two analogous pictures as the case before but this time the uncertainties are plotted as colored dots directly from the bootstrap resampling. The R plot is a histogram. Examples of these are saved as ‘example0_stereonet_bootstraps_S.png’ and ‘example0_stereonet_bootstraps_R.png’

    example0_stereonet_bootstraps_S
    example0_stereonet_bootstraps_S
    Example0_stereonet_bootstrap_R
    Example0_stereonet_bootstrap_R

     

    1D Example of stress inversion

    This example shows the temporal stress field orientation changes at NAFZ for the co-seismic period shown in the paper. The data is part of the studies from Bohnhoff et al., (2006), and Ickrath et al., (2014).

    The focal mechanisms are divided into 27 grid points that vary over the Y coordinate. Therefore, the problem is 1D. Each grid has 70 focal mechanisms.

    To obtain results from the coseismic period shown in the paper, type:

    load('INPUT_EXAMPLE1D.mat');
    [OUT] = msatsi('example1',example1D,'BootstrapResamplings',2000)

    In this case, we perform a damped inversion (settled by default) and uncertainty is calculated with 2000 bootstrap resamplings.

    Examples of plots

    1 By typing:

    [Hs, Hr] = msatsi_plot('example1','stereonet','ConfidenceIntervals','bootstraps','SText','on')

    We choose the plotting of the confidence intervals using the bootstrap resampling data. To write the name of each stress beside the data we use the property ‘SText’. We obtain two pictures for each grid point (one for stress and one for R values). Examples of these are saved as ‘example1_stereonet_bootstrap_S.png’ and ‘example1_stereonet_bootstrap_R.png’.

    Example1_stereonet_bootstrap_S
    Example1_stereonet_bootstrap_S
    Example1_stereonet_bootstrap_R
    Example1_stereonet_bootstrap_R

     

    2 By typing

    [Hs, Hr] = msatsi_plot('example1','stereonet','ConfidenceIntervals','off')

    We obtain only two pictures regardless of grid point number. Since we turned off the ‘ConfidenceIntervals’, the pictures contain only the trajectory described by the best solution along the grid points. Examples of these are saved as: ‘example1_stereonet_off_S.png’ and ‘example1_stereonet_off_R.png’

    Example1_confidence_off_S
    Example1_confidence_off_S
    Example1_confidence_off_R
    Example1_confidence_off_R

     

    3 By typing only

    [Hs, Hr] = msatsi_plot('example1','stereonet')

    We would obtain analogous pictures to those of the case before, this time together with their uncertainty intervals.

    4 By typing

    [Hs, Hr] = msatsi_plot('example1','profile','Title',{'This is the example n°1'})

    We obtain three pictures: one for variations with trend for S1, S2 and S3 along the grid points, a second analogous picture for variations in plunge and a third one with variations in R. Uncertainties are represented with error bars.With the property ‘Title’, we have written a title we on top of each figure. Examples of these are saved as: ‘example1_profile_TR.png’, ‘example1_profile_PL.png’, ‘example1_profile_R.png’.

    Example1_profile_TR
    Example1_profile_TR
    Example1_profile_PL
    Example1_profile_PL
    Example1_profile_R
    Example1_profile_R

     

    5 By typing

    [Hs, Hr] = msatsi_plot('example1','profile','ConfidenceIntervals','Bootstraps')

    We obtain analogous pictures as the case before, this time with the uncertainties plotted as points from the bootstrap resampling. This example was the one shown in the example from the paper.

    Example1_profile_bootstrap_TR
    Example1_profile_bootstrap_TR
    Example1_profile_bootstrap_PL
    Example1_profile_bootstrap_PL
    Example1_profile_bootstrap_R
    Example1_profile_bootstrap_R

     

    2D example of stress inversion

    This example shows the surface stress field orientation at The Geysers geothermal reservoir (focal mechanisms from Northern California Earthquake Datacenter). The focal mechanisms are divided into 20 grid points that vary over the X and Y coordinate. Therefore, the problem is 2D. Each grid has a different n° of focal mechanisms (from 35 to 448).

    To run the inversion of this example, type

    load('INPUT_EXAMPLE2D.mat');
    [OUT] = msatsi('example2',example2D,'BootstrapResamplings',2000,'MinEventsNode',30)

    Here, we are also performing a damped stress inversion (by default). Uncertainty is done by 2000 bootstrap resamplings. Additionally a minimum of 30 events per node is established.

    Examples of plots

    1 By typing

     [Hs, Hr] = msatsi_plot('example2','stereomap')

    We obtain only two pictures regardless of the number of grid points. The pictures contain one stereonet for each grid point in a map view, as well as R values. Examples of these are saved as: ‘example2_stereomap_intervals_S.png’ and ‘example2_stereomap_intervals_R.png’

    Example2_stereomap_intervals_S
    Example2_stereomap_intervals_S
    Example2_stereomap_intervals_R
    Example2_stereomap_intervals_R

     

    2 To create the figure from the example shown in the paper we can first define the grid label numbers (placed inside cells) and then run msatsi_plot as follows:

    xgridlab = num2cell([511:2:525]);
    ygridlab = num2cell([4289:2:4299]);
    [Hs, Hr] = msatsi_plot('example2','stereomap','ConfidenceIntervals','Bootstraps','XgridLabel',xgridlab,'YGridLabel',ygridlab)

    We obtain two pictures regardless of grid point number (one for stress and one for R values). Examples of these are saved as ‘example2_stereomap_bootstrap_S.png’ and ‘example2_stereomap_bootstrap_R.png’

    Example2_stereomap_bootstrap_S
    Example2_stereomap_bootstrap_S
    Example2_stereomap_bootstrap_R
    Example2_stereomap_bootstrap_R

     

    3 To place the stress inversion in any arbitrary position (e.g. their coordinates), we first create matrix with X’ Y’ (the new values to the grids ordered as OUT.GRID) and then we call msatsi_plot  as follows:

    arb_grid = [(20:-1:1)',(5:1:24)'];
    [Hs, Hr] = msatsi_plot('example2','stereomap','ArbitraryGrid',arb_grid,'ScaleFactor',0.5)

    By playing with the value of scale factor we will achieve increase/decrease size of circles and/or overlapping of them. Examples of these pictures are saved as ‘example2_stereomap_arbitrary_grid_S.png’ and ‘example2_stereomap_arbitrary_grid_R.png’

    Example2_stereomap_arbitrary_grid_S
    Example2_stereomap_arbitrary_grid_S
    Example2_stereomap_arbitrary_grid_R
    Example2_stereomap_arbitrary_grid_R

     

    4 By typing

    [Hs, Hr] = msatsi_plot('example2','wsm')

    We obtain the map with the direction of maximum horizontal stresses for each grid as calculated by Lund and Townend, (2007). This example corresponds to the picture shown in Fig 6b of our paper. Example of this is saved as: ‘example2_wsm.png’

    Example2_wsm
    Example2_wsm

     

    5 By typing

    [Hs, Hr] = msatsi_plot('example2','wsm','IntermediateStresses','on')

    We obtain the same picture as the previous example but this time also the intermediate stress inversion results plotted in black color (i.e. those not included as NF,TF or SS).

    Example2_wsm_inter
    Example2_wsm_inter

     

    3D example of stress inversion

    This example is a synthetic test varying the parameters of dip_direction, dip_angle and rake. The focal mechanisms are divided into 75 grid points that vary over X, Y and Z coordinates (3x5x5). Therefore, the problem is 3D. Each grid has 100 focal mechanisms.

    To obtain the results shown in the paper, type:

    load('INPUT_EXAMPLE3D.mat');
    [OUT] = msatsi('example3',example3D,'BootstrapResamplings',2000,'Damping','off')

    In this case, we have settled the ‘Damping’ off to not smooth the results of the different grids. Uncertainty assessment is performed with 2000 bootstrap resamplings.

    Examples of plots

    1 By typing

    [Hs, Hr] = msatsi_plot('example3','stereovolume','Xlabel',{'dip direction'},'YLabel',{'dip angle'},'ZLabel',{'Rake'})

    We obtain two pictures (one for stress and one for R values). We have used the properties ‘XLabel’,’YLabel’ and ‘ZLabel’ to write a label in the corresponding axes. Examples of these are saved as ‘example3_stereovolume_S.png’ and ‘example3_stereovolume_R.png’. This command was used to prepare the Fig. 7 shown in the paper.

    Example3_stereovolume_S
    Example3_stereovolume_S
    Example3_stereovolume_R
    Example3_stereovolume_R

     

    2 By typing:

    [Hs, Hr] = msatsi_plot('example3','stereovolume','ConfidenceIntervals','Bootstraps')

    We obtain two pictures. The picture for stress shows this time the uncertainties as bootstrap resampling. R plot keeps the same as in the case before. Examples of the stress plot is saved as: ‘example3_stereovolume_bootstraps_S.png’

    Example3_stereovolume_bootstrap_S
    Example3_stereovolume_bootstrap_S

     

    3 One useful property for 3D is ‘Slice’. In this example, we will represent only one 2D slice of our 3D results. For example, if we are interested in the inversions were dip direction = 45°, the corresponding X coordinate is 1 (because it is the second grid point). Therefore, we have to specify the condition ‘X==1’. By typing:

    [Hs, Hr] = msatsi_plot('example3','stereomap','Slice','X==1')

    We obtain the stereomap (2D) plot along the specified parameter. Two plots are created, one for stress and one for R values. Examples of these plots are saved as: ‘example3_stereomap_slice_X=1_S.png’ and example3_stereomap_slice_X=1_R.png

    Example3_stereomap_slice_S
    Example3_stereomap_slice_S
    example3_stereomap_slice_X=1_R
    example3_stereomap_slice_X=1_R

     

    6. Compilation of SATSI for different platforms

    The ./src directory contains modified C source code of SATSI library. Most of files have been slightly modified in comparison to the original source code developed by J. Hardebeck and A. Michael. One can download the original source files directly from the USGS website for comparison (http://earthquake.usgs.gov/research/software/). Notice that MSATSI library requires SATSI executable files compiled from MODIFIED source files (located ./src directory), therefore the original SATSI library available at USGS website and resulting executables can not be used as a replacement of the modified ones. For the convenience of the users, we provide the precompiled programs for different platforms and they are located in ./bin directory.

    6.1 Compilation for Linux platform

    We successfully compiled SATSI executables using GCC version 4.6.3 (Ubuntu/Linaro 4.6.3-1ubuntu5) under Ubuntu 12.04 LTS both for 64-bin and 32-bit versions. The resulting executables are available in /bin/linux directory of the MSATSI package separately for 32-bit and 64-bit version. The resulting executables should be copied to the folder containing msatsi.m and msatsi_plot.m while linux operating system is MATLAB host machine.

    Compilation procedure:

    1. Proceed to the ./src folder.
    2. Provided that you have GCC package, execute ‘make all’ in terminal. This should create seven executable files. Warning messages may or may not appear, but they may be easily ignored.
    3. Copy compiled executables to the folder containing msatsi.m and msatsi_plot.m.

    6.2 Compilation for Windows platform

    No procedure is provided in MSATSI package. The code was compiled following the rules from original MAKEFILE using the GCC/MINGW libraries and ECLIPSE Juno environment.

    6.3 Compilation for Mac platform

    1. Proceed to the ./src folder.
    2. Call ‘make all’. This should create seven executable files. Warning messages may appear, but they may be easily ignored.
    3. Copy compiled executables to the folder containing msatsi.m and msatsi_plot.m.

    7. References

    Hardebeck, J. L., and A. J. Michael (2006). Damped regional-scale stress inversions: Methodology and examples for southern California and the Coalinga aftershock sequence, J. Geophys. Res. Solid Earth 111, no. B11, B11310, doi 10.1029/2005JB004144.

    Lund B. and J. Townend, (2007). Calculating horizontal stress orientations with full or partial knowledge of the tectonic stress tensor, Geophys. J. Int., 170, 1328-1335, doi: 10.1111/j.1365-246X.2007.03468.x.

    Martínez-Garzón, P., G. Kwiatek, M. Ickrath and M. Bohnhoff (2013) MSATSI: A MATLAB package for stress tensor inversion combining solid classic methodology, a new simplified user-handling and a visualization tool. Seism. Res. Lett., 85, 4, doi: 10.1785/0220130189.

     

    25 Comments

    1. Marion Baques

      Hello, I have a problem when I try the example1D and for other examples. Could you help me? Thank you.
      Here what I have:
      >> OUT = msatsi(‘example1′,example1D,’BootstrapResamplings’,2000)
      Folder example1 already exist. Delete and continue [y/n]?y
      Calculating damping parameter.
      Exit status = 1
      Exit status = 1
      Exit status = 1
      Exit status = 1
      Exit status = 1
      Exit status = 1
      Exit status = 1
      Exit status = 1
      Exit status = 1
      Exit status = 1
      Exit status = 1
      Exit status = 1
      Exit status = 1
      Exit status = 1
      Exit status = 1
      Exit status = 1
      Exit status = 1
      Exit status = 1
      Exit status = 1
      Exit status = 1
      Exit status = 1
      Error using load
      Unable to read file ‘example1/example1_0.40.trd’. No such file or directory.

      Error in msatsi>tradeoff (line 868)
      TEMP = load(output_file);

      Error in msatsi (line 191)
      [damping_coeff] = tradeoff(projectname,caption,is_2D,ts_damp_ratio,exe_tradeoff);

      • Grzegorz

        This error appears when SATSI binaries are (somehow) not working correctly. So far all reports regarding this issue were related to Linux / Mac system. The solution is to compile SATSI binariers located in /src folder (the make configuration is provided therein).

    2. Jun Luo

      Excuse me, would you like to provide how to download the program? It is useful. The way in this web is failed.Thanks a lot.

      • Grzegorz

        You have to register with a valid e-mail address and you should then obtain the email message wit the download link. If this does not happen in some minutes, first check your spam folder and then feel free to contact me by email.

      • Grzegorz

        I am afraid this is not possible out of the box. But you could stop the program that is responsible for plotting the stresses onto the stereonet and convert it to horizontal stresses following approach you choose.

    3. Taufiq R

      I got a problem in running the script. I got an error text saying ” Error using textscan Invalid file identifier. Use fopen to generate a valid file identifier”. Please, could you help me how to solve this?. Thank you.

        • Liu

          I have the same problem mentioned above–“Error using textscan Invalid file identifier. Use fopen to generate a valid file identifier”. My matlab version is 2016b. I would appriate if you could help me. Thank you in advance.

        • Liu

          I have the same problem mentioned above–“Error using textscan Invalid file identifier. Use fopen to generate a valid file identifier”. My matlab version is 2016b. I would appriate if you couuld help me. Thank you in advance.

          • Grzegorz

            Please write an email to us (see the emails in the MSATSI documentation), attach the input file you use and the tell us how you run msatsi routine in matlab so we can try reproduce the error you have. I suspect your input file is wrong.

    4. Hu Meng

      Excuse me, I can not download this program,but my e-mail is valid. How can i get this program?Thanks a lot.

      • Grzegorz

        You should register with a valid email address. The email will be sent to you with a download link. In case you don’t receive email within a few minutes, please always check your spam box before contacting me. In this case I noticed you register with different email.

    5. Juchuan Wang

      Excuse me, I can not download this program,but my e-mail is valid. How can i get this program?Thanks a lot.

      • Grzegorz

        This is sometimes happening if the anti-spam filter decide your email address originate from a domain considered to contain spam email accounts. Please write directly to me with all credentials so I can register you and send you the download link

    6. Tom

      How could I relate my FMS’s lat and lon to the grid points? How can I convert it into grid point format to make the input data?
      or
      format conversion from “lon lat strike dip rake” to “x y dip_dir dip_angle rake”

      • Grzegorz

        It is completely depending on you. You could for example do the linear transformation from your MINLAT-MAXLAT to (0,1,2….n) (where MINLAT=0 and MAXLAT=n). Most important is that you have to provide integers for the grid. Likewise, same can be done for longitude. In case of large area, you might consider conversion from geographical to local UTM and then to grid.

    7. VIv

      I am looking for the output file to plot the stress field, which consists of each grid point’s Shmax and SHmin azimuthal orientation. But I am unsure which file/columns contain this Principal Stress Axis (PSA) information for each grid point (I believe, the number of data points ?<= number of grid points) when I successfully execute example 2. Could you help me?

    8. Anonymous

      I have some problem when I do 1D time series stress Inversion.
      When I type following code:

      1. msatsi_plot(‘testfile’,’profile’,’ConfidenceIntervals’,’Bootstraps’)
      2. msatsi_plot(‘testfile’,’profile’)

      My bootstraps distribution and confidence interval show different area, and best solution not locate between min and Max.
      Then I check the stereonet of P-T axis, their fittings are really weird.
      The ‘+’ also not locate inside of bootstraps cloud.
      I don’t know why.

    Leave a Reply

    Your email address will not be published. Required fields are marked *

    This site uses Akismet to reduce spam. Learn how your comment data is processed.