free grads

xdfopen

xdfopen filename

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 sdfopen command assumes all the metadata is internal to the self-describing file, whereas the xdfopen command allows the user to supplement or replace any internal metadata via a data descriptor file. In this way, xdfopen provides access to some self-describing files that do not comply with the COARDS conventions.

filename is the name of the data descriptor file that contains the supplemental metadata. It has a syntax very similar to the regular data descriptor files that are used with the open command. The few differences are noted below:  

1. DSET SDF_filename

   This is the only required entry. SDF_filename may be either the name of a netCDF or HDF-SDS file or a substitution template for a collection of netCDF or HDF-SDS files.

   Other than DSET, the only other data descriptor file entries that are supported are UNDEF, TITLE, XDEF, YDEF, ZDEF, TDEF, EDEF, OPTIONS, VARS, and ENDVARS. Valid arguments for the OPTIONS entry are: yrev, zrev, template, and 365_day_calendar.

   
   

2. XDEF, YDEF, ZDEF, TDEF, and EDEF:

   Each of these entries requires an additional argument, SDF_dimension_name, which comes before all the other arguments. The SDF_dimension_name is used to achieve dimension order independence, so it must be a real dimension in the SDF. The SDF_dimension_name string may be mixed case and should appear exactly as it is listed in the output from ncdump.

   If the coordinate variables in the SDF file exist and have the required metadata, then SDF_dimension_name is the only argument needed for the corresonding axis definition entry (XDEF, YDEF, ZDEF, TDEF, and EDEF) 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:
   edef <SDF_dimension_name> 
   edef <SDF_dimension_name> <size>
   edef <SDF_dimension_name> <size> names <list of names>

   
   

3. The first argument ("varname") of the variable definition lines that appear between VARS and ENDVARS has the following syntax:
   SDF_varname=>grads_varname

   SDF_varname 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 "=>" is omitted, then grads_varname must be identical to SDF_varname. This syntax (when "SDF_varname=>" is omitted) will only work properly in grads if SDF_varname 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 SDF_varname=>grads_varname is the only argument needed for the corresonding variable definition entry in the data descriptor file.

4. The order of the variable definition lines between VARS and ENDVARS is not important.

Usage Notes

1. If filename contains only the DSET entry, then xdfopen devolves into working just like sdfopen.
2. filename 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 filename will be looked for in the file's internal metadata.
3. The SDF_dimension_name 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.
4. For further information on the COARDS conventions, check out Conventions for the standardization of NetCDF files.
5. (GrADS version 2.0.a7.1+) The CHSUB entry will work with xdfopen.

Examples

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 this link to see output from ncdump for this file.

	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



	VARS 1



	TDEF dimension3 365 LINEAR 0Z01JAN1979 1DY



	Moisture=>moisture 1 99 Moisture



	ENDVARS

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 this link shows the output from running the HDF version of ncdump on DAOE054A.hdf. (Note that the output has been annotated with explanatory comments -- they are preceded with "//")

	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



	ENDVARS



	SPECIFICHUMIDITY=>shum 18 99 specific humidity



	TEMPERATURE=>temp 18 99 temperature