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 four different examples of assigning the _FillValue attribute in NCL:

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

    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:

    logical   : -1
    byte      : 0xff (hex), 0377 (octal)
    short     : -99
    integer   : -999
    long      : -9999
    float     : -999
    double    : -9999
    graphic   : -9999
    file      : -9999
    character : 0 or '\0' for those who know C
    string    : "missing"

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 perfectly allowed for all calculations and plots except for contour plots. This is a low-level graphics issue.