10 Feb 1995 - version 1.0
13 Mar 1995 - minor editorial repairs
01 May 1995 - added links, convention note
University participants:
NOAA participants:
This standard is a set of conventions adopted in order to promote the interchange and sharing of files created with the netCDF Application Programmer Interface (API). This standard is based upon version 2.3 of netCDF. Documentation of the netCDF API may be found in the "NetCDF Users' Guide, Version 2.3, April 1993 available from URL http://www.unidata.ucar.edu/packages/netcdf/ or via anonymous ftp at ftp.unidata.ucar.edu. All conventions named in that document will be adhered to in this standard unless noted to the contrary.
This standard also refers to version 1.7.1 of the udunits standard supported by Unidata. The udunits package is available via anonymous ftp at ftp.unidata.ucar.edu. Included in the udunits package is a file, udunits.dat, which lists collections of unit names. The names given therein and their plural forms will be regarded as acceptable unit names for this standard with the following additions and deletions:
The udunits package also supports linear transformation of all units through the syntax "scale_factor unit_name@offset", for example, "0.0005 degC@40000". This syntax, however, is not supported by this standard.
These conventions have been registered with Unidata as the COARDS conventions and are available at ftp://ftp.unidata.ucar.edu/pub/netcdf/Conventions/COARDS
File Name:
NetCDF files should have the file name extension ".nc".
Coordinate Variables:
1-dimensional netCDF variables whose dimension names are identical to
their variable names are regarded as "coordinate variables" (axes of
the underlying grid structure of other variables defined on this
dimension).
Global attributes:
Although not mandatory the attribute "history" is recommended to
record the evolution of the data contained within a netCDF file.
Applications which process netCDF data can append their information to
the history attribute.
The optional attribute "Conventions" is recommended to reference the COARDS conventions, registered with Unidata, and available via ftp at
directory: pub/netcdf/Conventions/COARDS host: ftp.unidata.ucar.edu
The attribute has this value:
:Conventions = "COARDS"; // Cooperative Ocean/Atmosphere Research Data Service
Units attribute:
A character array that specifies the units used for the variable's
data. Where possible the units attribute should be formatted as per
the recommendations in the Unidata udunits package.
Other attributes:
A file will normally contain many attributes that are not standardized
in this profile. Those attributes do not represent a violation of
this standard in any way. Application programs should ignore
attributes that they do not recognize.
Variable names:
Variable names should begin with a letter and be composed of letters,
digits, and underscores. It is recommended
that variable names be case-insensitive implying that the same
case-insensitive name should not be used for multiple variables within
a single file.
Rectilinear coordinate systems, only:
The space/time locations of points within the netCDF variables
should be the simple ordered tuples formed by associating values from
their coordinate axes. Thus, for example, curvilinear coordinate
systems in which the coordinate locations must be inferred from other
non-coordinate variables or from an equation are not standardized
by this netCDF profile.
Number of dimensions:
All netCDF variables will be defined on either one, two ,three, or
four dimensions (the nature of the data will dictate the natural
encoding). Where it makes sense single point locations should be
encoded as coordinate variables, for example, the latitude and
longitude positions of a vertical profile are natural candidates for
single point latitude and longitude coordinate variables.
If it is necessary to create a netCDF file
with more than 4 dimensions it is recommended that the additional
dimension(s) be added "to the left" of the space and time dimensions
as represented in CDL. For example
float my_variable(param_value,time,height,lat,lon);would be the recommended representation of a fifth, parameter value, coordinate.
Coordinate variable names:
The names of coordinate variables are not standardized by these
conventions (since data sets may in general contain multiple
coordinate variables of the same orientation). Coordinate variable
names should follow the same general naming rules (above) as other netCDF
variables.
Order of dimensions:
If any or all of the dimensions of a variable have the
interpretations of "date or time" (a.k.a. "T"), "height or depth"
(a.k.a. "Z"), "latitude" (a.k.a. "Y"), or "longitude" (a.k.a. "X") then
those dimensions should appear in the relative order T, then Z, then
Y, then X in the CDL definition corresponding to the file.
Data type:
The data type of coordinate and non-coordinate variables is
unrestricted (byte, short, long, float, and double are all acceptable
data types). Although not forbidden by this
standard the data type "char", which is functionally identical to
"byte", is not recommended as netCDF has reserved the option to modify
its behavior in future versions.
Coordinate value ordering:
The coordinate values of a coordinate variable must be either
monotonically increasing or monotonically decreasing. However, the
coordinate values need not be evenly spaced. Missing values are not permitted in coordinate variables.
Coordinate Variable
Attributes:
If a coordinate variable contains
longitude, latitude, depth, elevation, date, or time values then the
units attribute is mandatory; it is used to determine the orientation
of the coordinate variable. The long_name attribute is optional but
may be used to enhance clarity and the self-describing nature of the
netCDF file. Since coordinate variables may not contain missing
values the attributes _FillValue and missing_value may not be used
with coordinate variables.
Time or date dimension:
Coordinate variables representing time must always explicitly include
the units attribute; there is no default value.
A time coordinate variable will be identifiable by its units, alone.
The units attribute will be of character type with the string formatted
as per the recommendations in the Unidata udunits package version 1.7.1.
The following
excerpt from the udunits documentation explains the time unit
encoding by example:
The specification:
seconds since 1992-10-8 15:15:42.5 -6:00
indicates seconds since October 8th, 1992 at 3 hours, 15 minutes and 42.5 seconds in the afternoon in the time zone which is six hours to the west of Coordinated Universal Time (i.e. Mountain Daylight Time). The time zone specification can also be written without a colon using one or two-digits (indicating hours) or three or four digits (indicating hours and minutes).
The acceptable units for time are listed in the file udunits.dat. The
most commonly used of these strings (and their abbreviations) includes
day (d), hour (hr, h), minute (min), second (sec, s), year
(yr). Plural forms are also acceptable. The date string may include
date alone; date and time; or date, time, and time zone.
It is recommended that the unit "year" not be used as a unit of time.
Year is an ambiguous unit as years are of varying length. Udunits
defines a year as exactly 365 days.
A time coordinate variable is identifiable from its units string, alone. The udunits routines utScan and utIsTime can be used to make this determination. (*Note that at the time of this writing the author of this draft profile had not tested these routines personally.)
Climatological time:
Coordinate variables representing
climatological time (an axis of 12 months, 4 seasons, etc. that is
located in no particular year) should be encoded like other time axes
but with the added restriction that they be encoded to begin in the
year 0000. (Note - at the time of this writing this encoding has not been
tested with the udunits package.)
Vertical (height or depth) dimension:
Coordinate variables representing height or depth must
always explicitly include the units attribute; there is no default
value for the units attribute. The units attribute will be of
character type.
The acceptable units for vertical (depth or height) coordinate variables are
The direction of positive, whether up or down, cannot in all cases be inferred from the units. The direction of positive is useful for applications displaying the data. For this reason the new attribute positive is defined in this standard. The inclusion of the positive attribute is required by this standard if the vertical axis units are not a valid unit of pressure (a determination which can be made using the udunits routine, utScan) -- otherwise its inclusion is optional. The positive attribute may have the value "up" or "down" (case insensitive).
For example, if an oceanographic netCDF file encodes the depth of the surface as 0 and the depth of 1000 meters as 1000 then the axis would use attributes as follows:
axis_name:units="meters";
axis_name:positive="down";
If, on the other hand, the depth of 1000 meters were represented as -1000 then the value of the positive attribute would have been "up". If the units attribute value is a valid pressure unit the default value of the positive attribute is "down".
A vertical coordinate variable will be identifiable by
The recommended unit of latitude is "degrees_north". Also acceptable are "degree_north", "degree_N", and "degrees_N".
A latitude coordinate variable is identifiable from its units string, alone. The udunits routines utScan can be used to make this determination. (Note that at the time of this writing the author of this draft profile had not tested these routines personally.)
Longitude dimension:
Coordinate variables representing longitudes must always explicitly
include the units attribute; there is no default value for the units
attribute. The units attribute will be of character type with the
string formatted as per the recommendations in the Unidata udunits
package.
The recommended unit of longitude is "degrees_east" (eastward positive). Also acceptable are "degree_east", "degree_E", and "degrees_E". The unit "degrees_west" (westward positive) is not recommended because it implies a negative conversion factor from degrees_east.
Longitudes may be represented modulo 360. Thus, for example, -180, 180, and 540 are all valid representations of the International Dateline and 0 and 360 are both valid representations of the Prime Meridian. Note, however, that the sequence of numerical longitude values stored in the netCDF file must be monotonic in a non-modulo sense.
A longitude coordinate variable is identifiable from its units string, alone. The udunits routines utScan can be used to make this determination. (Note that at the time of this writing the author of this draft profile had not tested these routines personally.)
The CDL file contains the following elements: