This entry specifies the filename of the data file being described. If the data and the descriptor file are not in the same directory, then data_filename must include a full path. If a ^ character is placed in front of data_filename, then data_filename is assumed to be relative to the path of the descriptor file. If you are using the ^ character in the DSET entry, then the descriptor file and the data file may be moved to a new directory without changing any entries in the data descriptor file, provided their relative paths remain the same. For example:

If the data descriptor file is:
      /data/wx/grads/sa.ctl
and the binary data file is:
      /data/wx/grads/sa.dat
then the data file name in the data descriptor file can be:
      DSET ^sa.dat
instead of:
      DSET /data/wx/grads/sa.dat

If data_filename does not include a full path or a ^, then GrADS will only look for data files in the directory where you are running GrADS.

GrADS allows you use a single DSET entry to aggregate multiple data files and handle them as if they were one individual file. The individual data files must be identical in all dimensions except time, and the time range of each individual file must be indicated it its filename. To accomplish this, the DSET entry has a substitution template instead of a filename. See the section on Using Templates for a description of all the possible components of the template. Second, the OPTIONS entry must contain the template keyword.

(GrADS version 1.9b4) This entry is used with a new option for templating data files that allows for any user-specified string substitution, instead of only date string substitution. This is useful when none of the standard template options match the time ranges in the files you wish to aggregate, or if the files are located on different disks. When you put the %ch template in your DSET entry, then you also need to put additional CHSUB entries in the descriptor file. The string will be substituted for %ch in the data file name for the time steps beginning with t1 and ending with t2.See the section on Using Templates for examples.

INDEX filename

TITLE string

