Reading NetCDF and HDF Files with GrADS
Data files in the NetCDF and HDF file formats are called self-describing files (SDF) because the data and metadata are packaged together in the same file. GrADS can read data NetCDF and HDF formatted files, as long as the data are on a regular grid. The HDF format is very general; the GrADS interface is limited to gridded data sets that fit into the internal 5-D lon/lat/lev/time/ensemble grid space. GrADS handles HDF4 Scientific Data Sets and (as of version 2.0.a7) some HDF5 files. In order to read the data in SDFs, GrADS needs a certain amount of metadata in order to place the data in the internal grid space. There are three ways to do this:
sdfopencommand to open the file. This requires the least amount of effort for the user -- simply provide the file name (or an OPeNDAP URL) and GrADS does the rest. If you use the sdfopen command to open your SDF, then all the metadata in the file that GrADS requires must conform to the COARDS conventions. The 'sdfopen' interface does not support the HDF5 format. If sdfopen doesn't work, then ...
xdfopencommand to open the file. This requires a bit more effort for the user -- you must write a data descriptor file to supplement or replace the existing metadata so that GrADS can understand it. The syntax of the descriptor file used with xdfopen is not exactly the same as that used in a descriptor file for gridded binary data -- see the documentation page for further details. The xdfopen command provides access to a greater number of SDFs, including many that do not conform to any known standard. The 'xdfopen' interface does not support the HDF5 format. If xdfopen doesn't work, then ...
opencommand to open the file. This requires the user to write a complete GrADS descriptor file to override all the metadata in the file. Guidance for composing a complete descriptor file for NetCDF, HDF-SDS, or HDF5 gridded data files is given below. Please also see the reference page Elements of a Data Descriptor File. The 'open' interface is recommended if you are templating large numbers of data files together, the data are pre-projected onto a non-lat/lon grid, the variables in the file have different undefined values, or the variables in the file have been packed in a non-standard way. The 'open' interface is the only way to read HDF5 files.
The data descriptor file is free format, which means the components of each record (line of text) are blank delimited and can appear in any order. Leading blanks at the beginning of each record are removed before parsing. Individual records may not be more than 255 characters long. Each record begins with a specific entry name, followed by a number of arguments or keywords, depending on the entry.
Descriptor file entries used for NetCDF, HDF-SDS, and HDF5 files are:
|DSET||This entry points to the data file. See the reference page for more details.|
|DTYPE||This entry should have either the 'netcdf' or 'hdfsds' keywords.
(GrADS version 2.0.a7+) For HDF5, use the 'hdf5_grid' keyword.
|TITLE||It is good general practice to include a descriptive title in every GrADS descriptor file.|
This entry specifies the undefined or missing data
value. An optional second argument is the name of the attribute in the
SDF that contains the undefined value. This should be used when individual
variables in the data file have different undefined values. After data
I/O, the missing values in the grid are converted from the variable undef
to the file-wide undef (the numerical value in the first argument of the
UNDEF record). Then it appears to GrADS that all variables have the same
undef value, even if they don't in the SDF. Attribute names are case sensitive,
and it is assumed that the name is identical for all variables in the
SDF. If the name given does not match any attributes, or if no name is
given, the file-wide undef value will be used.
entry is used for data variables that are 'packed' -- i.e. non-float data
that need to be converted to float by applying the following formula:
y = x * scale_factor + add_offset
Only the attribute name for the scale factor is required. If your SDF does not have an offset attribute, the 2nd argument may be omitted, and the offset will be assigned the default value of 0.0. Attribute names are case sensitive, and it is assumed that the names are identical for all variables in the netcdf or hdfsds data file. If the names given do not match any attributes, the scale factor will be assigned a value of 1.0 and the offset will be assigned a value of 0.0. The transformation of packed data is done after the undef test has been applied.
UNPACK scale_factor add_offset
UNPACK Slope Intercept
|OPTIONS||Valid keywords are 'yrev', 'zrev', 'template', and '365_day_calendar'.|
|CACHESIZE||(GrADS version 2.0.a8+) This entry overrides the default size of the cache for reading HDF5 or NetCDF4 files. It is not relevant for other data types. It should not be necessary to set the cache size explicitly unless the data file has especially large chunks. Please see the documentation on compression.|
|PDEF||(GrADS version 1.9b4+) This is used when the SDF contains data on a native projection other than lat/lon, such as a lambert conformal or polar stereographic grid. See the PDEF documentation for more information.|
|These entries are used to describe the coordinate dimensions in the SDF. The syntax is the same as for binary files. See the reference page for more details. You can use the output from ncdump with the -c option to get information about the coordinate dimensions in the SDF.|
This entry is for explicity identifying vector component pairs. The VECTORPAIRS entry is only necessary if the data are on a native projection other than lat/lon (i.e. you are using PDEF) and if the winds have to be rotated from a grid-relative sense to an Earth-relative sense. (GrADS has to retrieve both the u and v component in order to do the rotation calculation.)
The arguments are the U-component and V-component
variable names, separated by a comma, with no spaces. More than one
pair of components may be listed; in this case, the pairs should be separated
by a space.
The variable declarations in a SDF descriptor file have a few special features, described below. It is not necessary to include a variable declaration for all the variables in the SDF, only those you wish to read with GrADS.
The varname field has the following syntax:
The levs field is an integer that specifies the number of vertical levels the variable contains. Variables that do not have a Z dimension should have a levs value of 0. Variables that do have a Z dimension should have a levs value equal to the znum value specified in the ZDEF statement.
The units field is a comma-delimited list of the varying dimensions of the variable. The dimensions are expressed as x, y, z, t, and e and correspond to the five axes defined by XDEF, YDEF, ZDEF, TDEF, and EDEF. The order of the dimensions listed in the units field is important -- it must describe the shape of the variable as it was written to the SDF data file. For NetCDf files, this information appears in the output from ncdump next to the variable name. For HDF5 files, this information appears in the output from h5dump as the variable's dataspace.
VAR=>hist0 0 0,y,x
First historgram interval for VAR
VAR=>hist1 0 1,y,x Second historgram interval for VAR
VAR=>hist2 0 2,y,x Third histogram interval for VAR
Another option in this example would be to fill the unused Z axis with the histogram intervals:
ZDEF 3 linear 1 1
VAR=>hist 3 z,y,x VAR Histogram
In this case, it would appear to GrADS that variable 'hist' varies in Z, but the user would have to remember that the Z levels correspond to histogram intervals and not pressure levels. The latter technique makes it easier to slice through the data, but is not the most accurate representation. And if you don't have an unsued world-coordinate axis available, then you still have a way to access all the dimensions of your data variable.