cf.Field.regrids

Field.regrids(dst, src_cyclic=None, dst_cyclic=None, method='conservative', ignore_dst_mask=False, compute_field_mass=None, i=False)

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

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.

Metadata

The field’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. 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 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.

The output field’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 also taken into account. If the destination field data has more than two dimensions then the mask is taken from the two dimensionsal section of the data where the indices of all axes other than X and Y are zero.

Method

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 field f conservatively onto a grid contained in field g and point to the result with reference h.

>>> h = f.regrids(g)

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 ('X', 'Y') or ('Y', 'X').

src_cyclic: bool, optional

Force the use of a periodic X axis for the source field, without altering the original field.

dst_cyclic: bool, optional

Force the use of a periodic X axis for the destination grid, without altering the original field.

method : string, optional

By default the regridding method is conservative. If this option is set to ‘bilinear’ then bilinear interpolation is used. Conservative regridding is supported for 2D latitude and longitude dimensions only if contiguous CF-Compliant bounds are provided in the metadata.

ignore_dst_mask : bool, optional

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

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 in the keywords ‘srcmass’ and ‘dstmass’.

Returns:

out : cf.Field

The regridded field.

Examples 2:

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

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

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

>>> h = f.regrids(g, ignore_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')})