cf.Field.regridc

Field.regridc(dst, axes, method=None, use_src_mask=True, use_dst_mask=False, fracfield=False, axis_order=None, ignore_degenerate=True, i=False, _compute_field_mass=None)

Return the field with the specified Cartesian axes regridded onto a new grid.

Between 1 and 3 dimensions may be regridded.

Regridding, also called remapping or interpolation, is the process of changing the grid underneath field data values while preserving the qualities of the original data.

By default the the regridding is a first-order conservative interpolation, but bilinear interpolation is available. The latter method is particular useful for cases when the latitude and longitude coordinate cell boundaries are not known nor inferrable. Higher order patch recovery is available as an alternative to bilinear interpolation. This typically results in better approximations to values and derivatives compared to the latter, but the weight matrix can be larger than the bilinear matrix, which can be an issue when regridding close to the memory limit on a machine. It is only available in 2D. Nearest neighbour interpolation is also available.

Metadata

The field’s domain must have axes matching those specified in src_axes. The same is true for the destination grid, if it provided as part of another field. Optionally the axes to use from the destination grid may be specified separately in dst_axes.

The output field’s coordinate objects which span the specified axes are replaced with those from the destination grid. Any fields contained in coordinate reference objects will also be regridded, if possible.

Mask

The data array mask of the field is automatically taken into account, such that the regridded data array will be masked in regions where the input data array is masked. By default the mask of the destination grid is not taken into account. If the destination field data has more dimensions than the number of axes specified then, if used, its mask is taken from the 1-3 dimensional section of the data where the indices of all axes other than X and Y are zero.

Implementation

The interpolation is carried by out using the ESMF package - a Python interface to the Earth System Modeling Framework (ESMF) regridding utility.

Logging

Whether ESMF logging is enabled or not is determined by cf.REGRID_LOGGING. If it is logging takes place after every call. By default logging is disabled.

Examples 1:

Regrid the time axes of field f conservatively onto a grid contained in field g:

>>> h = f.regridc(g, axes='T', 'conservative')

Parameters:

dst: cf.Field or dict

The field containing the new grid or a dictionary with the axes specifiers as keys referencing dimension coordinates. If dst is a field list the first field in the list is used.

axes:

Select dimension coordinates from the source and destination fields for regridding. See cf.Field.axes for options for selecting specific axes. However, the number of axes returned by cf.Field.axes must be the same as the number of specifiers passed in.

method: str

Specify the regridding method. The method parameter must be one of:

method	Description
'bilinear'	Multilinear interpolation.
'patch'	Higher order patch recovery.
'conservative'	First-order conservative regridding will be used (requires both of the fields to have contiguous, non-overlapping bounds).
'nearest_stod'	Nearest neighbour interpolation is used where each destination point is mapped to the closest source point
'nearest_dtos'	Nearest neighbour interpolation is used where each source point is mapped to the closest destination point. A given destination point may receive input from multiple source points, but no source point will map to more than one destination point.

use_src_mask: bool, optional

For all methods other than ‘nearest_stod’, this must be True as it does not make sense to set it to False. For the ‘nearest_stod’ method if it is True then points in the result that are nearest to a masked source point are masked. Otherwise, if it is False, then these points are interpolated to the nearest unmasked source points.

use_dst_mask: bool, optional

By default the mask of the data on the destination grid is not taken into account when performing regridding. If this option is set to True then it is.

fracfield: bool, optional

If the method of regridding is conservative the fraction of each destination grid cell involved in the regridding is returned instead of the regridded data if this is True. Otherwise this is ignored.

axis_order: sequence, optional

A sequence of items specifying dimension coordinates as retrieved by the dim method. These determine the order in which to iterate over the other axes of the field when regridding slices. The slowest moving axis will be the first one specified. Currently the regridding weights are recalculated every time the mask of a slice changes with respect to the previous one, so this option allows the user to minimise how frequently the mask changes.

ignore_degenerate: bool, optional

True by default. Instructs ESMPy to ignore degenerate cells when checking the grids for errors. Regridding will proceed and degenerate cells will be skipped, not producing a result, when set to True. Otherwise an error will be produced if degenerate cells are found. This will be present in the ESMPy log files if cf.REGRID_LOGGING is set to True. As of ESMF 7.0.0 this only applies to conservative regridding. Other methods always skip degenerate cells.

i: bool, optional

If True then update the field in place. By default a new field is created. In either case, a field is returned.

_compute_field_mass: dict, optional

If this is a dictionary then the field masses of the source and destination fields are computed and returned within the dictionary. The keys of the dictionary indicates the lat/long slice of the field and the corresponding value is a tuple containing the source field’s mass and the destination field’s mass. The calculation is only done if conservative regridding is being performed. This is for debugging purposes.

Returns:

out: cf.Field

The regridded field.

Examples 2:

Regrid the T axis of field f conservatively onto the grid specified in the dimension coordinate t:

>>> h = f.regridc({'T': t}, axes=('T'), 'nearest_stod')

Regrid the T axis of field f using bilinear interpolation onto a grid contained in field g:

>>> h = f.regridc(g, axes=('T'), method='bilinear')

Regrid the X and Y axes of field f conservatively onto a grid contained in field g:

>>> h = f.regridc(g, axes=('X','Y'), 'conservative')

Regrid the X and T axes of field f conservatively onto a grid contained in field g using the destination mask:

>>> h = f.regridc(g, axes=('X','Y'), use_dst_mask=True, method='bilinear')