This entry gives brief description of the contents of the data set. String will be included in the output from a query command and it will appear in the directory listing if you are serving this data file with the GrADS-DODS Server (GDS), so it is helpful to put meaningful information in the title field. For GDS use, do not use double quotation marks (") in the title.

FILEHEADER length

THEADER length

OPTIONS keyword

This entry controls various aspects of the way GrADS interprets the raw data file. It replaces the old FORMAT record. The keyword argument may be one or more of the following:

XDEF xnum mapping <additional arguments>

This entry defines the grid point values for the X dimension, or longitude. The first argument, xnum, specifies the number of grid points in the X direction. xnum must be an integer >= 1. mapping defines the method by which longitudes are assigned to X grid points. There are two options for mapping:

LINEAR    Linear mapping
LEVELS    Longitudes specified individually

The LINEAR mapping method requires two additional arguments: start and increment. start is a floating point value that indicates the longitude at grid point X=1. Negative values indicate western longitudes. increment is the spacing between grid point values, given as a positive floating point value.

The LEVELS mapping method requires one additional argument, value-list, which explicitly specifies the longitude value for each grid point. value-list should contain xnum floating point values. It may continue into the next record in the descriptor file, but note that records may not have more than 255 characters. There must be at least 2 levels in value-list; otherwise use the LINEAR method.

Here are some examples:

XDEF	144	LINEAR	0.0 2.5
XDEF	72	LINEAR	0.0 5.0
XDEF	12	LEVELS	0 30 60 90 120 150 180 210 240 270 300 330
XDEF	12	LEVELS	15 45 75 105 135 165 195 225 255 285 315 345

LINEAR    Linear mapping
LEVELS    Latitudes specified individually
GAUST62   Gaussian T62 latitudes
GAUSR15   Gaussian R15 latitudes
GAUSR20   Gaussian R20 latitudes
GAUSR30   Gaussian R30 latitudes
GAUSR40   Gaussian R40 latitudes

The LINEAR mapping method requires two additional arguments: start and increment. start is a floating point value that indicates the latitude at grid point Y=1. Negative values indicate southern latitides. increment is the spacing between grid point values in the Y direction. It is assumed that the Y dimension values go from south to north, so increment is always positive.

The LEVELS mapping method requires one additional argument, value-list, which explicitly specifies the latitude for each grid point, from south to north. value-list should contain ynum floating point values. It may continue into the next record in the descriptor file, but note that records may not have more than 255 characters. There must be at least 2 levels in value-list; otherwise use the LINEAR method.

The Gaussian mapping methods require one additional argument: start. This argument indicates the first gaussian grid number. If the data span all latitudes, start would be 1, indicating the southernmost gaussian grid latitude.

Here are some examples:

YDEF	73	LINEAR	-90 2.5
YDEF	180	LINEAR	-90 1.0
YDEF	18	LEVELS	-85 -75 -65 -55 -45 -35 -25 -15 -5 5 15 25 35 45 55 65 75 85
YDEF	94	GAUST62	1
YDEF	20	GAUSR40	15

The NCEP/NCAR Reanalysis surface variables are on the GAUST62 grid.

The final example shows that there are 20 Y dimension values which start at Gaussian Latitude 15 (64.10 south) on the Gaussian R40 grid

This entry defines the grid point values for the Z dimension. The first argument, znum, specifies the number of pressure levels. znum must be an integer >= 1. mapping defines the method by which longitudes are assigned to Z grid points. There are two options for mapping:

LINEAR    Linear mapping
LEVELS    Pressure levels specified individually

The LINEAR mapping method requires two additional arguments: start and increment. start is a floating point value that indicates the longitude at grid point Z=1. increment is the spacing between grid point values in the Z direction, or from lower to higher. increment may be a negative value.

The LEVELS mapping method requires one additional argument, value-list, which explicitly specifies the pressure level for each grid point in ascending order. value-list should contain znum floating point values. It may continue into the next record in the descriptor file, but note that records may not have more than 255 characters. There must be at least 2 levels in value-list; otherwise use the LINEAR method.

Here are some examples:

ZDEF	10	LINEAR	1000 -100
ZDEF	7	LEVELS	1000 850 700 500 300 200 100
ZDEF	17	LEVELS	1000 925 850 700 600 500 400 300 250 200 150 100 70 50

This entry defines the grid point values for the T dimension. The first argument, tnum, specifies the number of time steps. tnum must be an integer >= 1. The method by which times are assigned to T grid points is always LINEAR.

start indicates the initial time value at grid point T=1. start must be specified in the GrADS absolute date/time format:

hh:mmZddmmmyyyy

where:

hh	=	hour (two digit integer)
mm	=	minute (two digit integer)
dd	=	day (one or two digit integer)
mmm	=	3-character month
yyyy	=	year (may be a two or four digit integer; 2 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 intervening blanks are allowed in the GrADS absolute date/time format.

increment is the spacing between grid point values in the T direction. increment must be specified in the GrADS absolute time increment format:

vvkk

where:

vv	=	an integer number, 1 or 2 digits
kk	=	mn (minute) hr (hour) dy (day) mo (month) yr (year)

Here are some examples:

TDEF	60	LINEAR	00Z31dec1999 1mn
TDEF	73	LINEAR	3jan1989 5dy
TDEF	730	LINEAR	00z1jan1990 12hr
TDEF	12	LINEAR	1jan2000 1mo
TDEF	365	LINEAR	12Z1jan1959 1dy
TDEF	40	LINEAR	1jan1950 1yr

(GrADS version 1.9b4) This entry is for explicity identifying vector component pairs. This is only necessary if the data are on a native projection other than lat/lon (i.e. you are using PDEF) and if the winds have to be rotated from a grid-relative sense to an Earth-relative sense. (GrADS has to retrieve both the u and v component in order to do the rotation calculation.)

Using this entry replaces the old technique of putting 33 (for U) or 34 (for V) in the first element of the units field in the variable declaration. The U-component and V-component arguments should be variable names that appear in the VARS list. They are separated by a comma, with no spaces. More than one pair of components may be listed; in this case, the pairs should be separated by a space. For example:

VECTORPAIRS  u,v  u10,v10  uflx,vflx

This ensemble of entries describes all the variables contained in the data set. varnum indicates the number of variables in the data set and is therefore also equal to the number of variable records that are listed between the VARS and ENDVARS entries. ENDVARS must be the final line of the Grads data descriptor file. Any blank lines after the ENDVARS statement may cause open to fail!

The format of the variable records is as follows:

varname levs units description

The syntax of varname and units is different depending on what kind of data format (DTYPE) you are describing. Details provided below:

(GrADS version 1.9b4) To supplement the metadata in your descriptor file, use attribute comments. The first two characters of the attribute comment must be "@" followed by a space -- this distinguishes it from an ordinary comment (see below). Attribute comments may appear anywhere in the descriptor file, and they will be ignored if used with older versions of GrADS.

All file attributes may be retrieved with the 'query attr' command.

varname may be set to "global" to describe general attributes that are valid for the entire data set. Set varname to "lon", "lat", "lev", or "time" to describe attributes of the four coordinate axes; otherwise, use one of the variable names listed in the variable declarations. If a variable name is aliased, use the grads_varname instead of the native SDF_varname.

attribute_type should be one of the following case-sensitive types: String, Byte, Int16, UInt16, Int32, UInt32, Float32, Float64.

attribute_name may be any single word or string with no spaces (e.g.: "units", "minimum_value")

attribute_value can be any string as long as the length of the entire entry does not exceed 512 characters.

For example:
@ precip String units mm/day
@ global String documentation http://put.your.documentation.url.here