User API¶

Regridder¶

class xesmf.frontend.Regridder(ds_in, ds_out, method, locstream_in=False, locstream_out=False, periodic=False, parallel=False, **kwargs)¶

__init__(ds_in, ds_out, method, locstream_in=False, locstream_out=False, periodic=False, parallel=False, **kwargs)¶

Make xESMF regridder

Parameters:

ds_in, ds_outxarray Dataset, DataArray, or dictionary

Contain input and output grid coordinates. All variables that the cf-xarray accessor understand are accepted. Otherwise, look for lon, lat, optionally lon_b, lat_b for conservative methods, and mask. Note that for mask, the ESMF convention is used, where masked values are identified by 0, and non-masked values by 1.

For conservative methods, if bounds are not present, they will be computed using cf-xarray (only 1D coordinates are currently supported).

Shape can be 1D (n_lon,) and (n_lat,) for rectilinear grids, or 2D (n_y, n_x) for general curvilinear grids. Shape of bounds should be (n+1,) or (n_y+1, n_x+1). CF-bounds (shape (n, 2) or (n, m, 4)) are also accepted if they are accessible through the cf-xarray accessor.

If either dataset includes a 2d mask variable, that will also be used to inform the regridding.

If DataArrays are passed, the are simply converted to Datasets.

methodstr

Regridding method. Options are

‘bilinear’
‘conservative’, need grid corner information
‘conservative_normed’, need grid corner information
‘patch’
‘nearest_s2d’
‘nearest_d2s’

periodicbool, optional

Periodic in longitude? Default to False. Only useful for global grids with non-conservative regridding. Will be forced to False for conservative regridding.

parallelbool, optional

Compute the weights in parallel with Dask. Default to False. If True, weights are computed in parallel with Dask on subsets of the output grid using chunks of the output grid.

filenamestr, optional

Name for the weight file. The default naming scheme is:

{method}_{Ny_in}x{Nx_in}_{Ny_out}x{Nx_out}.nc

e.g. bilinear_400x600_300x400.nc

reuse_weightsbool, optional

Whether to read existing weight file to save computing time. False by default (i.e. re-compute, not reuse).

extrap_methodstr, optional

Extrapolation method. Options are

‘inverse_dist’
‘nearest_s2d’

extrap_dist_exponentfloat, optional

The exponent to raise the distance to when calculating weights for the extrapolation method. If none are specified, defaults to 2.0

extrap_num_src_pntsint, optional

The number of source points to use for the extrapolation methods that use more than one source point. If none are specified, defaults to 8

weightsNone, coo_matrix, dict, str, Dataset, Path,

Regridding weights, stored as

a scipy.sparse COO matrix,
a dictionary with keys row_dst, col_src and weights,
an xarray Dataset with data variables col, row and S,
or a path to a netCDF file created by ESMF.

If None, compute the weights.

ignore_degeneratebool, optional

If False (default), raise error if grids contain degenerated cells (i.e. triangles or lines, instead of quadrilaterals)

unmapped_to_nan: boolean, optional

Set values of unmapped points to np.nan instead of zero (ESMF default). This is useful for target cells lying outside of the source domain when no output mask is defined. If an output mask is defined, or regridding method is nearest_s2d or nearest_d2s, this option has no effect.

Returns:

regridderxESMF regridder object

class xesmf.frontend.SpatialAverager(ds_in, polys, ignore_holes=False, periodic=False, filename=None, reuse_weights=False, weights=None, ignore_degenerate=False, geom_dim_name='geom')¶

__init__(ds_in, polys, ignore_holes=False, periodic=False, filename=None, reuse_weights=False, weights=None, ignore_degenerate=False, geom_dim_name='geom')¶

Compute the exact average of a gridded array over a geometry.

This uses the ESMF conservative regridding method to compute and apply weights mapping a 2D field unto geometries defined by polygons. The conservative method preserves the areal average of the input field. That is, the value at each output grid cell is the average input value over the output grid area. Here, the output grid cells are not rectangles defined by four corners, but polygons defined by multiple vertices (ESMF.Mesh objects). The regridding weights thus compute the areal-average of the input grid over each polygon.

For multi-parts geometries (shapely.MultiPolygon), weights are computed for each geometry, then added, to compute the average over all geometries.

When polygons include holes, the weights over the holes can either be substracted, or ignored.

Parameters:

ds_inxr.DataArray or xr.Dataset or dictionary

Contain input and output grid coordinates. Look for variables lon, lat, lon_b and lat_b.

Optionally looks for mask, in which case the ESMF convention is used, where masked values are identified by 0, and non-masked values by 1.

Shape can be 1D (n_lon,) and (n_lat,) for rectilinear grids, or 2D (n_y, n_x) for general curvilinear grids. Shape of bounds should be (n+1,) or (n_y+1, n_x+1). DataArrays are converted to Datasets.

polyssequence of shapely Polygons and MultiPolygons

Sequence of polygons (lon, lat) over which to average ds_in.

ignore_holesbool

Whether to ignore holes in polygons. Default (True) is to subtract the weight of holes from the weight of the polygon.

filenamestr, optional

Name for the weight file. The default naming scheme is:

spatialavg_{Ny_in}x{Nx_in}_{Npoly_out}.nc

e.g. spatialavg_400x600_30.nc

reuse_weightsbool, optional

Whether to read existing weight file to save computing time. False by default (i.e. re-compute, not reuse).

weightsNone, coo_matrix, dict, str, Dataset, Path,

Regridding weights, stored as

a scipy.sparse COO matrix,
a dictionary with keys row_dst, col_src and weights,
an xarray Dataset with data variables col, row and S,
or a path to a netCDF file created by ESMF.

If None, compute the weights.

ignore_degeneratebool, optional

If False (default), raise error if grids contain degenerated cells (i.e. triangles or lines, instead of quadrilaterals)

self.geom_dim_namestr

Name of dimension along which averages for each polygon are stored.

Returns:

xarray.DataArray: Average over polygons along geom_dim_name dimension. The lon and lat coordinates are the polygon centroid coordinates.

References

This approach is inspired by OCGIS.

property w: xarray.DataArray¶

Return weights as a 3D DataArray with dimensions (geom, y_in, x_in).

ESMF stores the weights in a 2D array with dimensions (out_dim, in_dim), the size of the output and input grids respectively (ny x nx). This property returns the weights reshaped as a 3D array to simplify comparisons with the original grids.

util¶

xesmf.util.grid_2d(lon0_b, lon1_b, d_lon, lat0_b, lat1_b, d_lat)¶

2D rectilinear grid centers and bounds

Parameters:

lon0_b, lon1_bfloat: Longitude bounds
d_lonfloat: Longitude step size, i.e. grid resolution
lat0_b, lat1_bfloat: Latitude bounds
d_latfloat: Latitude step size, i.e. grid resolution

Returns:

dsxarray DataSet with coordinate values

xesmf.util.cf_grid_2d(lon0_b, lon1_b, d_lon, lat0_b, lat1_b, d_lat)¶

CF compliant 2D rectilinear grid centers and bounds.

Parameters:

lon0_b, lon1_bfloat: Longitude bounds
d_lonfloat: Longitude step size, i.e. grid resolution
lat0_b, lat1_bfloat: Latitude bounds
d_latfloat: Latitude step size, i.e. grid resolution

Returns:

dsxarray.DataSet with coordinate values

xesmf.util.grid_global(d_lon, d_lat, cf=False, lon1=180)¶

Global 2D rectilinear grid centers and bounds

Parameters:

d_lonfloat: Longitude step size, i.e. grid resolution
d_latfloat: Latitude step size, i.e. grid resolution
cfbool: Return a CF compliant grid.
lon1{180, 360}: Right longitude bound. According to which convention is used longitudes will vary from -180 to 180 or from 0 to 360.

Returns:

dsxarray DataSet with coordinate values

xesmf.util.split_polygons_and_holes(polys)¶

Split the exterior boundaries and the holes for a list of polygons.

If MultiPolygons are encountered in the list, they are flattened out in their constituents.

Parameters:

polysSequence of shapely Polygons or MultiPolygons

Returns:

exteriorslist of Polygons: The polygons without any holes
holeslist of Polygons: Holes of the polygons as polygons
i_extlist of integers: The index in polys of each polygon in exteriors.
i_hollist of integers: The index in polys of the owner of each hole in holes.

xesmf.util.simple_tripolar_grid(nlons, nlats, lat_cap=60, lon_cut=-300)¶

Generate a simple tripolar grid, regular under lat_cap.

Parameters:

nlons: int: Number of longitude points.
nlats: int: Number of latitude points.
lat_cap: float: Latitude of the northern cap.
lon_cut: float: Longitude of the periodic boundary.

data¶

Standard test data for regridding benchmark.

xesmf.data.wave_smooth(lon, lat)¶

Spherical harmonic with low frequency.

Parameters:

lon, lat2D numpy array or xarray DataArray: Longitute/Latitude of cell centers

Returns:

f2D numpy array or xarray DataArray depending on input: 2D wave field

Notes

Equation from [1] [2]:

\[\begin{split}Y_2^2 = 2 + \cos^2(\\theta) \cos(2 \phi)\end{split}\]

References

[1]

Jones, P. W. (1999). First-and second-order conservative remapping schemes for grids in spherical coordinates. Monthly Weather Review, 127(9), 2204-2210.

[2]

Ullrich, P. A., Lauritzen, P. H., & Jablonowski, C. (2009). Geometrically exact conservative remapping (GECoRe): regular latitude–longitude and cubed-sphere grids. Monthly Weather Review, 137(6), 1721-1741.