Tutorial: Basics of Scripting

This tutorial is short and focuses on the very basics of GrADS scripting.  It is the goal of this tutorial to provide a little background on scripting and to help the budding GrADS user avoid various (and frustrating) syntax pitfalls often encountered while scripting with GrADS.

Why Script?  Easy; because it's annoying to keep typing the same commands over and over in the console. Scripting allows you to place all of your commands in one file, and then execute a number of GrADS commands in sequence with a single command.  Additionally, scripting allows you to further extend the capability of the GrADS software; for example you can use tools such as mathematical functions, conditional statements and loops within a script, whereas you cannot use these tools using the command line.  There are however a few important syntax issues that differ when using scripting vs. using the command console.

How to start a new GrADS script:  It is straightforward to start a new GrADS script.  All you need to do is open up a text file and start adding various GrADS commands to it, in the order that you wish to execute the commands.  When you want to run the script, simply save it with the suffix ".gs", If you are using Windows, be sure to change the "save as" option from ".txt" to "all files", and use the ".gs" suffix.  To run the script in GrADS, open GrADS, and type in the name of the script (be sure to include the path if it is in a different directory than the one you are running GrADS out of).

Scripting Basics: How to avoid syntax errors when writing your GrADS Script:  The following list is designed to help you learn some of the basic syntax involved in using GrADS commands within a script.  Because scripting allows you to use functions, and variables that fall outside of the basic GrADS command structure, you must be able to distinguish GrADS commands within your script.  Below is a list of several syntax quirks and methods used in the GrADS scripting format.

• GrADS commands must be inside single quotes (')
• Variables must be outside of the single quotes
• NO indentations are allowed, avoid the TAB button keep at all costs
• Lines can be commented out using the astrix  (*)
• Note: When commenting the * must be on the farthest left column of your text

• Semi-colons (;) can be used in place of a new line
• The results of queries are put into the default variable 'result'
• Concatenating (adding) strings is easy, just type them in sequence
• e.g., str1='Hello' and str2='World': str1' 'str2 outputs as 'Hello World'

• Mathematical operations involving control file variables occur inside single quotes (')
• For example, converting Temperature in C to F would look like 'temp_f=(tmp_c-32)*5/9'
• Mathematical operations involving variables not within the control file occur outside of single quotes (')
• Built in math functions on control file variables are inside single quotes
• For example, 'cosZ=cos(Z)'
• Built in math functions on variables not within the control file occur outside single quotes and usually require the prefix "math_"
• For example, cozZ=math_cos(Z)

Example Scripts:
(Note: the file dates within the example scripts may need to be changed to be more recent for these scripts to work)

To run the following examples, copy paste the text into a file and save it with the suffix ".gs".  Then simply type the name of the script in the GrADS console.

• Query file dimensions and output date/time for the May 2, 2013 00z GFS

          'sdfopen http://nomads.ncep.noaa.gov:9090/dods/gfs_hd/gfs_hd20130502/gfs_hd_00z' 
          'q dims'
          say result ;* Say command prints to console
         timestring=sublin(result,5) ;*5th line of the result
         date=subwrd(timestring, 6) ;*6th word of the time string
         say 'Date: 'date  ;* Note the string concatenation here

         The following output from this script will appear on the console:

          Default file number is: 1
          X is varying   Lon = 0 to 360   X = 1 to 721
          Y is varying   Lat = -90 to 90   Y = 1 to 361
         Z is fixed     Lev = 1000  Z = 1
         T is fixed     Time = 00Z02MAY2013  T = 1
         E is fixed     Ens = 1  E = 1

        Date: 00Z02MAY2013

 Download this script

• Prompt user for a variable to plot and plot variable

        'sdfopen http://nomads.ncep.noaa.gov:9090/dods/gfs_hd/gfs_hd20130502/gfs_hd_00z' 

        say 'Please Enter a Variable to Plot: (1=CAPE, 2=PRECIPITABLE WATER, 3=CLOUD COVER)'

        check=1
        while(check=1)
         pull var       ;*Pull command prompts user to enter a variable
          if(var !=1 & var !=2 & var!=3);check=1; say 'Not an acceptable choice, please choose again';else
            if(var=1);plot='capesfc';endif
            if(var=2);plot='pwatclm';endif
            if(var=3);plot='tcdcclm';endif
            say 'Plotting Variable: 'plot
            check=0
          endif
        endwhile
        'set gxout shaded'
        'd 'plot
        'draw title 'plot
       'printim img_test.png'    ;*printim command

Download this script 
      
     The preceding script will prompt the user for a variable and output an image similar to the one here (depending on what variable you choose):

  

Output image from example 2

Hopefully these example use enough of the basic scripting functions to give you an idea of how to use them.  You can see the use of the semi-colon in place of new lines to save space in the scripts, the use of the astrix to denote comments and the use of the say/pull commands.  Scripting can be kind of tricky to get a handle of at first, but it's a skill that comes with practice.  Good Luck!

This post was updated on March 13th 2014.