Skip to content

4. User Guidelines

Jump to bottom
DemAnasta edited this page Jul 3, 2019 · 2 revisions

How to use StrainTensor.py

StrainTensor.py computes strain tensor parameters on a selcted grid. The program comes with an extended help message, that can be displayed via the -h or --help switch (aka

$> ./StrainTensor.py [...] --help

will show the help message on screen). Users can controll StrainTensor.py's behaviour via a variety of available switches.

Basic Usage

To use the program, the only mandatory switch is the -i or --input-file, which specifies the input file to be used. All other options will automaticaly assume default values (see Options for a detailed list). Basic usage is described below:

usage: StrainTensor.py [-h] -i INPUT_FILE [--x-grid-step X_GRID_STEP]
                       [--y-grid-step Y_GRID_STEP] [-m METHOD] [-r REGION]
                       [-c] [-b] [--max-beta-angle MAX_BETA_ANGLE]
                       [-t WEIGHTING_FUNCTION] [--Wt Wt] [--dmin D_MIN]
                       [--dmax D_MAX] [--dstep D_STEP] [--d-param D_PARAMETER]

Options

The whole list of available options, is:

optional arguments:
  -h, --help            show this help message and exit
  -i INPUT_FILE, --input-file INPUT_FILE
                        The input file. This must be an ascii file containing the columns: 'station-name longtitude latitude Ve Vn SigmaVe SigmaVn Sne time-span'. Longtitude and latitude must be given in decimal degrees; velocities (in east and north components) in mm/yr. Columns should be seperated by whitespaces. Note that at this point the last two columns (aka Sne and time-span) are not used, so they could have random values.
  --x-grid-step X_GRID_STEP
                        The x-axis grid step size in degrees. This option is only relevant if the program computes more than one strain tensors. Default is 0.5(deg).
  --y-grid-step Y_GRID_STEP
                        The y-axis grid step size in degrees. This option is only relevant if the program computes more than one strain tensors. Default is 0.5(deg)
  -m METHOD, --method METHOD
                        Choose a method for strain estimation. If 'shen' is passed in, the estimation will follow the algorithm described in Shen et al, 2015, using a weighted least squares approach. If 'veis' is passed in, then the region is going to be split into delaneuy triangles and a strain estimated in each barycenter. Default is 'shen'.
  -r REGION, --region REGION
                        Specify a region; any station (in the input file) falling outside will be omitted. The region should be given as a rectangle, specifying min/max values in longtitude and latitude (using decimal degrees). E.g. "[...] --region=21.0/23.5/36.0/38.5 [...]"
  -c, --cut-excess-stations
                        This option is only considered if the '-r' option is set. If this option is enabled, then any station (from the input file) outside the region limit (passed in via the '-r' option) is not considered in the strain estimation.
  -b, --barycenter      Only estimate one strain tensor, at the region's barycentre.
  --max-beta-angle MAX_BETA_ANGLE
                        Only relevant for '--method=shen'. Before estimating a tensor, the angles between consecutive points are computed. If the max angle is larger than max_beta_angle (in degrees), then the point is omitted (aka no tensor is computed). This option is used to exclude points from the computation that only have limited geometric coverage (e.g. the edges of the grid). Default is 180 deg.
  -t WEIGHTING_FUNCTION, --weighting-function WEIGHTING_FUNCTION
                        Only relevant for '--method=shen'. Choose between a 'gaussian' or a 'quadratic' spatial weighting function. Default is 'gaussian'.
  --Wt Wt               Only relevant for '--method=shen' and if 'd-param' is not passed in. Let W=Σ_i*G_i, the total reweighting coefficients of the data, and let Wt be the threshold of W. For a given Wt, the smoothing constant D is determined by Wd=Wt . It should be noted that W is a function of the interpolation coordinate, therefore for the same Wt assigned, D varies spatially based on the in situ data strength; that is, the denser the local data array is, the smaller is D, and vice versa. Default is Wt=24.
  --dmin D_MIN          Only relevant for '--method=shen' and if 'd-param' is not passed in. This is the lower limit for searching for an optimal d-param value. Unit is km. Default is dmin=1km.
  --dmax D_MAX          Only relevant for '--method=shen' and if 'd-param' is not passed in. This is the upper limit for searching for an optimal d-param value. Unit is km. Default is dmax=500km.
  --dstep D_STEP        Only relevant for '--method=shen' and if 'd-param' is not passed in. This is the step size for searching for an optimal d-param value. Unit is km. Default is dstep=2km.
  --d-param D_PARAMETER
                        Only relevant for '--method=shen'. This is the 'D' parameter for computing the spatial weights. If this option is used, then the parameters: dmin, dmax, dstep and Wt are not used.
  -g, --generate-statistics
                        Only relevant when '--mehod=shen' and '--barycenter' is not set. This option will create an output file, named 'strain_stats.dat', where estimation info and statistics will be written. (default: False)
  --verbose             Run in verbose mode (show debugging messages) (default: False)
  --multicore           Run in multithreading mode (default: False)
  -v                    Display version and exit. (default: False)

