1.1.7. Grid2GMT - location results or 3D grid data to GMT command script

Grid2GMT writes ASCII, GMT command scripts which will generate postscript plots of event location results and sections of 3D grid files.

`Overview <#_overview_>`__ - `Running the program-Input <#_running_>`__ - `Output <#_output_>`__ - [NonLinLoc Home]

1.1.7.1. Overview

The Grid2GMT utility generates and runs an ASCII, GMT command script for plotting sections and plan views of 3D grid files and location misfit, PDF and “scatter-cloud” results. When run, the GMT command script creates a postscript file which can be viewed on screen or printed. Running the GMT command script requires the intallation of the GMT plotting package.

For flexibility, the Grid2GMT utility takes most of its parameters from the command line. However, some parameters are obtained from the `Generic Statements section <./control.html#_generic_>`__ of the Input Control File.

The default GMT script plots the views in the transformed X-Y coordinates. Horizontal (plan) view only plots can also be plotted in geographic lat-long coordinates. See the notice and instructions in the *.gmt script file generated by Grid2GMT for more details.

Grid2GMT can be somewhat cumbersome and confusing to use because it combines several functions (i.e. plotting sections and location results), it requires several paths and filenames, and it does not have as sophisticated error checking as other NonLinLoc programs.

1.1.7.2. Running the program - Input

The Grid2GMT utility takes a number of command line arguments and has three basic modes - (1) Vertical cross section (V), (2) Horizontal section (H), and (3) Location (L) which generates a horizontal section and two vertical sections through the maximum likelihood point of an event location.

If a GMT-cpt file named Grid2GMT.cpt is present in the directory in which the GMT script is run, it will be used for the plot and scalebar contours levels and colors for all plot types that use contouring. (ver 2.0)

If a GMT script file named Grid2GMT.?.gmt, where ? = H, X, Y or V is present in the directory in which the main GMT script is run, it will be run for the corresponding view (H, X, Y or V)after all standard GMT script is run for that view. (ver 2.0)

Synopsis:

Vertical cross section (V):

Grid2GMT InputControlFile GridRoot Outroot V PlotType iX1 iY1 iX2 iY2

or, Vertical cross section lat/long (VL): (ver 2.0)

Grid2GMT InputControlFile GridRoot Outroot VL PlotType lat1 long1 lat2 long2

or, Horizontal section (H):

Grid2GMT InputControlFile GridRoot Outroot H PlotType iZ

or, Location (L, horizontal section and 2 vertical sections):

Grid2GMT InputControlFile GridRoot Outroot L PlotType

Parameters: (general)

InputControlFile (chars)
specifies the complete path and filename for an Input Control File with certain required and optional statements specifying program parameters and file names. To run Grid2GMT the `Generic Statements section <./control.html#_generic_>`__ of the Input Control File must contain the CONTROL and TRANS (Geographic Transformation) statements; it may optionally contain one or more MAPLINE (Geographic Mapline) statements; and may contain a MAPTRANS (Geographic Transformation for Grid2GMT plotting), or MAPGRID (Grid region for Grid2GMT plotting), statements (ver 2.3). If maplines are specified, they will be transformed if necessary and plotted on horizontal views. If a MAPTRANS statement is specified, it will be used for plotting, regardless if a TRANS statement is present in the control file. If a MAPGRID statement is specified, it will be used for plotting, regardless if any LOCGRID specification is given in any hypocenter files.

GridRoot (chars)
full or relative path and root name (no extension) for a `3D Grid <formats.html#_grid_>`__ (modes V or H), or for an event location (mode L). Mulitple root names may be specified using standard UNIX “wild-card” characters (* and ?); however, if any “wild-card” characters are used then the path and root name must be enclosed in double quotes (”) to prevent the shell from evaluating the “wild-card” characters.

Outroot (chars)
full or relative path and optional root name for output and temporary files.

PlotType
type of data to plot, options are:

G - Plot grided data as a contoured, color grid. For locations (L), also plots location statistics.

S - Plot location “scatter-cloud” results. For locations (L), also plots location statistics.

Ennndx - Plot location statistics (Maximum Likelihood location and/or traditional, Gaussian/Normal Expectation and Confidence Ellipsoid). nnndx is a code of: three integers with values n = 0 (no) or 1 (yes) specifying which statistics to plot (Maximum Likelhood point, Expectation point and Confidence Ellipsoid, respectively), and an optional float dx which specifies a maximum distance in km between the Expectation and Maximum Likelihood points allowed for each event to be plotted.

M (ver 2.3) - Plot focal mechanisms.

Rphases/scale (ver 2.3) - Plot phase residuals as symbols with a size proportional to residual magnitude and with type and color dependent on phase. phases is a set of phase codes, i.e. P or SnSg specifying which phases to plot. scale (float) specifyies the relative size of the residual symbols.

Parameters: (Vertical cross section - ``V``)

iX1 iY1 iX2 iY2 (integers)
the minimum and maximum grid indices (0 to Num-1, where Num is the number of grid nodes) for the x and y directions. This option plots sections parallel to the cooridinate axes and oblique sections (ver 2.0). Set iX1=iX2 and iY1<iY2 for a section in the y,z plane, or iY1=iY2 and iX1<iX2 for a section in the x,z plane. The full grid range in the z direction is always plotted.

