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

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:

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:

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:

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

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:

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: