Go to the previous, next section, or Table of Contents.

EPS Implementation of Unidata NetCDF File Format

The EPS routines can be used to read and write a netCDF data file with the following restrictions:

• The time units must follow the Unidata udunits convention or other conventions discussed in this section.

• The spatial axes names and units must use those discussed in this section.

• The maximum dimension numbers of a variable must be 4 or less.

Refer to NetCDF User's Guide for details about the netCDF data format and EPIC netCDF General Conventions for detailed information about EPIC netCDF convnetions. In this section, we will discuss EPS implementation of Unidata netCDF file format.

Time Units and Formats

The input netCDF time axis will be converted into EPS (two-integer) time representation when the file is loaded into the internal database, and EPS time will be converted into user specified time format when writing out the file. Therefore, it is very important for EPS routines to recognize the time units and format in the input netCDF file as well as those defined by user when creating the netCDF file.

EPS routines can read and write time axes in following formats:

1. NetCDF Unidata udunits library supported time representation. The units attribute must be in the form of

             units = ``time-units since yyyy-mm-dd hh:mm:ss''
   

   where ``time-units'' is also the udunits library supported time units, and ``yyyy-mm-dd hh:mm:ss'' is the year-month-day hour:minute:second base time. If the base time is not provided, then the time base is assumed to be True Julian Day 0.

2. A local (non-standard) netCDF time representation. The units attribute and time_origin attribute must be in the form of

             units = ``time-units''
             time_origin = ``dd-MMM-yyyy hh:mm:ss''
   

   where ``time-units'' is the udunits library supported time units (upper cases are also accepted), and ``dd-MMM-yyyy hh:mm:ss'' is the day-month(first 3 characters)-year hour:minute: second base time.

3. EPS two-integer time representation When creating a netCDF file, if time units specified is none of the above two formats, then the time axis will be written in EPS two-integer time representation. The output time axis units attribute for the first integer will be ``True Julian Day'' and for the second integer will be ``msec since 0:00 GMT''. The time axis name for the second integer will be the (first) time axis name appended by ``2''.

   Here is an example of the output netCDF file time axis variable in this form:

           ......
           variables:
                   long time(time) ;
                        time:units = "True Julian Day" ;
                        ...
   
                   long time2(time)
                        time2:units = "msec since 0:00 GMT" ;
                        ...
           ......
    
   

   When reading a netCDF file, if attribute epic_code = 624 or the units attribute units= ``True Julian Day'' for the first time axis and units = ``msec since 0:00 GMT'' for the second time axis, where the second time axis name must be the first appended by a ``2''; then it will be read in as EPS time format.

The EPS routines will accept the upper case time units if the units is supported by udunits library after it is converted to lower case and the time axis name must start with "tim" (regardless the case). However, EPS routines will write out the time units all in lower case even it is defined in upper case by user.

As part of EPS library distribution, a utility program called ``tunits'' is available which lists the time units supported by Unidata udunits library.

Spatial Axis Names and Units

In order for EPS routines to read and write a netCDF correctly, the spatial axes must be defined in such a way that either the axis name, or axis ``units'' attribute, or axis ``epic_code'' attribute equals a value described in the following table. For the longitude axis, use of the West longitude axis convention is required for compatibility with the netCDF calculator function of PPLUS V1.2c (and earlier versions). The West longitude convention means that values of the longitude axis in the netCDF file are positive for West longitudes. In future releases of the netCDF calculator function of PPLUS, both East and West longitude conventions will be supported. The West longitude convention is described more completely in the Axis section of the EPS File Components chapter of this manual.

Spatial Axis Name, Units, and Epic_code Lookup Table

Dimension Numbers and Order

The dimension numbers for each variable in an EPS netCDF file must be 4 or less. When writing a new netCDF file, all variables will be created with 4 dimensions and in the order of (t, z, y, x) unless a unlimited axis is defined which will appear first. This is always true regardless how a variable is defined. A variable with number of dimension less than 4 will be filled up with ``dummy'' axes at time of writing, the value of 0 will be assigned and dimensions will be reordered if they are not in the right order. The EPS checks the axis direction based on its name, its epic_code attribute, or its units attribute. If an axis is not recognized as a spatial or time axis, it will be treated as a non-physical axis; in this case, the dimensions will be written in the order they are defined.

Variable Data Types

The current version of EPS routines only write out variables with data type EPBYTE (8-bit data), EPSHORT (16-bit integer), EPINT (32-bit integer) or EPREAL (32-bit float-point); and write out axis variables with data type either float or long integer. If an existing netCDF file has a double typed variable, EPS routine will not read the data; if a double typed axis variable is found, the EPS routine will read it and convert it into float type; in this case, some precision will be lost.

Go to the previous, next section, or Table of Contents.