NCL Home > Documentation > Language

Missing values in NCL

If an NCL variable has an attribute called _FillValue, then all values in your variable that are equal to the value of this attribute are considered missing values. The _FillValue attribute was originally used by the netCDF file format to represent missing values, and was adopted by NCL to mean the same thing.

The following are different examples of assigning the _FillValue attribute in NCL:

    x@_FillValue = -999           ; sets _FillValue to -999

    x@_FillValue = default_fillvalue("double") ; sets _FillValue to the default for a double;
                                             ; versions 6.0.0 or later

    x = new(5,double,1e20)        ; sets _FillValue to 1e20

    x@_FillValue = y@_FillValue

    assignFillValue(y,x)        ; sets x's _FillValue to y's _FillValue

Use of _FillValue in NCL functions

Many NCL functions automatically ignore any elements set to _FillValue. For example, in the NCL code snippet below:

    x = (/1., 2., 3., 4., 5./)
    print(avg(x))

    x@_FillValue = 5.
    print(avg(x))

The average of x is equal to 3.0 (15./5) without the _FillValue attribute set, and 2.5 (10./4) with the _FillValue attribute set.

Most graphical functions also recognize this attribute, and will not plot data equal to the _FillValue.

Default missing values

The following are the default settings for _FillValue by type. Note that the default missing values will be different in version 6.0.0, so both sets are listed here:

Variable type versions 5.2.x and earlier versions 6.x and later
byte* 0xff -127
short -99 -32767
ushort 0 65535
integer -999 -2147483647
uint 0 4294967295
long -9999 -2147483647
ulong 0 4294967295
int64 -99999999 -9223372036854775806
uint64 0 18446744073709551614
float -999 9.96921e+36
double -9999 9.969209968386869e+36
character* 0 0x00

* The missing values for bytes and characters are rather different. This is because in version 6.0.0, an NCL byte will go from being an unsigned byte to a signed byte, and an NCL character will go from being a signed byte to an unsigned byte. This change keeps us in line with the definition of a NetCDF byte and character as well.

missing_value attribute

An NCL variable may instead contain the user-defined attribute missing_value. This usually comes from having read the variable off a netCDF file that had this attribute set. Since NCL doesn't recognized this attribute, it will plot and/or perform calculations on values set to missing_value.

If you want NCL to recognize the missing_value values as missing values, it is necessary to rename this attribute:

    x@_FillValue = x@missing_value
    delete(x@missing_value)      ; not necessary, just cleaning up
Whenever _FillValue is assigned a new value, every occurrence in your data that was equal to the value specified by the old _FillValue will be set to the value specified by the new _FillValue. The delete> function is used to remove the missing_value attribute. This is not really necessary since NCL doesn't do anything special with this attribute. It does help to avoid possible confusion later in having both _FillValue and missing_value set.

You could have also used the assignFillValue function, since it recognizes both attributes as being valid missing values (_FillValue trumps missing_value if both are set).

_FillValue = 0

A note about _FillValue = 0: this is allowed, but not recommended. It will not work for contour plots; this is a low-level graphics issue.