salem.Grid¶
- class salem.Grid(proj=<pyproj.Proj object at 0x7f02c81c1a10>, nxny=None, dxdy=None, corner=None, ul_corner=None, ll_corner=None, pixel_ref='center')¶
A structured grid on a map projection.
Central class in the library, taking over user concerns about the gridded representation of georeferenced data. It adds a level of abstraction by defining a new coordinate system.
A grid requires georeferencing information at instantiation and is immutable in principle. I didn’t implement barriers: if you want to mess with it, you can (not recommended). Note that in most cases, users won’t have to define the grid themselves: most georeferenced datasets contain enough metadata for Salem to determine the data’s grid automatically.
A grid is defined by a projection, a reference point in this projection, a grid spacing and a number of grid points. The grid can be defined in a “upper left” convention (reference point at the top left corner, dy negative - always -). This is the python convention, but not that of all datasets (for example, the output of the WRF model follows a down-left corner convention). Therefore, grids can also be defined in a “lower left” corner convention (dy positive). The use of one or the other convention depends on the data, so the user should take care of what he is doing.
The reference points of the grid points might be located at the corner of the pixel (upper left corner for example if dy is negative) or the center of the pixel (most atmospheric datasets follow this convention). The two concepts are truly equivalent and each grid instance gives access to one representation or another (“center_grid” and “corner_grid” properties). Under the hood, Salem uses the representation it needs to do the job by accessing either one or the other of these parameters. The user should know which convention he needs for his purposes: some grid functions and properties are representation dependant (transform, ll_coordinates, ...) while some are not (extent, corner_ll_coordinates ...).
Attributes
ij_coordinates Tuple of i, j coordinates of the grid points. x_coord x coordinates of the grid points (1D, no mesh) y_coord y coordinates of the grid points (1D, no mesh) xy_coordinates Tuple of x, y coordinates of the grid points. ll_coordinates Tuple of longitudes, latitudes of the grid points. center_grid (Grid instance) representing the grid in center coordinates. corner_grid (Grid instance) representing the grid in corner coordinates. extent [left, right, bottom, top] boundaries of the grid in the grid’s proj (pyproj.Proj instance) defining the grid’s map projection nx (int) number of grid points in the x direction ny (int) number of grid points in the y direction dx (float) x grid spacing (always positive) dy (float) y grid spacing (positive if ll_corner, negative if ul_corner) x0 (float) reference point in X proj coordinates y0 (float) reference point in Y proj coordinates order (str) ‘ul_corner’ or ‘ll_corner’ convention pixel_ref (str) ‘center’ or ‘corner’ convention - __init__(proj=<pyproj.Proj object at 0x7f02c81c1a10>, nxny=None, dxdy=None, corner=None, ul_corner=None, ll_corner=None, pixel_ref='center')¶
Parameters: proj : pyproj.Proj instance
defines the grid’s map projection. Defaults to ‘PlateCarree’ (wgs84)
nxny : (int, int)
(nx, ny) number of grid points
dxdy : (float, float)
(dx, dy) grid spacing in proj coordinates
corner : (float, float)
- (x0, y0) cartesian coordinates (in proj) of the upper left
or lower left corner, depending on the sign of dy
ul_corner : (float, float)
(x0, y0) cartesian coordinates (in proj) of the upper left corner
ll_corner : (float, float)
(x0, y0) cartesian coordinates (in proj) of the lower left corner
pixel_ref : str
either ‘center’ or ‘corner’ (default: ‘center’). Tells the Grid object where the (x0, y0) is located in the grid point
Notes
The corner, ul_corner and ll_corner parameters are mutually exclusive: set one and only one. If pixel_ref is set to ‘corner’, the ul_corner parameter specifies the corner grid point’s upper left corner coordinates. Equivalently, the ll_corner parameter then specifies the corner grid point’s lower left coordinate.
Examples
>>> g = Grid(nxny=(3, 2), dxdy=(1, 1), ll_corner=(0, 0), proj=wgs84) >>> lon, lat = g.ll_coordinates >>> lon array([[ 0., 1., 2.], [ 0., 1., 2.]]) >>> lat array([[ 0., 0., 0.], [ 1., 1., 1.]]) >>> lon, lat = g.corner_grid.ll_coordinates >>> lon array([[-0.5, 0.5, 1.5], [-0.5, 0.5, 1.5]]) >>> lat array([[-0.5, -0.5, -0.5], [ 0.5, 0.5, 0.5]]) >>> g.corner_grid == g.center_grid # the two reprs are equivalent True
Methods
__init__([proj, nxny, dxdy, corner, ...]) Parameters: extent_in_crs([crs]) Get the extent of the grid in a desired crs. ij_to_crs(i, j[, crs, nearest]) Converts local i, j to cartesian coordinates in a specified crs map_gridded_data(data[, grid, interp, ks, out]) Reprojects any structured data onto the local grid. region_of_interest([shape, geometry, grid, ...]) Computes a region of interest (ROI). regrid([nx, ny, factor]) Make a copy of the grid with an updated spatial resolution. transform(x, y[, z, crs, nearest, maskout]) Converts any coordinates into the local grid. Attributes
center_grid (Grid instance) representing the grid in center coordinates. corner_grid (Grid instance) representing the grid in corner coordinates. extent [left, right, bottom, top] boundaries of the grid in the grid’s ij_coordinates Tuple of i, j coordinates of the grid points. ll_coordinates Tuple of longitudes, latitudes of the grid points. pixcorner_ll_coordinates Tuple of longitudes, latitudes (dims: ny+1, nx+1) at the corners of the grid. x_coord x coordinates of the grid points (1D, no mesh) xstagg_ll_coordinates Tuple of longitudes, latitudes of the X staggered grid. xstagg_xy_coordinates Tuple of x, y coordinates of the X staggered grid. xy_coordinates Tuple of x, y coordinates of the grid points. y_coord y coordinates of the grid points (1D, no mesh) ystagg_ll_coordinates Tuple of longitudes, latitudes of the Y staggered grid. ystagg_xy_coordinates Tuple of x, y coordinates of the Y staggered grid.