base_grid

class gridkit.base_grid.BaseGrid(crs=None)[source]

Bases: object

Abstraction base class that represents an infinite grid.

Initialization parameters

offset: Tuple(float, float) (optional)

The offset in dx and dy. Shifts the whole grid by the specified amount. The shift is always reduced to be maximum one cell size. If the supplied shift is larger, a shift will be performed such that the new center is a multiple of dx or dy away. Default: (0,0)

crs: pyproj.CRS (optional)

The coordinate reference system of the grid. The value can be anything accepted by pyproj.CRS.from_user_input(), such as an epsg integer (eg 4326), an authority string (eg “EPSG:4326”) or a WKT string. If None, no CRS is set. Default: None

abstract property definition

The parameters that define the infinite grid. Passing these parameters into a new object instance will create a perfectly aligned grid. Note that Bounded Grids are defined by the bounds and data. Therefore, the properties returned by this property do describe the grid but cannot be used to create a new Bounded Grid object instance.

Returns:

A dictionary outlying the parameters that define the grid

Return type:

dict

property crs

The Coordinate Reference System (CRS) represented as a pyproj.CRS object.

Returns:

None if the CRS is not set, and to set the value it :getter: Returns a pyproj.CRS or None. When setting, the value Coordinate Reference System of the geometry objects. Can be anything accepted by pyproj.CRS.from_user_input(), such as an authority string (eg “EPSG:4326”) or a WKT string.

Return type:

pyproj.CRS

property size: float

The size of the cell as supplied when initiating the class

abstract dx() → float[source]

The distance in x-direction between two adjacent cell centers.

abstract dy() → float[source]

The distance in y-direction between two adjacent cell centers.

property cell_height: float

The height of a cell

property cell_width: float

The width of a cell

property offset: float

The offset off the grid in dx and dy. The offset is never larger than the size of a single grid cell. The offset represents the shift from the origin (0,0).

property rotation: float

The counter-clockwise rotation of the grid around the origin in degrees.

property rotation_matrix

The matrix performing the counter-clockwise rotation of the grid around the origin in degrees. Note: makes a copy every time this is called.

property rotation_matrix_inv

The matrix performing the inverse (clockwise) rotation of the grid around the origin in degrees. Note: makes a copy every time this is called.

property area

The area of a cell. The unit is the unit used for the cell’s BaseGrid.size(), squared.

abstract centroid(index) → float[source]

Coordinates at the center of the cell(s) specified by index.

If this method is called on a ‘Bounded’ class, the index argument is optional. In such a case the cell IDs of the cells contained in the Bounded product are returned.

Parameters:

index (GridIndex) – The index of the cell(s) of which the centroid is to be obtained.

Returns:

Multidimensional array containing the longitude and latitude of the center of each cell respectively, in (width, height, lonlat)

Return type:

numpy.ndarray

Raises:

ValueError – No index parameter was supplied to a grid that does not contain data.

abstract cells_near_point(point) → float[source]

The cells nearest to a point, often used in interpolation at the location of the point. For a TriGrid there are 6 nearby points. For a HexGrid there are 3 nearby points. For a RectGrid there are 4 nearby points.

abstract to_bounded(bounds, fill_value=nan)[source]

Create a bounded version of this grid where the data in the bounds is filled with the supplied fill_value

Parameters:

  • bounds (tuple) – The bounds of the area of interest in (minx, miny, maxx, maxy). The bounds need to be aligned to the grid. See BaseGrid.align_bounds()

  • fill_value (numpy.dtype (optional)) – The value to assign to the newly created array that fills the supplied bounds. Default: numpy.nan

Returns:

A bounded version of the current grid where the data is filled with fill_value.

Return type:

BoundedHexGrid or BoundedRectGrid

See also

BaseGrid.to_bounded(), RectGrid.to_bounded(), HexGrid.to_bounded()

abstract relative_neighbours(depth=1, connect_corners=False, include_selected=False)[source]
neighbours(index, depth=1, connect_corners=False, include_selected=False)[source]

The indices of the neighbouring cells. The argument ‘depth’ can be used to include cells from further away.

Parameters:

  • index (numpy.ndarray) – The index of the cell(s) of which to get the neighbours.

  • depth (int Default: 1) – Determines the number of neighbours that are returned. If depth=1 the direct neighbours are returned. If depth=2 the direct neighbours are returned, as well as the neighbours of these neighbours. depth=3 returns yet another layer of neighbours, and so forth.

  • connect_corners (bool Default: False) – Whether to consider cells that touch corners but not sides as neighbours. This does not apply to HexGrid.relative_neighbours(). For further information on this argument, refer to RectGrid.relative_neighbours().

  • include_selected (bool Default: False) – Whether to include the specified cell in the return array. Even though the specified cell can never be a neighbour of itself, this can be useful when for example a weighted average of the neighbours is desired in which case the cell itself often should also be included.

Examples

The direct neighbours of a cell can be returned by using depth=1, which is the default.

>>> from gridkit.rect_grid import RectGrid
>>> grid = RectGrid(dx=2, dy=3)
>>> grid.neighbours([1,2]).index
array([[1, 3],
       [0, 2],
       [2, 2],
       [1, 1]])

For more detailed examples:

See also

