cf.Field.regrids

Field.regrids(dst, method=None, src_cyclic=None, dst_cyclic=None, use_src_mask=True, use_dst_mask=False, fracfield=False, src_axes=None, dst_axes=None, axis_order=None, ignore_degenerate=True, inplace=False, i=False, _compute_field_mass=None, return_operator=False)

Return the field regridded onto a new latitude-longitude grid.

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.

The regridding method must be specified. First-order conservative interpolation conserves the global area integral of the field, but may not give approximations to the values as good as linear interpolation. Second-order conservative interpolation also takes into account the gradient across the source cells, so in general gives a smoother, more accurate representation of the source field especially when going from a coarser to a finer grid. Linear interpolation is available. The latter method is particular useful for cases when the latitude and longitude coordinate cell boundaries are not known nor inferable. Higher order patch recovery is available as an alternative to linear interpolation. This typically results in better approximations to values and derivatives compared to the latter, but the weight matrix can be larger than the linear matrix, which can be an issue when regridding close to the memory limit on a machine. Nearest neighbour interpolation is also available. Nearest source to destination is particularly useful for regridding integer fields such as land use.

Metadata

The field construct’s domain must have well defined X and Y axes with latitude and longitude coordinate values, which may be stored as dimension coordinate objects or two dimensional auxiliary coordinate objects. If the latitude and longitude coordinates are two dimensional then the X and Y axes must be defined by dimension coordinates if present or by the netCDF dimensions. In the latter case the X and Y axes must be specified using the src_axes or dst_axes keyword. The same is true for the destination grid, if it provided as part of another field.

The cyclicity of the X axes of the source field and destination grid is taken into account. If an X axis is in fact cyclic but is not registered as such by its parent field (see cf.Field.iscyclic), then the cyclicity may be set with the src_cyclic or dst_cyclic parameters. In the case of two dimensional latitude and longitude dimension coordinates without bounds it will be necessary to specify src_cyclic or dst_cyclic manually if the field is global.

The output field construct’s coordinate objects which span the X and/or Y 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 than two dimensions then the mask, if used, is taken from the two dimensional section of the data where the indices of all axes other than X and Y are zero.

Implementation

The interpolation is carried 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.

Latitude-Longitude Grid

The canonical grid with independent latitude and longitude coordinates.

Curvilinear Grids

Grids in projection coordinate systems can be regridded as long as two dimensional latitude and longitude coordinates are present.

Rotated Pole Grids

Rotated pole grids can be regridded as long as two dimensional latitude and longitude coordinates are present. It may be necessary to explicitly identify the grid latitude and grid longitude coordinates as being the X and Y axes and specify the src_cyclic or dst_cyclic keywords.

Tripolar Grids

Tripolar grids are logically rectangular and so may be able to be regridded. If no dimension coordinates are present it will be necessary to specify which netCDF dimensions are the X and Y axes using the src_axes or dst_axes keywords. Connections across the bipole fold are not currently supported, but are not be necessary in some cases, for example if the points on either side are together without a gap. It will also be necessary to specify src_cyclic or dst_cyclic if the grid is global.

New in version 1.0.4.

See also

regridc

Parameters

dst: Field or dict or RegridOperator

The destination grid. Must be one of:

• Field. The grid is defined by the field constuct’s domain.

• dict. The grid is defined by a dictionary with keys 'latitude' and 'longitude' whose values are with either both 1-d dimension coordinates constructs, or both 2-d auxiliary coordinate constructs. In the 2-d case, both coordinate constructs must have their axes in the same order and this must be specified with the 'axes' key as either of the tuples ('X', 'Y') or ('Y', 'X').

• RegridOperator. The grid is defined by a regrid operator that has been returned by a previous call to regrids with return_operator=True.

  This option can give large performance increases, as greastest computiotnal expense is often the creation of the regrid operator, rather than running the regrid operator to regrid the data.

  The regrid operator defines the source grid and the regridding weights, so the method, axes, ignore_degenerate, use_src_mask, and use_dst_mask parameters are not required and are ignored if set.

  An exception will be raised if the domain of the source field being regridded is inconsistent with source grid of the regrid operator.

  The source field being regridded may, however, have a different data mask to that of the source grid in the regrid operator. In this case a new regrid operator is automatically created, with the associated loss in performance.

method: str, optional

Specify the regridding method. This parameter must be set unless the new grid is specified by a regridding operator, which stores its own method. See the dst parameter.

The method parameter may be one of the following:

Method	Description
'linear'	Bilinear interpolation.
'bilinear'	Deprecated alias for 'linear'.
'conservative_1st'	First order conservative interpolation. Preserve the area integral of the data across the interpolation from source to destination. It uses the proportion of the area of the overlapping source and destination cells to determine appropriate weights. In particular, the weight of a source cell is the ratio of the area of intersection of the source and destination cells to the area of the whole destination cell. It does not account for the field gradient across the source cell, unlike the second-order conservative method (see below).
'conservative_2nd'	Second-order conservative interpolation. As with first order (see above), preserves the area integral of the field between source and destination using a weighted sum, with weights based on the proportionate area of intersection. Unlike first-order, the second-order method incorporates further terms to take into consideration the gradient of the field across the source cell, thereby typically producing a smoother result of higher accuracy.
'conservative'	Alias for 'conservative_1st'
'patch'	Higher-order patch recovery interpolation. A second degree polynomial regridding method, which uses a least squares algorithm to calculate the polynomial. This method gives better derivatives in the resulting destination data than the linear method.
'nearest_stod'	Nearest neighbour interpolation for which each destination point is mapped to the closest source point. Useful for extrapolation of categorical data.
'nearest_dtos'	Nearest neighbour interpolation for which each source point is mapped to the destination point. Useful for extrapolation of categorical data. A given destination point may receive input from multiple source points, but no source point will map to more than one destination point.
None	This is the default and can only be used the new grid is specified by a regridding operator, which stores its own method.

Note

When dst is a regrid operator then the method may still be set, but must have the value None or else agree with the regridding operator’s method.

src_cyclic: bool, optional

Specifies whether the longitude for the source grid is periodic or not. If None then, if possible, this is determined automatically otherwise it defaults to False.

dst_cyclic: bool, optional

Specifies whether the longitude for the destination grid is periodic of not. If None then, if possible, this is determined automatically otherwise it defaults to False.

Note

When dst is a regrid operator then dst_cyclic is ignored, and its value is set by the regrid operator’s parameters.

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.

Note

When dst is a regrid operator then use_src_mask is ignored, and its value is set by the regridding operator’s parameters.

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. If the destination field has more than two dimensions then the first 2-d slice in index space is used for the mask e.g. for an field varying with (X, Y, Z, T) the mask is taken from the slice (X, Y, 0, 0).

Note

When dst is a regrid operator then use_dst_mask is ignored, and its value is set by the regrid operator’s parameters.

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.

src_axes: dict, optional

A dictionary specifying the axes of the 2-d latitude and longitude coordinates of the source field when no 1-d dimension coordinates are present. It must have keys 'X' and 'Y'. TODO

Parameter example:

src_axes={'X': 'ncdim%x', 'Y': 'ncdim%y'}

Parameter example:

src_axes={'X': 1, 'Y': 0}

dst_axes: dict, optional

A dictionary specifying the axes of the 2-d latitude and longitude auxiliary coordinates of the destination grid when no dimension coordinates are present. It must have keys 'X' and 'Y'.

Parameter example:

dst_axes={'X': 'ncdim%x', 'Y': 'ncdim%y'}

Note

When dst is a regrid operator then dst_axes is ignored, and its value is set by the regrid operator’s parameters.

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 X-Y slices. The slowest moving axis will be the first one specified. Currently the regridding weights are recalculated every time the mask of an X-Y slice changes with respect to the previous one, so this option allows the user to minimise how frequently the mask changes. TODO.

ignore_degenerate: bool, optional

True by default. Instructs ESMF 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 ESMF 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.

Note

When dst is a regrid operator then ignore_degenerate is ignored, and its value is set by the regrid operator’s parameters.

inplace: bool, optional

If True then do the operation in-place and return None.

_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 construct’s mass and the destination field construct’s mass. The calculation is only done if conservative regridding is being performed. This is for debugging purposes.

return_operator: bool, optional

If True then do not perform the regridding, rather return a RegridOperator instance that defines the regridding operation, including the destination grid, and which can be used in subsequent calls to regrids.

New in version 3.10.0.

i: deprecated at version 3.0.0

Use the inplace parameter instead.

Returns

Field or None or RegridOperator

The regridded field construct, or None if the operation was in-place, or the regridding operator if return_operator is True.

Examples:

Regrid field construct f conservatively onto a grid contained in field construct g:

>>> h = f.regrids(g, 'conservative')

Regrid f to the grid of g using linear regridding and forcing the source field f to be treated as cyclic.

>>> h = f.regrids(g, src_cyclic=True, method='linear')

Regrid f to the grid of g using the mask of g.

>>> h = f.regrids(g, 'conservative_1st', use_dst_mask=True)

Regrid f to 2-d auxiliary coordinates lat and lon, which have their dimensions ordered “Y” first then “X”.

>>> lat
<CF AuxiliaryCoordinate: latitude(110, 106) degrees_north>
>>> lon
<CF AuxiliaryCoordinate: longitude(110, 106) degrees_east>
>>> h = f.regrids(
...         {'longitude': lon, 'latitude': lat, 'axes': ('Y', 'X')},
...         'conservative'
...     )

Regrid field, f, on tripolar grid to latitude-longitude grid of field, g.

>>> h = f.regrids(g, 'linear',
...               src_axes={'X': 'ncdim%x', 'Y': 'ncdim%y'},
...               src_cyclic=True)

Regrid f to the grid of g iterating over the ‘Z’ axis last and the ‘T’ axis next to last to minimise the number of times the mask is changed.

>>> h = f.regrids(g, 'nearest_dtos', axis_order='ZT')

Store the regrid operator and use it for a subsequent regrids:

>>> op = f.regrids(g, method='conservative', return_operator=True)
>>> h = f.regrids(op)
>>> h2 = f2.regrids(op)