GrADS Seminar for Grad Students

"Grid Analysis and Display System"

To use this tutorial, you will need to copy the contents of the gradsem folder in the ~gcm directory into your own directory. Use the command

cp -r ~gcm/gradsem gradsem

Then you may have to edit the gpcp96.ctl and markP.ctl control files to reflect the actual location of the two data sets at the time of the seminar.

Best Source of Info:

The GrADS Homepage: grads.iges.org/grads

This has a complete tutorial and reference section. For advanced scripting or interface problems, check out the grads user-group online archive (linked to the webpage); a compilation of all the questions and answers ever posted.


Outline

I. How GrADS handles data (5 minutes)
	A. The Control File
	B. Arrangement of Data in a File

II. Interactive Sessions (25 minutes)
	A. Opening and displaying data
	B. Changing parameters/boundaries: animation
	C. Line, scatter, and bar graphs
	D. Multiple maps or graphs on one page
	E. Multiple data files
        F. Averages, anomalies, other calculations

III. Setting Display Colors (5 min)

IV. Saving and Printing  (5 minutes)
	A. Saving processed data
        B. Saving and printing Graphics

V. Scripting (10 minutes)
	A. Creating and running a script file
	B. The programming language


Anatomy of a Control File

markP.ctl

DSET homes/metogra/gcm/gradsdata/cru_p_0196_2.5.gdat
TITLE CRU monthly precipitation 1/01-12/96
UNDEF -9999. (the value -9999 indicates lack of data)
OPTIONS sequential (describes data format; only a few types)
XDEF 144 LINEAR 1.25 2.5 (144=360/2..5; x starts at 1.25 ; 2.5=increment)
YDEF 72 LINEAR -88.75 2.5 (72=180/2.5: y starts at -88.75: 2.5=increment)
ZDEF 1 levels 0 (surface level only)
TDEF 1152 linear JAN1901 1 mo (1152=12months*96 years; 1901-1996)
VARS
prc 0 0 precipitation mm/day (variable prc - 0 levels (surface); 0 for dimensions N/A for binary)
ENDVARS

The data file was probably created by writing a sequence of FORTRAN arrays to a data file in binary. Each 144x72 array represents one period of time.

cru_p_0196_2.5.gdat:

		    x  to  144 data points  ->

y		2	0.8	3.2	-9999 	....	(t = 1)

72		0.2	1.6	4	0	....

points		0.6	1	3	.4	...

...
...
		3.5	2.4	1.3	1	...	(t = 2)

		4.1	1.9	2	.6	...
...
...


Grads in Interactive Mode

To enter grads, simply type the command "grads". You'll be asked if you want "landscape" (8.5"x11" turned on its side) or "portrait" (8.5"x11" held the normal way). Most maps look better in landscape mode, so we'll just accept it and continue. What happens when you execute the commands below should largely be self explanatory.

***basic display******
>open markP.ctl
>display prc
>clear
>set gxout shaded
>d prc
>run cbar
>draw title My First Graph
>c
>set t  2
>d prc
>c
>set lat 20 50
>set lon -10 60
>d prc
>set lon 60 -10
>d prc         (what's wrong?)
>c
***animation******
>set lat -90 90
>set lon 0 360
>set t 1 120
>d prc
>c
***line graph****
>set lat 39
>set lon -77
>set t 1105 1129
>set gxout line
>d prc
>draw title DC Precip 
>c
***bar graph***
>set gxout bar
>d prc
*
**multiple maps, graphs**
*(quit and re-enter grads..
* ... select "portrait" mode)*
>open markP
>set gxout shaded
>set t 1105
>set lat -90 90
>set lon -180 180
*
*top half of page
>set vpage 0 8.5 5.5 11
>d prc
>draw title January
*
*bottom half of page
>set vpage 0 8.5 0 5.5
>set t 1106 
>d prc
>draw title February
>c
***Multiple files**
>reinit  
>open markP
>open gpcp96
>set t 1141 (Jan 1996)
>d prc (markP)
>d  p  (what's wrong?)
>d  p.2  (gpcp, opened second)
>c
>d  prc - p.2
>reinit
>open ndvi
>open markP
>set t 7 18 (Jan-Dec 82)
>set lat 39
>set lon -77
>set gxout line
>d NDVI.1
>d prc.2  (what's wrong?)
*
****two files, overlay different resolutions
>close 2
>set gxout bar
>d  NDVI   (this is already set for Jan-Dec 82)
>close 1 (don't clear!)
>open markP
>set lat 39
>set lon -77
>set t  973  984 (Jan-Dec 82)
>set gxout line
>d prc
>draw title NDVI vs Precip
> draw string 3  7 NDVI=bar
>draw string 3  6.5 prc=line
*
* Useful Graphics for Multiple Files *
*
***line styles***
>reinit
>open gpcp96
>open markP
>set lat 0
>set lon -60
>set t 1 12
>set gxout line
>set cstyle 3
>d  p.1
>set cstyle 5
>d prc.2
***scatter graphs**
>reinit
>open gpcp96
>open markP
>set lat 0
>set lon -60
>set t 1 12
>set gxout scatter
>d p.1; prc.2
>quit


Built-in Functions

All the usual functions (cos, sqrt, etc) can operate on grid variables, and GrADS has a few special ones as well. Refer to the web page documentation for a complete list, we will only demonstrate general principles about how they are used here.

Enter grads and try the following:

**time averages**
>open markP.ctl
>set  t  1 12
>define monavg=ave(prc,t+0,t+180,1yr)     ( '1yr' is the increment )

** the above command averages t = 1, 13, 25 etc ; t = 2, 14, 26, etc
** for a period of 15 years (15x12=180) and places the averages
** in the grid variable 'monavg' with the dimensions of x, y, and t.
** Note that the x and y dimensions had been previously set when the
** data file was opened, you simply had to redefine the time dimension
** with the 'set' command so that you had a time level for each of 12 months.

>modify monavg seasonal             (so tmonavg(t=1) = tmonavg(t=13) etc.)
>set gxout shaded
>set t 3
>d monavg
>set t 15
>d monavg
>c
***Anomalies*****
>set t 1 120
>define anomaly = prc - monavg
>d anomaly
>c
***what's this?***
>set t 1 12
>define sd = sqrt(ave(anomaly*anomaly,t+0,t+120,1yr))
>d sd
>c
***Area weighted averages****
>set t 1 120
>define gavg = aave(prc,lon=0, lon=360, lat=-90, lat=90)
>set gxout line
>set lat 0		(line graphs won't plot if spatial dimensions
>set lon 0		   are specified: any single coordinate will do)
>d gavg


Setting Display Colors

In the absence of direction from the user GrADS will choose the colors and contour levels for any displayed graphics. They are seldom in any discernable order as can be seen by issuing the 'run cbar' command. The user can specify contour colors by number for the following built-in values:

0 black	4 dark blue	8 orange		12 dark yellow
1 white	5 light blue	9 purple		13 aqua
2 red	6 magenta	10 yellow-green		14 dark purple
3 green	7 yellow	11 medium blue		15 gray

To see how to combine this with contour levels, let's assume you want to display temperature in Fahrenheit ranging from 60 to 80 degrees in increments of 4 degrees, with blue being the coldest and red being the hottest in spectral order. You might issue the commands:

>set clevs  60 64 68 72 76 80
>set ccols 4 5 3 10  7 8 2
>run cbar

Note that there is one more color than level: the color 7 (blue) represents everything below 60 F, color 8 represents 60-64 F; and eventually color 10 represents everything above 80 F.

The built-in colors leave much to be desired, as they do not allow near-continous graduations in color, and many times you may want to represent extremes by, say, dark blue fading into a light green which deepens to dark green. This can be addressed by running the script colors.gs:

> run colors

Now you have color numbers 20-99 available to you, where the 20's have light blue (20) deepening to dark blue (29), the 30's have light green (30) deepening to dark green (39), etc. To get an indication of what this looks like, run a script I wrote called showcol.gs (you'll need to open the gpcp96 control file as file #1 in portrait mode for this to work)

> run showcol

If you have a color printer, you may want to print out the result for reference.

WARNING: the colors you see will vary in exact hue from terminal to terminal, from browser to browser, and from printer to printer. At times I've had to come up with three different color schemes depending on where or how the graphics will be viewed.


Saving and Printing Graphics or Files

Saving Data: After processing data you can save the result to a file which can be read by grads by issuing the following commands:

>set fwrite file.dat
>set gxout fwrite
>display var

Where 'file.dat' is the file you are saving to, and 'var' is the processed data (i.e. you previously did something like 'define var=prc+2').

Saving Graphics: Let's say you have produced a graph with a color scheme you like, a title, some labels, etc. and you want to save it for later. You can save graphics to a form which can be viewed later in UNIX by issuing the following GrADS commands:

>enable print file.gmf
>print

Where the 'gmf' file extension is recommended.

Viewing: To view the graphics later, issue the following command at the UNIX prompt (must be in a halo machine):

% gxtran             input: file.gmf

You'll have to hit the "enter" key to view the result.

Printing: you'll need to convert a gmf file to a postscript ps file. This must be done at the UNIX prompt by doing the following (in a holo machine):

	% gxps -c -i file.gmf  -o file.ps

Where as prompted you have entered the name of your gmf file and the desired name of your postscript file. The extension 'ps' is mandatory. You may now send the file 'file.ps' to the printer:

% lp file.ps

GIF Files: convert a .gmf file to a .gif file using the command (in a holo machine):

% gxpng -gif -i file.gmf -o file.gif

You may want to use the switch '-r' ('reverse') to make the background white.


Scripting

Any commands you entered in interactive mode could also be written out beforehand (using any UNIX text editor) and saved in a file called a 'script', using the form "file.gs". The "gs" extension in mandatory for it to be recognized. The short file below is an example:

		*my first grads script!
		'open gpcp96.ctl'
		'd p'
		'draw title Pretty Map'
		'enable print first.gmf'
		'print'
		pull pause
		'quit'

Type this in and save it as "first.gs". Check to make sure the permissions allow you to read and execute it.

Notice that the interactive commands (referred to as "grid commands") must be in quotes, as though you are writing a conversation. This is to distinquish them from other script commands such as "pull pause" (which causes the computer to wait until you enter a carriage return). Comments are preceded by an asterisk.

Enter GrADS and run this script by typing: > run first

You'll see that it will do everything you ask, and then quit when you hit enter. The "'quit'" and "pull pause" commands are included only for demonstration and are not essential.

GrADS has many of the features of other programming languages: loops, decision structures, string assignments and variable arrays. These operate very much like BASIC, so rather than discuss them in detail, some sample scripts are presented with commentary about the features they demonstrate.


Sample Scripts

These simple scripts were designed to create maps and charts displayed on the GPCP webpage. The data used in the interactive session was only a fraction of this data, so don't expect these scripts to operate with it alone! The quotes indicate commands that could be issued interactively. Commands that cannot be issued interactively are not surrounded in quotes.

Yearavg.gs - this is an example of a script using only grid commands. It averages all data over the time period given. There are some variable string substitutions in the modifications box: note that since these are not grid variables, you must drop these variables out of quotations when using them in a command.

Years.gs - calculates the annual average for each year and labels it as such. Note the use of a loop to label each year individually, and how GrADS has no problem treating the variable 'y' as both a number and a string for use in labelling the year number.

Monavg.gs - averages each month of the year (Jan, Feb, etc.) with the same months from all years to create a monthly climatology. Each month is labelled and stored as a gmf file. Note how a variable array can be used to store the names of the months.


Features not Discussed