RectGrid.relative_neighbours(), HexGrid.relative_neighbours(), TriGrid.relative_neighbours()

abstract cell_at_point(point: ndarray) → tuple[source]

Determine the ID of the cell in which point falls.

Parameters:

point (tuple) – The coordinates of the point to which to match the cell

Returns:

The ID of the cell in (x,y)

Return type:

tuple

abstract cell_corners(index: ndarray) → ndarray[source]

Coordinates of the cell corners as specified by index.

Parameters:

index (GridIndex) – The indices of the cells of interest. Each id contains an x and y value.

Returns:

An array of coordinates in (x,y) specifying each of the corners. The returned array will be of the same shape as the input index, but with an extra axis containing the corners. The last axis is always of size 2 (x,y). The second to last axis is the length of the corners. The other axis are in the shape of the supplied index.

Return type:

numpy.ndarray

is_aligned_with(other)[source]

Returns True if grids are algined and False if they are not. Grids are considered to be aligned when: - they are the same type of grid - the CRS is the same - the cell_size is the same - the offset from origin is the same - the cell shape is the same

Returns:

Whether or not the grids are aligned

Return type:

bool

abstract to_crs(crs)[source]

Transforms the Coordinate Reference System (CRS) from the current CRS to the desired CRS. This will update the cell size and the origin offset.

The crs attribute on the current grid must be set.

Parameters:

crs (Union[int, str, pyproj.CRS]) – The value can be anything accepted by pyproj.CRS.from_user_input(), such as an epsg integer (eg 4326), an authority string (eg “EPSG:4326”) or a WKT string.

See also

Examples:

Example: coordinate transformations

Methods:

RectGrid.to_crs() HexGrid.to_crs() BoundedRectGrid.to_crs() BoundedHexGrid.to_crs()

property parent_grid
anchor(target_loc: Tuple[float, float], cell_element: Literal['centroid', 'corner'] = 'centroid', in_place: bool = False)[source]

Position a specified part of a grid cell at a specified location. This shifts (the origin of) the grid such that the specified cell_element is positioned at the specified target_loc. This is useful for example to align two grids by anchoring them to the same location.

Parameters:

  • target_loc (Tuple[float, float]) – The coordinates of the point at which to anchor the grid in (x,y)

  • cell_element (Literal["centroid", "corner"] - Default: "centroid") – The part of the cell that is to be positioned at the specified target_loc. Currently only “centroid” and “corner” are supported. When “centroid” is specified, the cell is centered around the target_loc. When “corner” is specified, a nearby cell_corner is placed onto the target_loc.

  • in_place (bool (Default: False)) –

    The original grid instance is modified if in_place is True and no return argument is specified. If in_place is False, the original grid instance remains unchanged and a modified copy is returned.

    Note

    Even though in_place=True saves the creation of a Python object, a new Python object that wraps the Rust implementation needs to be updated and hence a new Python object is still created. Nevertheless, creating one new object is often better than creating two new objects.

Returns:

BaseGrid if in_place=False or None if in_place=True

Return type:

BaseGrid | None

See also

BoundedTriGrid.anchor(), BoundedRectGrid.anchor(), BoundedHexGrid.anchor()

abstract property parent_grid_class
abstract cells_in_bounds(bounds, return_cell_count: bool = False)[source]

Cells contained within a bounding box.

Parameters:

  • bounds (tuple) – The bounding box in which to find the cells in (min_x, min_y, max_x, max_y)

  • return_cell_count (bool) – Return a tuple containing the nr of cells in x and y direction inside the provided bounds

Returns:

The indices of the cells contained in the bounds

Return type:

GridIndex

are_bounds_aligned(bounds, separate=False)[source]
align_bounds(bounds, mode='expand')[source]
intersect_geometries(geometries, suppress_point_warning=False)[source]
to_shapely(index, as_multipolygon: bool = False)[source]

Represent the cells as Shapely Polygons

Parameters:

  • index (numpy.ndarray) – The indices of the cells to convert to Shapely Polygons

  • as_multipolygon (numpy.ndarray) – Returns a Shapely MultiPolygon if True, returns a list of Shapely Polygons if False

See also

BoundedRectGrid.to_shapely(), BoundedHexGrid.to_shapely()

interp_from_points(points, values, method='linear', nodata_value=nan)[source]

Interpolate the cells containing nodata, if they are inside the convex hull of cells that do contain data.

This function turns any set of points at arbitrary location into a regularly spaced BoundedGrid that has the properties of the current BaseGrid (self). BoundedGrid.interpolate() works in the other direction, where a values on a BoundedGrid are sampled in order to obtain values at arbitrary location.

Note

This function is significantly slower than BoundedGrid.interpolate()

Parameters:

  • point (numpy.ndarray) – A 2d numpy array containing the points in the form [[x1,y1], [x2,y2]]

  • values (numpy.ndarray) – The values corresponding to the supplied points, used as input for interpolation

  • method (str) – The interpolation method to be used. Options are (“nearest”, “linear”, “cubic”). Default: “linear”.

Returns:

A Bounded version of the supplied grid where the data is interpolated between the supplied points.

Return type:

BoundedGrid

See also

BoundedGrid.resample(), BoundedGrid.interpolate()

abstract update(size=None, shape=None, offset=None, rotation=None, **kwargs)[source]