GrADS for GrADS for BeginnersBeginners

Bob KuligowskiBob Kuligowski

NOAA/NESDIS/STARNOAA/NESDIS/STARMay 28, 2009May 28, 2009

OutlineOutline What is GrADS and how do I get it?What is GrADS and how do I get it? GrADS essentialsGrADS essentials

Getting startedGetting started Gridded data setsGridded data sets Displaying dataDisplaying data Script languageScript language Saving your plotsSaving your plots

GrADS-related resourcesGrADS-related resources

What is GrADS?What is GrADS? GrGrid id AAnalysis and nalysis and DDisplay isplay SSystemystem Developed at the Center for Ocean-Developed at the Center for Ocean-

Land-Atmosphere Studies (COLA)Land-Atmosphere Studies (COLA) Used for displaying and Used for displaying and

manipulating earth science datamanipulating earth science data Binary, GRIB, NetCDF, HDF-SDSBinary, GRIB, NetCDF, HDF-SDS Station data (contours / grid boxes) and Station data (contours / grid boxes) and

gridded datagridded data Line and bar graphs, scatter plots, Line and bar graphs, scatter plots,

streamlines, wind vectorsstreamlines, wind vectors

How do I Get GrADS?How do I Get GrADS? GrADS home page with FREE GrADS home page with FREE

downloads: downloads: http://http://www.iges.orgwww.iges.org/grads//grads/ Latest version (GrADS 2.0.a5) runs onLatest version (GrADS 2.0.a5) runs on

LinuxLinux Mac OS XMac OS X

Older versions available forOlder versions available for SUN, SGI/IRIX, DEC, IBM/AIXSUN, SGI/IRIX, DEC, IBM/AIX

Installation details are left to the user Installation details are left to the user and /or friendly neighborhood and /or friendly neighborhood sysadminsysadmin

GrADS Essentials: Getting GrADS Essentials: Getting StartedStarted Type Type gradsgrads (there are a (there are a

bunch of arguments bunch of arguments you can use, but we you can use, but we won’t get into them won’t get into them here)here)

You will be prompted You will be prompted for landscape mode; for landscape mode; ‘no’ will get portrait ‘no’ will get portrait mode (shown)mode (shown)

Your work areas will Your work areas will consist of a display consist of a display screen and the window screen and the window where you executed where you executed GrADs, which is where GrADs, which is where you type your you type your commandscommands (note: all examples are (note: all examples are

from the Linux version; I from the Linux version; I can’t vouch for the can’t vouch for the others)others)

To exit, type To exit, type quitquit

Gridded Data Sets: File Gridded Data Sets: File SpecsSpecs GrADS descriptor files (*.ctl) contain the basic GrADS descriptor files (*.ctl) contain the basic

information on a data file:information on a data file:dset ^model.grbdset ^model.grbtitle "Sample Model Data for GrADS Tutorial“title "Sample Model Data for GrADS Tutorial“undef 1e+20undef 1e+20dtype gribdtype gribindex ^model.gmpindex ^model.gmpxdef 72 linear 0.000000 5.000000xdef 72 linear 0.000000 5.000000ydef 46 linear -90.000000 4.000000ydef 46 linear -90.000000 4.000000zdef 7 levels 1000 850 700 500 300 200 100zdef 7 levels 1000 850 700 500 300 200 100tdef 5 linear 0Z2jan1987 1dytdef 5 linear 0Z2jan1987 1dyvars 8vars 8ps 0 1, 1, 0, 0 Surface pressure [hPa]ps 0 1, 1, 0, 0 Surface pressure [hPa]u 7 33,100 Eastward wind [m/s]u 7 33,100 Eastward wind [m/s]v 7 34,100 Northward wind [m/s]v 7 34,100 Northward wind [m/s]z 7 7,100 Geopotential height [m]z 7 7,100 Geopotential height [m]t 7 11,100 Air Temperature [K]t 7 11,100 Air Temperature [K]q 7 51,100 Specific humidity [kg/kg]q 7 51,100 Specific humidity [kg/kg]ts 0 11,105, 2 Surface (2m) air temperature [K]ts 0 11,105, 2 Surface (2m) air temperature [K]p 0 59, 1, 0, 0 Total precipitation rate [kg/(m^2*s)]p 0 59, 1, 0, 0 Total precipitation rate [kg/(m^2*s)]endvars endvars

File name (^ means current directory)

Description

“Undefined” (i.e., ignored) value

Data type

grib and grib2 formats require an index file with additional information (can greate using gribmap or grib2map in GrADS)

Gridded Data Sets: Grid Gridded Data Sets: Grid SpecsSpecs GrADS descriptor files (*.ctl) contain the basic GrADS descriptor files (*.ctl) contain the basic

information on a data file:information on a data file:dset ^model.grbdset ^model.grbtitle "Sample Model Data for GrADS Tutorial“title "Sample Model Data for GrADS Tutorial“undef 1e+20undef 1e+20dtype gribdtype gribindex ^model.gmpindex ^model.gmpxdef 72 linear 0.000000 5.000000xdef 72 linear 0.000000 5.000000ydef 46 linear -90.000000 4.000000ydef 46 linear -90.000000 4.000000zdef 7 levels 1000 850 700 500 300 200 100zdef 7 levels 1000 850 700 500 300 200 100tdef 5 linear 0Z2jan1987 1dytdef 5 linear 0Z2jan1987 1dyvars 8vars 8ps 0 1, 1, 0, 0 Surface pressure [hPa]ps 0 1, 1, 0, 0 Surface pressure [hPa]u 7 33,100 Eastward wind [m/s]u 7 33,100 Eastward wind [m/s]v 7 34,100 Northward wind [m/s]v 7 34,100 Northward wind [m/s]z 7 7,100 Geopotential height [m]z 7 7,100 Geopotential height [m]t 7 11,100 Air Temperature [K]t 7 11,100 Air Temperature [K]q 7 51,100 Specific humidity [kg/kg]q 7 51,100 Specific humidity [kg/kg]ts 0 11,105, 2 Surface (2m) air temperature [K]ts 0 11,105, 2 Surface (2m) air temperature [K]p 0 59, 1, 0, 0 Total precipitation rate [kg/(m^2*s)]p 0 59, 1, 0, 0 Total precipitation rate [kg/(m^2*s)]endvars endvars

Zonal and meridional grid specs: number of grid boxes, increment type, minimum, resolution

Vertical grid: number of levels, increment type, pressure levels

Time grid: number of time periods, increment type, minimum, resolution

Gridded Data Sets: Data Gridded Data Sets: Data SpecsSpecs GrADS descriptor files (*.ctl) contain the basic GrADS descriptor files (*.ctl) contain the basic

information on a data file:information on a data file:dset ^model.grbdset ^model.grbtitle "Sample Model Data for GrADS Tutorial“title "Sample Model Data for GrADS Tutorial“undef 1e+20undef 1e+20dtype gribdtype gribindex ^model.gmpindex ^model.gmpxdef 72 linear 0.000000 5.000000xdef 72 linear 0.000000 5.000000ydef 46 linear -90.000000 4.000000ydef 46 linear -90.000000 4.000000zdef 7 levels 1000 850 700 500 300 200 100zdef 7 levels 1000 850 700 500 300 200 100tdef 5 linear 0Z2jan1987 1dytdef 5 linear 0Z2jan1987 1dyvars 8vars 8ps 0 1, 1, 0, 0 Surface pressure [hPa]ps 0 1, 1, 0, 0 Surface pressure [hPa]u 7 33,100 Eastward wind [m/s]u 7 33,100 Eastward wind [m/s]v 7 34,100 Northward wind [m/s]v 7 34,100 Northward wind [m/s]z 7 7,100 Geopotential height [m]z 7 7,100 Geopotential height [m]t 7 11,100 Air Temperature [K]t 7 11,100 Air Temperature [K]q 7 51,100 Specific humidity [kg/kg]q 7 51,100 Specific humidity [kg/kg]ts 0 11,105, 2 Surface (2m) air temperature [K]ts 0 11,105, 2 Surface (2m) air temperature [K]p 0 59, 1, 0, 0 Total precipitation rate [kg/(m^2*s)]p 0 59, 1, 0, 0 Total precipitation rate [kg/(m^2*s)]endvarsendvars

Number of variables in fileList of variables: name

used by GrADS, number of vertical levels, units (used only for grib; use 99 otherwise), description

End of variable listing

Displaying Data: Default Displaying Data: Default DisplayDisplay

From the control file on the previous From the control file on the previous slides, a default display can be slides, a default display can be created using simply :created using simply :

> open model.ctl> open model.ctl

> d ps> d ps

Open the GrADS control file

Plot the pressure (‘ps’) field

We can also modify the area of interest:We can also modify the area of interest:> clear> clear

> set lon -180 0> set lon -180 0

> set lat 40> set lat 40

> set lev 500> set lev 500

> set t 1> set t 1

> d z> d z

Displaying Data: Cross Displaying Data: Cross SectionSection

Clear the display

Plot the height (‘z’) field

Subset lon.=180 W to 0 W, lat.=40 N, 500 hPa, time=1

We can also display multiple variables We can also display multiple variables on a field:on a field:

> clear> clear

> set lon -90> set lon -90

> set lat -90 90> set lat -90 90

> set lev 1000 100> set lev 1000 100

> set t 1> set t 1

> d t> d t

> d u> d u

Displaying Data: Displaying Data: Multivariate Cross SectionMultivariate Cross Section

Plot the temperature (‘t’) field followed by the height (‘u’) field

Subset lon.=90 W, lat.=90 S to 90 N, height=1000-100 hPa, time=1

GrADS can produce numerous types of file GrADS can produce numerous types of file displays using gridded data using displays using gridded data using set set gxoutgxout::

Displaying Data: Graphics Displaying Data: Graphics TypesTypes

barbar (bar chart)(bar chart) lineline (line graph)(line graph)

barbbarb (wind barbs)(wind barbs) linefilllinefill (color fill (color fill between two between two lines)lines)

contourcontour (contour plot)(contour plot) scatterscatter (scatter plot)(scatter plot)

errbarerrbar (error bars)(error bars) shadedshaded (shaded contour (shaded contour plot)plot)

grfillgrfill (shaded grid (shaded grid boxes)boxes)

streamstream (wind (wind streamlines)streamlines)

fgridfgrid (grid boxes (grid boxes shaded for shaded for specified values)specified values)

vectorvector (wind vector (wind vector arrows)arrows)

gridgrid (grid boxes with (grid boxes with printed values)printed values)

Example of plotting wind vectors:Example of plotting wind vectors:> clear> clear

> set gxout vector> set gxout vector

> d u;v> d u;v

Displaying Data: Wind Displaying Data: Wind VectorsVectors

Plot both zonal (‘u’) and meridional (‘v’) components of wind

Graphics output type=vector

Example of plotting actual grid point Example of plotting actual grid point values:values:

> clear> clear

> set gxout grid> set gxout grid

> d u> d u

Displaying Data: Grid Displaying Data: Grid ValuesValues

Graphics output type=grid

We can also display the data in other We can also display the data in other projections using the projections using the set mprojset mproj command: command:

Default isDefault is latlon latlon set mproj offset mproj off turns off the map projection turns off the map projection

Displaying Data: Other Displaying Data: Other ProjectionsProjections

latlonlatlon (lat/lon—(lat/lon—maintains aspect maintains aspect ratio)ratio)

lambertlambert (Lambert (Lambert conformal conic)conformal conic)

scaledscaled (lat/lon—does not (lat/lon—does not maintain aspect maintain aspect ratio)ratio)

mollweidemollweide (Mollweide)(Mollweide)

npsnps (North polar (North polar stereographic)stereographic)

orthogrorthogr (Orthographic)(Orthographic)

spssps (South polar (South polar stereographic)stereographic)

robinsonrobinson (Robinson—(Robinson—requires set lon -requires set lon -180 180 and set 180 180 and set lat -90 90)lat -90 90)

Example of plotting in polar stereo:Example of plotting in polar stereo:> clear> clear> Set lon -140 -40> Set lon -140 -40> Set lat 15 80> Set lat 15 80> set mpvals -120 -75 25 65> set mpvals -120 -75 25 65> set mproj nps> set mproj nps> set gxout contour> set gxout contour> set cint 30> set cint 30> d z> d z

Displaying Data: Other Displaying Data: Other ProjectionsProjections

Reference values (Polar Stereographic only): plots 120 to 75 W and 25 to 65 N

Contour interval=30

The script language has all the basics you The script language has all the basics you would expect from a programming language:would expect from a programming language: VariablesVariables AssignmentsAssignments OperatorsOperators FunctionsFunctions File input / OutputFile input / Output Screen input / OutputScreen input / Output If-then structuresIf-then structures LoopsLoops CommentsComments

Note that multiple GrADS commands can be Note that multiple GrADS commands can be placed on the same line if separated by a placed on the same line if separated by a semicolon.semicolon.

GrADS Script LanguageGrADS Script Language

Script variables are always treated like Script variables are always treated like strings but can be operated on like numbersstrings but can be operated on like numbers Arithmetic operations are done in floating point Arithmetic operations are done in floating point

but are expressed as integers if the result is but are expressed as integers if the result is integralintegral

Variable names can be 1-8 characters longVariable names can be 1-8 characters long Alphanumeric characters ONLYAlphanumeric characters ONLY Must start with a letterMust start with a letter Case sensitiveCase sensitive

No variable declaration statementsNo variable declaration statements GrADS allows for arrays using the syntax GrADS allows for arrays using the syntax varname.i.j varname.i.j (e.g., for a 2-D array), where (e.g., for a 2-D array), where ii and and jj must be integers. must be integers.

GrADS Script Language: GrADS Script Language: VariablesVariables

It’s as easy as: It’s as easy as: variablevariable==expressionexpression Where expression can be a number, variable, Where expression can be a number, variable,

or a combination of both with appropriate or a combination of both with appropriate operatorsoperators

GrADS Script Language: GrADS Script Language: AssignmentsAssignments

GrADS uses most standard operators:GrADS uses most standard operators:

Operations follow a fairly standard Operations follow a fairly standard precedence level, and parentheses are precedence level, and parentheses are available when in doubt…available when in doubt…

GrADS Script Language: GrADS Script Language: OperatorsOperators

|| (logical OR)(logical OR) << (less than)(less than)

&& (logical AND)(logical AND) <=<= (less than or equal)(less than or equal)

!! (unary NOT)(unary NOT) %% (concatenation)(concatenation)

-- (unary minus)(unary minus) ++ (addition)(addition)

== (equal)(equal) -- (subtraction)(subtraction)

!=!= (not equal)(not equal) ** (multiplication)(multiplication)

>> (greater than)(greater than) // (division)(division)

>=>= (greater than or equal)(greater than or equal)

GrADS has a number of useful intrinsic GrADS has a number of useful intrinsic functions, but you can also make your own functions, but you can also make your own (though they have to be part of the script (though they have to be part of the script at this time—no at this time—no includeinclude statements) statements) strlenstrlen((stringstring)) returns string length returns string length sublinsublin((string,nstring,n)) returns line n from a multi- returns line n from a multi-

line stringline string subwrdsubwrd((string,nstring,n)) returns the nth word from returns the nth word from

a stringa string substrsubstr((string,start,lengthstring,start,length)) returns a sub- returns a sub-

string of length length starting at character string of length length starting at character startstart

GrADS Script Language: GrADS Script Language: FunctionsFunctions

GrADS can read and write to ASCII files:GrADS can read and write to ASCII files: variablevariable==readread((filenamefilename)) reads a file reads a file

Resulting string contains two lines (use Resulting string contains two lines (use var2var2==sublin(sublin(variable,nvariable,n)) to separate): to separate):

First line (n=1) is return code (0=OK)First line (n=1) is return code (0=OK) Second line (n=2) is record read from fileSecond line (n=2) is record read from file

retcoderetcode==writewrite((filenamefilename,, record record, <, <append>) variableappend>) variable writes to a filewrites to a file

First use opens the file in write mode—will destroy an First use opens the file in write mode—will destroy an existing file if existing file if appendappend argument not included! argument not included!

retcoderetcode==closeclose((filenamefilename)) closes or rewinds a file closes or rewinds a file The The retcoderetcode is a return code that GrADS gives when is a return code that GrADS gives when

a file is written to or closed. As with a file is written to or closed. As with readread, the first , the first line (line (sublinsublin) is 0 if it wrote / closed successfully.) is 0 if it wrote / closed successfully.

Note that there is no Note that there is no openopen statement in GrADS; a file statement in GrADS; a file is opened when the first is opened when the first readread or or writewrite occurs. occurs.

GrADS Script Language: GrADS Script Language: File I/OFile I/O

If you want to save your data in standard If you want to save your data in standard GrADS format (real*4 binary, bottom to GrADS format (real*4 binary, bottom to top, left to right), you can do that using top, left to right), you can do that using fwritefwrite fnamefname with the following options: with the following options:

Note: GrADS 2..0.a5 and after can also Note: GrADS 2..0.a5 and after can also produce GeoTIFF and TIFF with KML produce GeoTIFF and TIFF with KML reference files (i.e., for Google Earth)—reference files (i.e., for Google Earth)—see documentation for details.see documentation for details.

