# About GrADS Gridded Data Sets

This section describes GrADS gridded data sets -- their structure and format, how to create them, and how to instruct GrADS to interpret them properly. Here are some quick links for skipping through this section:

- Introduction
- The Data Descriptor File
- Structure of a Gridded Binary Data File
- Binary Formats
- Creating Data Files

## Introduction

In GrADS, the raw binary data and the meta data (information about the binary data) are stored in separate files. The meta data file contains a complete description of the binary data as well as instructions for GrADS on where to find the data and how to read it. The binary data file is purely data with no space or time identifiers. The meta data file is the one you open in GrADS -- it is called the data descriptor file. The data descriptor file has a default file extension of `.ctl` and is therefore also referred to as a control file.

`ga-> open filename.ctl`

## The Data Descriptor File

The data descriptor file contains a complete description of the binary data as well as instructions for GrADS on where to find the data and how to read it. The descriptor file is an ascii file that can be created easily with a text editor. The general contents of a gridded data descriptor file are as follows:

- Filename for the binary data
- Missing or undefined data value
- Mapping between grid coordinates and world coordinates
- Description of variables in the binary data set

The individual components of data descriptor files are discussed in detail in the section Elements of a Data Descriptor File.

The data descriptor file is free format, which means the components of each record (line of text) are blank delimited. Leading blanks at the beginning of each record are removed before parsing. Comment records must start with an asterisk (*). Individual records may not be more than 255 characters long. Here is an example of a basic data descriptor file:

    DSET  ^gridded_data_sample.dat
    TITLE Gridded Data Sample
    UNDEF -9.99E33
    XDEF 180 LINEAR 0.0  2.0
    YDEF  90 LINEAR -90  2.0
    ZDEF  10 LEVELS 1000 850 700 500 400 300 250 200 150 100
    TDEF   4 LINEAR 0Z10apr1991 12hr
    VARS      4
    slp     0  99  sea level pressure
    hgt    10  99  heights
    temp   10  99  temperature
    shum    6  99  specific humidity
    ENDVARS

In this example, the binary data set is named `gridded_data_sample.dat` and is located in the same directory as the descriptor file. This is specified by the caret (^) in front of the data filename. The undefined or missing data value is -9.99e33, there are 180 grid points in the X direction, 90 grid points in the Y direction, 10 vertical levels, 4 time steps, and 4 variables. The variable "slp" is a surface variable -- it has no vertical levels, but is assigned a default vertical coordinate of Z=1. The variables "hgt" and "temp" have 10 vertical levels, and the variable "shum" has 6 vertical levels (the first six listed, 1000 to 300).

## Structure of a Gridded Binary Data File

The binary data file is purely data with no space or time identifiers. The data descriptor specifies the data's grid dimensions, but it is up to the user to make sure that the binary data have been written to file in the proper order so GrADS will interpret them correctly.

GrADS views gridded data sets as multi-dimensional arrays varying in longitude, latitude, vertical level, variable, and time. In version 2.0, a fifth grid dimension was added. The fifth grid dimension is assumed to be used for ensembles, and so it is given the name E (or ens), but because it is generally implemented, it may be used for other grid dimensions such as EOFs. The default size of the E dimension is 1 -- if no E dimension exists, it is not necessary to explicity declare it the descriptor file.

It is helpful to think of a gridded binary data file as a sequence of "building blocks", where each building block is a horizonal grid of data varying in the X and Y dimensions. The first dimension (X) always varies from west to east; the second dimension (Y) varies from south to north (by default). One horizontal grid represents a particular variable at a particular height and time. Each horizontal grid in a GrADS binary data file must be the same size. If you have two variables with different horizontal grids, you must create two separate data sets.

The structure of a 3-D, 4-D, or 5-D data set is determined by the order in which the horizonal grids are written to file. The building blocks are stacked in a sequence according to dimension. The 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), and ensemble (E).

For example, suppose you want to create a 4-D binary data set containing four variables. The horizonal grids would be written to the data set in the following order:

    Time 1, Variable 1, Each vertical level from bottom to top
    Time 1, Variable 2, Each vertical level from bottom to top
    Time 1, Variable 3, Each vertical level from bottom to top
    Time 1, Variable 4, Each vertical level from bottom to top

    Time 2, Variable 1, Each vertical level from bottom to top
    Time 2, Variable 2, Each vertical level from bottom to top
    Time 2, Variable 3, Each vertical level from bottom to top
    Time 2, Variable 4, Each vertical level from bottom to top

    etc.

