GMT and TCSH shell scripting tutorial

Background
The Generic Mapping Tools (GMT) software package is designed to make various plots
using the method of Paint by numbers. It is widely used in earth science due to its ease
of application, quality of plots, and origin of being written by oceanographers at the
University of Hawaii (Paul Wessel and Walter Smith).

The tools take command line options and formatted files to produce post-script output.
Post-scripts are then easily converted to other standard images such as .pdf, .png, .tif,
.bmp, etc with the imagemagick library or can usually be directly plotted from a printer
or viewed with ghost-viewer.

While the tools can be independently called on a terminal command line, the most
typical way of creating plots is by creating a shell script. There are many shells available
to use, but the most common in seismology (or at least at Berkeley) is tcsh. The
advantage of shell scripting is you use the same syntax interactively that you can also call
in the script. This allows you to string together a series of commands which together
result in the desired final result.

Before you get started, make sure you have the zip archive,
plot_stations_for_orientation.zip which contains this document. You can get it from the
IRIS website in the resources for interns section or from a given directory (on board
during session).

Objectives
By the end of this session, students should be able to:
Create simple tcsh scripts
Create presentation quality location maps
Overlay various plots to create informative figures

Getting started
Open a terminal to begin. This can be done in different ways varying by system, but the
most universal method is to right click somewhere on the desktop and then select
Open/New terminal. You should get something similar to this:
This is a screenshot of a default terminal from MAC OS X. Ive customized it slightly to
give the time, name of computer, and current directory in the terminal prompt. The grey
bar following the $ is a placeholder to start entering commands. You can also see in this
image the title bar is Terminal bash 80x8. This tells me the terminal is currently
running the Bourne Again SHell (BASH). If your terminal does not say this, you may be
able to find out what shell youre running by typing:

You can see the terminal is running /bin/bash (which is the full location of the bash
shell). You can change to tcsh by entering tcsh at the prompt. All shells have their
advantages and disadvantages, but for this tutorial it will be most straightforward if
youre using tcsh.

