ĵ > UsingtheGridAnalysis

UsingtheGridAnalysis


 
 

         Using the Grid Analysis and Display System

                           (GrADS) 
 

                        Brian E. Doty 

        Center for Ocean-Land-Atmosphere Interactions

                  Department of Meteorology

                    University of Maryland 

                      (doty@cola.umd.edu)

                         (301)405-5356 

                          July 5, 1992   
 
 

    Release Notes:  Version 1.3.1 

      Please note the following bug fixes: 

      The new version of GrADS has a slight change to the 'ave' and

      'aave' functions.  In previous versions, these functions did an

      areal weighting when averaging over latitude.  The weights were

      calculated using the cosine of the latitude of the center of

      the grid box.  It has been pointed out that a more correct

      weighting is to use the delta of the sin of the latitudes at

      the edges of the grid box.  This is now the weighting technique

      used in these functions.  You should not notice any change to the

      result values unless you are doing averages over small regions

      near the poles.   

      An error has been fixed in the countouring algorithm.

      In some special cases, the contour line for the maximum

      contour level was not plotted.  This was due to an error in

      handling round-off accumulations.  You may want to redo any

      plots where this error would be important, to verify whether

      the error occurred on your plots.  It does not appear that

      this error occurred very often.  
 

      Highlights of what is new: 

          - Scripting language 

          - Define command   

          - Axis orientation control (set xyrev, set xflip, set yflip) 

          - Rainbow color control (set rbcols, set rbrange) 

          - New graphics output types (wx symbols, streamlines) 

          - Log axis for Z dimension 

          - Greyscale option for monochrome monitors 

     

    0.0  Problems and Suggestions and Documentation 

       I am always interested in hearing from users on what they

       like or don't like about GrADS, and am always looking for

       ways to improve the product.   

       I am especially interested in hearing about any problems you

       may have; I always try to fix any bugs I find out about within

       a day.   

       We are working on a well formatted, easier to read printed

       documentation for GrADS.  If you would like us to send you

       a copy when it is completed (expected to be August, 1992),

       send me your name and postal address, and I will put you on

       the mailing list for that document.  

       Send comments, suggestions, bug reports, or requests for

       documentation to: 

          doty@cola.umd.edu.

            
 

    1.0  Topics 

       Starting GrADS             Functions   

       Opening files              Defined variables 

       Dimension Environment      Graphics Options 

       Display command            Page Control 

       Animation                  Graphics Primitives 

       Graphics Output Types      Station Data Sets 

       GrADS Data Sets            EXEC Command 

       Variable Names             Hardcopy Output 

       Expressions                Scripting Language 

      

       Appendix A: GrADS Data Sets 

       Appendix B: Scripting Language Reference 
 
 

    2.0  Starting GrADS 

     GrADS is started by entering the command: grads 

     Before initializing the graphics output environment, GrADS

     will prompt for landscape or portrait mode.  Landscape is

     11 x 8.5 inches (usually what you want).  Portrait is 8.5 x 11

     inches, primarily used for producing vertically oriented hardcopy

     output.  The actual size of the window will not, of course,

     be 11 x 8.5 inches (or 8.5 x 11 inches), but instead will be

     whatever size you chose by using your workstation's window

     manager.  But GrADS will treat the window as if it were one of

     the above sizes, so it is best to size the window with

     approximately the proper aspect ratio. 

     After answering this prompt, a graphics output window will be

     opened.  You may move or resize this window at any time. 

     You will enter GrADS commands from the text window where you

     started GrADS from.  Graphics output will appear in the graphics

     window in response to the commands you enter.  You will thus need

     to make the text window the "active" window; the window that

     receives keyboard input. 
 
 

    3.0  Opening Files 

     You will need to open at least one file before you can enter

     other GrADS commands. 

     You open the data-descriptor file, not the raw data file

     (more on this later).  The command is: 

          open filename 

     You can open more than one file.  Each file is numbered in

     the order that you open it in.  Initially, the "default file"

     is file 1, or the first file you open.  The importance of the

     default file will be discussed later. 
 
 

    4.0  Dimension Environment 

     The data set is always viewed by GrADS as a generalized 4-D

     data set, even if it is in reality a subset of a 4-D data set. 

     The current dimension environment describes what part of the

     data set you want to work with.  Expressions are evaluated

     with respect to the dimension environment (which allows

     for simplicity in the expression syntax), and the final display

     will be determined by the dimension environment.  Thus, the

     dimension environment is a GrADS concept that is important to

     understand. 

     The dimension environment is set up by the user by entering

     one of the following set commands: 

         set lat|lon|lev|time val1 <val2> 

     This set command sets one dimension of the dimension environment

     using world coordinates.  Alternatively: 

         set x|y|z|t val1 <val2> 

     This sets one dimension of the dimension environment using

     grid coordinates.  You may use whatever coordinates are

     convenient to you.  Issuing "set lon" is equivalent to

     issuing "set x", both set the x dimension.  The difference is

     only the units you wish to enter the command in. 

     When you enter just one value, that dimension is said to be

     "fixed".  When you enter two values, that dimension is said

     to be "varying".  The combination of fixed and varying dimensions

     defines the dimension environment. 

     Examples: 

          set lon -180 0       (sets longitude to vary from 180W

                                 to 0).

          set lat 0 90         (sets latitude to vary from the

                                 equator to 90N)

          set lev 500          (sets the level to 500mb - a fixed

                                 dimension)

          set t 1              (sets time to the first time in the

                                 data set -- using grid coordinates

                                 in this case.  Time is now a fixed

                                 dimension). 

     When all dimensions are fixed, you are referring

     to a single data point. 

     When one dimension is varying, you are referring to

     a 1-D "slice" through the data set. 

     When two dimensions are varying, you are referring

     to a 2-D "slice" through the data set. 

     When 3 dimension vary, GrADS interprets this as

     a sequence of 2-D slices. 

     An important note:  When you enter dimensions in grid coordinates,

     they are always converted to world coordinates.  This conversion

     requires some knowledge of what scaling is in use for grid to

     world conversions.  The scaling that is used in all cases (except

     one) is the scaling of the DEFAULT FILE.  The exception is when

     you supply a dimension expression within a variable specification,

     which will be covered later. 
 
 

    5.0   The display Command 

     The display command is how you actually display data via the

     graphics output window.  The command is: 

         display expression 

     The simplest expression is a variable abbreviation. 

     If you display when all dimensions are fixed, you

     get a single value which is typed out. 

     If you display when one dimension varies, you get

     a 1-D line graph (by default). 

     If you display when two dimensions are varying,

     you get a 2-D contour plot (by default). 

     The groundwork has not yet been completely laid to

     describe this in more detail at this point. 

     GrADS will overlay the output from each display command.

     To clear the display, enter: 

         clear (or just c) 

     To leave GrADS, enter: 

         quit 
 
 

    6.0  Animation 

     If you display when 3 dimensions vary, you get

     an animation sequence.  You can animate through any

     of the three varying dimensions. 

     By default, the animation dimension is time.  You may set

     which dimension to animate through: 

           set loopdim x|y|z|t 

     If you wish to animate when fewer than three dimensions

     are varying (ie, animate a line graph), you can control

     animation by entering: 

           set looping on|off 

     Remember to turn looping off when you are done animating,

     or you will get suprised when you enter your next

     expression. 
 

    7.0  Graphics Output Types 

     By default, when one dimension varies, you get a line graph,

     and when two dimensions vary, you get a contour plot.  This

     default can be changed: 

       set gxout graphics_type 

       where graphics_type is one of: 

       contour:   Contour plot

       shaded:    Shaded contour plot

       grid:      Grid boxes with values

       vector:    Vector wind arrows

       stream:    Vector streamlines

       bar:       Bar chart

       line:      Line Graph

       fgrid:     Shaded grid boxes 

       For station data: 

       value:     Station values

       barb:      Wind barbs

       wxsym:     Wx symbols

       findstn:   Find nearest station  (see scripting language)

      

     There are many options that can be set that control how

     these grahpics types will be displayed.  This will be

     covered in more detail later. 

     For the graphics output types of vector, stream, and barb,

     the display routines need two result grids, where the 1st

     result grid is treated as the U component, and the 2nd result

     grid is treated as the V component.  To obtain two result grids,

     you enter two expressions on the display command seperated by

     a semicolon: 

       display u ; v

       display ave(u,t=1,t=10) ; ave(v,t=1,t=10) 

     For the types of vector and stream, you can specify a 3rd

     grid that will be used to colorize the vectors or streamlines: 

       display u;v;hcurl(u,v)

       display u;v;mag(u,v) 

     For a gxout of wxsym, each value at a station location is assumed

     to be a wx symbol code number.  If you wish to use wx symbols

     please contact me for a list of the symbols and their values.

     (doty @ cola.umd.edu). 
 
 

    8.0  GrADS Data Sets 

     The raw data is on disk in binary direct access format. 

     The data set is described by a data-descriptor file, which

     contains: 

       - Name of the binary data set.

       - Mapping between grid coordinates and world

         coordinates.

       - Number of variables, abbreviations for

         variables. 

     The data-descriptor file is free format, where each field

     is blank delimeted.  It can be created easily with a text

     editor. 

     The format of these files is described in detail in

     Appendix A.  For now, it is sifficient to note that the

     data descriptor file assigns a one to six character

     abbreviation for each variable in the file.  These

     abbreviations are used in GrADS expressions. 
 
 

    9.0  Variable Names 

     The complete specification for a variable name is: 

       abbrev.file#(dimexpr,dimexpr,...) 

       abbrev  is the abbreviation for the variable as

               specified in the data descriptor file 

       file#   is the file number that contains this

               variable.  The default initially is 1.

               ("set dfile" changes the default). 

       dimexpr is a dimension expression that locally

               modifies the current dimension

               environment. 

     A dimension expression is used to locally modify the

     dimension environment for that variable only.

     Only fixed dimensions can be thus modified. 

     An absolute dimension expression is: 

       X|Y|Z|T|LON|LAT|LEV|TIME = value 

     A relative dimension expression (relative to the

     current dimension environment): 

       X|Y|Z|T|LON|LAT|LEV|TIME +/- offset 

     Examples of variable specifications are: 

       z.3(lev=500)       File 3, absolute dimension expression 

       tv.1(time-12hr)    Relative dimension expression 

       rh                 Default file number is used 

       q.2(t-1,lev=850)   Two dimension expressions 

       z(t+0)             This does have uses.... 

     An important note:   When you enter a dimension in grid units,

     GrADS always converts it to world coordinates.  Usually this

     conversion is done using the scaling of the default file.

     However, when a grid coordinate is supplied within a dimension

     expression as part of a variable specification, the scaling for

     that file (ie, the file that variable is to be taken from) is

     used. 
 
 

    10.0  Expressions 

     A GrADS expression consists of operators, operands, and

     parentheses.  Parentheses are used the same as in FORTRAN

     to control the order of operation. 

     Operators are:   +   Addition

                      -   Subtraction

                      *   Multiplication

                      /   Division 

     Operands are:  Variable specifications, functions, and

                    constants. 

     Operations are done on equivalent grid points in each

     grid.  Missing data values in either grid give a result

     of a missing data value at that grid point.  Dividing

     by zero gives a result of a missing data value at that

     grid point. 

     Operations cannot be done between grids that have

     different scaling in their varying dimensions -- ie,

     grids that have different rules for converting the

     varying dimensions from grid space to world coordinate

     space.  This can only be encountered when you are attempting

     operations between grids from different files that have

     different scaling rules. 

     If one grid has more varying dimensions than

     the other, the grid with fewer varying dimensions

     is 'expanded' and the operation is performed. 

     Some examples of expressions: 

       z - z(t-1)              (Height change over time)

       t(lev=500)-t(lev=850)   (Temp change between 500 and 850)

       ave(z,t=1,t=5)          (Average of z over first 5 times in file)

       z - ave(z,lon=0,lon=360,-b)  (Remove zonal mean)

       tloop(aave(p,x=1,x=72,y=1,y=46))  (Time series of globally

                                          averaged precip -- assuming

                                          72x46 grid) 
 
 

    11.0  Functions 

     Functions are invoked by name, with their arguments

     separated by commas and enclosed in parentheses. 

     Expressions are typically one of the arguments supplied to

     a function.  Functions may be nested.  Some functions

     modify the dimension environment when they operate. 

     The list of available functions follows: 

       sin(expr)   - argument in radians 

       cos(expr) 

       tan(expr) 

       exp(expr)   - e**expr 

       log(expr)   - log base e 

       log10(expr) - log base 10 

       abs(expr)   - absolute value 

       pow(expr1, expr2)  -  expr1**expr2 

       mag(expr1,expr2) - sqrt(expr1*expr1+expr2*expr2) 

       hdivg(expr1,expr2) - horizontal divergence

             (center differenced) given the u component

             (expr1) and the v component (expr2).

             Note that calulating divergence this way

             can be numerically unstable.  Assumes constant

             pressure level.  Requires a horizontal

             dimension environment.  Assumes winds are

             in m/sec. 

       hcurl(expr1,expr2) - relative vorticity, given the

             u and v horizontal wind components (assumes

             winds are m/sec). 

       vint(expr1, expr2, top) - mass weighted vertical

             integral.  expr1 = surface pressure, and

             expr2 is the quantity to be vertically

             integrated.  top is a constant, and gives

             the top pressure level capping the

             integration.  This functions assumes the

             vertical pressure coordinate is mb.  This

             function requires a horizontal dimension

             environment. 

       maskout(expr1,expr2) - whenever a grid point in

             expr2 is negative, the coorsponding grid

             point in expr1 is set to missing.  This function

             is most useful when expr2 is a land/sea mask.

             One possible application is: 

             aave(maskout(p,mask),...)  to calculate the global

                 averaged precip. over land (or ocean) only. 

       ave(expr,dimexpr1,dimexpr2,<time increment>,<flag>) -

             generalized averaging function.  expr1

             is averaged through the dimension range

             specified by dimexpr1 and dimexpr2.

             The two dimension expressions must refer to

             the same dimension.  Averaging is done with

             appropriate weighting for non-linear grids.

             Latitude weighting is also done.  Missing

             data values do not participate -- the average

             is taken with fewer data points. 

             The flag, if provided, would be -b.  The averaging

             function weights each grid point equally,

             including the end points.  Thus, if one is calculating

             a zonal average by ave(z,lon=0,lon=360) the end point

             gets weighted twice (once at 0, once at 360).  To give

             the endpoint a half-weight (ie, average to the exact

             boundary only), use: ave(z,lon=0,lon=360,-b). 

             Note on ave function:  The dimension expressions

             are evaluated with respect to the dimension

             scaling of the default file. 

             Examples of the ave function: 

             ave(z,t=1,t=20)    - Average variable z through

                                  times 1 to 20.

             ave(t,x=1,x=72)    - Average variable t through

                                  x = 1 to 72.

             ave(q,t=1,t=60,12) - Average variable q through

                                  times 1 to 60 with an

                                  increment of 12

             ave(mag(u,v),t-1,t+1)    - Average mag(u,v) over

                                  3 times, relative to the

                                  current dimension environment 

       aave(expr,dimexpr1,dimexpr2,dimexpr3,dimexpr4) -

             does area average.  dimexpr1 and dimexpr2 must

             be for longitude or x, dimexpr3 and dimexpr4 must

             be for latitude or y.  Equivalent to nesting two

             ave functions, except when there are missing data

             values -- is thus more accurate than two nested

             ave functions, and also faster.  This function

             will not operate if z or t are varying dimensions,

             thus aave must be used in conjunction with tloop to

             perform time series averages. 

       tloop(expr)  -  evaluates the expr by locally fixing

             the time dimension.  tloop will loop through

             the varying time dimension, locally fix that

             dimension, and 'contstruct' the output grid by

             repeatedly evaluating the dimension at various

             fixed times. 

             Example:  Time series of global average 

                 set x 1            (We want a time series, so we

                 set y 1             fix x, y, z, and let t vary)

                 set lev 500

                 set t 1 100

                 display tloop(aave(p,lon=0,lon=360,lat=-90,lat=90)) 

             Example:  5 Year running mean 

                 display tloop(ave(stuff,t-2,t+2)) 
 

    12.0  Defined Variables 
 

      The define command allows you to interactively create a new variable.

      The syntax is: 

         define varname = expr 

      The new variable can then be used in subsequent expressions (it can

      be used in subsequent define and/or display commands).  The new

      variable is stored in memory, not on disk, so avoid defining

      variables over large dimension ranges. 

      The variable is defined to cover the dimension ranges in effect

      at the time the command is issued.  You may define a variable that

      has from 0 to 4 varying dimensions.  The define command is the only

      case within GrADS where four varying dimensions is valid.   

      When Z and/or T are varying dimensions, the define command

      evaluates the expression by stepping through Z and T.

      In other words, the expression is evaluated within a dimension

      environment that has fixed Z and T.  This will affect how you

      compose the expression.  

      When you use a defined variable, data is taken from the variable

      in a way similar to data taken from a GrADS data file.  For example,

      say you define a four dimensional variable: 

        set lon -180 0

        set lat 0 90

        set lev 1000 100

        set t 1 10

        define temp = rh 

      After issuing the define command, remember to change the dimension

      environment so less than 4 dimensions are varying!   

        set t 5

        set lev 500

        d temp 

      The display of the defined variable will display a 2-D slice taken

      at time 5 and level 500.   

      If you define a variable that has fixed dimensions, and then later

      access this variable, the fixed dimensions are treated as "wild

      cards".  The best way to show this is with an example: 

        set lon -180 0

        set lat 0 90

        set lev 500

        set t 10

        define zave = ave(z,t=1,t=30) 

      The defined variable has two varying dimensions.  If we now display

      this variable (or use it in an expression), the fixed dimensions

      of the defined variable, namely Z and T, will match ANY Z and T

      dimension setting: 

        set t 1

        set lev 200

        d zave 

      In the above display, the variable zave would be displayed as it

      was defined, ie you would get a time average of 500mb heights, even

      though the level is set to 850.   

      When the defined variable has varying dimensions, and you have a

      dimension environment where that dimension is fixed, the proper

      dimension will be retrieved from the variable: 

        set lon -180 0

        set lat 0 90

        set lev 500

        set t 10

        define temp = z

        set lat 40

        d temp

   

      In the above example, the defined variable has a varying Y dimension.

      We then fix the Y dimension to be 40N, and display a 1-D slice.

      The data from 40N in the defined grid will be accessed.  If you then

      did: 

        set lat -40

        d temp 

      The data from 40S would be accessed from the defined variable. 

      Since this is beyond the dimensions originally used when the

      variable was defined, the data would be set to missing. 

      You can also locally override the dimension environment: 

        d temp(lat=50) 

      If that dimension is a varying dimension within the defined variable.

      If the dimension is a fixed dimension for that variable, the

      local override will be ignored: 

        d temp(t=15) 

      In the above command, the defined variable temp has fixed T, so

      the t=15 would be ignored.   

      Note:  the define command currently supports only grids.  

 

      Once you have defined a grid variables, you may tell GrADS that

      the new variable is climatological, ie that you wish to treat

      the time dimension of the new variable in a wild card sense.   

      The command is:   

         modify varname <seasonal>

                        <diurnal> 

      where the varname is the name of the defined grid (the define

      command must have been previously used).  If the grid is described

      as seasonal, then it is assumed that the grid contains monthly

      (or multi-month) means.  Note that daily or multi-day means

      are not yet supported.  If diurnal is specified, it is assumed

      the defined variable contains means over some time period less than

      a day.   

      After describing the defined variable as climatological, then

      the date/times are treated appropriately when data is accessed

      from the defined variable.   

      An example.  The data set contains 10 years of monthly means: 

         set lon -180 180

         set lat -90 90

         set lev 500

         set t 1 12

         define zave = ave(z,t+0,t=120,1yr) 

      This define will set up a variable called zave which contains

      12 times, each time being the 10 year mean for that month.

      We are making use here of the fact that the define command

      loops through a varying time dimension when evaluating the

      expression, and within the ave function we are making use

      of the variable time offset of t+0, which uses a start time

      that is whatever time the define command is using as it

      loops. 

         modify zave seasonal

         set t 120

         d z - zave 

      The final display will remove the 10 year monthly mean for December

      from the last December in the data set.   
 
 

    13.0  Graphics Options 

     Graphics options control the way graphics output looks.

     Some options are valid for most graphics output types, some

     valid for only one. 

     Some of the options "stick" until changed.  Others

     stay the same until a clear command is issued, and

     yet others are reset to their defaults by either a

     clear command or a display command. 

     For graphics type = contour: 

         set ccolor color  - sets the contour color,

                             where color is specified as

                             a color number:

                             0 - black  5 - cyan

                             1 - white  6 - magenta

                             2 - red    7 - yellow

                             3 - green  8 - orange

                             4 - blue   15 - grey

                             Reset by clear or display 

                             You can also issue: 

                             set ccolor rainbow

 

                             to obtain the rainbow color sequence. 

         set cstyle style  - sets the contour linestyle.

                             Style numbers are:

                             1 - solid

                             2 - long dash

                             3 - short dash

                             5 - dots

                             Reset by clear or display 

         set cthick thckns - Sets the line thickness for

                             the contours given an integer in

                             the range of 1 to 10 representing

                             relative line thicknesses.

                             Thickness of 6 or more will be

                             thicker on the screen.

                             Primarily used for controlling

                             hardcopy output. 

         set cterp on|off  - Turns spline smoothing on

                             or off.  "Sticks" until reset. 

                             Shaded contours are drawn without

                             spline fitting, so to insure an

                             exact match when overlaying contour

                             lines and shaded contours of the

                             same field, specify cterp as off.

                             You can still use the 'csmooth'

                             option, which affects both contour

                             lines and shaded contours. 

         set clab on|off|forced   - Controls contour labeling.

                             "Sticks" until reset.         

                             on - indicates 'fast' contour

                                  labels.  Labels are plotted

                                  where the contour line is

                                  horizontal.

                             off - no contour labels

                             forced - an attempt is made to label

                                      all contour lines 

     For gxout = contour or shaded: 

         set cint value    - sets the contour interval

                             to the specified value.

                             Reset by a clear or display 

         set clevs lev1 lev2 ...  - Sets specified contour

                             levels.

                             Reset by clear or display 

         set ccols col1 col2 ...  - Sets specified color

                             for clev levels.

                             Reset by clear or display 

         (Note: Rainbow sequence is: 9, 14, 4, 11, 5, 13,

                             3, 10, 7, 12, 8, 2, 6 

         set csmooth on|off  - If on, the grid is

                             interpolated to a finer grid

                             using cubic interpolation

                             before contouring. "Sticks". 

                             Note:  this option will

                             result in contour values below

                             and above the min and max of the

                             un-interpolated grid.  This may

                             result in physically invalid

                             values such as in the case of

                             negative rainfall. 

         set cmin value    - Contours not drawn below this

                             value.  Reset by clear or

                             display. 

         set cmax value    - Contours not drawn above this

                             value.  Reset by clear or

                             display. 

         set black val1 val2  - Contours not drawn within

                             this interval.  Reset by

                             clear or display. 

     Options for contour, shaded, vector, stream: 

         set rbcols color1 color2 <color3> ...

                    <auto>

                             Specifies a new 'rainbow' color

                             sequence.  The color numbers may be

                             new colors defined via the 'set rgb'

                             command.  These colors replace the

                             default rainbow color sequence whenever

                             the rainbow color sequence is used. 

                             If you 'set rbcols auto' the built

                             in rainbow sequence is used.

                            

                             This 'sticks' until reset.  

         set rbrange low high - sets the range of values used to

                             determine which values acquire which

                             rainbow color.  By default, the low and

                             high are set to the min and max of

                             the result grid.  This is reset by a

                             clear command.  

     Options for line graphs (gxout = line): 

         set ccolor color  - Sets line color.

                             Reset by clear or display 

         set cstyle style  - Sets line style

                             Reset by clear or display 

         set cmark marker  - Sets line marker:

                             0 - none

                             1 - cross

                             2 - open circle

                             3 - closed circle

                             4 - open square

                             5 - closed square

                             Reset by clear or display 

         set axlim val1 val2 - Specifies the range of the

                             variable values for axis

                             scaling (usually the y axis).

                             Reset by clear only.

     For gxout = bar 

         set bargap val    - Sets the gap between bars in percent.

                             val should range from 0 to 100.  The

                             default is 0, or no gap.  A value of

                             100 gives a single vertical line for

                             each bar. 

         set barbase val|bottom|top  - If val is given, each bar

                             rises or falls from that value, assuming

                             the value is within the plotting range.

                             If bottom is specified, each bar rises

                             from the bottom of the plot.  If top is

                             specified, each bar falls from the top of

                             the plot. 

     For gxout = grid: 

         set dignum number - Number of digits after the

                             decimal place 

         set digsize size  - Size (in inches, or plotter

                             units) of the numbers.

                             0.1 to 0.15 is usually a good

                             range to use. 

                             Both of these options stay

                             the same until changed. 

     For gxout = vector: 

         set arrscl size <magnitude>  - Specifies arrow length

                             scaling.  Size is the length of the

                             arrow in plotting units (inches on

                             the virtual page).  A typical value

                             would be 0.5 to 1.0.  Magnitude is

                             the vector magnitude that will produce

                             an arrow of the specified size.

                             Other arrow lengths will be scaled

                             appropriately.  If magnitude is not

                             given, all the arrows will be the same

                             length. 

                             Reset by clear or display. 
 

     For gxout = fgrid: 

         set fgvals value color <value color> <value color> ...

                             The fgrid output type treats the

                             grid values as rounded integers,

                             and will shade a specified integer

                             valued grid with the specified color.

                             Unspecified values are not shaded.

                             "Sticks". 

     To control log scaling when the Z dimension is plotted on

     any plot: 

         set zlog on|off  -  Sets log scaling of the Z dimension

                             on or off.  Sticks until reset.  
 

     To control axis labeling for the next display

     command only: 

         set xaxis|yaxis start end <incr> - Specifies the

                             axis is to be labeled from

                             the specified start value to

                             the specified end value with

                             the specified increment.

                             Labels may have no relation

                             to data or dimensions. 

         set grid on|off <style> <color> - Draw or do not

                             draw grid lines using the

                             specified color and linestyle.

                             Default is to draw grid lines

                             with color 15 (grey) and with

                             linestyle 5 (dotted). 

     For annotation: 

       draw title string   - Draw title at top of graph.

                             Backslash within string

                             denotes new line. 

       draw xlab string    - Draws X axis label. 

       draw ylab string    - Draws Y axis label. 

       set annot color <thickness> - Sets color and line thicknesses

                                     for the above 3 draw commands.

                                     Default is white, thickness 6.

                                     This command also sets the color

                                     and thickness for the axis border,

                                     axis labels, and tickmarks. 

                                     Axis tickmarks and labels are

                                     plotted at the specified thickness

                                     minus 1.  

     To control axis orientation: 

       set xyrev on         - Reverses the axes on a plot.    

          Example: 

          By default for a Z, T plot, the time dimension is plotted

          horizontally, and the Z dimension is plotted vertically.

          By setting xyrev, the time dimension would be plotted

          vertically and the Z dimension would be plotted horizontally. 

       set xflip on         - flips the order of the horizontal

                              axis (whatever axis is horizontal after

                              xyrev is applied).  

       set yflip on         - flips the order of the vertical axis. 

       All the above axis orientation commands are reset by a 'clear'

       or 'set vpage' command.  
 

     For map projections: 

       set mproj proj  -- Sets current map projection.

                          Keywords are:

                          latlon - the default. Lat/lon

                                   projection with aspect

                                   ratio maintained.

                          scaled - latlon projection

                                   where aspect ratio is not

                                   maintained.  The plot fills

                                   the plotting area.

                          nps    - north polar stereographic

                          sps    - south polar stereographic

                          off    - same as scaled, but no map

                                   is drawn and axis lables are

                                   not interpreted as lat/lon

                                   labels. 

       set mpvals lonmin lonmax latmin latmax --

                          Sets reference longitudes and latitudes

                          for polar stereographic plots.  By default,

                          these are set to the current dimension

                          environment limits.  This command overrides

                          that, and allows the data-reference to

                          be decoupled with the map display.

                          The polar plot will be drawn such that

                          the region bounded by these longitudes and

                          latitudes will be entirely included in the

                          plot. 
 

     To select an alternate map data set: 

       set mpdset <lowres|mres|hires|nmap> - lowres is the default.

                          mres and hires have state and country

                          outlines.  nmap covers only North America. 

       set poli on|off    Selects whether you want political boundries

                          drawn for the mres or hires map data sets.

                          The default is on. 
 

     For console display control:  

       set display grey|greyscale|color  <black|white> --

                          Sets the mode of the display.  By default,

                          the mode is color, where shading and

                          contouring is done with a rainbow of

                          colors.  When using a monochrome display,

                          these colors may not map to greyscale in

                          a pleasing way.  When the mode is set to

                          greyscale, contours are displayed using a

                          single grey level, and shaded contours are

                          done using a sequence of greyscales.  

                          You may optionally set the hardware background

                          color to black or white.  The default is

                          black.   

                          Issuing:  set display grey white 

                          gives a result on the display that is very

                          similar to the output produced by gxps. 

                          This command DOES NOT affect hardcopy output. 
 
 
 

    14.0  Page Control 

     The number and size of plots can be controlled on the "real" page

     by defining one or more "virtual" pages.  The relevent command is: 

        set vpage xmin xmax ymin ymax 

     This command defines a "virtual page" that fits within the specified

     limits of the real page.  All graphics output will be drawn into this

     "virtual page" until another 'set vpage' command is entered.  A clear

     command clears the physical page (and any virtual pages drawn on it). 

     When GrADS is first started, it prompts for landscape or portrait

     mode.  This defines the size of the real page (11x8.5 or 8.5x11),

     and the dimensions for the virtual page must fit within this real

     page. 

     The 'set vpage' command will define virtual page limits in terms

     of inches (virtual page inches), which are the coordinates that will

     be used in the various commands that require inches to be used.

     The new page limits are printed when the 'set vpage' command

     completes. 

     To return to the default state where the real page equals the virtual

     page, enter: 

        set vpage off 

     To control the area within the virutal page that GrADS plots

     into, use: 

        set parea xmin xmax ymin ymax 

     The command specifies the area for plotting contour plots, maps, or

     line graphs.  This area does not include axis labels, titles, etc.,

     so if you need to see those, provide for an adequate margin. 

     The region is specified in terms of virtual page units.  By default,

     the virtual page is equal to the real page, so the units are

     approximately inches on the real page. 

     Maps are scaled to fit within the plotting area such that their correct

     aspect ratio is maintained.  Thus, the map will not fill the entire

     plotting area except under certain lat/lon ranges.  A line graph or

     a contour plot without a map will be scaled to fit entirely within the

     specified plotting area. 

     By default, an appropriate plotting area is chosen depending on the

     type of graphics output.  To return to this default, enter: 

       set parea off 

     It is not appropriate to use this command to put multiple plots on

     one page.  It is better to use the 'set vpage' command. 
 

    15.0  Graphics Primitives 

     Various commands are provided to allow control and display of

     various graphics primitives: 
 

     draw string x y string 

        Draws the character string at the x,y position.  x and y are

        given in inches on the virtual page.  The string is drawn using

        current string attributes -- set the "set string" and "set strsiz"

        commands. 

     draw line x1 y1 x2 y2 

        Draws a line from x1, y1 to x2, y2 using current line

        drawing attributes.  See the "set line" command. 

     draw rec xlo ylo xhi yhi 

        Draws an unfilled rectangle from xlo, ylo to xhi, ylo to xhi, yhi

        to xlo, yhi to xlo, ylo.  The rectangle is drawn using current line

        drawing attributes. 

     draw recf xlo ylo xhi yhi 

        Draws a filled rectangle in the area described by xlo, ylo, xhi,

        yhi.  The fill color is the current line drawing attribute color. 

     draw mark marktype x y size 

        Draws a marker of type marktype at position x, y at the requested

        size.  Marker types are: 

            1 - crosshair

            2 - open circle

            3 - closed circle

            4 - open square

            5 - closed square 

     set line color <style> <thickness> 

        Sets current line attributes.  Colors are: 

            0 - black      5 - cyan

            1 - white      6 - magenta

            2 - red        7 - yellow

            3 - green      8 - orange

            4 - blue      15 - grey 

        styles are: 

            1 - solid               5 - dotted

            2 - long dash           6 - dot dash

            3 - short dash          7 - dot dot dash

            4 - long, short dashed 

        Thickness values range from 1 to 6, and provide various

        line thicknesses on laser printed output. 

     set string color <justification> <thickness> 

        Sets string drawing attributes.  Color is as described above.

        Justification is the string justification, or how the string is

        plotted with respect to the x, y position given in the

        "draw string" command.  Refer to the following picture for the

        appropriate codes: 

           tr            tc              tr          tl - top left

            +-------------+--------------+           tc - center top

            |                            |           tr - right top

          l +             + c            + r          etc.

            |                            |

            +-------------+--------------+

           bl             bc             br 

     set strsiz hsiz <vsiz> 

        This command sets the string character size, where hsiz is the

        width of the characters, vsiz is the height of the characters,

        in virtual page inches.  If vsiz is not specified, it will be

        set the the same value as hsiz. 

     set rgb color-number red green blue 

        Defines new colors within GrADS, and assigns them to a new

        color number.  This new color number may then be used within

        any GrADS command that needs a color number, such as "set ccols". 

        The color-number must be a value between 16 and 99 (0 to 15 are

        predefined).  The red, green, and blue values must be between

        0 and 255.  For example: 

           set rgb 50 255 255 255 

        Would define a new color number, 50, and assign a color to it.

        In this case, the color would be white. 

        The translator gxpsc will make use of the new color settings

        although the output colors will have to be checked for

        the desired rendering.  gxps will NOT directly translate new

        colors into greyscales -- instead, it will translate the

        GREEN intensity ONLY into a new greyscale value.  Note that

        gxps has a predefined mapping between color values from 0 to 15

        such that the predefined "rainbow" color effect is rendered as

        a fairly pleasing greyscale gradation, which cannot be done for

        newly defined colors. 

     To control map drawing: 

       set map color style thickness - Draws the map background

                          using the requested line attributes. 

       set mpdraw on|off - If off, does not draw the map background.

                          Requested map scaling is still in force. 

     All the above settings stay the same until changed by

     new set commands. 
 

    16.0  Station Data 

     Station Data is also supported within GrADS to a limited

     extent.  Station data consists of data points distributed

     essentially randomly within the four dimensions. 

     Currently, station data operations and display are

     supported for three distinct dimension environments: 

         X, Y varying (horizontal X, Y plot)

         Z varying  (vertical profile)

         T varying  (time series) 

     Operations may be done on station data as with gridded

     data.  Operations between grids and station data are not

     supported. 

     Operations between station data are defined as being

     the operation performed on data points that have

     exactly the same varying dimension values. 

     For example, if T is the only varying dimension,

     the expression: 

       display ts-ds 

     would result in a time series of station data reports

     being retrieved for two seperate variables.  Then,

     for station reports having exactly the same time, the

     operation is performed.  Note that duplicates are

     ignored, with the operation being performed between

     the first occurences encountered. 

     When both X and Y are both fixed dimensions, the

     variable specification may include a station identifier,

     which specifies a local override for both lat and lon. 

     The syntax for this would be: 

          varname(stid=ident) 

     The station identifiers are case insensitive. 

     Some functions do not support station data types.  These are: 

        hdivg   hcurl  vint   maskout  ave  aave  tloop 

     When X and Y are varying, station data values are displayed

     as numbers centered at their locations.  If two expressions

     are supplied on the display command (ie, display ts;ds) then

     two values are displayed, above and below the station location.

     The display is controlled by the following set commands: 

          set ccolor color

          set dignum digits

          set digsiz size

          set stid on|off 

     The 'set stid' command controls whether the station identifier

     is displayed with each value. 

     One function is supplied that is unique to station data: 

        gr2stn (expr1, expr2) 

        where expr1 is a grid expression

        and expr2 is a station data expression 

        Using bilinear interpolation, the grid is interpolated

        to each station, the result being a station data result

        of the interpolated stations. 
 

    17.0  EXEC Command 

     The exec command is used to execute a sequence of GrADS

     commands from a file.  If a clear command is encountered,

     GrADS waits until enter is pressed before clearing and

     continuing with command processing. 

     The command is: 

          exec file-name <arg0 arg1 ... arg9> 

     where file-name is the name of a file containing GrADS

     commands. 

     The variables &0 to &9 may be used within the exec file

     to be replaced by blank delimited arguments to the exec. 

     A fully capable scripting language is under development for

     GrADS. 
 

    18.0  Hardcopy Output 
 

     If you plan to do hardcopy output, you must first

     (before you have produced the plot you want to output)

     enter the command: 

       enable print file-name 

     This enables the print command, and directs print command

     output to the file given.  Any existing contents of this file

     will be lost. 

     Note:  Any 'set rgb' commands done before the 'enable print'

            is issued will not be reflected in the output file. 

     When you have a graphic displayed that you want to print,

     enter the command: 

        print 

     This will copy the vector instructions used to create the

     current display into the output file in a metacode format. 

     You can close the output file either by quiting GrADS

     (quit command), or by entering: 

        disable print 

     Once the output file has been closed, the metacode commands

     within it must be translated to the desired format.  Utilities

     have been provided to do this.  These utilities do not run

     from within the GrADS command environment, you must execute them

     from the UNIX command line: 

       gxps  - Translate to monochome postscript (white background).

               The default GrADS rainbow colors (color numbers 2 to 14)

               are translated into pleasing greyscale values.  User

               defined colors (numbers above 15) are translated

               to greyscale intensity based on their GREEN content

               only.  

       gxpsc - Translate to color postscript. 

       gxpscw - Translates to color postscript with a white

                background (black and white are reversed). 

     These utilities will prompt for both an input filename and an

     output filename.  The input filename will be the file created

     by the enable print command.  The output filename will be a name

     of your choice.  Any existing file with this name will be deleted.

     Once the output file is created, you may print it using UNIX print

     commands. 
 
 

    19.0  Scripting Language 

     The GrADS scripting language, used via the GrADS run command,

     provides a similar capability to the exec command, except that

     a script may have variables, flow control, and access GrADS command

     output.  Scripts may be written to perform a variety of functions,   

     such as allowing a user to point and click on the screen to

     select something, to animate any desired quantities, to

     annotate plots with information obtained from GrADS query commands. 

     The command to execute a script is the run command: 

          run file-name options 

     This command runs the script contained in the named file.

     See Appendix B for documentation of the scripting language. 

     Some GrADS commands that complement the scripting langauge are: 

       query <option>  

        Issue the query command with no options to see what options

        are available.

      

       set gxout findstn 

        This graphics output type expects three arguments via a display

        command.  The first argument is a station data argument.  The

        2nd and 3rd arguments are the X and Y position on the screen

        of the desired search coordinates.  GrADS will search for the

        nearest station to the specified X and Y position, and print the

        stid, lon, and lat of the station found.   This should only be

        used when X and Y are the varying dimensions and AFTER a regular

        display command (that results in graphics output) is entered. 

        This command is primarily intended for use with a script.  Note

        that this command is provided as an interim facility for doing

        this operation; a more complete facility will be provided for

        doing a variety of filtering and search operations.  Thus, you

        should isolate the use of the command in your scripts in case it

        is necessary to change it later.  

      set dbuff on|off 

        Sets double buffer mode on or off.  This allows animation to

        be controlled from a script.  The clear command also sets

        double buffer mode off. 

      swap 

        Swaps buffers, when double buffer mode is on.  If double

        buffer mode is off, this command has no effect.   

        The usual usage of these command would be: 

          set dbuff on 

          loop --->

            display something

            swap

          <--- endloop 

          set dbuff off 
 
 

    Appendix A:  GrADS Data Sets 
 

    Gridded Data Sets 

     The GrADS gridded data set is a direct access binary data set.

     It may contain any number of variables at specified longitude,

     latitude, vertical, and time intervals. 

     GrADS views this data set as a giant array -- with X (longitude)

     varying the fastest, then Y (latitude), then Z (vertical level),

     then the variable type, then T (time). 

     It is easier for us to think of the data set in terms of a sequence

     of horizontal grids, where longitude and latitude vary.  Each

     horizontal grid represents a particular variable at a particular

     height and time.  Each horizontal grid is the same size in any particular

     GrADS data set (if you have grids of different sizes, you must create

     seperate data sets). 

     These grids are written to the data set in the following order:

     starting with a particular variable, grids for each vertical level

     (at a particular time) are written out in ascending order.  Then the

     grids for the next variable are written out.  When all the grids at

     a particular time have been written, grids for the next time are

     written. 

     The format of this data set is thus exactly the same as the COLA

     Pressure History format, except:  there are no date/time records,

     and latitude varies from south to north (not north to south as in

     the pressure history data). 

     Each binary gridded data set is described by a data descriptor file,

     essentially a table of contents for the binary data set.  Following is

     an example of such a file: 

       DSET     ua.dat

       TITLE Upper Air Data

       UNDEF  -9.99E33

       XDEF    80 LINEAR  -140.0  1.0

       YDEF    50 LINEAR   20.0   1.0

       ZDEF   10 LEVELS  1000 850 700 500 400 300 250 200 150 100

       TDEF    4 LINEAR 0Z10apr1991  12hr

       VARS     5

       slp      0    0  sea level pressure

       z       10    0  heights

       t       10    0  temps

       td       6    0  dewpoints

       u       10    0  u winds

       v       10    0  v winds

       ENDVARS 

     The data descriptor file is 'free format', ie each entry is

     blank delimited and may appear in any column.  Comment records

     start with an asterisk ('*') in column 1.  Comments may not

     appear in the list of variable records (between the vars and

     endvars records).  Records may not be more than 80 characters

     long.  

     In this example, the binary data set is named ua.dat, the undefined,

     or missing, data value is -9.99e33, there are 80 grid points in the

     X direction, 50 in the Y direction, 10 levels, 4 times, and 5 variables.

     The variables z, t, u, and v have 10 levels, the variable td has 6

     levels, and the variable slp has one level (see below for a more

     specific description of each entry). 

     Think in terms of the X and Y data points at one level for

     one variable at one time being a horizontal grid.  This grid is

     exactly in the same storage order as a FORTRAN array, in this case

     an array DIMENSION A(80,50).  The first dimension always varies from

     west to east, the second from south to north. 

     In the above example the horizontal grids would be written in the

     following order: 

          Time 1, Level    ?, Variable slp

          Time 1, Level 1000, Variable z

          Time 1, Level  850, Variable z

                 then levels 700, 500, 400, 300, 250, 200, then

          Time 1, Level  150, Variable z

          Time 1, Level  100, Variable z

          Time 1, Level 1000, Variable t

          Time 1, Level  850, Variable t

                 then levels 700, 500, 400, 300, 250, 200, then

          Time 1, Level  150, Variable t

          Time 1, Level  100, Variable t

          Time 1, Level 1000, Variable td

          Time 1, Level  850, Variable td

          Time 1, Level  700, Variable td

          Time 1, Level  500, Variable td

          Time 1, Level  400, Variable td

          Time 1, Level  300, Variable td

          Time 1, Level 1000, Variable u

          Time 1, Level  850, Variable u

                 then levels 700, 500, 400, 300, 250, 200, then

          Time 1, Level  150, Variable u

          Time 1, Level  100, Variable u

          Time 1, Level 1000, Variable v

          Time 1, Level  850, Variable v

                 then levels 700, 500, 400, 300, 250, 200, then

          Time 1, Level  150, Variable v

          Time 1, Level  100, Variable v

          Time 2, Level    ?, Variable slp

          Time 2, Level 1000, Variable z

          Time 2, Level  850, Variable z

          Time 2, Level  700, Variable z

          Time 2, Level  500, Variable z

          Time 2, Level  400, Variable z

                    .

                    .

                    .

                   etc 

     A description of each record in the GrADS data descriptor file

     follows: 

     DSET data-set-name 

         This entry specifies the name of the binary data set.

         It may be entered in mixed case.   

         If the binary data set is in the same directory as the data

         descriptor file, you may enter the filename in the data

         descriptor file without a full path name by prefixing it

         with a ^ character.  For example, if the data descriptor file

         is:

              /data/wx/grads/sa.ctl 

         and the binary data file is:

  

              /data/wx/grads/sa.dat 

         you could use the following file name in the data descriptor file: 

              DSET  ^sa.dat 

         instead of:

  

              DSET /data/wx/grads/sa.dat 

         As long as you keep the two files together, you may move them to

         any directory without changing the entries in the data descriptor

         file.  

     TITLE string 

         A brief description of the contents of the data set.  This will

         be displayed during a QUERY command, so it is helpful to put

         meaningful information here. 

     UNDEF value 

         The undefined, or missing, data value.  GrADS operations and

         graphics routines will ignore data with this value from this

         data set. 

     BYTESWAPPED 

         Indicates the binary data file is in reverse byte order

         from the normal byte order of the machine.  This would happen

         if you sent a file in binary fromat from, for example,

         a Sun to a PC.  Putting this keyword in the descriptor file

         tells GrADS to swap the byte order as the data is being read.  

     XDEF number <LINEAR start increment>

                 <LEVELS value-list> 

         Defines the mapping between grid values and longitude.

         Specifically: 

         number    -- the number of grid values in the X direction,

                      specified as an integer number.

                      Must be >= 1.

         LINEAR or LEVELS -- Indicates the grid mapping type.      

         For LINEAR:  

         start     -- the starting longitude, or the longitude for X = 1.

                      Specified as a floating point value, where negative

                      indicates degrees west. 

         increment -- the spacing between grid value in the X direction.

                      It is assumed that the X dimension values go from

                      west to east.  Specified as a positive floating value. 

         For LEVELS: 

         value-list -- List of 'number' values representing the

                       longitude of each X dimension.  May start and

                       continue on the next record in the descriptor

                       file (records may not be > 80 characters).

                       There must be at least 2 levels (otherwise

                       use LINEAR mapping). 

     YDEF number mapping start <increment>

                 <LEVELS value-list> 

         Defines the mapping between grid values and latitude.

         Specifically: 

         number    -- the number of grid values in the X direction,

                      specified as an integer number.

         mapping   -- mapping type, specified as a keyword.

                      Valid are:

                          LINEAR        -- Linear mapping

                          GAUSR15       -- Gaussian R15 latitudes

                          GAUSR20       -- Gaussian R20 latitudes

                          GAUSR30       -- Gaussian R30 latitudes

                          GAUSR40       -- Gaussian R40 latitudes

         start     -- For LINEAR mapping, the starting latitude, ie the

                      latitude for Y = 1, and is specified as a floating

                      point value, with negative indicating degrees south.

                      For GAUSRxx mapping, the start value indicates

                      the first gaussian grid number, where 1 would be the

                      southernmost gaussian grid latitude.

         increment -- the spacing between grid values in the Y direction.

                      It is assumed that the Y dimension values go from

                      south to north.  Specified as a positive floating

                      point value.  Used only for LINEAR mapping. 

         For LEVELS: 

         value-list -- List of 'number' values representing the

                       latitude of each X dimension.  May start and

                       continue on the next record in the descriptor

                       file (records may not be > 80 characters).

                       There must be at least 2 levels (otherwise

                       use LINEAR mapping). 

         Examples of specifying GAUSRxx mapping: 

           YDEF 20 GAUSR40 15 

           Indicates that there are 20 Y dimension values which start

           at Gaussian Latitude 15 (64.10 south) on the Gaussian R40 grid.

           Thus the 20 values would coorospond to Latitudes: 

            -64.10, -62.34, -60.58, -58.83, -57.07, -55.32, -53.56,

            -51.80, -50.05, -48.29, -46.54, -44.78, -43.02, -41.27,

            -39.51, -37.76, -36.00, -34.24, -32.49, -30.73 

           YDEF 102 GAUSR40 1 

           The entire gaussian grid is present, starting at the southernmost

           latitude (-88.66). 

     ZDEF number mapping <start increment>

                         <value-list> 

         Defines the mapping between grid values and pressure level.

         Specifically: 

         number    -- the number of grid values in the X direction,

                      specified as an integer number.

         mapping   -- mapping type, specified as a keyword.

                      Valid are:

                          LINEAR        -- Linear mapping

                          LEVELS        -- Arbitrary pressure levels

         start     -- when mapping is LINEAR, this is the starting value, or

                      the value when Z=1.

         increment -- when mappeing is LINEAR, the increment in the Z

                      direction, or from lower to higher.  This may be a

                      negative value, for example: 

                      ZDEF 10 LINEAR 1000 -100 

                      indicating that the data is for levels 1000, 900, 800,

                      700, etc. 

        value-list -- when the mapping is LEVELS, the specific levels

                      are simply listed in ascending order.  If there

                      is only one level, use LINEAR, since LEVELS

                      implies at least two levels. 

     TDEF number LINEAR start-time increment 

         Defines the mapping between grid values and time.

         Specifically: 

         number    -- the number of times in the data set.

                      Specified as an integer number.

        start-time -- The starting date/time value, specified in GrADS

                      absolute date/time format.  This is the value

                      when T=1.  The date/time format is: 

                          hh:mmZddmmmyyyy 

                      where: 

                          hh = hour (two digit integer)

                          mm = minutes (two digit integer)

                          dd = day (one or two digit integer)

                          mmm = month (jan, feb, mar, apr, may, jun, jul,

                                       aug, sep, oct, nov, dec)

                          yyyy = year (two or four digit integer.

                                       two digits implies a year between

                                       1950 and 2049). 

                      If not specified, hh defaults to 00, mm defaults to 00,

                      and dd defaults to 1.  The month and year must be

                      specified.  No intevening blanks are allowed in a

                      GrADS absolute date/time. 

                      Examples: 

                          12Z1JAN1990

                          14:20Z22JAN1987

                          JUN1960 

         increment -- time increment.  Specified in GrADS time increment

                      format: 

                          vvkk 

                      where: 

                          vv = an integer number, 1 or 2 digits

                          kk = an increment keyword,

                               mn = minutes

                               hr = hours

                               dy = days

                               mo = months

                               yr = year 

                      Examples: 

                          20mn   -- increment is 20 minutes

                           1mo   -- increment is 1 month

                           2dy   -- increment is 2 days 

         Some examples of a TDEF statement: 

             TDEF 24 LINEAR 00Z01JUN1987 1HR 

             The data set has 24 times, starting at 00Z on 1 Jun, 1987,

             with an increment of 1 hour. 

             TDEF 30 LINEAR 2JUN1988 1DY 

             The data set has 30 times, starting at 00Z on 2 Jun, 1988,

             with an increment of 1 day. 

     VARS number 

         Indicates the start of the records describing the variables

         in the data set. 

         number -- the number of variable records 

         Each variable record is in the following format: 

         abrev levs units description 

         abrev      -- a 1 to 8 character abbreviation for this variable.

                       This abreviation must start with an alphabetic

                       character (a-z) and be composed of alphabetic

                       characters and numbers.  This abbreviation will be

                       the "name" the variable is accessed by from within

                       GrADS.

         levs       -- an integer value specifying the number of levels

                       this variable has in the data set.  It may not

                       exceed the number of levels in the ZDEF statement.

                       A levs value of 0 indicates this variable has one

                       "level" that does not coorospond to a vertical level.

                       An example would be a surface variable. 

         units      -- Reserved for future use.  Put a value of 99 here. 

         description - A text description of the variable, max 40 characters. 

     After the last variable record comes the ENDVARS statement.  This ends

     the GrADS data descriptor file. 
 

    Station Data Sets 

     Station data sets are written to a binary file one report at a

     time.  The only ordering required is that the station reports

     be grouped within the file into some time interval.  For example,

     the time interval for upper air observations might be 12 hours.  

     Variables within each report are split into two groupings.

     Each variable is either a surface variable, thus can be reported

     at most once per report, or it is a level dependent variable,

     thus can be reported at a number of different levels within one

     report.

   

     The format of a station report in the binary station data file

     is:

 

           -  A header which provides information about the

              location of the station.

           -  Surface variables, if any

           -  Level dependent variables, if any 

     The header is described by the following C language data

     structure:

 

        struct rpthdr {

          char id[8];          /* Character station id           */

          float lat;           /* Latitude of report             */

          float lon;           /* Longitude of report            */

          float t;             /* Time in relative grid units    */

          int  nlev;           /* Number of levels following     */

          int flag;            /* Level independent var set flag */

        }; 

     A detailed description of each header entry follows: 

        id    - The station identifier.  This is a 1 to 7 character

                identifier that should identify the station uniquely.

                It may be assigned arbitrarily; ie. the stations could

                be numbered in some arbitrary order.

        lat   - The Y dimension location of the station in world

                coordinates, typically latitude.

        lon   - The X dimension location of the station in world

                coordinates, typically longitude.

        t     - The time of this report, in relative grid units.

                This refers to the way the stations are grouped in

                time.  For example, if you are working with surface

                airways reports, you would probably have a time grouping

                interval of one hour.  If you wanted to treat the

                report times of each report as being exactly on the

                hour, you would set t to 0.0.  If the report was

                for 12:15pm, and you were writing the time group for

                12pm, you would set t to be 0.25.  Thus, t would

                typically have the range of -0.5 to 0.5.

         nlev - Number of data groups following the header.  This

                is the count of the one surface group, if present,

                plus the number of level dependent groups.

                Is set to zero to mark the end of a time group in the

                file.

         flag - If zero, there are no surface variables following the

                header.  If one, then there are surface variables

                following the header.  

     Following the header, the data for this report is written. 

     The first group of data would be all the surface variables if

     present.  Whether or not the surface variable (if any) are

     present is determined by the flag in the header.  If present,

     then all the surface varialbes must be written -- missing

     variables should have the missing data value provided.

     Thus, each surface variable group will be the same size for

     each report in the file.

  

     The surface variables are written out as floating point

     numbers.  The ordering of the variables must be the same in

     each report, and is the ordering that will be given in the

     data descriptor file.  

     Following the surface variable group, any number of level dependent

     groups may be written.  The number of total data groups is

     provided in the header.  Each level dependent group must have

     all the level dependent variables present, even if they are

     filled with the missing data value.  Thus, each level dependent

     group will be the same size for all levels and all reports in the

     file.   

     The level dependent group is written out as follows: 

          level  -- floating point value giving the Z dimension

                    value in world coordinates for this level.

          variables -- The level dependent variables for this level.  

     After all the reports for one time grouping have been written,

     a special header (with no data groups) is written to indicate

     the end of the time group.  The header has an nlev value of zero.

     The next time group may then start immediately after.  A time

     group with no reports would still contain the time group terminator

     header record (ie, two terminators in a row).  

     GrADS station data files must be written as UNIX stream data sets

     without any imbedded record descriptor information.  This is

     easily done from a C program.  From a FORTRAN program, it

     usually requires a system-dependent option in the OPEN statement.

     For example, in DEC FORTRAN one can use the  

            RECORDTYPE='STREAM' 

     option to avoid having record descriptor information imbedded in

     the output file.  Examples of C and FORTRAN programs to create

     station data sets are provided later in this document.  

  

   Station Data Descriptor File 

     The format for the data descriptor file for station data is

     similar to the format for a gridded data set.  An example of

     a station data descriptor file is: 

        dset   ^ua.reps

        dtype  station

        stnmap ^ua.map

        undef  -999.0

        title  Real Time Upper air obs

        tdef  10 linear 12z18jan1992 12hr

        vars 12

        slp 0  99  SLP   

        ts  0  99  Temps

        ds  0  99  Dewpoints

        us  0  99  U Winds

        vs  0  99  V Winds

        z   1  99  Heights

        t   1  99  Temps

        d   1  99  Dewpoints

        u   1  99  U Winds

        v   1  99  V Winds

        endvars 

     Note the differences between this descriptor file and a

     grid descriptor file: 

        DTYPE record -- specify a data type of: station.

        STNMAP record -- gives the file name of the station mapping

                         file.  This file is created by the

                         stnmap utility, which will be described

                         later.

        XDEF, YDEF, ZDEF records -- not specified.

        TDEF record -- describes the time grouping interval and the

                       number of time groups in the file.

        VAR records -- surface variables must come first, and

                       are given a zero for the number-of-levels

                       field.  Level dependent variables are listed

                       after the surface variables, and are given

                       a one in the number-of-levels field.  

    STNMAP Utility 

      Once the data set has been written, and the descriptor file

      created, you should then create the station map file by running

      the stnmap utility.  This utility writes out hash table and/or

      link list information that allows GrADS to access the report

      data more efficiently.  The utility will prompt for the name

      of the data descriptor file. 

      If you change the data file -- perhaps by appending another time

      group -- you will also have to change the descriptor file to

      reflect the changes -- the new number of times for example --

      and then rerun the stnmap utility.  
 

 

    Examples of Creating a Gridded Data Set 

      On a workstation, the binary GrADS data sets need to be

      created as a 'stream' data set, ie, it should not have the

      normal FORTRAN record descriptor words imbedded in it.

      This can be done from FORTRAN using direct access I/O: 

          REAL  Z(72,46,16)

              .

              .

          OPEN (8,FILE='grads.dat',FORM='UNFORMATTED',

         &   ACCESS='DIRECT',RECL=72*46)

              .

              .

          IREC=1

          DO 10 I=1,18

            WRITE (8,REC=IREC) ((Z(J,K,I),J=1,72),K=1,46)

            IREC=IREC+1

      10  CONTINUE 

      This example writes out 16 levels of one variable to a file

      in direct access format.  We are really writing the data out

      sequentially, and using direct access to avoid having the

      record descriptor words written.  There may be options in

      your compiler to do this more directly, or you may wish to

      write the data using a C program.  

      Another simple sample might be: 

          REAL X(100)

          DO 10 I=1,100

            X(I)=I

      10  CONTINUE

          OPEN (8,FILE='samp.dat',FORM='UNFORMATTED',ACCESS='DIRECT',

         &         RECL=100)

          WRITE (8,REC=1) X

          STOP

          END 

      The associated descriptor file: 

          DSET samp.dat

          TITLE Sample Data Set

          UNDEF -9.99E33

          XDEF 100 LINEAR 1 1

          YDEF 1 LINEAR 1 1

          ZDEF 1 LINEAR 1 1

          TDEF 1 LINEAR 1JAN2000 1DY

          VARS 1

          x  0  99  100 Data Points

          ENDVARS 

      Once created, you can use this data set to experiment with

      GrADS data functions, such as:

 

          display sin(x/50) 
 
 

    Examples of Creating Station Data Sets 

      

      Lets say you have a data set with monthly rainfall: 

          Year Month Stid        Lat    Lon     Rainfall 

          1980    1  QQQ         34.3   -85.5   123.3

          1980    1  RRR         44.2   -84.5    87.1

          1980    1  SSS         22.4   -83.5   412.8

          1980    1  TTT         33.4   -82.5    23.3

          1980    2  QQQ         34.3   -85.5   145.1

          1980    2  RRR         44.2   -84.5   871.4

          1980    2  SSS         22.4   -83.5   223.1

          1980    2  TTT         33.4   -82.5    45.5

            .

            .

            . 
 

      A FORTRAN program in DEC FORTRAN to write this data set

      in GrADS format might be: 
 

             CHARACTER*8 STID

       C

             OPEN (8,NAME='rain.ch')

             OPEN (10,NAME='rain.dat',FORM='UNFORMATTED',

            &            RECORDTYPE='STREAM')

       C

             IFLAG = 0

       C 

       C  Read and Write

       C

       10    READ (8,9000,END=90) IYEAR,IMONTH,STID,RLAT,RLON,RVAL

       9000  FORMAT (I4,3X,I2,2X,A8,3F8.1)

             IF (IFLAG.EQ.0) THEN

               IFLAG = 1

               IYROLD = IYEAR

               IMNOLD = IMONTH

             ENDIF

       C

       C  If new time group, write time group terminator.

       C  Assuming no empty time groups.

       C

             IF (IYROLD.NE.IYEAR.OR.IMNOLD.NE.IMONTH) THEN

               NLEV = 0

               WRITE (10) STID,RLAT,RLON,TIM,NLEV,NFLAG

             ENDIF

             IYROLD = IYEAR

             IMNOLD = IMONTH

       C

       C  Write this report

       C

             TIM = 0.0

             NLEV = 1

             NFLAG = 1

             WRITE (10) STID,RLAT,RLON,TIM,NLEV,NFLAG

             WRITE (10) RVAL

             GO TO 10

       C

       C  On end of file write last time group terminator.

       C

       90    CONTINUE

             NLEV = 0

             WRITE (10) STID,RLAT,RLON,TIM,NLEV,NFLAG

             STOP

             END 

     For a different compiler, you would need to determine the

     appropriate OPEN statement to write a stream data set.  

     An equivalent C program might be: 
 

      #include <stdio.h> 

      /* Structure that describes a report header in a stn file */

 

      struct rpthdr {

        char id[8];           /* Character station id           */

        float lat;            /* Latitude of report             */

        float lon;            /* Longitude of report            */

        float t;              /* Time in relative grid units    */

        int  nlev;            /* Number of levels following     */

        int flag;             /* Level independent var set flag */

      } hdr; 

      main () {

      FILE *ifile, *ofile;

      char rec[80];

      int flag,year,month,yrsav,mnsav,i;

      float val; 

        /* Open files */ 

        ifile = fopen ("rain.ch","r");

        ofile = fopen ("rain.dat","wb");

        if (ifile==NULL || ofile==NULL) {

          printf ("Error opening files\n");

          return;

        } 

        /* Read, write loop */ 

        flag = 1;

        while (fgets(rec,79,ifile)!=NULL) { 

          /* Format conversion */ 

          sscanf (rec,"%i %i ",&year,&month);

          sscanf (rec+20," %g %g %g",&hdr.lat,&hdr.lon,&val);

          for (i=0; i<8; i++) hdr.id[i] = rec[i+11]; 

          /* Time group terminator if needed */ 

          if (flag) {

            yrsav = year;

            mnsav = month;

            flag = 0;

          }

          if (yrsav!=year || mnsav!=month) {

            hdr.nlev = 0;

            fwrite (&hdr,sizeof(struct rpthdr), 1, ofile);

          }

          yrsav = year;

          mnsav = month; 

          /* Write this report */ 

          hdr.nlev = 1;

          hdr.flag = 1;

          hdr.t = 0.0;

          fwrite (&hdr,sizeof(struct rpthdr), 1, ofile);

          fwrite (&val,sizeof(float), 1, ofile);

        }

        hdr.nlev = 0;

        fwrite (&hdr,sizeof(struct rpthdr), 1, ofile);

      } 

     Once the binary data file has been written, create the

     descriptor file.  It would look something like this: 

        dset   rain.dat

        dtype  station

        stnmap rain.map

        undef  -999.0

        title  Rainfall

        tdef  12 linear jan1980 1mo

        vars 1

        p  0  99  Rainfall

        endvars 

     Then run the stnmap utility to create the station map file. 

     You can then open and display this data from within GrADS.  
 
 

Appendix B:  Scripting Language 
 

   The GrADS scripting language, used via the GrADS run command,

   provides a similar capability to the exec command, except that

   a script may have variables, flow control, and access GrADS command

   output.  Scripts may be written to perform a variety of functions,   

   such as allowing a user to point and click on the screen to

   select something, to animate any desired quantities, to

   annotate plots with information obtained from GrADS query commands. 
 

Overview of the Scripting Language 

   The scripting language is similar to REXX in implementation.

   All variables are of type STRING.  Operations are supported on

   script variables.  Flow control is acheived via if/else/endif

   and while/endwhile constructs.  Loop flow may be modified by

   the continue or break commands.  Strings contained in variables

   or generated via an expression may be issued to GrADS as

   commands.  The result of those commands (the string that GrADS

   would have typed on the terminal) is put into a variable and made

   available to the script.  The language includes support for        

   functions. 
 

Elements of the Language 

   A script file is split into records.  The end of a script record

   is determined by either a newline character (end of record for the

   file) or a semicolon (where the semicolon is not contained within

   a constant string).   

   Each script record may be one of the following script record types: 

     Assignment

     If / Else / Endif

     while / endwhile / break / continue

     function header / return

     say / pull 

   If a script record is none of the above, it is assumed to be

   an statement record, which contains a script expression.  The result

   of the expression is passed to GrADS as a command for execution.  

   Many of the above record types will contain expressions.  Script

   expression are composed of operators and operands, where the

   operands are script variables, function calls, or constants,

   and the operators are mathematical, logical, or concatenation

   operations.  

   There is no 'goto' in this language.    
 

Variables 

   Script Language variable names are 1 to 8 characters, beginning with

   an alphabetic character and containing letters or numbers only.

   The name is case sensitive.   

   The contents of a script variable is always a character string.

   For some operations, the character string will be interpreted as

   a number.  

   If a variable has not yet been assigned, its value is its name.  

   If the contents of a variable or string constant are a number in

   the correct format,  certain operators will perform numeric

   operations, giving a string result which will also be a number. 

   Two variable names are predefined:  'result' and 'rc'.  It is

   a good idea to avoid assigning values to these variables.  
 

Operators   

   The following operators are implemented: 

       |   logical or

       &   logical and

       =   equality

       !=  not equal

       >   greater than

       >=  greater than or equal

       <   less than

       <=  less than or equal

       %   concatenation

       +   addition

       -   subtraction

       *   multiplication

       /   division

       !   unary not

       -   unary minus 

   The following operators will perform a numeric operation if

   the operands are numeric: 

       =, !=, >, >=, <, <=, +, -, *, / 

   If any of the following operations are attempted with non-numeric

   operands, an error will result: 

       +, -, *, / 

   Arithmetic operations are done in floating point.  If the

   result is integral, the result string will be integer. 

   A logical operator will give a character 0 if the result is false,

   and a character 1 if the result is true.  
 

Expressions 

   Script expressions consist of operands, operators, and parentheses. 

   The precedence of operators is: 

       -, !  (Unary)

       /, *

       +, -

       %

       =, !=, >, >=, <, <=   

       &

       | 

   Within the same precedence level, operations are performed

   left to right. 

   Operands may be variables (discussed earlier), string constants,

   or function calls.  String constants are enclosed in either

   single or double quotes.  Numeric constants may be entered without

   quotes -- but are still considered string constants.  

   An example of a string constant:

  

       'This is a string' 

   The entire expression, including all function calls, etc.  will

   be performed to obtain a result.  For example:  

       var1!='' & var1*var2<10 

   In this expression, both sides of the logical AND operation will

   be resolved, and the subexpression to the right might result in

   an error.  In these cases, a double nested if will be required.  

   In some cases, the concatenation operator is implied.  This takes

   place whenever two operands abut (with or without intervening

   blanks -- the blanks are ignored). 

   For example, the following expressions are identical: 

      var1%var2%'String' 

      var1 var2'String' 

   Keep in mind the order of precedence for the concatenation

   operator.   

   Parentheses modify the order of operation in the expected ways.  

   Function calls take the form of: 

      name(arg,arg,arg,...) 

   where the name follows the same rules as for variable names,

   and the args may be expressions.     

  

   

IF Blocks 

   Flow of control may be controlled via the if/else/endif

   construct.  The format is: 

       if expression                    Must be on seperate record

         script record

         script record

           .

           .

       else                             Optional

         script record

           .  

           .

       endif                            Required! 

   Note that the following script record is invalid:

 

       if (i=10) j=20 

   You would instead need to enter three script records:

 

       if (i=10)

         j = 20

       endif 

   You could enter these three script records on the same line:

  

       if (i=10); j=20; endif; 

   The portion of the if block executed depends on the result of the

   expression.  If the expression resolves to a string containing

   the character 0, the 'else' portion is executed.  If the result

   string is ANYTHING else, the 'if' portion is executed.  

 

WHILE Blocks 

   The while contstruct is as follows: 

      while expression                 On seperate script record

         script record

         script record

           .

           .

      endwhile                         Required! 

   While the expression is true -- ie, is not exactly equal to

   a character 0 -- the loop is executed.   

   Two additional script commands can be used to modify the loop

   execution.  break will end execution of the loop immediately.    

   continue will branch immediately back to the top of the loop, and

   the expression will be re-evaluated.  

   For example: 

     t = 1

     while (t<10)

       'set t 't

       'display z'

       if (rc!=0); break; endif;

       t = t + 1

     endwhile 

Functions 

   Functions may either be contained within the script file itself,

   or the may be intrinsic functions.  Functions contained within other

   script files are not supported as yet (other script files may

   be executed via the GrADS run command). 

   In either case, functions are invoked as a script expression is

   being evaluated.  Script functions always have a single string

   result, but may have one or more string arguments.  Functions

   are invoked by:

  

      name(arg,arg,arg...) 

   If the function has no arguments, you must still provide the

   parentheses:

 

      name() 

   You may provide your own functions from within your script file

   by using the function definition record: 

      function name(variable, variable, ...) 

   To return from a function, use the return command: 

      return expression         

   The expression is option; if not provided, a NULL string will be

   returned.  (A null string is: '')  The result of the function

   is the result of the expression specified on the return command.  

   When a function is invoked, the arguments are evaluated, then flow

   of control is transfered to the function.  The variables contained

   in the list within the function definition record are initialized

   to the values of the passed arguments.  If too few arguments

   where passed for the variables specified, the trailing variables

   are uninitialized.  If too many arguments are passed, the extra

   arguments are discarded.  

   You may modify the variables from the function definition record

   without modifying the variables from the calling routine.   

   Scope of variables is local to the function.  Global variables

   are not yet supported.   

   When a script file is first invoked (via the run command),

   execution starts at the beginning of the file.  A function definition

   record may optionally be provided at the beginning.  If it is, it

   should specify one variable name.  This variable will be initialized

   to any 'run' command options.  If no options were given, the

   variable will be initialized to NULL. 

 

Assignment 

   The format of the assignment record is: 

     variable = expression 

   The expression is evaluated, and the result is assigned to

   be the value of the indicated variable.  
 

Interacting With the User (Say, Pull) 

   The 'say' command is: 

     say expression 

   The result of the expression is written to the terminal.  

   The pull command is: 

     pull variable 

   The script pauses for user keyboard input (up to the carraige

   return), and the string entered by the user is assigned to the

   indicated variable name.  

 

Sending Commands to GrADS 

   The statement record consists only of an expression: 

      expression 

   The expression is evaluated, and the resulting string is submitted

   to GrADS as a command.  

   After this record is executed, the script variable 'result' is

   given the value of the result of the GrADS command (the result in

   this case is the string that GrADS would have typed to the terminal

   had you entered the command interactively).  The script variable

   'rc' is given the return code from the GrADS command (this will

   always be an integer value).  

   The result may contain several GrADS output lines.  These will be

   concatenated into one long string, and can be seperated in the

   script using the 'sublin' function.  

   A GrADS error resulting from an invalid command WILL NOT terminate

   execution of the script.  

   You may issue any GrADS commands from the scripting environment,

   including the run command.  The result string from issuing the

   run command will be the string passed back from that 'lower level'

   script via the 'return' command in that script -- when that script

   returns to GrADS (and thus returns to the higher level script).

   You may recursively call any script, but you are responsible for

   ensuring that you can get back out of the recursion.  

  

Intrinsic Functions 

   Only a few intrinsic (built in) functions are as yet implmented: 

  

      substr (string, start, length) 

       The sub-string of string starting at location 'start' for

       length 'length' will be returned.  If the string is too short,

       the result will be short or NULL.  'start' and 'length' must

       be integer string values. 
 

      subwrd (string, word) 

       The result is the nth 'word' from the string.  If the string is

       too short, the result is NULL.  'word' must be integer.  
 

      sublin (string, line) 

       The result is the nth 'line' from the string.  If the string

       has too few lines, the NULL string is returned.  'line' must

       be integer. 
 

      read (name) 

       The next record from file 'name' is read.  Repeated calls

       may be made to read consecutive records.  The result is two

       lines within one string.  The first line is the return code,

       the 2nd line is the record read.  The record may be a maximum

       of 80 characters.  Use the 'sublin' function to seperate the

       result.  Return codes are: 

         0 - ok

         1 - open error

         2 - end of file

         8 - file open for write

         9 - I/O error 

       Files are opened when the first call to read is made for a

       particular file name.  Files are closed when the execution of

       the script file terminates (note that files remain open

       between function calls, etc).  
 

      write (name, record <, append>) 

       The record is written to file 'name'.  On the first call to

       write for a particular file, the file is opened in write mode.

       This will destroy an existing file!  If you use the optional

       append flag, the file will be opened in append mode, and all  

       writes will be appended to the end of the file.   

       Return codes are: 

          0 - ok

          1 - open error

          8 - file open for read 
 

      close (name) 

       Closes the named file.  This must be done if you wish to read

       from a file you have been writing to.  This can also be used

       to rewind a file.  Return codes: 

          0 - ok

          1 - file not open 
 
 

  Examples:  

    A few simple example scripts are provided with the GrADS

    distribution.  If you do not know where these files are, send

    me email (doty@cola.umd.edu) and I will send them to you.

    I can also send you other (longer) examples which require

    data sets that you won't have, but which can provide more

    complex examples. 
 

    cbar.gs -   Draw color bars after a shaded contour plot is

                displayed 

    xyplot.gs - Does general XY plot. 

    string.gs - Plots string at point-click location. 

    draw.gs   - Draw line via point-click.    
 

  Suggestions: 

    Please forward any suggestions you have for improving GrADS

    to me:  doty@cola.umd.edu.  I am always interested in hearing

    what you like and don't like about GrADS, and am always looking

    for ways to improve it. 


Ϊҳ | ղ |

All Rights Reserved Powered by ĵ

Copyright © 2011
ĵ磬ַϵtousu#anggang.com
ض