ants.regrid package

ANTS regridding provides capability which extend beyond what is currently provided by iris for the convenience of ancillary generation. Therefore, the user is referred to iris.analysis for regridding capability provided by iris. ANTS provides:

• ants.regrid.rectilinear a set of rectilinear horizontal regridding/interpolation approaches.

• ants.regrid.interpolation a set of vertical points-based approaches.

• ants.regrid.esmf regridding schemes for ESMF framework using emspy.

The reader is referred to the module documentation for further details. For further details see the user guide.

class ants.regrid.GeneralRegridScheme(horizontal_scheme=None, vertical_scheme=None)

Bases: object

Abstract away the concept of horizontal and vertical regridding by providing a general scheme that handles both under the hood.

__init__(horizontal_scheme=None, vertical_scheme=None)

General scheme which handles both vertical and horizontal regrid.

The GeneralRegridScheme is useful to define a regrid method(s) and allow this regridding to be overridden after the fact via a configuration file where necessary. In the case where a fixed regridding scheme is wanted and no override is to be allowed, please use the regridding scheme directly.

Parameters:

• horizontal_scheme (str, optional) – Name or instance of horizontal regridding scheme to use. Default regridding scheme is None. A horizontal regrid scheme set in the GlobalConfiguration will take precedence over the value passed here.

• vertical_scheme (str, optional) – Name or instance of vertical regridding scheme to use. Default regridding scheme is None. A vertical regrid scheme set in the GlobalConfiguration will take precedence over the value passed here.

regridder(src_grid, target_grid)

Creates a GeneralRegridder to regrid from the source to target grid.

Parameters:

• src_grid (Cube) – Defining the source grid.

• target_grid (Cube) – Defining the target grid.

Returns:

Callable with the interface callable(cube)

where cube is a cube with the same grid as src_grid that is to be regridded to the target_grid.

Return type:

Callable

class ants.regrid.GeneralRegridder(src_grid, target_grid, horizontal_regridder=None, vertical_regridder=None)

Bases: object

__call__(cube)

Regrid both vertical and horizontally where appropriate.

Parameters:

cube (Cube) – Source to be regridded.

Returns:

Redridded result.

Return type:

Cube

__init__(src_grid, target_grid, horizontal_regridder=None, vertical_regridder=None)

General regridder abstracting away horizontal and vertical regridding.

Parameters:

• src_grid (Cube) – Defining the source grid.

• target_grid (Cube) – Defining the target grid.

• horizontal_regridder (str, optional) – Horizontal regridder callable.

• vertical_regridder (str, optional) – Vertical regridder callable.

Submodules

ants.regrid.esmf module

class ants.regrid.esmf.ConservativeESMF

Bases: object

ESMF regridding scheme using esmpy.

Regridding suitable for general curvilinear grids.

__init__()

regridder(src_grid_cube, target_grid_cube, **kwargs)

Creates an ESMF regridding scheme using esmpy.

Parameters:

• src_grid_cube (Cube) – Defining the source grid.

• target_grid_cube (Cube) – Defining the target grid.

Returns:

Callable with the interface callable(cube)

where cube is a cube with the same grid as src_grid_cube that is to be regridded to the target_grid_cube.

Return type:

ESMFRegridder

class ants.regrid.esmf.ESMFRegridder(src_cube, target_cube, **kwargs)

Bases: object

__call__(inp_cube)

Apply the interpolation weights to the source field.

Parameters:

inp_cube (Cube) – Defining the input cube which has same horizontal grid as src_cube, see constructor.

Returns:

Target cube with regridded data.

Return type:

class:~iris.cube.Cube

__init__(src_cube, target_cube, **kwargs)

Regridding using ESMF via ESMPY.

Suitable for general curvilinear grids.

Parameters:

• src_cube (Cube) – Defining the source grid. Must have latitude and longitude coordinates. Latitude and longitude can be axes (iris.coords.DimCoord) or auxilliary coordinates (iris.coords.AuxCoord) – lat/lon axes will be converted to iris.coords.AuxCoord if need be. The cube can have additional axes, e.g. elevation, time, etc., data will be interpolated linearly along those axes.

