<!--Copyright (C) 1988-2005 by the Institute of Global Environment and Society (IGES). See file COPYRIGHT for more information.-->
<html>
<head>
<title>GrADS Gridded Data</title>
</head>
<body bgcolor="e0f0ff" text="#000000">
<h1>About GrADS Gridded Data Sets</h1>
<p>
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:
<ul>
<li><a href="aboutgriddeddata.html#introduction">Introduction</a>
<li><a href="aboutgriddeddata.html#descriptor">The Data Descriptor File</a>
<li><a href="aboutgriddeddata.html#structure">Structure of a Gridded Binary Data File</a>
<li><a href="aboutgriddeddata.html#formats">Binary Formats</a>
<li><a href="aboutgriddeddata.html#create">Creating Data Files</a>
</ul>
<hr>
<p>
<h2><a name="introduction">Introduction</a></h2>
<p>
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 <b>data
descriptor file</b>. The data descriptor file has a default file extension of <code>.ctl</code>
and is therefore also referred to as a <b>control file</b>.
<p>
<code>ga-> <a href="gradcomdopen.html">open</a> <i>filename</i>.ctl</code>
<h2><a name="descriptor">The Data Descriptor File</a></h2>
<p>
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:
<ul>
<li>Filename for the binary data
<li>Missing or undefined data value
<li>Mapping between grid coordinates and world coordinates
<li>Description of variables in the binary data set
</ul>
<p>
The individual components of data descriptor files are discussed in
detail in the section <a href="descriptorfile.html">Elements of a Data
Descriptor File</a>.
<p> 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:
<p>
<ul>
<pre>
<a href="descriptorfile.html#DSET">DSET</a> ^gridded_data_sample.dat
<a href="descriptorfile.html#TITLE">TITLE</a> Gridded Data Sample
<a href="descriptorfile.html#UNDEF">UNDEF</a> -9.99E33
<a href="descriptorfile.html#XDEF">XDEF</a> 180 LINEAR 0.0 2.0
<a href="descriptorfile.html#YDEF">YDEF</a> 90 LINEAR -90 2.0
<a href="descriptorfile.html#ZDEF">ZDEF</a> 10 LEVELS 1000 850 700 500 400 300 250 200 150 100
<a href="descriptorfile.html#TDEF">TDEF</a> 4 LINEAR 0Z10apr1991 12hr
<a href="descriptorfile.html#VARS">VARS</a> 4
slp 0 99 sea level pressure
hgt 10 99 heights
temp 10 99 temperature
shum 6 99 specific humidity
<a href="descriptorfile.html#ENDVARS">ENDVARS</a>
</pre>
</ul>
<p>
In this example, the binary data set is named
<code>gridded_data_sample.dat</code> 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).
<p>
<h2><a name="structure">Structure of a Gridded Binary Data File</a></h2>
<p>
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.
<p>
GrADS views gridded data sets as multi-dimensional arrays varying in
longitude, latitude, vertical level, variable, and time. In version 2.0, a <a href="ensembles.html">fifth grid dimension</a> 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.
<p>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.
<p>
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).
<p>
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:
<ul>
<pre>
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.
</pre>
</ul>
<p>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) :
<ul>
<pre>
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
</pre>
</ul>
<h2><a name="formats">Binary Formats</a></h2>
<p>
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.
<p>
GrADS can also directly read GRIB formatted data -- one of GrADS
most powerful and unique features! See the section on
<a href="grib2ctl.html">Creating Data Descriptor Files for GRIB
Data</a> for more information.
<p>
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 <a
href="sdfdescriptorfile.html">reading NetCDF or HDF-SDS files</a>.
<p>
<h2><a name="create">Creating Data Files</a></h2>
<p>
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:
<ul><code><a href="descriptorfile.html#OPTIONS">OPTIONS</a> sequential</code></ul>
<p>
Following are three examples of how to create gridded binary data
files with simple FORTRAN programs.
<p>
<ol>
<li>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:
<p>
<pre>
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
</pre>
<p>
The data descriptor file would look something like:
<p>
<pre>
<a href="descriptorfile.html#DSET">DSET</a> ^model.dat
<a href="descriptorfile.html#TITLE">TITLE</a> Sample Model Data
<a href="descriptorfile.html#UNDEF">UNDEF</a> 0.10000E+16
<a href="descriptorfile.html#XDEF">XDEF</a> 144 linear 0 2.5
<a href="descriptorfile.html#YDEF">YDEF</a> 91 linear -90 2.0
<a href="descriptorfile.html#ZDEF">ZDEF</a> 8 levels 1000 900 800 700 500 300 100 50
<a href="descriptorfile.html#TDEF">TDEF</a> 4 linear 00z01apr85 6hr
<a href="descriptorfile.html#VARS">VARS</a> 2
u 8 99 U component
v 8 99 V component
<a href="descriptorfile.html#ENDVARS">ENDVARS</a>
</pre>
<p>
<li>This simple example write out one variable:
<p>
<pre>
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
</pre>
<p>
<li>Another simple sample might be:
<p>
<pre>
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
</pre>
<p>
The associated descriptor file:
<p>
<pre>
<a href="descriptorfile.html#DSET">DSET</a> samp.dat
<a href="descriptorfile.html#TITLE">TITLE</a> Sample Data Set
<a href="descriptorfile.html#UNDEF">UNDEF</a> -9.99E33
<a href="descriptorfile.html#XDEF">XDEF</a> 100 LINEAR 1 1
<a href="descriptorfile.html#YDEF">YDEF</a> 1 LINEAR 1 1
<a href="descriptorfile.html#ZDEF">ZDEF</a> 1 LINEAR 1 1
<a href="descriptorfile.html#TDEF">TDEF</a> 1 LINEAR 1JAN2000 1DY
<a href="descriptorfile.html#VARS">VARS</a> 1
x 0 99 100 Data Points
<a href="descriptorfile.html#ENDVARS">ENDVARS</a>
</pre>
<p>
Once created, you can use this data set to experiment with GrADS
data functions, such as:
<p>
<ul>
<code>
<a href="gradcomddisplay.html">display</a>
<a href="gradfuncsin.html"> sin</a>(x/50)
</code>
</ul>
</ol>
</body>
</html>
