Unidata Registration of PMEL-EPIC netCDF Conventions NOAA Pacific Marine Environmental Laboratory Seattle, WA 24 November, 1993 This document describes the netCDF implementation utilized by NOAA's Pacific Marine Environmental Laboratory (PMEL) for use with the EPIC software package for oceanographic data. PMEL has developed the EPIC system library (EPS library), which is layered on top of the netCDF input/output library, to write netCDF files with the conventions described here. This library is not intended to provide the complete functionality which is available with the netCDF library, but rather to simplify production of a standardized implementation of netCDF for oceanographic data. It transparently provides support for some commonly used variations on the recommended standard implementation, and could be modified to provide support for others. With the use of this library, all application programs are independent of data file format, and formats other than the Unidata netCDF format can be supported by the addition of a set of "format dependent" routines to the "format dependent" layer of the library. At present, one other format is supported in addition to the netCDF format. Both EPIC and the EPS library, are available via anonymous ftp. Data files with the PMEL-EPIC conventions are compatible with the netCDF calculator function which PMEL uses in conjunction with the PPLUS graphics package. Simple examples including C and Fortran programs to read and write EPIC netCDF files, PPLUS scripts to read, plot, calculate and make animations from netCDF files, information about the interactions of PPLUS, the EPS library, EPIC and the TOGA-TAO Display software, and information about the commercially available PPLUS graphics package, are all included in the anonymous ftp directories. In addition, PMEL-EPIC netCDF files are compatible with the MATLAB netCDF interface (mexcdf) developed by USGS/WHOI, and available from USGS or from PMEL. HOST: csg.pmel.noaa.gov (192.68.161.12) DIRECTORY: anonymous/epic anonymous/eps anonymous/eps/examples anonymous/eps/pplus anonymous/tao/matlab HOST: crusty.er.usgs.gov (128.128.19.19) DIRECTORY: /pub/mexcdf This document (from the Unidata /pub/netcdf/Conventions/PMEL-EPIC directory on unidata.ucar.edu) describes the Conventions common to all PMEL-EPIC style netCDF data files. Please see the accompanying documents describing Conventions specific to specific data types: /pub/netcdf/Conventions/PMEL-EPIC/CTD/Conventions.CTD /pub/netcdf/Conventions/PMEL-EPIC/Time_Series/Conventions.Time_series =================== General Conventions =================== The EPIC system library is intended for reading and writing geophysical data, and assumes this data is represented by three spatial axes and one time axis. Each data file has dimensions, or axes, of longitude, latitude, depth and time. One or more of these axes may be collapsed to a single point, but four axes are always present. For example, data files containing oceanographic observational data, such as time series data or CTD profile data, may have latitude and longitude axes each consisting of a single point. Although we provide the ability to read netCDF files with fewer than four axes, we do not recommend this practice. Our underlying philosophy is that all geophysical data is located by longitude, latitude, depth and time, and if this information is not included as an axis, it must be included elsewhere within the data file, if the file is to be self-describing. ==== AXES ==== EPIC axis conventions are described here. These conventions are compatible with the netCDF calculator function which PMEL uses in conjunction with the PPLUS scientific graphics package. Geographic axes in a PMEL-EPIC netCDF file are, at present, described by a numeric variable code included as an attribute in the data file. There is a disk file named "epic.key" which contains all EPIC variable codes with other related information. The numeric variable code is a unique identifier for the variable or axis, and is described more fully in the section below on "VARIABLES". The use of the numeric variable code to define the axis is necessary for EPS libary V2.1 and earlier, and for PPLUS V1.2c and earlier. In future releases of both the EPS libarary and PPLUS, the use of an axis variable code may be replaced by the use of units from UDUNITS, and may no longer be required. Longitude axis -------------- Many longitude representations are possible, however, for compatability with the netCDF calculator function of PPLUS V1.2c (and earlier versions), use of the the West longitude convention is required. The West longitude convention, described in detail below, defines the numeric representation of the longitude axis in the netCDF file, with positive values for west longitudes. In future releases of the netCDF calculator function of PPLUS and also of the EPS library, both East and West longitude conventions will be supported. The recommended West longitude convention is described in the following paragraphs. We recommend that users represent the longitude axis with the West longitude convention. This means that western longitudes are positive numbers, for example, 170W is +170.0. Eastern longitudes can have either of two representations, both of which are supported by the EPS library, EPIC system application programs, and the PPLUS graphics system: 1. If the data being represented would best be described as continuous across the dateline, then east longitudes are written as (360.-long). EXAMPLE: 170E is written as 190.0. 2. If the data being represented would best be described as continuous across the Greenwich meridian, then east longitudes are written as (-long). EXAMPLE: 170E is written as -170. The units of the longitude axis in the EPIC system library routine call should be selected either from the Unidata netCDF's udunits.dat file, or the EPIC system key file (see the EPS manual). The default spatial axis data type is real number. The recommended units are degree_west (epic variable code 501). Latitude axis ------------- The recommended latitude convention is for north latitudes to be represented by positive numbers (e.g., 10N is +10.0), and south latitudes by negative numbers (e.g., 10S is -10.0). The units of the axis should be compatible with UDUNITS. The default spatial axis data type is real number. The recommended units are degree_north (epic variable code 500). Depth axis ---------- The depth axis should be given with the oceanographic convention of depth as a positive number, increasing downwards from the surface of the water towards the bottom of the ocean. The units of the axis should be compatible with UDUNITS. The default spatial axis data type is real number. Recommended units include dbar (pressure axis with epic variable code 1) or meters (depth axis with epic variable code 3). Although the EPS library and PPLUS will support depth as a negative number, decreasing from the surface towards the bottom of the ocean, EPIC system application programs do not support this convention. At present, only surface atmospheric data is being written to EPIC style netCDF data files. Conventions could be expanded to include this axis type, if desired, e.g., if upper air data is written in future, this axis could have the name "Height", with a corresponding epic variable code created to identify it uniquely. Time axis --------- The EPIC system library routines return the time axis from a data file to the calling routine in the form of a two-integer array, in which the first integer is the "True Julian Day Number" with units of days, and the second integer is the number of milliseconds since 0000 GMT of the True Julian Day. The True Julian Day (eg, May 23, 1968 is 2,400,000), used by astronomers, should not be confused with the "year-day" (eg, Feb 2 is year-day 33). The "year-day" is frequently called julian day (incorrectly) by oceanographers and meteorologists. Our double-dimensioned integer time word (word1=True Julian Day, word2=milliseconds since 0000 GMT of the True Julian Day) allows millisecond accuracy for time periods extending over centuries. There is a complete set of EPS routines for manipulation, calculation, and character string representation of this standard representation of time. The representation of the time axis within the data file can be of several types, for both read and write, including the UDUNITS standard, the two-integer array which is used internally by the EPS routines, and some other time representations which are supported for compatibility with other in-house software packages. Time axes can be written or read in either real or integer format. Note that, regardless of the format of the time axis in the netCDF data file itself, the values used internally by the EPIC system library will be the two-integer array. ========= VARIABLES ========= Each variable in an EPIC data file is described by a numeric variable code in the data file. There is a disk file named "epic.key" which contains the variable code and other related information about the variable. The numeric variable code is a unique identifier for the variable. Although the idea of a numeric code identifying the variable may seem at first unnecessary for netCDF files, there are several advantages to having a dependable variable identifier associated with the variables in the file. One reason is that it is unlikely that all the information about the variable will actually be included in the netCDF file (for example, exactly what algorithm was used to calculate salinity). Another reason is that it is difficult to build tools that will do complex tasks based on generic netCDF files. For example, salinity calculated by two different methods could be identified with two different numeric variable codes, but application software can be written to recognize both of these codes as a "salinity" value for use in the calculation of density. Therefore, we recommend that the variable codes be used to identify variables in the data file. Although the EPS library will write netCDF files which omit the numeric code entirely, this omission will result in a lack of information available to EPIC or other application programs. ========== ATTRIBUTES ========== There are standard attributes created by the EPS library for EPS files, as described in the following table, and additional attributes may be defined by the user as desired. ======================================================= Standard Attributes Automatically Written for EPS Files ======================================================= Category Attribute Name Type Comments ----------------------------------------------------------------------- global CREATION_DATE c File creation date and time Conventions c ** Name of Conventions used by the file,(eg. PMEL-EPIC/CTD) ----------------------------------------------------------------------- variable name c variable name long_name c variable long name generic_name c variable generic name FORTRAN_format c data Fortran format units c variable unit epic_code i variable code; write only when it is defined in epic.key file ----------------------------------------------------------------------- axis FORTRAN_format c axis data Fortran format units c axis unit type c axis data type epic_code i axis variable code; write only when it is defined in epic.key file ----------------------------------------------------------------------- NOTES: "i" is integer "c" is character ** The global attribute "Conventions" is not automatically written by EPS libary V2.1, or earlier, but will be written automatically by later releases of EPS. Similarly, standard global attributes are created for EPS data files containing specific types of oceanographic data (e.g., PMEL-EPIC/CTD and PMEL-EPIC/Time_Series). Additional global and variable attributes may be defined by the user as desired. The standard global attributes for each specific data type are described in the Conventions documents in those subdirectories of pub/netcdf/Conventions (eg, pub/netcdf/Conventions/PMEL-EPIC/CTD). Contact for more information: Nancy N. Soreide Phone: 206-526-6728 NOAA/PMEL/OCRD FAX: 206-526-6744 7600 Sand Point Way NE OMNET: TAO.PMEL Seattle, WA 98115 Internet: nns@noaapmel.gov