<!--Copyright (C) 1988-2005 by the Institute of Global Environment and Society (IGES). See file COPYRIGHT for more information.-->
<html>
<head>
<title>GrADS Command: xdfopen</title>
<style type="text/css">
<!--
.style1 {color: #990000}
-->
</style>
</head>
<body bgcolor="e0f0ff" text="#000000">
<h2><b>xdfopen</b></h2>
<p>
<code>xdfopen <i>filename</i></code>
<p>
GrADS requires a certain amount of metadata in order to understand how
to read a NetCDF/HDF-SDS data file, also called a self-describing file
(SDF). The <a href="gradcomdsdfopen.html"><code>sdfopen</code></a>
command assumes all the metadata is internal to the self-describing
file, whereas the <code>xdfopen</code> command allows the user to supplement
or replace any internal metadata via a data descriptor file. In this
way, <code>xdfopen</code> provides access to some self-describing files
that do not comply with the
<a href="http://ferret.wrc.noaa.gov/noaa_coop/coop_cdf_profile.html">COARDS conventions</a>.
<p>
<code><i>filename</i></code> is the name of the data descriptor file that
contains the supplemental metadata. It has a syntax very similar to
the <a href="descriptorfile.html">regular data descriptor files </a>
that are used with the
<a href="gradcomdopen.html"><code>open</code></a> command.
The few differences are noted below:
<p>
<ol>
<li>
<code><a href="descriptorfile.html#DSET">DSET</a> <i>SDF_filename</i></code>
<p>
This is the only required entry. <code><i>SDF_filename</i></code>
may be either the name of a netCDF or HDF-SDS file or a <a
href="templates.html">substitution template</a> for a collection of
netCDF or HDF-SDS files.
<p>
Other than <code><a href="descriptorfile.html#DSET">DSET</a></code>,
the only other data descriptor file entries that are supported are
<code><a href="descriptorfile.html#UNDEF">UNDEF</a></code>,
<code><a href="descriptorfile.html#TITLE">TITLE</a></code>,
<code><a href="descriptorfile.html#XDEF">XDEF</a></code>,
<code><a href="descriptorfile.html#YDEF">YDEF</a></code>,
<code><a href="descriptorfile.html#ZDEF">ZDEF</a></code>,
<code><a href="descriptorfile.html#TDEF">TDEF</a></code>,
<code><a href="descriptorfile.html#EDEF">EDEF</a></code>,
<code><a href="descriptorfile.html#OPTIONS">OPTIONS</a></code>,
<code><a href="descriptorfile.html#VARS">VARS</a></code>, and
<code><a href="descriptorfile.html#ENDVARS">ENDVARS</a></code>.
Valid arguments for the
<a href="descriptorfile.html#OPTIONS"><code>OPTIONS</code></a> entry are:
<code>yrev, zrev, template,</code> and <code>365_day_calendar</code>.
<p>
<li>
<code><a href="descriptorfile.html#XDEF">XDEF</a></code>,
<code><a href="descriptorfile.html#YDEF">YDEF</a></code>,
<code><a href="descriptorfile.html#ZDEF">ZDEF</a></code>,
<code><a href="descriptorfile.html#TDEF">TDEF</a></code>, and
<code><a href="descriptorfile.html#EDEF">EDEF</a></code>:
<p>
Each of these entries requires an additional argument,
<code><i>SDF_dimension_name</i></code>, which comes before all the
other arguments. The <code><i>SDF_dimension_name</i></code> is used to
achieve dimension order independence, so it must be a real dimension
in the SDF. The <code><i>SDF_dimension_name</i></code> string may be
mixed case and should appear exactly as it is listed in the output
from ncdump.
<p>
If the coordinate variables in the SDF file exist and have the
required metadata, then <code><i>SDF_dimension_name</i></code> is the
only argument needed for the corresonding axis definition entry
(<code>XDEF, YDEF, ZDEF,</code> <code>TDEF, and EDEF</code>) in the data
descriptor file. If you need to supplement or override the coordinate metadata in the SDF file, you can fill out the axis definition entries in the descriptor file with the remaining arguments describing the size, linearity, start, and increment. For EDEF, there is support for three variations on the compact syntax of the EDEF entry:<br>
<code>edef <<i>SDF_dimension_name</i>> <br>
edef <<i>SDF_dimension_name</i>> <<em>size</em>><br>
edef <<i>SDF_dimension_name</i>> <<em>size</em>> names <<em>list of names</em>> </code>
<p>
<li>
The first argument ("<code><i>varname</i></code>") of the variable
definition lines that appear between <code><a
href="descriptorfile.html#VARS">VARS</a></code> and <code><a
href="descriptorfile.html#ENDVARS">ENDVARS</a></code> has the following syntax:<br>
<code><i>SDF_varname</i>=><i>grads_varname</i></code>
<p>
<code><i>SDF_varname</i></code> is the name of the variable as it appears
in the output from the NetCDF utility ncdump.
It may be of mixed case. If it includes blanks, substitute "~" for the blanks.
If everything up to and including the <code>"=>"</code> is omitted,
then <code><i>grads_varname</i></code> must be identical to
<code><i>SDF_varname</i></code>. This syntax (when
"<code><i>SDF_varname</i>=></code>" is omitted) will only work
properly in GrADS if <code><i>SDF_varname</i></code> is less than 15
characters and does not contain any upper case letters.
As it was with the coordinate variables, if the data variables in the
SDF file have the required metadata, then
<code><i>SDF_varname</i>=><i>grads_varname</i></code> is the only
argument needed for the corresonding variable definition entry in the
data descriptor file.
<li>The order of the variable definition lines between VARS
and ENDVARS is not important.
</ol>
<p>
<h3>Usage Notes</h3>
<ol>
<li>If <code><i>filename</i></code> contains only the DSET entry, then
<code>xdfopen</code> devolves into working just like
<a href="gradcomdsdfopen.html"><code>sdfopen</code></a>.
<li><code><i>filename</i></code> does not need to be a full data
descriptor file, it only needs to contain whatever metadata the SDF
file lacks. Anything not specified in <code><i>filename</i></code>
will be looked for in the file's internal metadata.
<li>The <code><i>SDF_dimension_name</i></code> parameter in the XDEF,
YDEF, ZDEF, TDEF, and EDEF entries and the first parameter of the VARIABLE
definition lines are the only parts of the data descriptor file that
aren't converted to lower case before they are interpreted.
<li>For further information on the COARDS conventions, check out <a
href="http://ferret.wrc.noaa.gov/noaa_coop/coop_cdf_profile.html">Conventions
for the standardization of NetCDF files</a>.
<li><span class="style1">(GrADS version 2.0.a7.1+) </span>The <a href="descriptorfile.html#CHSUB">CHSUB </a>entry will work with xdfopen.
</ol>
<h3>Examples </h3>
<p>This example shows the data descriptor file that would be required
in order to open a self-describing file that is missing much of the
required metadata. Below is the sample data descriptor file for the
NetCDF file moisture.nc. Follow <a href="xdfsample1.txt">this link</a>
to see output from ncdump for this file.
<pre>
DSET ^moisture.nc
TITLE This is a sample
UNDEF 99999.0
XDEF dimension1 144 LINEAR 0.0 2.5
YDEF dimension2 73 LINEAR 0.0 2.5
TDEF dimension3 365 LINEAR 0Z01JAN1979 1DY
VARS 1
Moisture=>moisture 1 99 Moisture
ENDVARS
</pre>
<p>
This second example comes from a real-world HDF-SDS file from the Data
Assimilation Office at NASA Goddard Space Flight Center. The data
descriptor file is shown below, and <a href="xdfsample2.txt">this
link</a> shows the output from running the HDF version of ncdump on
<code>DAOE054A.hdf</code>. (Note that the output has been annotated with
explanatory comments -- they are preceded with "//")
<pre>
DSET ^DAOE054A.hdf
TITLE This is only a test
OPTIONS YREV
UNDEF 1.0E15
XDEF XDim:DAOgrid 144 LINEAR -180.0 2.5
YDEF YDim:DAOgrid 91 LINEAR -90.0 2.0
ZDEF HGHT18DIMS:DAOgrid 18 LEVELS 1000 850 700 500 400 300 250 200 150 100 70 50 30 10 5 2 1 0.4
TDEF TIME4DIMS:DAOgrid 4 LINEAR 0Z31JUL1993 6HR
VARS 3
GEOPOTENTIAL_HEIGHT=>hgt 18 99 geopotential height
SPECIFICHUMIDITY=>shum 18 99 specific humidity
TEMPERATURE=>temp 18 99 temperature
ENDVARS
</pre>
</body>
</html>