Advanced File I/OAdvanced File I/O

-be-be (big Endian)(big Endian) oror -le-le (little Endian)(little Endian)

-sq-sq (sequential (sequential format)format)

oror -se-se (stream format)(stream format)

-ap-ap (append to (append to existing file)existing file)

oror -cl-cl (clobber existing (clobber existing file)file)

Screen output is handled by one of two Screen output is handled by one of two commands:commands: say say expressionexpression prompt prompt expressionexpression

Both are written to the terminal; prompt Both are written to the terminal; prompt does not put a carriage return after does not put a carriage return after expressionexpression

User input is handled byUser input is handled by pullpull variablevariable

Execution is paused until user input (with Execution is paused until user input (with a carriage return) occurs, and the input is a carriage return) occurs, and the input is assigned to assigned to variablevariable

GrADS Script Language: GrADS Script Language: Screen I/OScreen I/O

GrADS uses a basic IF/ELSE/ENDIF GrADS uses a basic IF/ELSE/ENDIF constructconstruct ifif (expression) (expression) is is notnot accompanied by accompanied by thenthen elseelse cannot have additional conditions (i.e., cannot have additional conditions (i.e.,

no no else ifelse if)) endifendif is the end of the block is the end of the block

GrADS Script Language: If-GrADS Script Language: If-Then StructuresThen Structures

Loops are handled by the Loops are handled by the whilewhile / / endwhileendwhile combination combination while while ((expressionexpression)) uses uses expressionexpression as the as the

condition for the loop to be executedcondition for the loop to be executed endwhile endwhile expressionexpression marks the end of the marks the end of the

looploop Since a counter is not part of the Since a counter is not part of the whilewhile

expression, you will need to include a expression, you will need to include a counter in the counter in the whilewhile loop loop

GrADS Script Language: GrADS Script Language: LoopsLoops

An asterisk (*) at the beginning of a line An asterisk (*) at the beginning of a line indicates a comment.indicates a comment.

If you want to comment the end of a line, If you want to comment the end of a line, use a semicolon followed by an asterisk.use a semicolon followed by an asterisk.

GrADS Script Language: GrADS Script Language: CommentsComments

GrADS graphic output can be written to GrADS graphic output can be written to GrADS metafiles (.gmf) by using the following GrADS metafiles (.gmf) by using the following commands before any display commands:commands before any display commands: ‘‘enable printenable print file.gmf’ file.gmf’ (opens the .gmf file)(opens the .gmf file)

And the following commands after any And the following commands after any display commands:display commands: ‘‘printprint’’ (performs the actual dump to the .gmf (performs the actual dump to the .gmf

file)file) ‘‘disable printdisable print’’ (closes the .gmf file)(closes the .gmf file)

You can view the files outside GrADS usingYou can view the files outside GrADS using gxtran –i gxtran –i fname fname (but for reasons I don’t (but for reasons I don’t

understand, this just opens the window. You need understand, this just opens the window. You need to hit to hit <Enter><Enter> to put up the display; hitting to put up the display; hitting <Enter><Enter> again exits.) again exits.)

Saving Your PlotsSaving Your Plots

GrADS supports several commands (run GrADS supports several commands (run outside GrADS) to convert the .gmf file to outside GrADS) to convert the .gmf file to other formats:other formats: gxps –i gxps –i fnamefname.gmf –o .gmf –o fnamefname.ps.ps

(PostScript)(PostScript) gxepsgxeps –i –i fnamefname.gmf –o .gmf –o fnamefname.eps.eps

(Encapsulated PostScript)(Encapsulated PostScript) gxpnggxpng –i –i fnamefname.gmf –o .gmf –o fnamefname.png.png (.png (.png

format, but can also create a .gif using the format, but can also create a .gif using the ––gifgif option) option)

Saving Your PlotsSaving Your Plots

The GrADS Documentation Page is a great The GrADS Documentation Page is a great resource:resource:

http://www.iges.org/grads/gadoc/http://www.iges.org/grads/gadoc/ Especially useful are the quick references Especially useful are the quick references

cards for GrADS commands and the cards for GrADS commands and the scripting language at the bottom of the scripting language at the bottom of the page!page!

You can also subscribe to the GrADS You can also subscribe to the GrADS Users Group (more info at Users Group (more info at http://http://www.iges.org/grads/users.htmlwww.iges.org/grads/users.html))

GrADS-Related GrADS-Related ResourcesResources

Questions?Questions?