Go to the previous, next section.

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_range

An array of two numbers specifying the minimum and maximum valid values for this variable. The type of each valid_range attribute should match the type of its variable.

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.

scale_factor

If present for a variable, the data are to be multiplied by this factor after the data are read by the application that accesses the data.

add_offset

If present for a variable, this number is to be added to the data after it is read by the application that accesses the data. If both scale_factor and add_offset attributes are present, the data are first scaled before the offset is added. The attributes scale_factor and add_offset can be used together to provide simple data compression to store low-resolution floating-point data as small integers in a netCDF file. When scaled data are written, the application should first subtract the offset and then divide by the scale factor.

When scale_factor and add_offset are used for packing, the associated variable (containing the packed data) is typically of type byte or short, whereas the unpacked values are intended to be of type float or double. The attributes scale_factor and add_offset should both be of the type intended for the unpacked data, e.g. float or double.

_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 and also to eliminate the duplicate writes that result from netCDF filling in missing data with its default fill value, only to be immediately overwritten by the programmer's preferred value. 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. See section Missing Values, for more information.

signedness

Used to indicate a nondefault interpretation of the signedness of integer values. By default, applications that deal with values should treat netCDF byte data as unsigned and netCDF short and long integer data as signed. If you declare a netCDF variable for storing bytes, and you intend that the values represent signed quantities, you should declare the variable attribute signedness with value "signed". Similarly, if you define a variable for an array of short or long integers and you intend that the values be interpreted as unsigned, it would be appropriate to define the variable attribute signedness = "unsigned". This attribute is ignored by the netCDF library, but applications may use it. Since there are no standard FORTRAN types corresponding to unsigned integers, FORTRAN programs that compute with or use the ordering of data values may need to handle this attribute.

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.

Go to the previous, next section.