Having set the shell, we have a little file system work. First create a new directory to
work in:
mkdir gmt_tutorial
and copy the files from the zip there:
cp r plot_stations_for_orientation/* gmt_tutorial
This will make identical copies of all the files and directories from the zip directory to the
newly created directory. You can now change directory to the gmt_tutorial directory and
list the contents with the following two commands:
cd gmt_tutorial
ls
Now we can start to make a script by opening a new text file with a simple editor.
gedit plot_stations.tcsh &
This will open the program gedit and open/create a file plot_stations.tcsh. The &
allows the terminal to continue to accept commands by placing the gedit program in the
background. Add the following three lines to the new file so it looks similar to the image
below:
#!/bin/tcsh
echo getting_started
exit
Select save from the menu bar and then go to the terminal. You can run this script by
first changing the permissions:
chmod +x plot_stations.tcsh
(This only ever needs to be done once for each file you make)
And then run the script with
./plot_stations.tcsh

This script will just display some text and exit (note that in the image, Ive changed to the
tcsh shell which has a different prompt on my computer).

Creating a basemap
Creating a basemap is a simple way to generate a new plot file and lay out boundary
information. Remove the line echo getting_started from the script and replace it
with:
psbasemap R0/1/0/1 JM3.5i Ba1f1/a1f1nsew >! station_map.ps
save and run the script to produce a new ps file station_map.ps (this could also be run as
is on the command line outside of the script)
This command will create a nearly blank image. The gmt tool psbasemap operates with
the options -R0/1/0/1 -JM3.5i and Ba1f1/a1f1nsew and outputs post-script file
information to what is called standard out. This standard out is redirected with >! to
create a new file station_map.ps. If you run the command without >! station_map.ps
on the command line you will see the post-script text put into the terminal.

There is extensive documentation on each of the gmt commands and options. The
easiest way to read is by using the man command:
man psbasemap
This will return necessary information to use the command. You can also check out the
GMT cookbook at this website:

http://www.soest.hawaii.edu/gmt/gmt/doc/gmt/html/GMT_Docs/GMT_Docs.html

The power of shell scripts can be more fully utilized by creating some shell variables. If
we set some variables before the psbasemap command we can use them repeatedly in a
relatively simple manner.
set region = "-R-106.93451/-106.90916/34.06863/34.08084"
set boundaries = "-BSWnea0.005f.1m/.0025f.05m"
set projection = "-JM9.5i"
set misc = "-K V X1i Y1.5i"
set post_script_name = station_map.ps
so the script is now like:

The region variable (-R option) defines the longitude and latitude box
The boundaries variable (-B option) defines how often to plot tick marks, annotations,
and gridlines. You can also add titles and axis labels in this option.
The projection (-J option) defines how to map the region of the spherical earth or
general data to a flat 2D image. This instance uses a Mercator (M) projection with a
horizontal length of 9.5 inches. In this case the vertical axis is defined automatically.
In the misc variable I put various GMT options. K allows more post script text to be
added later. V turns on verbose mode. X1i and Y1.5i move the plot 1 inch in the
horizontal direction and 1.5 inches in the vertical respectively.
The post_script_name variable is more commonly chosen to be simply ps or PS. This is a
variable commonly used in many scripts. This way you can copy and paste from one
script to another and not have to worry about changing the name of the output.

By using shell variables you can add many more commands and re-use the variables.
Using long named meaningful names can add significantly to the readability of a script,
but its also a good idea to add comments. Any text following the pound sign or hash (#)
is considered a comment. Ie:
# this is a comment

Plotting topography
In the directory, theres a file called PIC.xyz. This contains data in the form of
longitude latitude elevation (m)
in three columns. You can see the limits by using the gmt command minmax:
minmax PIC.xyz
You can change this to a grid file ready for gmt plot with the commands surface or
xyz2grd. I prefer surface as it creates a smooth output:
surface PIC.xyz GPIC.grd $region I.0001/.0001
In this command we re-use the region variable (which is very handy and will be used
significantly). We also add the GPIC.grd and I.0001/.0001 options. G{filename}
creates a new grid file named {filename} or in this case PIC.grd.
I{x_increment}/{y_increment} uses an increment of .0001 degrees between
each x point and between each y point. This value is a trade off between speed and
accuracy. However, theres a point of diminishing returns where surface is just heavily
interpolating.

In this instance surface only needs to be used once. Therefore you could put it on the
command line once to create the grid file. Or you can put it the script and comment it
out if things get slow.

It is also helpful to have a color palette designed specifically for the data we are about to
plot. This can be done with grd2cpt:
set misc = -D Z Chaxby
grd2cpt PIC.grd $msic >! PIC.cpt
This creates a file (PIC.cpt) with information GMT can use to create a color palette. Like
in surface above, the first argument after the command is the filename to use. D means
to set the back and fore-ground values to be the same as the min and maxes. Z creates
a continuous palette, which helps make smoother plots. Chaxby chooses the haxby
default palette to be used. GMT has several options you can browse by typing grd2cpt
without any arguments.

Finally we are ready to plot with grdimage (after resetting the misc variable)
set misc = -O CPIC.cpt V
grdimage PIC.grd $projection $region $misc >> $post_script_name
Your script should now look like:

This should yield a plot like:

If you wish you can now comment out the surface and grd2cpt lines and associated misc
variables by adding the hash sign at the front of the line.

Adding illumination with a gradient file

The GMT tool grdgradient creates a file with the spatial gradients of the 2D grid file
created earlier. So add the following commands between the surface command and the
grdimage command:
set misc = -A0 M Nt
grdgradient PIC.grd GPIC.grad $misc
In this case the A defines the angle (azimuth) in which the gradient is computed. M
tells grdgradient to compute in meters instead of lat/long. N is for normalization and
the t option with N uses a cumulative Cauchy distribution (see man grdgradient)

Now add -IPIC.grad to the misc command prior to the grdimage command. Again,
after a single run the grdgradient and associated misc can be commented out.

Adding contours
Contours can be added easily once you have a grid with the grdcontour command. But
before adding this, update the misc for grdimage to include K. Also, this is usually
better to have after the grdimage command.
set misc = -C10 A20f14 O V
grdcontour PIC.grd $region $projection $misc >> $post_script_name
The options C decides the interval of how many meters between each contour. A
defines the meters between each labeled contour and the f option at the end sets the
font size. O means overlay this image over previous images.
Important side note about O and K. Commands which write post-script files with
either >! $post_script_name or >> $post_script_name usually will need one or both.
The first command (in this case psbasemap) needs only K. The very last command
needs to NOT have K. All others need both O and K. If you get frustrated having
problems opening the post-script, go back and check the usage of O and K.

Overlaying points and text

Plotting x-y data is done with the psxy command. It can receive input from standard in
(similar to standard out mentioned before) or from simple data files with x in the first
column and y in the second (with the option of some z in the third).
set misc = -O K Sa0.2i -W1p/0 G0
psxy $region $projection $misc << END >> $post_script_name
-106.91911 34.07344
END
This invokes the psxy command to plot:
a star with radius .2 inches (-Sa0.2i)
a black border around that star with a 1 point black pen (-W1p/0)
fill in that star with black (-G0)
centered at the point -106.91911E longitude 34.07344N latitude

The syntax:
command << END
.
END
is the standard in method of saying run this command until you see the text string END

We can repeat this for the stations:

set misc = -O K Sa0.2i W1p/0 G0/0/255
psxy $region $projection $misc << END >> $post_script_name
-106.92027 34.073959
-106.92382 34.76003
-106.91941 34.075728
END
This will plot all stations as blue (-G0/0/255) stars. If you wished to make each station a
different color you could repeat the command with only the latitude and longitude of
the station with its own Gred/green/blue value where each of red/green/blue is a
number from 0 to 255. You can alter the symbols by changing Sa0.2i to something such
as Sc0.1i, which will make circles of radius 0.1 inches.

Text is plotted in a similar fashion with pstext.

set misc = -O K G0
pstext $region $projection $misc << END >> $post_script_name
 -106.91911 34.07294 14 0 1 TL PIC
END
In this case the input sent to pstext is a bit more complicated. The single line of standard
input is:
Longitude latitude font_size text_rotation font_type text_start_location text to plot
In many cases this can be such a pain its easier to just annotate with your final mark up
tool such as Powerpoint or Adobe Illustrator.

Adding a scale
Adding a scale bar is good practice. It may not always be necessary on topographic maps
as they are usually intuitively colored.
set misc = -D4.5i/-0.5i/9i/0.25ih O K B10/:meters:
psscale CPIC.cpt $misc >> $post_script_name
The D option is required for psscale. It tells the x-center/y-center/x-length/y-length and
Ive append h to make it horizontal while default is vertical. The B flag tells psscale to
label every 10 on the scale and put the text meters at the end.

Making a location map

You will be presenting your work to a large audience and many people may not know
where Socorro, the PIC, or your study area is. Therefore adding a larger scale location
map can help orient people. This can be done in four steps: new variables, new
basemap on top of the current plot, psxy to on the new plot, and pscoast to show
state/country boundaries and lakes/oceans, etc
set region_inset = -R-130/-70/26/50
set projection_inset = -JM3i
set misc = -O K G255 Bnews
psbasemap $region_inset $projection_inset $misc >> $post_script_name
Now reset misc and do a psxy
set misc = -O K Sa0.2 W1p/0 G0
psxy $region_inset $projection_inset $misc << END >>$post_script_name
-106.903 34.0663
END
Finally we use pscoast to draw state boundaries
set misc = -Dl Na W1p/0 O K
pscoast $region_inset $projection_inset $misc >> $post_script_name
In this case the Dl selects a low resolution dataset. Na means to draw all political
boundaries.

At this point your map should look similar to below:

Plotting a SAC waveform (ADVANCED)
Youve now created a presentation quality map, which will be useful to orient others to
your study location. You can also use a similar process to plot any type of xyz data (such
as a tomographic model) or you can use the tools to plot any number of figures. This
section goes a little bit further into preparing programs and then uses a simple c
program to prepare data and send the output to psxy to plot a seismic waveform at the
top of the map.

The first step is to compile the program sac2stdout. There are two versions of this code
currently available because SAC data files have slightly different formats between 32bit
and 64bit systems. The SAC data file IIPC.PC.LHZ.SAC included with this was created on a
64bit system. Therefore you should install the 64bit version of sac2stdout:
cd sac2stdout
cp Makefile.64 Makefile
make
cp sac2stdout ..
cd ..
This will create a copy of the exectuable function sac2stdout in the same working
directory youve been plotting in. Generally a best practice would be to move the
exectuable to a standard location (such as ~/bin) within your linux/unix search path so
you only have one version of the executable.
 Now were going to set up some variables. I often make use of the syntax:
command `other_unix_command`
This will first execute whatever is in the ` ` and then return the value to the outside
command similar to parentheses in math.
set sac_data = IIPC.PC.LHZ.SAC
set misc = -O K G255 Bnews Y6i
set projection_sac_data = -JX9.5i/.7i
set region_sac_data = `./sac2stdout $sac_data | minmax I1
Several options and syntax were introduced here:
-Y6i: Move the plot axis 6 inches vertically
-JX9.5i/.7i: The projection is flat x-y with an x axis of 9.5 inches and y axis of 0.7
inches
|: the pipe redirects output from the first command to become the input to the
second command.
-I1 on minmax returns the minimum and maximum of the input to the form:
-Rx_min/x_max/y_min/y_max
Now we can create a basemap
psbasemap $region_sac_data $projection_sac_data $misc >>
$post_script_name
We can also use minmax with the C option to return columns with each of the limits:
set limits = `sac2stdout $sac_data | minmax C`
This command creates a variable array called limits with 4 entries. We can then extract
them with the echo command:
set xmin = `echo $limits[1]`
set xmax = `echo $limits[2]`
set ymin = `echo $limits[3]`
set ymax = `echo $limits[4]`
With those variables in hand we can call on awk (which is another programming
language in itself) to do some simple math and calculate reasonable spacing for the tick
marks on our x-y seismic data plot.
set xtick = `echo $xmax $xmin | awk {print ($1-$2) / 20}`
set ytick =`echo $ymax $ymin | awk {print ($1-$2) / 5}`
Finally we can setup a new misc variable and plot
set misc = -O W2p/20/120/200
Ba${xtick}f${xtick}/a${ytick}f${ytick}nSeW
sac2stdout $sac_data | psxy $region_sac_data $projection_sac_data
$misc >> $post_script_name

This will be the last thing we plot in this exercise so the misc variable must contain O
but it must not contain K.

Finishing and exporting

If the ImageMagick library is properly installed, two common conversion tools are
available. ps2pdf will convert your freshly created post-script file to a more portable pdf
file (syntax: ps2pdf file.ps). convert will freely convert any input image format to any
desired output. It works on the last letters after the last . So be careful about naming
files. To make a .png you can add:
set png_name = station_map.png
convert $post_script_name $png_name
Finally, I like to finish my scripts with a message to the user.
echo $post_script_name created and converted to $png_name
Your final image should be similar to: