xcdat.regridder.xgcm.XGCMRegridder

class xcdat.regridder.xgcm.XGCMRegridder(input_grid, output_grid, method='linear', target_data=None, grid_positions=None, periodic=False, extra_init_options=None, **options)

__init__(input_grid, output_grid, method='linear', target_data=None, grid_positions=None, periodic=False, extra_init_options=None, **options)

Extension of xgcm regridder.

The XGCMRegridder extends xgcm by automatically constructing the Grid object, transposing the output data to match the dimensional order of the input data, and ensuring bounds and metadata are preserved in the output dataset.

Linear and log methods require a single dimension position, which can usually be automatically derived. A custom position can be specified using the grid_positions argument.

Conservative regridding requires multiple dimension positions, e.g., {“center”: “xc”, “left”: “xg”} which can be passed using the grid_positions argument.

xgcm.Grid can be passed additional arguments using extra_init_options. These arguments can be found on XGCM’s Grid documentation.

xgcm.Grid.transform can be passed additional arguments using options. These arguments can be found on XGCM’s Grid.transform documentation.

Parameters:

• input_grid (xr.Dataset) – Contains source grid coordinates.

• output_grid (xr.Dataset) – Contains destination grid coordinates.

• method (XGCMVerticalMethods) –

  Regridding method, by default “linear”. Options are

  • linear (default)

  • log

  • conservative

• target_data (str | xr.DataArray | None) – Data to transform onto, if this is a str it can be the key of a variable in the input dataset or “infer” to automatically determine the vertical coordinate. If it is an xr.DataArray, it should be a vertical coordinate that is compatible with the output grid. If None, then the source levels are mapped to the destination levels.

• grid_positions (dict[str, str] | None) – Mapping of dimension positions, by default None. If None then an attempt is made to derive this argument.

• periodic (bool) – Whether the grid is periodic, by default False.

• extra_init_options (dict[str, Any] | None) – Extra options passed to the xgcm.Grid constructor, by default None.

• options (dict[str, Any] | None) – Extra options passed to the xgcm.Grid.transform method.

Raises:

• KeyError – If data variable does not exist in the Dataset.

• ValueError – If method is not valid.

Examples

Import xCDAT:

>>> import xcdat

Open a dataset:

>>> ds = xcdat.open_dataset("...")

Create output grid:

>>> output_grid = xcdat.create_grid(lev=np.linspace(1000, 1, 5))

Regrid data to output_grid:

>>> output_data = ds.regridder.vertical(
>>>     "so", output_grid, tool="xgcm", method="linear"
>>> )

Create pressure variable:

>>> ds["pressure"] = (ds["hyam"] * ds["P0"] + ds["hybm"] * ds["PS"]).transpose(
>>>     **ds["T"].dims
>>> )

Regrid data to output_grid in pressure space:

>>> output_data = ds.regridder.vertical(
>>>     "so", output_grid, tool="xgcm", method="linear", target_data="pressure"
>>> )

Passing additional arguments to xgcm.Grid and xgcm.Grid.transform:

>>> regridder = xgcm.XGCMRegridder(
>>>     ds,
>>>     output_grid,
>>>     method="linear",
>>>     extra_init_options={"boundary": "fill", "fill_value": 1e27},
>>>     mask_edges=True
>>> )

Methods

__init__(input_grid, output_grid[, method, ...])	Extension of xgcm regridder.
horizontal(data_var, ds)	Placeholder for base class.
vertical(data_var, ds)	See documentation in xcdat.regridder.xgcm.XGCMRegridder()

horizontal(data_var, ds)

Placeholder for base class.

vertical(data_var, ds)

See documentation in xcdat.regridder.xgcm.XGCMRegridder()

_infer_target_data(ds)

Infer and decode the target vertical coordinate from a dataset.

Attempts to extract the CF-compliant vertical (“Z”) coordinate from the provided xarray dataset, verifies the presence and validity of the ‘formula_terms’ attribute, and decodes the vertical coordinate using CF conventions.

Parameters:

ds (xarray.Dataset) – The input dataset from which to infer and decode the vertical coordinate.

Returns:

xarray.DataArray or None – The decoded vertical coordinate as a DataArray if successful, otherwise None.

Raises:

• RuntimeError – If the ‘Z’ coordinate is missing, not CF-compliant, or lacks a valid ‘formula_terms’ attribute.

• KeyError – If required variables for decoding the vertical coordinate are missing from the dataset.

Notes

This method relies on the dataset being CF-compliant and having appropriate attributes on the vertical coordinate variable.

_get_target_data(ds)

Retrieve the target data from the given xarray Dataset.

Attempts to access the target data variable from the provided dataset using the attribute self._target_data. If self._target_data is a string and not found in the dataset, raises a RuntimeError. If self._target_data is not a string or is None, returns None. If a ValueError occurs, returns self._target_data as is.

Parameters:

ds (xr.Dataset) – The xarray Dataset from which to retrieve the target data.

Returns:

xr.DataArray or None – The target data as an xarray DataArray if found, otherwise None.

Raises:

RuntimeError – If self._target_data is a string and not found in the dataset.

_get_grid_positions()

Determine the grid point positions for the “Z” axis in the input grid.

Inspects the input grid to infer the position of the “Z” coordinate (e.g., center, left, or right) based on its relationship to the corresponding bounds. Raises informative errors if the method is not supported, if the “Z” coordinate or its bounds cannot be determined, or if the position cannot be inferred automatically.

Returns:

dict[str, Any | Hashable] – Mapping of the “Z” axis to its grid position, e.g., {“Z”: {“center”: <coord_name>}}.

Raises:

RuntimeError – If conservative regridding is requested, if the “Z” coordinate or bounds cannot be determined, if multiple “Z” axes are found, or if the grid position cannot be inferred.

_abc_impl = <_abc._abc_data object>