2.1 General Information

There are 18 GMT programs that directly create (or add overlays to) plots (Table 2.1); the remaining 45 are mostly concerned with data processing. This session will focus on the task of plotting lines, symbols, and text on maps. We will build on the skills we acquired while familiarizing ourselves with the various GMT map projections as well as how to select a data domain and boundary annotations.

Table 2.1: List of all 1-D and 2-D plotting programs in GMT.

Program	Purpose
BASEMAPS
psbasemap	Create an empty basemap frame with optional scale
pscoast	Plot coastlines, filled continents, rivers, and political borders
pslegend	Create legend overlay
POINTS AND LINES
pswiggle	Draw spatial time-series along their $(x,y)$-tracks
psxy	Plot symbols, polygons, and lines in 2-D
psxyz	Plot symbols, polygons, and lines in 3-D
HISTOGRAMS
pshistogram	Plot a rectangular histogram
psrose	Plot a polar histogram(sector/rose diagram)
CONTOURS
grdcontour	Contouring of 2-D gridded data sets
pscontour	Direct contouring or imaging of $xyz$ data by optimal triangulation
SURFACES
grdimage	Produce color images from 2-D gridded data
grdvector	Plot vector fields from 2-D gridded data
grdview	3-D perspective imaging of 2-D gridded data
UTILITIES
psclip	Use polygon files to initiate custom clipping paths
psimage	Plot Sun rasterfiles
psmask	Create clipping paths or generate overlay to mask
psscale	Plot grayscale or colorscale bar
pstext	Plot textstrings on maps

Plotting lines and symbols, psxy is one of the most frequently used programs in GMT. In addition to the common command line switches it has numerous specific options, and expects different file formats depending on what action has been selected. These circumstances make psxy harder to master than most GMT tools. Table 2.2 shows a complete list of the options.

Table 2.2: Optional switches in the psxy program.

Option	Purpose
-A	Suppress line interpolation along great circles
-Ccpt	Let symbol color be determined from $z$-values and the cpt file
-E[x$\vert$X][y$\vert$Y][cap][/pen]	Draw selected error bars with specified attributes
-Gfill	Set color for symbol or fill for polygons
-L	Explicitly close polygons
-M[flag]	Multiple segment input data; headers start with flag
-N	Do Not clip symbols at map borders
-S[symbol][size]	Select one of several symbols (See Table 2.3)
-Wpen	Set pen for line or symbol outline

The symbols can either be transparent (using -W only, not -G) or solid (-G, with optional outline using -W). The -S option takes the code for the desired symbol and optional size information. If no symbol is given it is expected to be given in the last column of each record in the input file. The size is optional since individual sizes for symbols may also be provided by the input data. The main symbols available to us are shown in Table 2.3.

Table 2.3: The symbol option in psxy. Lower case symbols (a, c, d, g, h, i, n, s, t, x) will fit inside a circle of given diameter. Upper case symbols (A, C, D, G, H, I, N, S, T, X) will have area equal to that of a circle of given diameter.

Option	Symbol
-S-size	horizontal dash; size is length of dash
-Sasize	star; size is radius of circumscribing circle
-Sbsize[/base][u]	bar; size is bar width, append u if size is in x-units
	Bar extends from base [0] to the y-value
-Scsize	circle; size is the diameter
-Sdsize	diamond; size is its side
-Se	ellipse; direction (CCW from horizontal), major, and minor axes in inches
	are read from the input file
-SE	ellipse; azimuth (CW from vertical), major, and minor axes in kilometers
	are read from the input file
-Sgsize	octagon; size is its side
-Shsize	hexagon; size is its side
-Sisize	inverted triangle; size is its side
-Sksymbol/size	kustom symbol; size is its side
-Slsize/string[%font]	letter; size is fontsize. Append a letter or text string, and optionally a font
-Snsize	pentagon; size is its side
-Sp	point; no size needed (1 pixel at current resolution is used)
-Srsize	rect, width and height are read from input file
-Sssize	square, size is its side
-Stsize	triangle; size is its side
-Sv[thick/length/width][nnorm]	vector; direction (CCW from horizontal) and length are read from input data
	Optionally, append the thickness of the vector and the width and length of the
	arrow-head. If the nnorm is appended, all vectors whose lengths are less than
	norm will have their attributes scaled by length/norm
-SV[thick/length/width][nnorm]	vector, except azimuth (degrees east of north) is expected instead of direction
	The angle on the map is calculated based on the chosen map projection
-Sw[size	pie wedge; start and stop directions (CCW from horizontal) are read from input data
-Sxsize	cross; size is length of crossing lines
-Sysize	vertical dash; size is length of dash

Because some symbols require more input data than others, and because the size of symbols as well as their color can be determined from the input data, the format of data can be confusing. The general format for the input data is (optional items are in brackets []):

$x\mbox{ } y$ [ $z$ ] [ $size$ ] [ $\sigma_x$ ] [ $\sigma_y$ ] [ $symbol$ ]

Thus, the only required input columns are the first two which must contain the longitude and latitude (or x and y). The remaining items apply when one (or more) of the following conditions are met:

1. If you want the color of each symbol to be determined individually, supply a cptfile with the -C option and let the 3rd data column contain the z-values to be used with the cptfile.

2. If you want the size of each symbol to be determined individually, append the size in a separate column.

3. To draw error bars, use the -E option and give one or two additional data columns with the $\pm dx$ and $\pm dy$ values; the form of -E determines if one (-Ex or -Ey) or two (-Exy) columns are needed. If upper case flags X or Y are given then we will instead draw a ``box-and-whisker'' symbol and the $\sigma_x$ (or $\sigma_y$) must represent 4 columns containing the minimum, the 25 and 75% quartiles, and the maximum value. The given $x$ (or $y$) coordinate is taken as the 50% quartile (median).

4. If you draw vectors with -Sv (or -SV) then size is actually two columns containing the direction (or azimuth) and length of each vector.

5. If you draw ellipses (-Se) then size is actually three columns containing the direction and the major and minor axes in plot units (with -SE we expect azimuth instead and axes lengths in km).

Before we try some examples we need to review two key switches; they specify pen attributes and symbol or polygon fill. Please consult Chapter 4 in the GMT Technical Reference and Cookbook before experimenting with the examples below.