A netCDF file contains dimensions, variables, and attributes, which all have both a name and an ID number by which they are identified. These components can be used together to capture the meaning of data and relations among data fields in an array-oriented dataset. The netCDF library allows simultaneous access to multiple netCDF files which are identified by file ID numbers, in addition to ordinary file names.
A netCDF file contains a symbol table for variables containing their name, data type, rank (number of dimensions), dimensions, and starting disk address. Each element is stored at a disk address which is a linear function of the array indices (subscripts) by which it is identified. This obviates the need for these indices to be stored, either as fields within records, or in an index to the records (as in a relational database). This provides a fast and compact storage method, unless there are many missing values.
The names of dimensions, variables and attributes consist of arbitrary sequences of alphanumeric characters (as well as underscore `_' and hyphen `-'), beginning with a letter or underscore. (However names commencing with underscore are reserved for system use.) Case is significant in netCDF names.
We will use a small netCDF example to illustrate the concepts of the netCDF data model. This includes dimensions, variables, and attributes. The notation used to describe this simple netCDF object is called CDL (network Common Data form Language), which provides a convenient way of describing netCDF files. The netCDF system includes utilities for producing human-oriented CDL text files from binary netCDF files and vice versa.
netcdf example_1 { // example of CDL notation for a netCDF file dimensions: // dimension names and sizes are declared first lat = 5, lon = 10, level = 4, time = unlimited; variables: // variable types, names, shapes, attributes float temp(time,level,lat,lon); temp:long_name = "temperature"; temp:units = "celsius"; float rh(time,lat,lon); rh:long_name = "relative humidity"; rh:valid_range = 0.0, 1.0; // min and max int lat(lat), lon(lon), level(level); lat:units = "degrees_north"; lon:units = "degrees_east"; level:units = "millibars"; short time(time); time:units = "hours since 1996-1-1"; // global attributes :source = "Fictional Model Output"; data: // optional data assignments level = 1000, 850, 700, 500; lat = 20, 30, 40, 50, 60; lon = -160,-140,-118,-96,-84,-52,-45,-35,-25,-15; time = 12; rh =.5,.2,.4,.2,.3,.2,.4,.5,.6,.7, .1,.3,.1,.1,.1,.1,.5,.7,.8,.8, .1,.2,.2,.2,.2,.5,.7,.8,.9,.9, .1,.2,.3,.3,.3,.3,.7,.8,.9,.9, 0,.1,.2,.4,.4,.4,.4,.7,.9,.9; }
The CDL notation for a netCDF file can be generated automatically by
using ncdump
, a utility program described later (see section ncdump).
Another netCDF utility, ncgen
, generates a netCDF file (or
optionally C or FORTRAN source code containing calls needed to produce a
netCDF file) from CDL input (see section ncgen).
The CDL notation is simple and largely self-explanatory. It will be explained more fully as we describe the components of a netCDF file. For now, note that CDL statements are terminated by a semicolon. Spaces, tabs, and newlines can be used freely for readability. Comments in CDL follow the characters `//' on any line. A CDL description of a netCDF file takes the form
netCDF name { dimensions: ... variables: ... data: ... }
where the name is used only as a default in constructing file names
by the ncgen
utility. The CDL description
consists of three optional parts, introduced by the keywords
dimensions
, variables
, and data
. NetCDF dimension
declarations appear after the dimensions
keyword, netCDF
variables and attributes are defined after the variables
keyword,
and variable data assignments appear after the data
keyword.
A dimension may be used to represent a real physical dimension, for example, time, latitude, longitude, or height. A dimension might also be used to index other quantities, for example station or model-run-number.
A netCDF dimension has both a name and a size.
A dimension size is an arbitrary positive integer, except that
one dimension in a netCDF file can have the size UNLIMITED
.
Such a dimension is called the unlimited dimension or the record dimension. A variable with an unlimited dimension can grow to any length along that dimension. The unlimited dimension index is like a record number in conventional record-oriented files. A netCDF file can have at most one unlimited dimension, but need not have any. If a variable has an unlimited dimension, that dimension must be the most significant (slowest changing) one. Thus any unlimited dimension must be the first dimension in a CDL shape (and first in C declarations, but last in FORTRAN).
CDL dimension declarations may appear on one or more lines following the
CDL keyword dimensions
. Multiple dimension declarations on the
same line may be separated by commas. Each declaration is of the form
name = size.
There are four dimensions in the above example: lat
, lon
,
level
, and time
. The first three are assigned
fixed sizes; time
is assigned the size UNLIMITED
, which means
it is the unlimited dimension.
The basic unit of named data in a netCDF file is a variable. When a variable is defined, its shape is specified as a list of dimensions. These dimensions must already exist.
The number of dimensions is called the rank (a.k.a. dimensionality). A scalar variable has rank 0, a vector has rank 1 and a matrix has rank 2.
It is possible to use the same dimension more than once in specifying a
variable shape.
For example, correlation(instrument, instrument)
could be a correlation matrix
giving correlations between measurements using different instruments.
But data whose dimensions correspond to those of physical space/time
should have a shape comprising
different dimensions, even if some of these have the same size.
Variables are used to store the bulk of the data in a netCDF file. A variable represents an array of values of the same type. A scalar value is treated as a 0-dimensional array. A variable has a name, a data type, and a shape described by its list of dimensions specified when the variable is created. A variable may also have associated attributes, which may be added, deleted or changed after the variable is created.
A variable data type is one of a small set of netCDF types that
have the names NC_BYTE
, NC_CHAR
, NC_SHORT
,
NC_LONG
, NC_FLOAT
, and NC_DOUBLE
in the C interface
and the corresponding names NCBYTE
, NCCHAR
, NCSHORT
,
NCLONG
, NCFLOAT
, and NCDOUBLE
in the
FORTRAN interface. In the CDL notation, these types are given the
simpler names byte
, char
, short
, long
,
float
, and double
. int
may be used as a synonym
for long
and real
may be used as a synonym for
float
in the CDL notation. We will postpone a discussion of the
exact meaning of each of the types until
section NetCDF Data Types.
CDL variable declarations appear after the variables
keyword in
a CDL unit. They have the form
type variable_name ( dim_name_1, dim_name_2, ... ) ;
for variables with dimensions, or
type variable_name ;
for scalar variables.
In the above CDL example there are six variables. As discussed below, four of
these are coordinate variables.
The remaining variables (sometimes called primary variables),
temp
and rh
, contain what is usually thought of as the
data. Each of these variables has the unlimited dimension time
as its first dimension, so they are called record variables. A
variable that is not a record variable has a fixed size (number of data
values) given by the product of its dimension sizes.
The size of a record variable is also the product of its dimension sizes,
but in this case the product is variable because it involves
the size of the unlimited dimension, which can vary.
The size of the unlimited dimension is the number of records.
It is legal for a variable to have the same name as a dimension. Such variables have no special meaning to the netCDF library. However there is a convention that such variables should be treated in a special way by software using this library.
A variable with the same name as a dimension is called a coordinate
variable.
It typically defines a physical coordinate corresponding to that dimension.
The above CDL example includes the coordinate variables lat
, lon
,
level
and time
, defined as follows:
int lat(lat), lon(lon), level(level); short time(time); ... data: level = 1000, 850, 700, 500; lat = 20, 30, 40, 50, 60; lon = -160,-140,-118,-96,-84,-52,-45,-35,-25,-15; time = 12;
These define the latitudes, longitudes, barometric pressures and times corresponding to positions along these dimensions. Thus there is data at altitudes corresponding to 1000, 850, 700 and 500 millibars; and at latitudes 20, 30, 40, 50 and 60 degrees north. Note that each coordinate variable is a vector and has a shape consisting of just the dimension with the same name.
A position along a dimension can be specified using an index. This is an integer with a minimum value of 0 for C programs and 1 for FORTRAN. Thus the 700 millibar level would have an index value of 2 for C and 3 for FORTRAN.
If a dimension has a corresponding coordinate variable, then this provides an alternative, and often more convenient, means of specifying position along it. Current application packages that make use of coordinate variables commonly assume they are numeric vectors and strictly monotonic (all values are different and either increasing or decreasing). There are plans to define more general conventions to allow such things as text labels as values of coordinate variables.
NetCDF attributes are used to store data about the data (ancillary data or metadata), similar in many ways to the information stored in data dictionaries and schema in conventional database systems. Most attributes provide information about a specific variable. These are identified by the name (or ID) of that variable, together with the name of the attribute.
Some attributes provide information about the file as a whole and are called global attributes. These are identified by the attribute name together with a blank variable name (in CDL) or a special null variable ID (in C or Fortran).
An attribute has an associated variable (null for a global attribute), a name, a data type, a length, and a value. The current version treats all attributes as vectors; scalar values are treated as single-element vectors.
Conventional attribute names should be used where applicable. New names should be as meaningful as possible.
The type of an attribute is specified when it is created. The types
permitted for attributes are the same as the netCDF data types
for variables. Attributes with the same name for different
variables should sometimes be of different types. For example, the
attribute valid_max
specifying the maximum valid data value for a
variable of type long
should be of type long
, whereas the
attribute valid_max
for a variable of type double
should
instead be of type double
.
Attributes are more dynamic than variables or dimensions; they can be deleted and have their type, length, and values changed after they are created, whereas the netCDF interface provides no way to delete a variable or to change its type or shape.
The CDL notation for defining an attribute is
variable_name:attribute_name = list_of_values ;
for a variable attribute, or
:attribute_name = list_of_values ;
for a global attribute. The type and length of each attribute are not explicitly declared in CDL; they are derived from the values assigned to the attribute. All values of an attribute must be of the same type. The notation used for constant values of the various netCDF types is discussed later (see section CDL Notation for Data Constants).
In the netCDF example (see section Components of a NetCDF File), units
is an attribute for the variable lat
that has a
13-character array value `degrees_north'. And valid_range
is an
attribute for the variable rh
that has length 2 and values
`0.0' and `1.0'.
One global attribute---source
---is defined
for the example netCDF file. This is a character array intended for
documenting the data. Actual netCDF files might have more global
attributes to document the origin, history, conventions, and other
characteristics of the file as a whole.
Most generic applications that process netCDF files assume
standard attribute conventions and it is strongly recommended that these
be followed unless there are good reasons for not doing so.
See section Attribute Conventions, for information about units
,
long_name
, valid_min
, valid_max
,
valid_range
, scale_factor
, add_offset
,
_FillValue
, and other conventional attributes.
Attributes may be added to a netCDF file long after it is first defined, so you don't have to anticipate all potentially useful attributes. However adding new attributes to an existing file can incur the same expense as copying the file. See section NetCDF File Structure and Performance, for a more extensive discussion.
In contrast to variables, which are intended for bulk data, attributes are intended for ancillary data, or information about the data. The total amount of ancillary data associated with a netCDF object, and stored in its attributes, is typically small enough to be memory-resident. However variables are often too large to entirely fit in memory and must be split into sections for processing.
Another difference between attributes and variables is that variables may be multidimensional. Attributes are all either scalars (single-valued) or vectors (a single, fixed dimension).
Variables are created with a name, type, and shape before they are assigned data values, so a variable may exist with no values. The value of an attribute must be specified when it is created, so no attribute ever exists without a value.
A variable may have attributes, but an attribute cannot have attributes.
Attributes assigned to variables may have the same units as the variable
(for example, valid_range
) or have no units (for example,
scale_factor
). If you want to store data that
requires units different from those of the associated variable, it is
better to use a variable than an attribute. More generally, if data
require ancillary data to describe them, are multidimensional, require
any of the defined netCDF dimensions to index their values, or require a
significant amount of storage, that data should be represented using
variables rather than attributes.
Go to the first, previous, next, last section, table of contents.