salem.Grid¶

class salem.Grid(proj=<Other Coordinate Operation Transformer: longlat> Description: PROJ-based coordinate operation Area of Use: - undefined, nxny=None, dxdy=None, x0y0=None, pixel_ref='center', corner=None, ul_corner=None, ll_corner=None)[source]¶

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

proj: pyproj.Proj instance defining the grid’s map projection.
nx: number of grid points in the x direction.
ny: number of grid points in the y direction.
dx: x grid spacing (always positive).
dy: y grid spacing (positive if ll_corner, negative if ul_corner).
x0: X reference point in projection coordinates.
y0: Y reference point in projection coordinates.
origin: 'upper-left' or 'lower-left'.
pixel_ref: if coordinates are at the 'center' or 'corner' of the grid.
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.
xstagg_xy_coordinates: Tuple of x, y coordinates of the X staggered grid.
ystagg_xy_coordinates: Tuple of x, y coordinates of the Y staggered grid.
xstagg_ll_coordinates: Tuple of longitudes, latitudes of the X staggered grid.
ystagg_ll_coordinates: Tuple of longitudes, latitudes of the Y staggered grid.
center_grid: salem.Grid instance representing the grid in center coordinates.
corner_grid: salem.Grid instance representing the grid in corner coordinates.
extent: [left, right, bottom, top] boundaries of the grid in the grid’s

__init__(proj=<Other Coordinate Operation Transformer: longlat> Description: PROJ-based coordinate operation Area of Use: - undefined, nxny=None, dxdy=None, x0y0=None, pixel_ref='center', corner=None, ul_corner=None, ll_corner=None)[source]¶

Parameters

projpyproj.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. dx must be positive, while dy can be positive or negative depending on the origin grid point’s lecation (upper-left or lower-left)
x0y0(float, float): (x0, y0) cartesian coordinates (in proj) of the upper left or lower left corner, depending on the sign of dy
pixel_refstr: either ‘center’ or ‘corner’ (default: ‘center’). Tells the Grid object where the (x0, y0) is located in the grid point. If pixel_ref is set to ‘corner’ and dy < 0, the x0y0 kwarg specifies the grid point’s upper left corner coordinates. Equivalently, if dy > 0, x0y0 specifies the grid point’s lower left coordinate.
corner(float, float): DEPRECATED in favor of x0y0 (x0, y0) cartesian coordinates (in proj) of the upper left or lower left corner, depending on the sign of dy
ul_corner(float, float): DEPRECATED in favor of x0y0 (x0, y0) cartesian coordinates (in proj) of the upper left corner
ll_corner(float, float): DEPRECATED in favor of x0y0 (x0, y0) cartesian coordinates (in proj) of the lower left corner

Examples

>>> g = Grid(nxny=(3, 2), dxdy=(1, 1), x0y0=(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, x0y0, ...])	Parameters
`almost_equal`(other[, rtol, atol])	A less strict comparison between grids.
`extent_as_polygon`([crs])	Get the extent of the grid in a shapely.Polygon and desired crs.
`extent_in_crs`([crs])	Get the extent of the grid in a desired crs.
`from_dict`(d)	Create a Grid from a dictionary
`from_json`(fpath)	Create a Grid from a json file
`grid_lookup`(other)	Performs forward transformation of any other grid into self.
`ij_to_crs`(i, j[, crs, nearest])	Converts local i, j to cartesian coordinates in a specified crs
`lookup_transform`(data[, grid, method, lut, ...])	Performs the forward transformation of gridded data into self.
`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.
`to_dataset`()	Creates an empty dataset based on the Grid's geolocalisation.
`to_dict`()	Serialize this grid to a dictionary.
`to_geometry`([to_crs])	Makes a geometrical representation of the grid (e.g.
`to_json`(fpath)	Serialize this grid to a json file.
`transform`(x, y[, z, crs, nearest, maskout])	Converts any coordinates into the local grid.

Attributes

`center_grid`	`salem.Grid` instance representing the grid in center coordinates.
`corner_grid`	`salem.Grid` instance representing the grid in corner coordinates.
`dx`	x grid spacing (always positive).
`dy`	y grid spacing (positive if ll_corner, negative if ul_corner).
`extent`	[left, right, bottom, top] boundaries of the grid in the grid's projection.
`ij_coordinates`	Tuple of i, j coordinates of the grid points.
`ll_coordinates`	Tuple of longitudes, latitudes of the grid points.
`nx`	number of grid points in the x direction.
`ny`	number of grid points in the y direction.
`origin`	`'upper-left'` or `'lower-left'`.
`pixcorner_ll_coordinates`	Tuple of longitudes, latitudes (dims: ny+1, nx+1) at the corners of the grid.
`pixel_ref`	if coordinates are at the `'center'` or `'corner'` of the grid.
`proj`	`pyproj.Proj` instance defining the grid's map projection.
`x0`	X reference point in projection coordinates.
`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.
`y0`	Y reference point in projection coordinates.
`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.