<!--Copyright (C) 1988-2005 by the Institute of Global Environment and Society (IGES). See file COPYRIGHT for more information.-->
<html>
<head>
<title>GrADS Variable Formats</title>
<style type="text/css">
<!--
.style1 {
color: #990000;
font-style: italic;
}
-->
</style>
</head>
<body bgcolor="e0f0ff" text="#000000">
<h2>Variable Formats and Binary Data File Structure</h2>
<p>
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:
<ul>
<li><a href="aboutgriddeddata.html">About GrADS Gridded Data Sets</a>
<li><a href="descriptorfile.html">Elements of a GrADS Data Descriptor File</a>
</ul>
<p>
In a GrADS data descriptor file each variable declaration record
has the following syntax:
<p>
<ul><code><i>varname levs units description</i></code></ul>
<p>
The <a href="descriptorfile.html#VARS">VARS</a> section of <a
href="descriptorfile.html">Elements of a GrADS Data Descriptor
File</a> explains the general syntax of the variable declaration
record. This section goes into further detail on the use of the
<code><i>units</i></code> keyword to invoke some special features that
allow GrADS to read binary files that do not conform to the default
structure.
<p>
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).
<p>
If your binary data set was created or "packed" according to a
different dimension sequence, then you can use the
<code><i>units</i></code> keyword to tell GrADS exactly how to unpack
the data. The <code><i>units</i></code> keyword is actually a series
of one or more comma-delimited numbers. If <code><i>units</i></code>
is set to <code>99</code> then all the features for unpacking special
data formats are ignored. If <code><i>units</i></code> is set to
<code>-1</code>, then the features are invoked via additional
parameters that follow the <code>-1</code> and are separated by
commas:
<p>
<ul><code><i>units</i> = -1, <i>structure</i> <,arg></i></code></ul>
<p>
There are four options for <code><i>structure</i></code>, outlined
below. Some of these options have additional attributes which are
specified with <code><i>arg</i></code>.
<p>
<ol>
<li><code><i>units</i> = -1,10,1</code>
<p>
<span class="style1">This option was removed in GrADS version 2.0. </span>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.
<p>
This feature was designed to be used with NASA GCM data in the
"phoenix" format. The upper air <i>prognostic</i> variables were
transposed, but the <i>diagnostic</i> variables were not. Thus an
<code><i>arg</i></code> of <code>1</code> means the variable has been
var-z transposed, and an <code><i>arg</i></code> of <code>2</code>
means the variable has not.
<p class="style1">
<li><code><i>units</i> = -1,20</code>
<p>
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.
<p>
Suppose your data set is actually a collection of separate files that
are aggregated by using a <a href="templates.html">template</a>. Then
you must use an additional argument to tell GrADS how many time steps
are contained in each individual file. Use <code><i>arg</i></code> 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:
<p>
<ul>
<pre>
DSET ^monthlydata_%y4.dat
OPTIONS template
...
TDEF 120 linear jan79 1mo
VARS 3 <br>
u 18 -1,20,12 u component
v 18 -1,20,12 v component
t 18 -1,20,12 temperature
ENDVARS
</pre>
</ul>
<p>
<li><code><i>units</i> = -1,30</code>
<p>
<span class="style1">This option was removed in GrADS version 2.0. </span>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.
<p>
<li><code><i>units</i> = -1,40</code>
<p>
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 <code><i>arg</i></code>
tells GrADS what type of data values are in the binary file:
<p>
<ul>
<code><i>units</i> = -1,40,1 </code>
= 1-byte unsigned chars (0-255) <br>
<code><i>units</i> = -1,40,2 </code>
= 2-byte unsigned integers<br>
<code><i>units</i> = -1,40,-2 </code>
= 2-byte signed integers<br>
<code><i>units</i> = -1,40,4 </code>
= 4-byte integers<br>
</ul>
</ol>
</body>
</html>