Parameters: (Vertical cross section lat/long - ``VL``) (ver 2.0)

lat1 long1 lat2 long2 (floats)
the latitude and longitude of the left (1) and right (2) end of the cross section (all lat/long locations must be within the 3D grid) . This option plots sections parallel to the cooridinate axes and oblique sections. The lat/long locations are coverted to grid locations using the transformation specified in the TRANS statement of the InputControlFile. The full grid range in the z direction is always plotted.

Parameters: (Horizontal cross section - ``H``)

iZ (integer)
the grid index (0 to zNum-1, where zNum is the number of grid nodes) for the section level in the z direction. Currently this option only plots sections parallel to the x,y cooridinate axes. The full grid range in the x and y directions is always plotted.

Parameters: (Location - ``L``)

(no additional parameters)
The full grid range in the x, y and z directions is always plotted.

Notes:

See the `Definitions section <./control.html#_definitions_>`__ of the NonLinLoc Control File documentation for more information on datatypes.
Grid2GMT uses cm units, thus for proper execution of the GMT command script, the MEASURE_UNIT entry in the .gmtdefaults file must be set to cm (i.e. MEASURE_UNIT = cm)
The x, y and z coordinate limits and the number of grid nodes is determined by the grid origin and dimensions in the grid header file corresponding to the GridRoot root name. For plotting event locations which have no corresponding grid files, create a `3D Grid <formats.html#_grid_>`__ header file named (GridRoot.hdr) with the desired grid origin and dimensions.
The plotted ellipsoids are 2D projections of the Confidence Ellipsoids as calculated by the NLLoc location program (see `Inversion section <./NLLoc.html#_inversion_>`__ of the NLLoc program documentation); the 2D projections DO NOT represent the 2D, marginal distributions of the 3D Confidence Ellipsoids.

Examples:

Grid2GMT run/nlloc_sample.in time/layer.P.AURF.time gmt/ V G 0 0 0 301

Using Input Control File run/nlloc_sample.in, creates a GMT script for the 3D grid travel-time file with root name time/layer.P.AURF.time. The GMT script and temporary files are written to directory ./gmt/. The script will plot a Vertical cross section (V), showing the travel-time grid (G) for grid nodes = 0 in the x direction and between grid nodes 0 and 301 in the y direction. (View resulting plot)
Grid2GMT run/nlloc_sample.in "loc/vinti.*.*.grid0.loc" gmt/ L S

Using Input Control File run/nlloc_sample.in, creates a GMT script for each location with root name "loc/dur.*.*.grid0.loc". The GMT script and temporary files are written to directory ./gmt/. For each location, the script will plot a Location (L, horizontal section and 2 vertical sections), showing the location PDF “scatter-cloud” samples (S). (View one of the resulting plots)
Grid2GMT run/nlloc_sample.in loc/vinti.sum.grid0.loc gmt/ L E111

Using Input Control File run/nlloc_sample.in, creates a GMT script for the summary hypocenter file with root name loc/vinti.sum.grid0.loc. The GMT script and temporary files are written to directory ./gmt/. The script will plot a Location (L, horizontal section and 2 vertical sections), showing all location statistics (E111, Maximum Likelihood location and traditional, Gaussian/Normal Expectation and projection of Confidence Ellipsoid), with no restriction on the maximum distance between the Expectation and Maximum Likelihood points (dx omitted). Note that for the summary hypocenter files there are no corresponding grid files, thus a `3D Grid <formats.html#_grid_>`__ header file named dur.sum.grid0.loc.hdr with the desired grid origin and dimensions had to be created. ( View resulting plot)
Grid2GMT run/nlloc_sample.in loc/vinti gmt/ L S Using Input Control File run/nlloc_sample.in, creates a GMT script for the summary hypocenter/scatter file with root name loc/vinti created by program LocSum. The GMT script and temporary files are written to directory ./gmt/. The script will plot a Location (L, horizontal section and 2 vertical sections), showing the “scatter-cloud” samples (S for all events. (View resulting plot)
Grid2GMT run/dur.in dur.19950725.111732.grid2.loc gmt/ L G

Using Input Control File run/dur.in, creates a GMT script for the 3D grid grid-search PDF file in the current directory with root name dur.19950725.111732.grid2.loc. The GMT script and temporary files are written to directory ./gmt/. The script will plot a Location (L, horizontal section and 2 vertical sections), showing the location PDF as contoured, color confidence levels (S), along with location statistics (Maximum Likelihood location and traditional, Gaussian/Normal Expectation and projection of Confidence Ellipsoid). (View resulting plot)

1.1.7.3. Output

The Grid2GMT utility generates and runs an ASCII, GMT command script with the name Outroot/GridRoot.gmt. When run, this GMT command script creates a postscript file which can be viewed on screen with a postscript viewer, or printed on a postscript printer. Running the GMT command script requires the intallation of the GMT plotting package.

The GMT command script can be edited and elements of the script extracted to produce custom GMT plots.

Back to the NonLinLoc site Home page.

Anthony Lomax