cfdm.Data.apply_masking

Data.apply_masking(fill_values=None, valid_min=None, valid_max=None, valid_range=None, inplace=False)[source]

Apply masking.

Masking is applied according to the values of the keyword parameters.

Elements that are already masked remain so.

New in version (cfdm): 1.8.2

See also

get_fill_value, mask

Parameters
fill_values: bool or sequence of scalars, optional

Specify values that will be set to missing data. Data elements exactly equal to any of the values are set to missing data.

If True then the value returned by the get_fill_value method, if such a value exists, is used.

Zero or more values may be provided in a sequence of scalars.

Parameter example:

Specify a fill value of 999: fill_values=[999]

Parameter example:

Specify fill values of 999 and -1.0e30: fill_values=[999, -1.0e30]

Parameter example:

Use the fill value already set for the data: fill_values=True

Parameter example:

Use no fill values: fill_values=False or fill_value=[]

valid_min: number, optional

A scalar specifying the minimum valid value. Data elements strictly less than this number will be set to missing data.

valid_max: number, optional

A scalar specifying the maximum valid value. Data elements strictly greater than this number will be set to missing data.

valid_range: (number, number), optional

A vector of two numbers specifying the minimum and maximum valid values, equivalent to specifying values for both valid_min and valid_max parameters. The valid_range parameter must not be set if either valid_min or valid_max is defined.

Parameter example:

valid_range=[-999, 10000] is equivalent to setting valid_min=-999, valid_max=10000

inplace: bool, optional

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

Returns
Data or None

The data with masked values. If the operation was in-place then None is returned.

Examples

>>> d = cfdm.Data(numpy.arange(12).reshape(3, 4), 'm')
>>> d[1, 1] = cfdm.masked
>>> print(d.array)
[[0  1  2  3]
 [4 --  6  7]
 [8  9 10 11]]

>>> print(d.apply_masking().array)
[[0  1  2  3]
 [4 --  6  7]
 [8  9 10 11]]
>>> print(d.apply_masking(fill_values=[0]).array)
[[-- 1 2 3]
 [4 -- 6 7]
 [8 9 10 11]]
>>> print(d.apply_masking(fill_values=[0, 11]).array)
[[-- 1 2 3]
 [4 -- 6 7]
 [8 9 10 --]]

>>> print(d.apply_masking(valid_min=3).array)
[[-- -- -- 3]
 [4 -- 6 7]
 [8 9 10 11]]
>>> print(d.apply_masking(valid_max=6).array)
[[0 1 2 3]
 [4 -- 6 --]
 [-- -- -- --]]
>>> print(d.apply_masking(valid_range=[2, 8]).array)
[[-- -- 2 3]
 [4 -- 6 7]
 [8 -- -- --]]

>>> d.set_fill_value(7)
>>> print(d.apply_masking(fill_values=True).array)
[[0  1  2  3]
 [4 --  6 --]
 [8  9 10 11]]
>>> print(d.apply_masking(fill_values=True,
...                       valid_range=[2, 8]).array)
[[-- -- 2 3]
 [4 -- 6 --]
 [8 -- -- --]]