cfdm.Field.apply_masking

Field.apply_masking(inplace=False)[source]

Apply masking as defined by the CF conventions.

Masking is applied to the field construct data as well as metadata constructs’ data.

Masking is applied according to any of the following criteria that are applicable:

  • where data elements are equal to the value of the missing_value property;

  • where data elements are equal to the value of the _FillValue property;

  • where data elements are strictly less than the value of the valid_min property;

  • where data elements are strictly greater than the value of the valid_max property;

  • where data elements are within the inclusive range specified by the two values of valid_range property.

If any of the above properties have not been set the no masking is applied for that method.

Elements that are already masked remain so.

Note

If using the apply_masking method on a construct that has been read from a dataset with the mask=False parameter to the read function, then the mask defined in the dataset can only be recreated if the missing_value, _FillValue, valid_min, valid_max, and valid_range properties have not been updated.

New in version (cfdm): 1.8.3

See also

Data.apply_masking, read, write

Parameters
inplace: bool, optional

If True then do the operation in-place and return None.

Returns
Field or None

A new field construct with masked values, or None if the operation was in-place.

Examples

>>> f = cfdm.example_field(0)
>>> f.data[[0, -1]] = numpy.ma.masked
>>> print(f.data.array)
[[   --    --    --    --    --    --    --    --]
 [0.023 0.036 0.045 0.062 0.046 0.073 0.006 0.066]
 [0.11  0.131 0.124 0.146 0.087 0.103 0.057 0.011]
 [0.029 0.059 0.039 0.07  0.058 0.072 0.009 0.017]
 [   --    --    --    --    --    --    --    --]]
>>> cfdm.write(f, 'masked.nc')
>>> no_mask = cfdm.read('masked.nc', mask=False)[0]
>>> print(no_mask.data.array)
[9.96920997e+36, 9.96920997e+36, 9.96920997e+36, 9.96920997e+36,
 9.96920997e+36, 9.96920997e+36, 9.96920997e+36, 9.96920997e+36],
 [0.023 0.036 0.045 0.062 0.046 0.073 0.006 0.066]
 [0.11  0.131 0.124 0.146 0.087 0.103 0.057 0.011]
 [0.029 0.059 0.039 0.07  0.058 0.072 0.009 0.017]
[9.96920997e+36, 9.96920997e+36, 9.96920997e+36, 9.96920997e+36,
 9.96920997e+36, 9.96920997e+36, 9.96920997e+36, 9.96920997e+36]])
>>> masked = no_mask.apply_masking()
>>> print(masked.data.array)
[[   --    --    --    --    --    --    --    --]
 [0.023 0.036 0.045 0.062 0.046 0.073 0.006 0.066]
 [0.11  0.131 0.124 0.146 0.087 0.103 0.057 0.011]
 [0.029 0.059 0.039 0.07  0.058 0.072 0.009 0.017]
 [   --    --    --    --    --    --    --    --]]