## Elements of a GrADS Data Descriptor File

`DSET`
`DTYPE`
`INDEX`
`TITLE`
`UNDEF`
`OPTIONS`
`XDEF`
`YDEF`
`ZDEF`
`TDEF`
`VARS`
`ENDVARS`
`FILEHEADER`
`THEADER`
`XYHEADER`

`DSET data_filename`

This entry specifies the filename of the binary data set being described. If `data_filename` is prefixed with a `^``data_filename` must include a full path. 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`

As long as the two files are kept together, they may be moved to any directory without changing the entries in the data descriptor file.

`DTYPE station | grib`

This entry specifies the type of data being described. There are only two options: `station` or `grib`. If the data type is neither of these, then this entry is omitted completely from the descriptor file and GrADS will assume the data type is gridded binary.

`INDEX filename`

This entry specifies the name of the grib map file. It is required when using the `DTYPE grib` entry to read grib formatted data. The file is generated by running the external utility `gribmap`.

`TITLE string`

This entry gives brief description of the contents of the data set. This will be included in the output from a `query` command, so it is helpful to put meaningful information here.

Here are some examples:

    TITLE 5 Days of Sample Model Output
    TITLE NCEP Reanalysis Jan 1987 thru Jul 1999

`UNDEF value`

This entry specifies the undefined, or missing, data value. GrADS operations and graphics routines will ignore data with this value from this data set. `UNDEF` is a required parameter even if there are no undefined data.

Here is an examples:

    UNDEF -9.99e33

`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:

`yrev`

Indicates that the Y dimension (latitude) in the data file has been written in the reverse order from what GrADS assumes. An important thing to remember is that GrADS still presents the view that the data goes from south to north. The YDEF statement does not change; it still describes the transformation from a grid space going from south to north. The reversal of the Y axis is done as the data is read from the data file.

`zrev`

Indicates that the Z dimension (pressure) in the data file has been written from top to bottom, rather than from bottom to top as GrADS assumes. The same considerations as noted above for `yrev` also apply.

`template`

Indicates that a template for multiple data files is in use. For more information, see the section on Using Templates.

`sequential`

Indicates that the file was written in sequential unformatted I/O. This keyword may be used with either station or gridded data. If your gridded data is written in sequential format, then each record must be an X-Y varying grid. If you have only one X and one Y dimension in your file, then each record in the file will be one element long (it may not be a good idea to write the file this way).

`byteswapped`

Indicates the binary data file is in reverse byte order from the normal byte order of your machine. Putting this keyword in the `OPTIONS` record of the descriptor file tells GrADS to swap the byte order as the data is being read. May be used with gridded or station data.

The best way to ensure hardware independence for gridded data is to specify the data's source platform. This allows the data to be used on any type of hardware without having to worry about byte ordering. The following `OPTION` keywords indicate the actual byte ordering of the data. If the data are already in the correct order, no conversion is performed. These options facilitate moving data files and descriptor files between machines.

`big_endian`

Indicates the data file contains 32-bit IEEE floats created on a big_endian platform (e.g., sun, sgi and hp). May be used with gridded or station data.

`little_endian`

Indicates the data file contains 32-bit IEEE floats created on a little_endian platform (e.g., iX86, and dec). May be used with gridded or station data.

`cray_32bit_ieee`

Indicates the data file contains 32-bit IEEE floats created on a cray. May be used with gridded or station data.

`365_day_calendar`

Indicates the data file was created with perpetual 365-day years, with no leap years. This is used for some types of model output.

`XDEF xnum mapping <additional arguments>`

This entry defines the grid point values for the X dimension. 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

`YDEF ynum mapping <additional arguments>`

This entry defines the grid point values for the Y dimension. The first argument, `ynum`, specifies the number of grid points in the Y direction. `ynum` must be an integer >= 1. `mapping` defines the method by which latitudes are assigned to Y grid points. There are several options for `mapping`:

`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.

`ZDEF znum mapping <additional arguments>`

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 30 20 10

`TDEF tnum LINEAR start increment`

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

`VARS varnum
` variable_record_1
variable_record_2
...
variable_record_varnum
ENDVARS

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`

`varname` is a 1-15 character "name" or abbreviation for the variable. `varname` may contain alphabetic and numeric characters but it must start with an alphabetic character (a-z).

`levs` is an integer that specifies the number of vertical levels the variable contains. `levs` may not exceed `znum` as specified in the ZDEF statement. If `levs` is 0, the variable does not correspond to any vertical level. Surface variables (e.g. sea level pressure) have a `levs` value of 0.

The `units` component of the `variable_record` is used for data in GRIB and other special formats. If the data your are describing are not in one of these formats, put a value of `99` here.

`description` is text description of the variable, max 40 characters.

Here is an example:

    VARS 8
    PS 0 99 Surface Pressure
    U  7 99 U-Winds
    V  7 99 V-Winds
    Z  7 99 Geopotential Heights
    T  7 99 Temperature
    Q  5 99 Specific Humidity
    TS 0 99 Surface Temperature
    P  0 99 Precipitation
    ENDVARS

`FILEHEADER length`

This optional entry tells GrADS that your data file has a header record of `length` bytes that precedes the data. GrADS will skip past this header, then treat the remaineder of the file as though it were a normal GrADS binary file after that point. This optional descriptor file entry is only valid for GrADS gridded data sets.

`THEADER length`

This optional entry tells GrADS that the data file has a header record of `length` bytes preceding each time block of binary data. This optional descriptor file entry is only valid for GrADS gridded data sets. See the section on structure of a gridded binary data file for more information.

`XYHEADER length`

This optional entry tells GrADS that the data file has a header record of `length` bytes preceding each horizontal grid (XY block) of binary data. This optional descriptor file entry is only valid for GrADS gridded data sets. See the section on structure of a gridded binary data file for more information.