next up previous contents index
Next: 2.1.1 Examples Up: 2. SESSION TWO Previous: 2. SESSION TWO   Contents   Index

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
psbasemap Create an empty basemap frame with optional scale
pscoast Plot coastlines, filled continents, rivers, and political borders
pslegend Create legend overlay
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
pshistogram Plot a rectangular histogram
psrose Plot a polar histogram(sector/rose diagram)
grdcontour Contouring of 2-D gridded data sets
pscontour Direct contouring or imaging of $xyz$ data by optimal triangulation
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
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.

next up previous contents index
Next: 2.1.1 Examples Up: 2. SESSION TWO Previous: 2. SESSION TWO   Contents   Index
Paul Wessel 2006-05-31