mbm_xyplotSection: MB-System 5.0 (1)
Updated: 9 January 2015
NAMEmbm_xyplot - Create an executable shellscript which will generate a GMT plot of xy data.
SYNOPSISmbm_xyplot -I[filepars:]file [-I[filepars:]file -Gfill -H -Oroot -Ppagesize -Ssymbol/size -Uorientation -V -Wpen ]
[-Btickinfo -Jprojection[/scale | width] -Ltitle[:xlabel:ylabel] -Mmisc -Q -Rw/e/s/n -X -Z]
[-MGDgmtdef/value -MGL[f][x]lon0/lat0/slat/length[units][+llabel] -MGTx/y/size/angle/font/just/text -MGU[/dx/dy/][label] ]
DESCRIPTIONmbm_xyplot is a macro to generate a shellscript of GMT commands which, when executed, will generate a Postscript plot of xy data. Axes may be linear, log, or any of several geographic projections. Data may be plotted as symbols or lines. The plot will be scaled to fit on the specified page size or, if the scale is user defined, the page size will be chosen in accordance with the plot size. The primary purpose of this macro is to allow the simple, semi-automated production of nice looking plots with a few command line arguments.
By default mbm_xyplot expects the input data files to have values organized in columns separated by white space. However, users may optionally specify a non-white-space delimiter for each file. Input data files can have an arbitrary number of columns. When two or more columns exist the one may specify which two columns to plot (the first vs second is the default). In addition, users may optionally specify a single column to be plotted versus data-point-number.
The standard syntax with which one selects columns to plot may also be embedded into a larger Perl expression, which will be evaluated for each line of the data file. In this way, one may do on-the-fly mathematics or substring extractions as required. Indeed, one may specify most any Perl expression that when evaluated, will be a numeric result for plotting. For example, one can multiply the values in a column by a constant, add the values of two columns together or even extract latitude and longitude degrees and minutes in a file of NMEA strings and convert the results to decimal degrees for plotting. The macro uses the specified delimter to extract the values from each column, evaluate the expressions, and then leaves the result in temporary data in files to be read by the plotting shellscript. The temporary files are deleted on execution of the shell script by default, but can optionally be retained for debugging purposes.
For users seeking more control over the plot appearance, a number of additional optional arguments are provided. Truly ambitious users may edit the plot shellscript to take advantage of GMT capabilities not supported by this macro.
By default the output plot generation shellscript includes lines which execute a program to display the Postscript image on the screen. The program to be used to display the Postscript is set using mbdefaults; the default value can be overridden by setting the environment variable $MB_PS_VIEWER. Invoking the plot generation shellscript with a -N command line argument suppresses the screen display of the plot.
The plot scripts generated by this macro will work with GMT version 5.0 and later, and are not compatible with earlier versions of GMT.
AUTHORSHIPDavid W. Caress (email@example.com)
Monterey Bay Aquarium Research Institute
Dale N. Chayes (firstname.lastname@example.org)
Lamont-Doherty Earth Observatory
Suzanne H. O'Hara (email@example.com)
Lamont-Doherty Earth Observatory
SIMPLE DESCRIPTION OF BASIC OPTIONS
Default parameters are whitespace [ D(\s+) ], column 1 vs column 2 [ Cc_c ], black lines without symbols [ SN ], [ GN ], [ W1 ], and no multiple segments (omitted M flag).
Please see the "Complete Description of Options" below for details.
Specifies the files containing the data to be plotted, and for each file, a list of file parameters which are comprised of the rules used by mbm_xyplot to parse and manipulate the x and y values on the fly, as well as the line and symbol characters used for plotting the results.
The file parameters are an optional list of flags and their arguments concatinated and strung together with colons. A full specification has the following general syntax although individual flags and their arguments need not appear in any particular order as long as argument follows corresponding flag.:
The delimiter may be any character string. The default delimiter is whitespace.
By default, mbm_xyplot uses the first column as the x value and the second column as the y value for the plot. However, the C flag and column expression allows the user to chose other columns to plot. The general syntax is
where 'xcol' and 'ycol' designate the x and y columns respectively. Columns are numbered starting at '1' one the left most column in the file. In addition, either c expression may be replaced with a single '#' symbol to plot the other variable vs. line number. For example,
will plot the values in column 'ycol' vs their line number in the file.
Other valid Perl expressions may be substituted for either column expression as well. For example, to plot in kilometers, a file whose columns contain x and y coordinates in meters, one would specify
The line and symbol characteristics are set using the G, S, and W options. For example, the command -IG255/0/0:Sa/0.1:xy.dat will plot the (x,y) data pairs in the file xy.dat as 0.1 inch diameter red stars. [Default is a solid black line]. See the psxy man page for more details.
When multiple data files are specified (with multiple -I statements, the last G, S, and W options specified are for subsequent files. In order to plot different files using different line or symbol characteristics, new sets of commands can be specified for each file.
Finally, note that there are two ways in which one may plot multiple data sets on the same plot. One may specify multiple sets of file arguments [i.e. -I[filepars:]xy_file], one for each file to be plotted. This allows the most flexibility, including different one-the-fly manipulations and colors for each xy series.
An alternative is to utilize the "multiple segments" feature of psxy. Specify the M flag in the file argument list to invoke this feature. A single file may then contain all the data, one series after the next, with lines containing a single ">" and nothing more to delineate breaks in data segments. This is the default break character for psxy, and currently the only break character supported by mbm_xyplot. For example -IM:xy.dat would plot multiple data series in the file xy.dat whose segements were separated as in the following snippet:
-Joalon0/lat0/azimuth/scale (Oblique Mercator - point and azimuth)
-Joblon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
-Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point and pole)
-Jqlon0/scale (Equidistant Cylindrical Projection (Plate Carree))
-Jtlon0/scale (TM - Transverse Mercator)
-Juzone/scale (UTM - Universal Transverse Mercator)
-Jylon0/lats/scale (Basic Cylindrical Projection)
-Jslon0/lat0/scale (General Stereographic)
-Jklon0/scale (Eckert VI)
-Jrlon0/scale (Winkel Tripel)
-Jpscale (Linear projection for polar (theta,r) coordinates)
-Jxx-scale[l|ppow][/y-scale[l|ppow]] (Linear, log, and power scaling)
More details can be found in the psbasemap manpages.
American ANSI sizes:
A 8.5 x 11.0 in. ( 215.9 x 279.4 mm)
B 11.0 x 17.0 in. ( 279.4 x 431.8 mm)
C 17.0 x 22.0 in. ( 431.8 x 558.8 mm)
D 22.0 x 34.0 in. ( 558.8 x 863.6 mm)
E 34.0 x 44.0 in. ( 863.6 x 1117.6 mm)
F 28.0 x 40.0 in. ( 711.2 x 1016.0 mm)
E1 44.0 x 68.0 in. (1117.6 x 1727.2 mm)
Metric ISO A sizes:
A0 841.0 x 1189.0 mm (33.11 x 46.81 in.)
A1 594.0 x 841.0 mm (23.39 x 33.11 in.)
A2 420.0 x 594.0 mm (16.54 x 23.39 in.)
A3 297.0 x 420.0 mm (11.69 x 16.54 in.)
A4 210.0 x 297.0 mm ( 8.27 x 11.69 in.)
A5 148.0 x 210.0 mm ( 5.83 x 8.27 in.)
A6 105.0 x 148.0 mm ( 4.13 x 5.83 in.)
A7 74.0 x 105.0 mm ( 2.91 x 4.13 in.)
A8 52.0 x 74.0 mm ( 2.05 x 2.91 in.)
A9 37.0 x 52.0 mm ( 1.46 x 2.05 in.)
A10 26.0 x 37.0 mm ( 1.02 x 1.46 in.)
Metric ISO B sizes:
B0 1000.0x 1414.0 mm (39.37 x 55.67 in.)
B1 707.0 x 1000.0 mm (27.83 x 39.37 in.)
B2 500.0 x 707.0 mm (19.68 x 27.83 in.)
B3 353.0 x 500.0 mm (13.90 x 19.68 in.)
B4 250.0 x 353.0 mm ( 9.84 x 13.90 in.)
B5 176.0 x 250.0 mm ( 6.93 x 9.84 in.)
B6 125.0 x 176.0 mm ( 4.92 x 6.93 in.)
B7 88.0 x 125.0 mm ( 3.46 x 4.92 in.)
B8 62.0 x 88.0 mm ( 2.44 x 3.46 in.)
B9 44.0 x 62.0 mm ( 1.73 x 2.44 in.)
B10 31.0 x 44.0 mm ( 1.22 x 1.73 in.)
Metric ISO C sizes:
C0 914.4 x 1300.5 mm (36.00 x 51.20 in.)
C1 650.2 x 914.4 mm (25.60 x 36.00 in.)
C2 457.2 x 650.2 mm (18.00 x 25.60 in.)
C3 325.1 x 457.2 mm (12.80 x 18.00 in.)
C4 228.6 x 325.1 mm ( 9.00 x 12.80 in.)
C5 162.6 x 228.6 mm ( 6.40 x 9.00 in.)
C6 114.3 x 162.6 mm ( 4.50 x 6.40 in.)
C7 81.3 x 114.3 mm ( 3.20 x 4.50 in.)
MB-System large format sizes:
m1 1371.6 x 1828.8 mm (54.00 x 72.00 in.)
m2 1371.6 x 2133.6 mm (54.00 x 84.00 in.)
m3 1371.6 x 2438.4 mm (54.00 x 96.00 in.)
m4 1524.0 x 1828.8 mm (60.00 x 72.00 in.)
m5 1524.0 x 2133.6 mm (60.00 x 84.00 in.)
m6 1524.0 x 2438.4 mm (60.00 x 96.00 in.)
The default page size is A.
mblist -F41 -Isb2112_example.mb41 -OmZ > mz.dat
Here time is in seconds from the start of the file and the depths are in meters, positive upward (topography rather than bathymetry). Now, we use mbm_xyplot to generate shellscripts which in turn generate plots when executed. First, we generate a simple black line plot:
mbm_xyplot -Imz.dat -Omz
The above command generates an executable shellscript mz_line.cmd; executing this shellscript will generate a Postscript plot and display it on the screen.
Suppose we also have a sparse set of depth estimates in a file called sr.dat obtained by picking the seafloor on a seismic reflection record, and we wish to compare the two sets of depths. We can plot the swath sonar derived depths as a black line and the seismic derived depths as red stars as follows:
mbm_xyplot -Omz_sr -Imz.dat \
As an example, the contents of the plotting shellscript "mz.cmd" are:
# Shellscript to create Postscript plot of data in grd file
# Created by macro mbm_xyplot
# This shellscript created by following command line:
# mbm_xyplot -Imz.dat -Omz
# Save existing GMT defaults
echo Saving GMT defaults...
gmtdefaults -L > gmtdefaults$$
# Set new GMT defaults
echo Setting new GMT defaults...
gmtset ANOT_FONT Helvetica
gmtset LABEL_FONT Helvetica
gmtset HEADER_FONT Helvetica
gmtset ANOT_FONT_SIZE 8
gmtset LABEL_FONT_SIZE 8
gmtset HEADER_FONT_SIZE 10
gmtset FRAME_WIDTH 0.074999999999999997
gmtset TICK_LENGTH 0.074999999999999997
gmtset PAGE_ORIENTATION LANDSCAPE
gmtset COLOR_BACKGROUND 0/0/0
gmtset COLOR_FOREGROUND 255/255/255
gmtset COLOR_NAN 255/255/255
# Make xy data plot
echo Running psxy...
psxy mz.dat \
-X1 -Y0.5 -K -V > mz.ps
# # Make basemap
echo Running psbasemap...
psbasemap -Jx0.0011071486125582637/0.0062732342007434947 \
-B500/100:."Data File mz.dat": \
-O -V >> mz.ps
# Delete surplus files
echo Deleting surplus files...
# Reset GMT default fonts
echo Resetting GMT fonts...
mv gmtdefaults$$ .gmtdefaults
# Run xpsview
echo Running xpsview in background...
xpsview -ps a -or landscape -maxp 4m mz.ps &
# All done!
echo All done!
Suppose we have a file of NMEA GGA strings logged from a GPS receiver whose data looks like the following:
We can specify a comma delimited file and convert the latitude and longitude fields to decimal degrees on the fly with the following:
mbm_xyplot -ID,:C'substr(c,0,3)+substr(c,3,length(c)) /60_substr(c,0,2)+substr(c,2,length(c))/60':gps.raw
This is about as ugly as it gets. However, it is quite straightforward and very handy, so let us pick this apart. The -I flag specifies the file to plot and its parameters. The D subfield followed by ',' indicates the file is comma delimited. The C subfield followed by the Perl expression extracts fields to plot. There are two expressions here, the x values, (longitude) and the x values (latitude) separated by an "_". In the longitude expression, the degree portion of the longitude, which is the 5th field (c) is extracted and added to the minute portion of the longitude divided by 60. The same is done with the latitude field, (c).
Note the single quotes surrounding the C expression. These are required to ensure complex expressions such as these are not inadvertently interpreted by the shell.
Last Updated: 9 January 2015
Return to list of MB-System manual pages...
Back to MB-System Home Page...