For example, the command we used on the Example section:

$> ./StrainTensor.py -i ../data/CNRS_midas.vel -r 18.75/30.25/32.75/42.25 --x-grid-step=0.5 --y-grid-step=0.5 --dmin=1 --dmax=500 --dstep=1 --Wt=24 -c

meant that we are estimating strain tensor parameters for the region within min/max longtitude: 18.75/30.25 degrees and min/max latitude: 32.75/42.25 degrees. We are seperating the region into cells of size 0.5 degrees and estimating one strain tensor in each cell centre (aka the first cell centre is $lon = lon_{min} + lon_{step}/2 = 18.75 + 0.5/2=19.0deg.$ and $lat = lat_{min} + lat_{step}/2 = 32.75 + 0.5/2 = 33.0deg.$, then next one will be at lon=19.5, lat=33.5, etc...). To estimate each strain tensor, the program will search for a "optimal" D coefficient within the range [1, 500) km with a step of 1km. This "optimal" D will be found when the condition $W = \sum_{n=1}^{#sta*2} Z(i)*L(i) \geq W_t$ is met. The stations that will be used for the calculations are only those that fall within the specified longtitude/latitude range. For more information, see Background and Algorithms section.

Input Files

To perform the computations, StrainTensor.py needs an input file, that holds input data. Usually, this implies a list of GPS/GNSS stations with their ellipsoidal coordinates (aka longtitude and latitude) and their respective tectonic velocities (usually estimated using position time-series) allong with the corresponding standard deviation values. The format of these files, should follow the convention:

        station-name  longtitude   latitude   Ve     Vn    SigmaVe  SigmaVn  Sne  time-span 
         string           deg.        deg.   mm/yr  mm/yr   mm/yr    mm/yr    /   dec. years

Station coordinates are provided in longtitude/latitude pairs in decimal degrees. Velocities and velocity standard deviations are provided in mm per years (mm/yr). Sne is the correlation coefficient between East and North velocity components and time-span is the total time span of the station timeseries in decimal degrees. Note that at his point the last two columns (aka Sne and time-span) are not used, so they could have random values.

There are no strict formating rules on how the individual elements should be printed (i.e. how many fields, decimal places, etc). The only condition is that fields are seperated by whitespace(s). To see an example of a valid input file, you can check data/CNRS_midas.vel.

Output Files

Results of StrainTensor.py are recorded in the following three files:

  • strain_info.dat : This file includes strain tensor parameters, principal axis, rotational rates, dilatation etc.
    The columns of the file are structured as below:
Latitude  Longtitude     vx+dvx          vy+dvy           w+dw          exx+dexx        exy+dexy        eyy+deyy       emax+demax      emin+demin       shr+dshr        azi+dazi      dilat+ddilat   sec.inv.+dsec.inv.
   deg       deg         mm/yr           mm/yr          deg/Myr       nstrain/yr      nstrain/yr      nstrain/yr      nstrain/yr      nstrain/yr      nstrain/yr         deg.         nstrain/yr      nstrain/yr
  • station_info.dat : Stations' data used for the calculation of strain tensor are written at htis file. Format is:
Code Longtitude Latitude Ve Vn
  • StrainTensor.out : Parameters used to modigy grid, calculate Strain tensors etc.

How to use Plot Tools

Plotting scripts are placed under plot/ directory. They are:

  • gmtstrainplot.sh,
  • gmtstatsplot.sh, and
  • plotall.sh

All of the scripts need the file named default-param to be in the same folder.default-param file options

   
pth2inptf=../data/  # set default folder for input files (strain_info.dat, strain_stats.dat, station_info.dat)
west, east, south, north, projscale, frame, sclength: set region parameters

PAPER_SIZE="30cx30c" : set custom paper size (width x height)

vscmagn=20 : magnitude of horizontal arrow scale
VSC=0.05 : Horizontal velocity scale

strscmagn=100 : set magnitude of principal axes scale
STRSC=0.01 : set principal axis plot scale

ROTSC=.7 : set rotational rates plot scale
ROT_wedge_mag=1 : set magnitude of rotational 1-wedge.

gmtstrainplot.sh options:

Basic Plots & Background :
     -r | --region : region to plot (default Greece)
         usage: -r west east south north projscale frame

Plot station and velocities:
    -psta [:=stations] plot only stations from input file
    -deltr [:= delaunay triangles] plot delaunay triangles
    -vhor (station_file)[:= horizontal velocities]
    -vsc [:=velocity scale] change valocity scale default 0.05

Plot strain tensor parameters:
     -str (strain file)[:= strains] Plot strain rates
     -rot (strain file)[:= rots] Plot rotational rates
     -gtot(strain file)[:=shear strain] plot total shear strain rate contours
     -gtotaxes (strain file) dextral and sinistral max shear strain rates
     -dil (strainfile)[:= dilatation] Plot dilatation and principal axes
     -secinv (strain file) [:=2nd invariand] Plot second invariand
     -strsc [:=strain scale]
     -rotsc [:=rotational scales]
   *for -gtot | -dil | -secinv use +grd to plot gridded data
        ex:-gtot+grd

Other options:
     -o | --output : name of output files
     -l | --labels : plot labels
     -mt | --map_title "text": title map default none, use quotes
     -jpg : convert eps file to jpg
     -h | --help : help menu

For example, to plot the principal axis fo strain rates for the example case above you can use the following command:

$> ./gmtstrainplot.sh -jpg -str strain_info.dat -psta -l

gmtstatsplot.sh options:

Basic Plots & Background :
     -r | --region : region to plot (default Greece)
         usage: -r west east south north projscale frame

Plot Stations and triangles:
     -psta [:=stations] plot only stations from input file
     -deltr [:= delaunay triangles] plot delaunay triangles

Plot Statistics:
     -stats (input file) set input file
     --stats-stations : plot used stations
     --stats-doptimal : plot optimal distance (D)
     --stats-sigma : plot sigma 

Other options:
     -o | --output : name of output files
     -l | --labels : plot labels
     -leg : plot legends
     -mt | --map_title  : title map default none, use quotes
     -jpg : convert eps file to jpg
     -h | --help : help menu

For example, to plot the principal axis fo strain rates for the example case above you can use the following command:

$> ./gmtstatsplot.sh -jpg -stats strain_stats.dat --stats-stations -leg -o output_stats-stations

plotall.sh options:

   - no switch produce default output names
   -p | --prefix : add prefix work id to output file
   -s | --suffix : add suffix work id to output file
   -h | --help: help panel
	
$> ./plotall.sh -p test -s test2

StrainTool ©️ 2018 Dionysos Satellite Observatory

Clone this wiki locally