cf.Field.regridc

Field.regridc(dst, axes=None, method=None, use_src_mask=True, use_dst_mask=False, fracfield=False, axis_order=None, ignore_degenerate=True, return_operator=False, check_coordinates=False, min_weight=None, inplace=False, i=False, _compute_field_mass=None)[source]

Regrid the field to a new Cartesian grid.

Regridding is the process of interpolating the field data values while preserving the qualities of the original data, and the metadata of the unaffected axes. The metadata for the regridded axes are taken from the dst parameter.

Between one and three axes may be simultaneously regridded in Cartesian space.

Coordinates

The source and destination grids of the regridding must both be defined by equivalent coordinates, which must be 1-d dimension coordinates. These are automatically detected from the field being regridded and the specification of the destination grid given by the dst parameter.

Masked cells

By default, the data mask of the source data is taken into account during the regridding process, but the destination grid mask is not. This behaviour may be changed with the use_src_mask and use_dst_mask parameters.

In general the source data may be arbitrarily masked, meaning that the mask for the regridding axes may vary along the non-regridding axes. The exceptions to this are for second-order conservative, patch recovery regridding, and nearest source to destination methods, for which the mask of the regridding axes must be the same across all non-regridding axes. In these special cases an exception will be raised if the source data mask does not meet this requirement.

Implementation

The interpolation is carried out using regridding weights calculated by the ESMF package, a Python interface to the Earth System Modeling Framework (ESMF) regridding utility: `https://earthsystemmodeling.org/regrid`_. Outside of ESMF, these weights are then modified for masked cells (if required) and the regridded data are created as the dot product of the weights with the source data. (Note that whilst the ESMF package is able to also create the regridded data from its weights, this feature can’t be integrated with the dask framework that underpins the field’s data.)

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.

See also

regrids

Parameters
dst: Field, Domain, RegridOperator or sequence of DimensionCoordinate

The definition of the destination grid on which to regrid the field’s data. One of:

  • Field: The grid is defined by the coordinates of the field construct’s domain.

  • Domain: The grid is defined by the coordinates of the domain construct.

  • Sequence of DimensionCoordinate: The grid is defined by between one and three 1-d dimension coordinate constructs that define the coordinates of the destination grid. The order of the coordinate constructs must match the order of source field regridding axes defined by the src_axes or axes parameter.

  • RegridOperator: The grid is defined by a regrid operator that has been returned by a previous call with the return_operator parameter set to True.

    Unlike the other options, for which the regrid weights need to be calculated, the regrid operator already contains the weights. Therefore, for cases where multiple fields with the same source grids need to be regridded to the same destination grid, using a regrid operator can give performance improvements by avoiding having to calculate the weights for each source field. Note that for the other types of dst parameter, the calculation of the regrid weights is not a lazy operation.

    Note

    The source grid of the regrid operator is immediately checked for compatibility with the grid of the source field. By default only the computationally cheap tests are performed (checking that the coordinate system, cyclicity and grid shape are the same), with the grid coordinates not being checked. The coordinates check will be carried out, however, if the check_coordinates parameter is True.

method: str or None, optional

Specify the regridding interpolation method. This parameter must be set unless dst is a RegridOperator, when the method is ignored.

The method parameter may be one of the following:

  • 'linear': Bilinear interpolation.

  • 'bilinear': Deprecated alias for 'linear'.

  • 'conservative_1st': First order conservative interpolation. Preserves 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.

  • 'conservative': Alias for 'conservative_1st'

  • 'conservative_2nd': Second-order conservative interpolation. As with first order conservative interpolation, preserves the area integral of the field between source and destination using a weighted sum, with weights based on the proportionate area of intersection. In addition the second-order conservative method takes the source gradient into account, so it yields a smoother destination field that typically better matches the source data.

  • 'patch' Patch recovery interpolation. A second degree 2-d polynomial regridding method, which uses a least squares algorithm to calculate the polynomials. This method typically results in better approximations to values and derivatives when compared to bilinear interpolation.

  • 'nearest_stod': Nearest neighbour interpolation for which each destination point is mapped to the closest source point. Useful for extrapolation of categorical data. Some destination cells may be unmapped.

  • 'nearest_dtos': Nearest neighbour interpolation for which each source point is mapped to the destination point. Useful for extrapolation of categorical data. All destination cells will be mapped.

  • None: This is the default and can only be used when dst is a RegridOperator.

use_src_mask: bool, optional

By default the mask of the source field is taken into account during the regridding process. The only possible exception to this is when the nearest source to destination regridding method ('nearest_stod') is being used. In this case, if use_src_mask is False then each destination point is mapped to the closest source point, whether or not it is masked (see the method parameter for details).

Ignored if dst is a RegridOperator.

use_dst_mask: bool, optional

If dst is a Field and use_dst_mask is False (the default) then the mask of data on the destination grid is not taken into account when performing regridding. If use_dst_mask is True then any masked cells in the dst field construct are transferred to the result. If dst has more dimensions than are being regridded, then the mask of the destination grid is taken as the subspace defined by index 0 of all the non-regridding dimensions.

Ignored if dst is not a Field.

src_axes: sequence, optional

Define the source grid axes to be regridded. The sequence of between one and three values identify unique domain axes by passing each axis description to a call of the source field construct’s domain_axis method. For example, for a value of 'ncdim%x', the domain axis construct returned by f.domain_axis('ncdim%x') is selected.

Must have the same number of values as the dst_axes parameter, if set, and the source and destination regridding axes must be specified in the same order. See the axes parameter.

Ignored if dst is a RegridOperator.

Parameter example:

['T']

Parameter example:

[1, 0]

New in version 3.14.0.

dst_axes: sequence, optional

When the destination grid is defined by a Field or Domain, define the destination grid axes to be regridded. The sequence of between one and three values identify unique domain axes by passing each axis description to a call of the destination field or domain construct’s domain_axis method. For example, for a value of 'ncdim%x', the domain axis construct returned by g.domain_axis('ncdim%x') is selected.

Must have the same number of values as the src_axes parameter, if set, and the source and destination regridding axes must be specified in the same order. See the axes parameter.

Ignored if dst is a RegridOperator.

Parameter example:

['T']

Parameter example:

[1, 0]

New in version 3.14.0.

axes: optional

Define the axes to be regridded for the source grid and, if dst is a Field or Domain, the destination grid. The axes parameter is a convenience that may be used to replace src_axes and dst_axes when they would contain identical sequences. It may also be used in place of src_axes if dst_axes is not required.

ignore_degenerate: bool, optional

For conservative regridding methods, if True (the default) then degenerate cells (those for which enough vertices collapse to leave a cell as either a line or a point) are skipped, not producing a result. Otherwise an error will be produced if degenerate cells are found, that will be present in the ESMF log files.

For all other regridding methods, degenerate cells are always skipped, regardless of the value of ignore_degenerate.

Ignored if dst is a RegridOperator.

return_operator: bool, optional

If True then do not perform the regridding, rather return the RegridOperator instance that defines the regridding operation, and which can be used in subsequent calls. See the dst parameter for details.

New in version 3.10.0.

check_coordinates: bool, optional

If True and dst is a `RegridOperator`then the source grid coordinates defined by the operator are checked for compatibility against those of the source field. By default this check is not carried out. See the dst parameter for details.

Ignored unless dst is a RegridOperator.

New in version 3.14.0.

min_weight: float, optional

