Attribute Conventions

Generic applications that take netCDF files as input may by convention expect certain variable and global attributes. A few other attributes are handled in special ways by the netCDF library (these reserved attributes will have names that begin with a leading underscore character `_'). If you want to be able to use generic applications with your files, you should use the following conventional names for these commonly used attributes:

units

A character array that specifies the units used for the variable's data. A standard for conventional ways to name units in each specific discipline should be used, if available. Unidata has developed a freely-available library of routines to convert between character string and binary forms of unit specifications and to perform various useful operations on the binary forms. This library is used in some netCDF applications. Using the recommended units syntax permits data represented in conformable units to be automatically converted to common units for algebraic operations. See section Units, for more information.

long_name

A long descriptive name. This could be used for labelling plots, for example. If a variable has no long_name attribute assigned, the variable name will be used as a default.

valid_min

valid_max

One or both of these may be used instead of valid_range; this handles the case where it only makes sense to bound the data below or above.

_FillValue

If a scalar attribute with this name is defined for a variable and is of the same type as the variable, it will be subsequently used as the fill value for that variable. The purpose of this attribute is to save the applications programmer the work of prefilling the data This value is considered to be a special value that indicates missing data, and is returned when reading values that were not written. The missing value should be outside the range specified by valid_range for a variable. It is not necessary to define your own _FillValue attribute for a variable if the default fill value for the type of the variable is adequate. Note that if you change the value of this attribute, the changed value only applies to subsequent writes; previously written data are not changed. See section Missing Values, for more information.

missing_value

missing_value is a conventional name for a missing value that will not be treated in any special way be the library, as the _FillValue attribute is. It is also useful when it is necessary to distinguish between two kinds of missing values. For example, _FillValue might be useful to indicate data that was expected but did not appear, whereas missing_value might be used to indicate grid regions that are not intended to contain data.

C_format

A character array for the format that should be used to print values for this variable by C applications. For example, if you know a variable is only accurate to three significant digits, it would be appropriate to define the C_format attribute as "%.3g". The ncdump utility program uses this attribute for variables for which it is defined.

FORTRAN_format

A character array for the format that should be used to print values for this variable by FORTRAN applications.

 

title

A global attribute that is a character array providing a succinct description of what is in the data set.

 

history

A global attribute that is a character array with a line for each invocation of a program and arguments that were used to derive the file. Well-behaved generic netCDF filters (programs that take netCDF files as input and produce netCDF files as output) will automatically append their name and the parameters with which they were invoked to the global history attribute of an input netCDF file.

Differences between Attributes and Variables

In contrast to variables, which are intended for bulk data, attributes are intended for ancillary data, or information about the data. Typically the data in variables of an open netCDF will reside on disk, because the data are too large to fit in memory all at once. In contrast, the total amount of ancillary data associated with a netCDF object and stored in its attributes is typically small enough to be memory-resident.

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.

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 attribut