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:

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

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:

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:

  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: