| • |
|
|
|
|||
|
||||
[Next] [Previous] [Top] [Contents] [Index] [netCDF Home Page] [Unidata Home Page]
NetCDF User's Guide for C
A netCDF dataset 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 datasets which are identified by dataset ID numbers, in addition to ordinary file names.
A netCDF dataset 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. Hence, these indices need not be stored separately (as in a relational database). This provides a fast and compact storage method.
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 datasets. The netCDF system includes utilities for producing human-oriented CDL text files from binary netCDF datasets and vice versa.
netcdf example_1 { // example of CDL notation for a netCDF dataset
dimensions: // dimension names and lengths 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 dataset can be generated automatically by using ncdump,
a utility program described later (see
Section 10.5 "ncdump," page 104). Another netCDF utility, ncgen,
generates a netCDF dataset (or optionally C or FORTRAN source code containing
calls needed to produce a netCDF dataset) from CDL input (see
Section 10.4 "ncgen," page 103).
The CDL notation is simple and largely self-explanatory. It will be explained
more fully as we describe the components of a netCDF dataset. 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 dataset 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 length. A dimension length
is an arbitrary positive integer, except that one dimension in a netCDF dataset
can have the length 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 dataset 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 the first dimension in corresponding C array declarations.
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
= length.
There are four dimensions
in the above example: lat, lon, level,
and time. The first three are assigned fixed lengths; time
is assigned the length UNLIMITED, which means it is the unlimited
dimension.
The basic unit of named data in a netCDF dataset 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 (but this was not possible in previous netCDF versions). For example,
correlation(instrument, instrument) could be a 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 length.
Variables are used to store the bulk of the data in a netCDF dataset. 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
external data type is one of a small set of netCDF types
that have the names NC_BYTE,
NC_CHAR,NC_SHORT,
NC_INT,NC_FLOAT,
and NC_DOUBLE
in the C interface. NC_LONG
is a deprecated synonym for NC_INT in the C interface.
In the CDL notation,
these types are given the simpler names byte,
char,
short, int,
float,
and double.
real may be used as a synonym for float in the CDL
notation. long
is a deprecated synonym for int. The exact meaning of
each of the types is discussed in Section
3.1 "netCDF external data types," page 15.
CDL
variable declarations appear after the variable 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 length (number of data
values) given by the product of its dimension lengths. The length of a record
variable is also the product of its dimension lengths, but in this case the
product is variable because it involves the length of the unlimited dimension,
which can vary. The length 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. Thus the 700 millibar level would have an index value of 2 in the example above.
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).
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 dataset 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 "global variable" ID (in C or Fortran).
An attribute has an associated variable (the null "global variable" 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 external type of
an attribute is specified when it is created. The types permitted for attributes
are the same as the netCDF external 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 int should be of type int,
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 10.3 "CDL Notation for Data Constants," page 102).
In the netCDF example (see Section 2.1.2 "network
Common Data Form Language (CDL)," page 9), 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 dataset.
This is a character array intended for documenting the data. Actual netCDF
datasets might have more global attributes to document the origin, history,
conventions, and other characteristics of the dataset as a whole.
Most generic
applications that process netCDF datasets assume standard attribute conventions
and it is strongly recommended that these be followed unless there are good
reasons for not doing so. See Section
8.1 "Attribute Conventions," page 81, 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 dataset long after it is first defined, so you don't have to anticipate all potentially useful attributes. However adding new attributes to an existing dataset can incur the same expense as copying the dataset. See Chapter 9 "NetCDF File Structure and Performance," page 95, 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.
[Next] [Previous] [Top] [Contents] [Index] [netCDF Home Page] [Unidata Home Page]
| Contact Us • Site Map • Search • Terms and Conditions • Privacy Policy • Participation Policy | ||||||
|
||||||