• target_cube (Cube) – Defining the target grid. Same conditions as for src_cube apply for the coordinates.

• method (str, optional) –

  Defining the regridding method. Currently supported methods are:

  ”areaWeighted” (default)

• persistent_cache (bool, optional) – Determine whether cache persists between runs. That is, whether the cache persists after the program is terminated and will be available for successive runs of the application. The cache location is determined by the TMPDIR environmental variable. Cache filenames are derived from source-target grid metadata checksums. Default is False (that is, cache is destroyed with the class).

property cache

Return the cache produced from the esmf regrid.

Return the deferred columns, rows and weights esmf cache: where columns correspond to source cell indices; rows correspond to target cell indices and weights corresponding to the column-row mapping. All three will match in size. The weights correspond to the fraction of the target cell which is overlapped by the given source cell. See the following illustration:

|-|             - Source
|---------|    - Target

Here the weight between the source and target cell is 0.25 as the
source cell covers 25% of the target cell.

|---------|     - Source
|-|              - Target

Here the weight between the source and target cell is 1 as the
source cell covers 100% of the target cell.

See also

http://earthsystemmodeling.org/docs/release/ESMF_8_3_1/ESMF_refdoc/node3.html#SECTION03029000000000000000 : for esmf weight only file specification.

Note

ESMPy currently only creates a “Weight Only Weight File” and so doesn’t contain the destination fraction (frac_b). Points are assumed not to extend beyond the grid.

Returns:

source indices (columns), target indices (rows), weights.

Return type:

numpy.ndarray, numpy.ndarray, numpy.ndarray

Examples

Example usage of cache in performing area weighted regrid calculation:

regridder = self.scheme.regridder(source, target_grid)
columns, rows, weights = regridder.cache
source_flattened = source.data.reshape(-1)
result = target_grid.copy(
    np.zeros(target_grid.shape, dtype='float'))
result_flattened = result.data.reshape(-1)
for ind in range(rows.size):
    row = rows[ind]
    column = columns[ind]
    result_flattened[row] = (
        result_flattened[row] +
        (weights[ind]*source_flattened[column]))

Example as above but with sparse array usage:

result = target.copy(np.zeros(target.shape, dtype='float'))
sparse_array = scipy.sparse.coo_matrix(
   (weights, (rows, columns)),
   shape=(np.prod([tgt.data.shape[1], tgt.data.shape[2]]),
          src.data.size)).tocsc()
result.data.reshape(-1)[:] = (sparse_array * src.data.reshape(-1))

ants.regrid.interpolation module

class ants.regrid.interpolation.Conservative

Bases: _StratifyScheme

Conservative regridding scheme.

regridder(src_grid, tgt_grid)

Return a conservative vertical interpolator.

A callable is returned for performing vertical interpolation between a specified source and target. This is done via the regridding interface to iris (iris.regrid(target, scheme)).

Parameters:

• src_grid (Cube) – Defining the source grid.

• tgt_grid (Cube) – Defining the target grid.

Returns:

Callable with the interface callable(cube)

where cube is a cube with the same grid as src_grid and is to be nterpolated to tgt_grid.

Return type:

Callable

class ants.regrid.interpolation.Linear(extrapolation='linear')

Bases: _StratifyPointsScheme

Linear regridding scheme.

INTERPOLATION = 'linear'

__init__(extrapolation='linear')

Return a Linear regridder object.

Parameters:

extrapolation (str, optional) – Extrapolation modes include, ‘nearest’, ‘linear’ and ‘nan’.

class ants.regrid.interpolation.Nearest(extrapolation='nearest')

Bases: _StratifyPointsScheme

Nearest neighbour regridding scheme.

INTERPOLATION = 'nearest'

__init__(extrapolation='nearest')

Return a Nearest regridder object.

Parameters:

extrapolation (str, optional) – Extrapolation modes include, ‘nearest’, ‘linear’ and ‘nan’.

