cf.Field.regrids

Field.regrids(dst, method, 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 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 inferrable. 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 ESMPy 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

The field containing the new grid. If dst is a field list the first field in the list is used. Alternatively a dictionary can be passed containing the keywords ‘longitude’ and ‘latitude’ with either two 1D dimension coordinates or two 2D auxiliary coordinates. In the 2D case both coordinates must have their axes in the same order and this must be specified by the keyword ‘axes’ as either of the tuples ('X', 'Y') or ('Y', 'X').

method: str

Specify the regridding method. The method parameter must be one of the following, which are described in more detail in Regridding methods, but to summarise:

method	Form of regridding to be applied:
'linear' (previously called 'bilinear', which is is still supported)	Linear interpolation in the corresponding number of dimensions, which for spherical regridding is always two, so this amounts to bilinear interpolation (linear interpolation in both X and Y).
'conservative' or 'conservative_1st'	First-order conservative. Note this requires both of the fields to have contiguous, non-overlapping bounds.
'conservative_2nd'	Second-order conservative. Note this requires both of the fields to have contiguous, non-overlapping bounds.
'patch'	Higher order patch recovery.
'nearest_stod'	Nearest neighbor interpolation where each destination point is mapped to the closest source.
'nearest_dtos'	Nearest neighbor interpolation where each source point is mapped to the closest destination point.

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.

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. If the destination field has more than two dimensions then the first 2D 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).

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 2D latitude and longitude coordinates of the source field when no 1D 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 2D latitude and longitude coordinates of the destination field when no dimension coordinates are present. It must have keys ‘X’ and ‘Y’.

Parameter example:

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

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.

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.

inplace: bool, optional

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

i: deprecated at version 3.0.0

Use the inplace parameter instead.

_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.

Returns

Field

The regridded field construct.

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 2D 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')