GrADS Variable Formats

## Variable Formats and Binary Data File Structure

This section describes how to refine the variable declarations in the data descriptor file to accurately reflect the structure and format of each variable in a binary file. Before continuing, it is recommended that you review the material in these other sections:

- About GrADS Gridded Data Sets
- Elements of a GrADS Data Descriptor File

In a GrADS data descriptor file each variable declaration record has the following syntax:

`varname levs units description`

The VARS section of Elements of a GrADS Data Descriptor File explains the general syntax of the variable declaration record. This section goes into further detail on the use of the `units` keyword to invoke some special features that allow GrADS to read binary files that do not conform to the default structure.

The structure of a 3-D or 4-D data set is determined by the order in which the horizonal grids are written to file. The default sequence goes in the following order starting from the fastest varying dimension to the slowest varying dimension: longitude (X), latitude (Y), vertical level (Z), variable (VAR), time (T).

If your binary data set was created or "packed" according to a different dimension sequence, then you can use the `units` keyword to tell GrADS exactly how to unpack the data. The `units` keyword is actually a series of one or more comma-delimited numbers. If `units` is set to `99` then all the features for unpacking special data formats are ignored. If `units` is set to `-1`, then the features are invoked via additional parameters that follow the `-1` and are separated by commas:

`units = -1, structure <,arg>`

There are four options for `structure`, outlined below. Some of these options have additional attributes which are specified with `arg`.

1. `units = -1,10,1`

   This option was removed in GrADS version 2.0. This option indicates that "VAR" and "Z" have been transposed in the dimension sequence. The order is: longitude (X), latitude (Y), variable (VAR), vertical level (Z), time(T). Thus, all variables are written out one level at a time.

   This feature was designed to be used with NASA GCM data in the "phoenix" format. The upper air prognostic variables were transposed, but the diagnostic variables were not. Thus an `arg` of `1` means the variable has been var-z transposed, and an `arg` of `2` means the variable has not.

2. `units = -1,20`

   This option indicates that "VAR" and "T" have been transposed in the dimension sequence. The order is: longitude (X), latitude (Y), vertical level (Z), time(T), variable (VAR). Thus, all times for one variable are written out in order followed by all times for the next variable, etc.

   Suppose your data set is actually a collection of separate files that are aggregated by using a template. Then you must use an additional argument to tell GrADS how many time steps are contained in each individual file. Use `arg` to tell GrADS the size of the time dimension in each individual file. For example, here are the relevant records from a descriptor file for 10 years of monthly wind component and temperature data packaged with "VAR" and "T" dimensions transposed:

       DSET ^monthlydata_%y4.dat
       OPTIONS template
       ...
       TDEF 120 linear jan79 1mo
       VARS 3

         u 18 -1,20,12 u component
         v 18 -1,20,12 v component
         t 18 -1,20,12 temperature
       ENDVARS

3. `units = -1,30`

   This option was removed in GrADS version 2.0. This option handles the cruel and unusual case where X and Y dimensions are transposed and the horizontal grids are (lat,lon) as opposed to (lon,lat) data. This option causes GrADS to work very inefficiently because it wasn't worth it to make a big change to GrADS internal I/O to handle this type of pathological data. However, it is useful for initial inspection and debugging and that's basically what it is designed for.

4. `units = -1,40`

   This option handles non-float data. Data are converted to floats internally after they are read from the binary file. The dimension sequence is assumed to be the default. The secondary `arg` tells GrADS what type of data values are in the binary file:

   `units = -1,40,1` = 1-byte unsigned chars (0-255)
   `units = -1,40,2` = 2-byte unsigned integers
   `units = -1,40,-2` = 2-byte signed integers
   `units = -1,40,4` = 4-byte integers