5-D ensemble data sets are created by concatenating 4-D data sets together -- the ensemble dimension varies outside of all the others. To extend the previous example, suppose you are creating a data set that has 3 ensembles (but only 2 variables) :

    Ensemble 1, Time 1, Variable 1, Each vertical level from bottom to top
    Ensemble 1, Time 1, Variable 2, Each vertical level from bottom to top
    Ensemble 1, Time 2, Variable 1, Each vertical level from bottom to top
    Ensemble 1, Time 2, Variable 2, Each vertical level from bottom to top
                <...>
    Ensemble 1, Time N, Variable 1, Each vertical level from bottom to top
    Ensemble 1, Time N, Variable 2, Each vertical level from bottom to top
    Ensemble 2, Time 1, Variable 1, Each vertical level from bottom to top
    Ensemble 2, Time 1, Variable 2, Each vertical level from bottom to top
    Ensemble 2, Time 2, Variable 1, Each vertical level from bottom to top
    Ensemble 2, Time 2, Variable 2, Each vertical level from bottom to top
                <...>
    Ensemble 2, Time N, Variable 1, Each vertical level from bottom to top
    Ensemble 2, Time N, Variable 2, Each vertical level from bottom to top
    Ensemble 3, Time 1, Variable 1, Each vertical level from bottom to top
    Ensemble 3, Time 1, Variable 2, Each vertical level from bottom to top
    Ensemble 3, Time 2, Variable 1, Each vertical level from bottom to top
    Ensemble 3, Time 2, Variable 2, Each vertical level from bottom to top
                <...>
    Ensemble 3, Time N, Variable 1, Each vertical level from bottom to top
    Ensemble 3, Time N, Variable 2, Each vertical level from bottom to top

## Binary Formats

GrADS can read binary data that are formatted with or without FORTRAN record length headers. Files containing record length headers are called "sequential" and those without embedded record length information are called "direct access" or "stream" files. Unless otherwise specified, GrADS will assume the data file does not contain the record length headers.

GrADS can also directly read GRIB formatted data -- one of GrADS most powerful and unique features! See the section on Creating Data Descriptor Files for GRIB Data for more information.

A third category of data formats that GrADS can read are "self-describing files" such as NetCDF or HDF-SDS. For more information, see the references pages for reading NetCDF or HDF-SDS files.

## Creating Data Files

The default format for GrADS gridded binary data files is "stream" or "direct access". If you want to read FORTRAN "sequential" unformatted binary data files, you must include the following additional record in the data descriptor file:

`OPTIONS sequential`

Following are three examples of how to create gridded binary data files with simple FORTRAN programs.

1. Suppose you have U and V wind components in 4-dimensions (X, Y, Z, and T) and you want to write them out in so they can be viewed in GrADS. The FORTRAN code might look something like this:

       parameter (ni=144,nj=91,nk=8,nt=4)
       dimension u(ni,nj,nk),v(ni,nj,nk),dum(ni,nj)
       do n=1,nk
          call load(u,ni,nj,nk,n,dum)
          write(10) dum
       end do
       do n=1,nk
          call load(v,ni,nj,nk,n,dum)
          write(10) dum
       end do

       subroutine load(a,ni,nj,nk,n,dum)
       dimension a(ni,nj,nk),dum(ni,nj)
       do i=1,ni
          do j=1,nj
          dum(i,j)=a(i,j,n)
       end do
       end do
       return

   The data descriptor file would look something like:

       DSET      ^model.dat
       TITLE     Sample Model Data
       UNDEF    0.10000E+16
       XDEF     144 linear   0 2.5
       YDEF      91 linear -90 2.0
       ZDEF       8 levels 1000 900 800 700 500 300 100 50
       TDEF       4 linear 00z01apr85 6hr
       VARS      2
          u 8 99 U component
          v 8 99 V component
       ENDVARS

2. This simple example write out one variable:

          REAL  Z(72,46,16)
          ....
          OPEN(8,FILE='grads.dat',FORM='UNFORMATTED',
        & ACCESS='DIRECT',RECL=72*46)
          ....
          IREC=1
          DO 10 I=1,16
            WRITE (8,REC=IREC) ((Z(J,K,I),J=1,72),K=1,46)
            IREC=IREC+1
       10 CONTINUE

3. Another simple sample might be:

          REAL X(100)
          DO 10 I=1,100
            X(I)=I
       10 CONTINUE
          OPEN (8,FILE='samp.dat',FORM='UNFORMATTED',ACCESS='DIRECT',
         &RECL=100)
          WRITE (8,REC=1) X
          STOP
          END

   The associated descriptor file:

       DSET      samp.dat
       TITLE     Sample Data Set
       UNDEF    -9.99E33
       XDEF     100 LINEAR 1 1
       YDEF     1 LINEAR 1 1
       ZDEF      1 LINEAR 1 1
       TDEF      1 LINEAR 1JAN2000 1DY
       VARS      1
       x  0  99  100 Data Points
       ENDVARS

   Once created, you can use this data set to experiment with GrADS data functions, such as:

   `display sin(x/50)`