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
, optionallylon_b
,lat_b
for conservative methods, andmask
. 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
andlat_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
\[\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.