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
HEADERBYTES length<

CACHESIZE bytes

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 level values 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 level value at grid point Z=1. increment is the spacing between grid point values in the Z direction, or from lower to higher. increment must be non-zero and non0negative.

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.

Here are some examples:

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

(GrADS version 2.0) (For DTYPE grib2 only) If your Z axis is pressure, the gribmap utility requires the level values to be given in units of Pascals instead of millibars. Use the "options pascals" keyword to convert the unit of the level values to millibars after the gribmap index is generated and when the descriptor file is opened with GrADS. Pressure level values may remain in Pascals, but then many of the internal functions (which assume a vertical dimension in units of millibars) will not work properly.

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 2.0) This entry defines the ensemble dimension. All ensemble members must have identical X, Y, and Z dimensions, the same list of variables, and the same time axis increment. There are two different syntaxes for the EDEF entry: the first is simpler and requires only the names for each ensemble member, the second expanded form contains a name, individual time axis information, and optional GRIB2 codes.

Both EDEF syntaxes begin with the enum argument, an integer >=1 which specifies the number of ensemble members.

If all of the ensemble members have an identical time axis (i.e. length, initial time, and increment are the same for each one), then it is only necessary to distinguish the ensembles by their names, and the simplified EDEF syntax with the NAMES keyword may be used. A simple space-delimited list of names is all that is required. Ensemble names must have between 1 and 15 alphanumeric characters, lower case only. (In version 2.0.0 and later, mixed case ensemble names are allowed). Some examples are:

EDEF	10	NAMES	1 2 3 4 5 6 7 8 9 10
EDEF	12	NAMES	m01 m02 m03 m04 m05 m06 m07 m08 m09 m10 m11 ensm
EDEF	7	NAMES	e1 e2 e3 e4 e5 e6 e7

When the OPTIONS TEMPLATE entry is used with EDEF, the ensemble names are used in the %e substitution template to generate the file name. See Using Templates for more details.

If the ensemble members do not have identical time axes (i.e., their lengths or initial times are not the same), or if you need to include the GRIB2 codes, then you must use the expanded EDEF syntax: a collection of records framed by EDEF and ENDEDEF. The format of the ensemble records is as follows:

ensname length start <grib2 codes>

The ensname is the 1-15 character "name" for the ensemble member. The length is the size of the time axis of the ensemble, which must be less than or equal to the tnum argument in the TDEF entry. (The time axis described by TDEF must span all the ensemble members.) The start argument is the initial time of the ensemble member and must be given in GrADS absolute date/time format. (See TDEF for details).

The grib2 codes are required if (1) the DTYPE is grib2 and (2) there is more than one ensemble member (enum > 1). The expanded form of the EDEF entry must be used when grib2 codes are required, even if the length and start times are the same for all members. For GRIB2 ensembles, support currently exists for four different Product Definition Template (PDT) numbers: 1, 2, 11, and 12. These are grouped into two types: individual ensemble forecasts (PDT 1 and 11) or derived forecasts based on all ensemble members (PDT 2 and 12). For individual ensemble forecasts (PDT 1 and 11), two comma-delimited grib2 codes are required: the ensemble type and perturbation number. For derived forecasts based on all ensemble members (PDT 2 and 12), only one grib2 code is required: the derived forecast. Clarification of all the GRIB2 nomenclature may be found in the documentation at WMO and NCEP. Two examples are given below.

The first example illustrates ensemble members with different lengths and start times:

TDEF 591 linear 12z09dec1980 12hr
EDEF 16
ensm	591	12z09dec1980
m01	591	12z09dec1980
m02	589	12z10dec1980
m03	587	12z11dec1980
m04	585	12z12dec1980
m05	583	12z13dec1980
m06	571	12z19dec1980
m07	569	12z20dec1980
m08	567	12z21dec1980
m09	565	12z22dec1980
m10	563	12z23dec1980
m11	549	12z30dec1980
m12	547	12z31dec1980
m13	545	12z01jan1981
m14	543	12z02jan1981
m15	541	12z03jan1981
ENDEDEF

The second example illustrates the use of GRIB2 codes:

TDEF 31 linear 00z24apr2007 12hr
EDEF 23
p01	31	00z24apr2007	3,1
p02	31	00z24apr2007	3,2
p03	31	00z24apr2007	3,3
p04	31	00z24apr2007	3,4
p05	31	00z24apr2007	3,5
p06	31	00z24apr2007	3,6
p07	31	00z24apr2007	3,7
p08	31	00z24apr2007	3,8
p09	31	00z24apr2007	3,9
p10	31	00z24apr2007	3,10
p11	31	00z24apr2007	3,11
p12	31	00z24apr2007	3,12
p13	31	00z24apr2007	3,13
p14	31	00z24apr2007	3,14
p15	31	00z24apr2007	3,15
p16	31	00z24apr2007	3,16
p17	31	00z24apr2007	3,17
p18	31	00z24apr2007	3,18
p19	31	00z24apr2007	3,19
p20	31	00z24apr2007	3,20
c00	31	00z24apr2007	1,0
avg	31	00z24apr2007	0
spr	31	00z24apr2007	2
ENDEDEF

(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                                 (Version 2.0.1 or earlier)
varname levs <additional_codes> units description    (Version 2.0.2 or later)

The syntax of varname and units is different depending on what kind of data format (DTYPE) you are describing. The <additional_codes> are only necessary for certain types of GRIB2 data sets. 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