xcdat.mask.pcmdi_land_sea_mask

xcdat.mask.pcmdi_land_sea_mask#

xcdat.mask.pcmdi_land_sea_mask(da, threshold1=0.2, threshold2=0.3, source=None, source_data_var=None)[source]#

Generate a land-sea mask using the PCMDI method.

This method uses a high-resolution land-sea mask and regrids it to the resolution of the input DataArray. It then iteratively improves the mask based on specified thresholds.

Parameters:

  • da (xr.DataArray) – The DataArray to generate the mask for.

  • threshold1 (float, optional) – The first threshold for improving the mask, by default 0.2.

  • threshold2 (float, optional) – The second threshold for improving the mask, by default 0.3.

  • source (xr.Dataset | None, optional) – A custom Dataset containing the variable to use as the high-resolution source. If not provided, a default high-resolution land-sea mask is used.

  • source_data_var (str | None, optional) – The name of the variable in source to use as the high-resolution source. If source is not provided, this defaults to “sftlf”.

Returns:

xr.DataArray – The generated land-sea mask.

Raises:

ValueError – If source is provided but source_data_var is None.

Notes

By default, the navy_land.nc file is used as the high-resolution land–sea mask. This file is distributed by the [1] PCMDI (Program for Climate Model Diagnosis and Intercomparison) Metrics Package, and is derived from the U.S. Navy 1/6° land–sea mask dataset.

If source is not provided, the navy_land.nc file is automatically downloaded and cached from the xcdat-data repository: xCDAT/xcdat-data.

For more information on caching behavior, refer to the xcdat._data._get_pcmdi_mask_path() function.

References

Examples

Generate a land-sea mask using the PCMDI method:

>>> import xcdat
>>> ds = xcdat.open_dataset("/path/to/file")
>>> land_sea_mask = xcdat.mask.pcmdi_land_sea_mask(ds["tas"])

Generate a land-sea mask using the PCMDI method with custom thresholds:

>>> land_sea_mask = xcdat.mask.pcmdi_land_sea_mask(
...     ds["tas"], threshold1=0.3, threshold2=0.4
... )

Generate a land-sea mask using the PCMDI method with a custom high-res source:

>>> highres_ds = xcdat.open_dataset("/path/to/file")
>>> land_sea_mask = xcdat.mask.pcmdi_land_sea_mask(
...     ds["tas"], source=highres_ds, source_data_var="highres"
... )

For offline workflows, you can pre-download the mask with:

>>> from xcdat._data import _get_pcmdi_mask_path
>>> path = _get_pcmdi_mask_path()
Contents