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, thex0y0
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, ...])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.
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. for drawing).
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
salem.Grid
instance representing the grid in center coordinates.salem.Grid
instance representing the grid in corner coordinates.x grid spacing (always positive).
y grid spacing (positive if ll_corner, negative if ul_corner).
[left, right, bottom, top] boundaries of the grid in the grid's projection.
ij_coordinates
Tuple of i, j coordinates of the grid points.
Tuple of longitudes, latitudes of the grid points.
number of grid points in the x direction.
number of grid points in the y direction.
'upper-left'
or'lower-left'
.pixcorner_ll_coordinates
Tuple of longitudes, latitudes (dims: ny+1, nx+1) at the corners of the grid.
if coordinates are at the
'center'
or'corner'
of the grid.pyproj.Proj
instance defining the grid's map projection.X reference point in projection coordinates.
x coordinates of the grid points (1D, no mesh)
Tuple of longitudes, latitudes of the X staggered grid.
Tuple of x, y coordinates of the X staggered grid.
Tuple of x, y coordinates of the grid points.
Y reference point in projection coordinates.
y coordinates of the grid points (1D, no mesh)
Tuple of longitudes, latitudes of the Y staggered grid.
Tuple of x, y coordinates of the Y staggered grid.