xcdat.regridder.accessor.RegridderAccessor

class xcdat.regridder.accessor.RegridderAccessor(dataset)

An accessor class that provides regridding attributes and methods for xarray Datasets through the .regridder attribute.

Examples

Import xCDAT:

>>> import xcdat

Use RegridderAccessor class:

>>> ds = xcdat.open_dataset("...")
>>>
>>> ds.regridder.<attribute>
>>> ds.regridder.<method>
>>> ds.regridder.<property>

Parameters:

dataset (xr.Dataset) – The Dataset to attach this accessor.

__init__(dataset)

Methods

__init__(dataset)
horizontal(data_var, output_grid[, tool])	Transform data_var to output_grid.
horizontal_regrid2(data_var, output_grid, ...)	Deprecated, will be removed with 0.7.0 release.
horizontal_xesmf(data_var, output_grid, ...)	Deprecated, will be removed with 0.7.0 release.
vertical(data_var, output_grid[, tool])	Transform data_var to output_grid.

Attributes

grid	Extract the X, Y, and Z axes from the Dataset and return a new xr.Dataset.

_ds

property grid

Extract the X, Y, and Z axes from the Dataset and return a new xr.Dataset.

Returns:

xr.Dataset – Containing grid axes.

Raises:

• ValueError – If axis dimension coordinate variable is not correctly identified.

• ValueError – If axis has multiple dimensions (only one is expected).

Examples

Import xCDAT:

>>> import xcdat

Open a dataset:

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

Extract grid from dataset:

>>> grid = ds.regridder.grid

_get_axis_data(name)

horizontal_xesmf(data_var, output_grid, **options)

Deprecated, will be removed with 0.7.0 release.

Extends the xESMF library for horizontal regridding between structured rectilinear and curvilinear grids.

This method extends xESMF by automatically constructing the xe.XESMFRegridder object, preserving source bounds, and generating missing bounds. It regrids data_var in the dataset to output_grid.

Option documentation xcdat.regridder.xesmf.XESMFRegridder()

Parameters:

• data_var (str) – Name of the variable in the xr.Dataset to regrid.

• output_grid (xr.Dataset) – Dataset containing output grid.

• options (Dict[str, Any]) – Dictionary with extra parameters for the regridder.

Returns:

xr.Dataset – With the data_var variable on the grid defined in output_grid.

Raises:

ValueError – If tool is not supported.

Examples

Generate output grid:

>>> output_grid = xcdat.create_gaussian_grid(32)

Regrid data to output grid using xesmf:

>>> ds.regridder.horizontal_xesmf("ts", output_grid)

horizontal_regrid2(data_var, output_grid, **options)

Deprecated, will be removed with 0.7.0 release.

Pure python implementation of CDAT’s regrid2 horizontal regridder.

Regrids data_var in dataset to output_grid using regrid2’s algorithm.

Options documentation xcdat.regridder.regrid2.Regrid2Regridder()

Parameters:

• data_var (str) – Name of the variable in the xr.Dataset to regrid.

• output_grid (xr.Dataset) – Dataset containing output grid.

• options (Dict[str, Any]) – Dictionary with extra parameters for the regridder.

Returns:

xr.Dataset – With the data_var variable on the grid defined in output_grid.

Raises:

ValueError – If tool is not supported.

Examples

Generate output grid:

>>> output_grid = xcdat.create_gaussian_grid(32)

Regrid data to output grid using regrid2:

>>> ds.regridder.horizontal_regrid2("ts", output_grid)

horizontal(data_var, output_grid, tool='xesmf', **options)

Transform data_var to output_grid.

When might Regrid2 be preferred over xESMF?

If performing conservative regridding from a high/medium resolution lat/lon grid to a coarse lat/lon target, Regrid2 may provide better results as it assumes grid cells with constant latitudes and longitudes while xESMF assumes the cells are connected by Great Circles [1].

Supported tools, methods and grids:

• xESMF (https://pangeo-xesmf.readthedocs.io/en/latest/)

  • Methods: Bilinear, Conservative, Conservative Normed, Patch, Nearest s2d, or Nearest d2s.

  • Grids: Rectilinear, or Curvilinear.

  • Find options at xcdat.regridder.xesmf.XESMFRegridder()

• Regrid2

  • Methods: Conservative

  • Grids: Rectilinear

  • Find options at xcdat.regridder.regrid2.Regrid2Regridder()

Parameters:

• data_var (str) – Name of the variable to transform.

• output_grid (xr.Dataset) – Grid to transform data_var to.

• tool (str) – Name of the tool to use.

• **options (Any) – These options are passed directly to the tool. See specific regridder for available options.

Returns:

xr.Dataset – With the data_var transformed to the output_grid.

Raises:

ValueError – If tool is not supported.

References

[1]

https://earthsystemmodeling.org/docs/release/ESMF_8_1_0/ESMF_refdoc/node5.html#SECTION05012900000000000000

Examples

Import xCDAT:

>>> import xcdat

Open a dataset:

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

Create output grid:

>>> output_grid = xcdat.create_uniform_grid(-90, 90, 4.0, -180, 180, 5.0)

Regrid variable using “xesmf”:

>>> output_data = ds.regridder.horizontal("ts", output_grid, tool="xesmf", method="bilinear")

Regrid variable using “regrid2”:

>>> output_data = ds.regridder.horizontal("ts", output_grid, tool="regrid2")

vertical(data_var, output_grid, tool='xgcm', **options)

Transform data_var to output_grid.

Supported tools:

• xgcm (https://xgcm.readthedocs.io/en/latest/index.html)

  • Methods: Linear, Conservative, Log

  • Find options at xcdat.regridder.xgcm.XGCMRegridder()

Parameters:

• data_var (str) – Name of the variable to transform.

• output_grid (xr.Dataset) – Grid to transform data_var to.

• tool (str) – Name of the tool to use.

• **options (Any) – These options are passed directly to the tool. See specific regridder for available options.

Returns:

xr.Dataset – With the data_var transformed to the output_grid.

Raises:

ValueError – If tool is not supported.

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, 20))

Regrid variable using “xgcm”:

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