cf.FieldList.regrids

FieldList.regrids(dst, src_cyclic=None, dst_cyclic=None, method='auto', use_dst_mask=False, _compute_field_mass=None, i=False)

For each field, 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. Nearest neighbour interpolation is also available.

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 not taken into account. If the destination field data has more than two dimensions then the mask, if used, 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.

New in version 1.0.4.

Examples 1:

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

>>> 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 set to ‘auto’. In this case conservative regridding will be used unless one or both of the fields does not have contiguous bounds, in which case bilinear regridding will be used. If a 1D dimension coordinate does not have bounds then contiguous bounds will be created automatically. If this parameter is set to conservative then first-order conservative regridding is used. If it is set to ‘bilinear’ then multilinear interpolation is used. If it is set to ‘nearest_stod’ then nearest neighbor interpolation is used where each destination point is mapped to the closest source point. A given source point may map to multiple destination points, but no destination point will receive input from more than one source point. If it is set to ‘nearest_dtos’ then nearest neighbor 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_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).

i : bool, optional

If True then update the field list in place. By default a new field list is created. In either case, a field list 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.FieldList

The regridded field list.

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 using the mask of g.

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