A very small non-negative number. By default min_weight is 2.5 * np.finfo("float64").eps, i.e. ``5.551115123125783e-16`. It is used during linear and first-order conservative regridding when adjusting the weights matrix to account for the data mask. It is ignored for all other regrid methods, or if data being regridded has no missing values.

In some cases (described below) for which weights might only be non-zero as a result of rounding errors, the min_weight parameter controls whether or a not cell in the regridded field is masked.

The default value has been chosen empirically as the smallest value that produces the same masks as ESMF for the use cases defined in the cf test suite.

Define w_ji as the multiplicative weight that defines how much of Vs_i (the value in source grid cell i) contributes to Vd_j (the value in destination grid cell j).

Linear regridding

Destination grid cell j will only be masked if a) it is masked in destination grid definition; or b) w_ji >= min_weight for those masked source grid cells i for which w_ji > 0.

Conservative first-order regridding

Destination grid cell j will only be masked if a) it is masked in destination grid definition; or b) The sum of w_ji for all non-masked source grid cells i is strictly less than min_weight.

New in version 3.14.0.

inplace: bool, optional

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

axis_order: sequence, optional

Deprecated at version 3.14.0.

fracfield: bool, optional

Deprecated at version 3.14.0.

_compute_field_mass: dict, optional

Deprecated at version 3.14.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

>>> src, dst = cf.example_fields(1, 0)
>>> print(src)
Field: air_temperature (ncvar%ta)
---------------------------------
Data            : air_temperature(atmosphere_hybrid_height_coordinate(1), grid_latitude(10), grid_longitude(9)) K
Cell methods    : grid_latitude(10): grid_longitude(9): mean where land (interval: 0.1 degrees) time(1): maximum
Field ancils    : air_temperature standard_error(grid_latitude(10), grid_longitude(9)) = [[0.76, ..., 0.32]] K
Dimension coords: atmosphere_hybrid_height_coordinate(1) = [1.5]
                : grid_latitude(10) = [2.2, ..., -1.76] degrees
                : grid_longitude(9) = [-4.7, ..., -1.18] degrees
                : time(1) = [2019-01-01 00:00:00]
Auxiliary coords: latitude(grid_latitude(10), grid_longitude(9)) = [[53.941, ..., 50.225]] degrees_N
                : longitude(grid_longitude(9), grid_latitude(10)) = [[2.004, ..., 8.156]] degrees_E
                : long_name=Grid latitude name(grid_latitude(10)) = [--, ..., b'kappa']
Cell measures   : measure:area(grid_longitude(9), grid_latitude(10)) = [[2391.9657, ..., 2392.6009]] km2
Coord references: grid_mapping_name:rotated_latitude_longitude
                : standard_name:atmosphere_hybrid_height_coordinate
Domain ancils   : ncvar%a(atmosphere_hybrid_height_coordinate(1)) = [10.0] m
                : ncvar%b(atmosphere_hybrid_height_coordinate(1)) = [20.0]
                : surface_altitude(grid_latitude(10), grid_longitude(9)) = [[0.0, ..., 270.0]] m
>>> print(dst)
Field: specific_humidity (ncvar%q)
----------------------------------
Data            : specific_humidity(latitude(5), longitude(8)) 1
Cell methods    : area: mean
Dimension coords: latitude(5) = [-75.0, ..., 75.0] degrees_north
                : longitude(8) = [22.5, ..., 337.5] degrees_east
                : time(1) = [2019-01-01 00:00:00]
>>> x = src.regridc(dst, method='linear', axes=['Y'])
>>> print(x)
Field: air_temperature (ncvar%ta)
---------------------------------
Data            : air_temperature(atmosphere_hybrid_height_coordinate(1), latitude(5), grid_longitude(9)) K
Cell methods    : latitude(5): grid_longitude(9): mean where land (interval: 0.1 degrees) time(1): maximum
Dimension coords: atmosphere_hybrid_height_coordinate(1) = [1.5]
                : latitude(5) = [-75.0, ..., 75.0] degrees_north
                : grid_longitude(9) = [-4.7, ..., -1.18] degrees
                : time(1) = [2019-01-01 00:00:00]
Coord references: standard_name:atmosphere_hybrid_height_coordinate
Domain ancils   : ncvar%a(atmosphere_hybrid_height_coordinate(1)) = [10.0] m
                : ncvar%b(atmosphere_hybrid_height_coordinate(1)) = [20.0]
                : surface_altitude(latitude(5), grid_longitude(9)) = [[--, ..., --]] m
>>> r = src.regridc(dst, method='linear', axes=['Y'], return_operator=True)
>>> y = src.regridc(r)
>>> y.equals(x)
True