class ants.regrid.interpolation.StratifyInterpolator(src_grid, tgt_grid, interpolator)

Bases: object

Stratification interpolator.

__call__(src)

Regrid the provided source.

Parameters:

src (Cube) – Source dataset to be regridded.

Returns:

Interpolated result.

Return type:

Cube

__init__(src_grid, tgt_grid, interpolator)

Return a stratify regridder object.

Parameters:

interpolation (str) – Interpolation schemes include, ‘linear’, optional

ants.regrid.interpolation.scalar_coord(cube, coord_name)

Determine whether coordinate is scalar.

ants.regrid.rectilinear module

class ants.regrid.rectilinear.AreaWeighted(mdtol=1)

Bases: AreaWeighted

regridder(src_grid_cube, target_grid_cube)

Creates an area-weighted regridder to perform regridding from the source grid to the target grid.

Typically you should use iris.cube.Cube.regrid() for regridding a cube. There are, however, some situations when constructing your own regridder is preferable. These are detailed in the user guide.

• This regridder automatically converts the target to zonal mean data if required.

Parameters:

• src_grid_cube (Cube) – defining the source grid.

• target_grid_cube (Cube) – defining the target grid.

Returns:

Callable with the interface callable(cube)

Return type:

Callable

class ants.regrid.rectilinear.Linear(extrapolation_mode='nan')

Bases: Linear

__init__(extrapolation_mode='nan')

Linear interpolation and regridding scheme.

Suitable for interpolating or regridding over one or more orthogonal coordinates. This class acts as a wrapper to the iris iris.analysis.Linear, with the following differences:

• Default extrapolation mode to ‘nan’.

• Adheres to ANTS coordinate systems of equivalence (see ants.coord_systems).

• This regridder automatically converts the target to zonal mean data if required.

interpolator(cube, coords)

Creates a linear interpolator.

Interpolation is to perform over the given Cube specified by the dimensions of the given coordinates.

Parameters:

• cube (iris.cube.Cube) – Source to be interpolated.

• coords (Iterable) – The names or coordinate instances that are to be interpolated over.

Returns:

Callable with the interface: callable(sample_points, collapse_scalar=True)

where sample_points is a sequence containing an array of values for each of the coordinates passed to this method, and collapse_scalar determines whether to remove length one dimensions in the result cube caused by scalar values in sample_points.

Return type:

Callable

regridder(src_grid, target_grid)

Creates a linear regridder to regrid from the source to target grid. This regridder automatically converts the target to zonal mean data if required.

Parameters:

• src_grid (Cube) – Defining the source grid.

• target_grid (Cube) – Defining the target grid.

Returns:

Callable with the interface callable(cube)

where cube is a cube with the same grid as src_grid that is to be regridded to the target_grid.

Return type:

Callable

class ants.regrid.rectilinear.TwoStage(mdtol=1)

Bases: AreaWeighted

Two-stage regridding scheme.

In the case where the source an target are the same coordinate system, the a single step area weighted regrid is performed between the provided source and target. When this is not the case, bilinear interpolation occurs between the original source and an intermediate grid. The intermediate grid has the same dimension size as the original source, covering the same extent, but with coordinate system matching the target grid. Following this, an area weighted regrid is performed between this intermediate grid and the target grid provided.

• This regridder automatically converts the target to zonal mean data if required.

regridder(src_grid_cube, target_grid_cube)

Creares a two-stage regridding scheme.

Parameters:

• src_grid_cube (Cube) – Definning the source grid.

• target_grid_cube (Cube) – Definning the target grid.

Returns:

Callable with the interface callable(cube)

where cube is a cube with the same grid as src_grid_cube that is to be regridded to the target_grid_cube.

Return type:

Callable

ants.regrid.rectilinear.compare_coordinate_reference_systems(source_crs, target_crs)

return True if the two CRSs are not equivalent and therefore a two stage regrid is required

ants.regrid.rectilinear.fill_range(source_cube, indices, value, coord)

ants.regrid.rectilinear.outside_bounds(bounds1, bounds2, decreasing)