pcmdi_metrics.utils.apply_landmask

pcmdi_metrics.utils.apply_landmask(obj, data_var=None, landfrac=None, keep_over='ocean', land_criteria=0.8, ocean_criteria=0.2)[source]

Apply a land-sea mask to a given DataArray or Dataset.

This function applies a land-sea mask to either a DataArray or a variable within a Dataset. It can keep values over land or ocean based on the specified criteria.

Parameters:

  • obj (Union[xr.Dataset, xr.DataArray]) – The Dataset or DataArray to which the land-sea mask will be applied.

  • data_var (str, optional) – Name of the DataArray in the Dataset. Required if obj is a Dataset.

  • landfrac (xr.DataArray, optional) – Land fraction data array. Values should range from 0 (ocean) to 1 (land). If None, a land-sea mask will be created automatically.

  • keep_over ({'land', 'ocean'}, optional) – Specifies whether to keep values over “land” or “ocean”. Default is “ocean”.

  • land_criteria (float, optional) – Threshold for considering a grid cell as land. Default is 0.8.

  • ocean_criteria (float, optional) – Threshold for considering a grid cell as ocean. Default is 0.2.

Returns:

xr.DataArray – DataArray with the land-sea mask applied.

Raises:

ValueError – If data_var is not provided when obj is a Dataset, or if keep_over is invalid.

Notes

  • If landfrac is not provided, it will be generated using the ‘create_land_sea_mask’ function.

  • The function can handle land fraction data in both percentage (0-100) and fractional (0-1) formats.

See also

create_land_sea_mask

The underlying function used to apply the mask.

apply_oceanmask

A sister function used to apply the mask out ocean.

Examples

>>> from pcmdi_metrics.utils import apply_landmask
>>> # Keep values over land (mask ocean)
>>> da_land = apply_landmask(da, landfrac=mask, keep_over="land")  # when input is DataArray
>>> da_land = apply_landmask(ds, data_var="ts", landfrac=mask, keep_over="land")  # DataSet
>>> # Keep values over ocean (mask land)
>>> da_ocean = apply_landmask(da, landfrac=mask, keep_over="ocean")  # when input is DataArray
>>> da_ocean = apply_landmask(ds, data_var="ts", landfrac=mask, keep_over="ocean")  # use DataSet