hex_grid

class gridkit.hex_grid.HexGrid(*args, size, shape='pointy', offset=(0, 0), rotation=0, **kwargs)

Bases: BaseGrid

Abstraction that represents an infinite grid with hexagonal cell shape.

Initialization parameters

size: float

The spacing between two cells in horizontal direction if shape is “pointy”, or in vertical direction if shape is “flat”.

shape: Literal[“pointy”, “flat”]

The shape of the layout of the grid. If shape is “pointy” the cells will be pointy side up and the regular axis will be in horizontal direction. If shape is “flat”, the cells will be flat side up and the regular axis will be in vertical direction.

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. Default: None

property dx: float

The spacing between cell centers in x-direction

property dy: float

The spacing between cell centers in y-direction

property r: float

The radius of the cell. The radius is defined to be the distance from the cell center to a cell corner.

property shape: str

The shape of the grid as supplied when initiating the class. This can be either “flat” or “pointy” referring to the top of the cells.

property size: float

The size of the cell as supplied when initiating the class. This is the same as dx for a flat grid and the same as dy for a pointy grid.

to_bounded(bounds, fill_value=nan)

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()

relative_neighbours(index, depth=1, include_selected=False, connect_corners=False) → ndarray

The relative indices of the neighbouring cells.

Parameters:

• 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.

• index (numpy.ndarray) – The index of the cell of which the relative neighbours are desired. This is mostly relevant because in hexagonal grids the neighbouring indices differ when dealing with odd or even indices.

• 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.

• connect_corners (bool Default: False) – Whether to consider cells that touch corners but not sides as neighbours. This is not relevant in hexagonal grids. It does nothing here. See RectGrid.relative_neighbours()

Examples

The direct neighbours of a cell can be returned by using depth=1, which is the default. For hexagonal grids, the relative indices of the neighbours differs depending on the index. There are two cases, neighbour indices for even colums and neighbour indices for odd columns, in the case of a grid ‘pointy’ shape. This works on rows if the grid has a ‘flat’ shape.

>>> from gridkit.hex_grid import HexGrid
>>> grid = HexGrid(size=3)
>>> grid.relative_neighbours(index=[0,0]).index
array([[-1,  1],
       [ 0,  1],
       [-1,  0],
       [ 1,  0],
       [-1, -1],
       [ 0, -1]])
>>> grid.relative_neighbours(index=[0,1]).index
array([[ 0,  1],
       [ 1,  1],
       [-1,  0],
       [ 1,  0],
       [ 0, -1],
       [ 1, -1]])

By specifying depth we can include indirect neighbours from further away. The number of neighbours increases with depth by a factor of depth*6. So the 3rd element in the list will be 1*6 + 2*6 + 3*6 = 36.

>>> [len(grid.relative_neighbours(index=[0,0], depth=depth)) for depth in range(1,5)]
[6, 18, 36, 60]

The specified cell can be included if include_selected is set to True:

>>> grid.relative_neighbours(index=[0,0], include_selected=True).index
array([[-1,  1],
       [ 0,  1],
       [-1,  0],
       [ 0,  0],
       [ 1,  0],
       [-1, -1],
       [ 0, -1]])

See also

BaseGrid.neighbours(), RectGrid.relative_neighbours(), TriGrid.relative_neighbours()

centroid(index=None)

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

Parameters:

index (tuple) – Index of the cell of which the centroid is to be calculated. The index consists of two integers specifying the nth cell in x- and y-direction. Multiple indices can be specified at once in the form of a list of indices or an Nx2 ndarray, where N is the number of cells.

Returns:

The longitude and latitude of the center of each cell. Axes order if multiple indices are specified: (points, xy), else (xy).

Return type:

numpy.ndarray

Raises:

ValueError – No index parameter was supplied. index can only be None in classes that contain data.

Examples

Cell centers of single index are returned as an array with one dimention:

>>> grid = RectGrid(dx=4, dy=1)
>>> grid.centroid((0, 0))
array([2. , 0.5])
>>> grid.centroid((-1, -1))
array([-2. , -0.5])

Multiple cell indices can be supplied as a list of tuples or as an equivalent ndarray:

>>> grid.centroid([(0, 0), (-1, -1)])
array([[ 2. ,  0.5],
       [-2. , -0.5]])
>>> ids = numpy.array([[0, 0], [-1, -1]])
>>> grid.centroid(ids)
array([[ 2. ,  0.5],
       [-2. , -0.5]])

Note that the center coordinate of the cell is also dependent on the grid’s offset:

>>> grid = RectGrid(dx=4, dy=1, offset = (1, 0.5))
>>> grid.centroid((0, 0))
array([3., 1.])

cells_near_point(point)

Nearest 3 cells around a point. This includes the cell the point is contained within, as well as two direct neighbours of this cell and one diagonal neighbor. What neighbours of the containing are selected, depends on where in the cell the point is located.

Parameters:

point (tuple) – Coordinate of the point around which the cells are to be selected. The point consists of two floats specifying x- and y-coordinates, respectively. Multiple points can be specified at once in the form of a list of points or an Nx2 ndarray.

Returns:

The indices of the 4 nearest cells in order (top-left, top-right, bottom-left, bottom-right). If a single point is supplied, the four indices are returned as 1d arrays of length 2. If multiple points are supplied, the four indices are returned as Nx2 ndarrays.

Return type:

GridIndex

cell_at_point(point)

Index of the cell containing the supplied point(s).

Parameters:

point (tuple) – Coordinate of the point for which the containing cell is to be found. The point consists of two floats specifying x- and y-coordinates, respectively. Mutliple poins can be specified at once in the form of a list of points or an Nx2 ndarray.

Returns:

The index of the cell containing the point(s). If a single point is supplied, the index is returned as a 1d array of length 2. If multiple points are supplied, the indices are returned as Nx2 ndarrays.

Return type:

numpy.ndarray

cell_corners(index: ndarray = None) → ndarray

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

to_crs(crs)

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.

Returns:

A copy of the grid with modified cell spacing to match the specified CRS

Return type:

HexGrid

See also

Examples:

Example: coordinate transformations

Methods:

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

cells_in_bounds(bounds, return_cell_count: bool = False)

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

property parent_grid_class

update(size=None, shape=None, offset=None, rotation=None, crs=None, **kwargs)

class gridkit.hex_grid.BoundedHexGrid(data, *args, bounds, shape='flat', **kwargs)

Bases: BoundedGrid, HexGrid

Initialization parameters

data: numpy.ndarray

A 2D ndarray containing the data

bounds: Tuple(float, float, float, float)

The extend of the data in minx, miny, maxx, maxy.

shape: Literal[“pointy”, “flat”]

The shape of the cells in the grid. If shape is “pointy”, the hexagons will be standing upright on a point with the flat sides to the left and right. If shape is “flat”, the hexagons will be flat side up and below and pointy side on the left and right.

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. Default: None

property height

Raster height

Returns:

The number of grid cells in y-direction

Return type:

int

property width

Raster width

Returns:

The number of grid cells in x-direction

Return type:

int

property nr_cells

Number of cells

Returns:

The total number of cells in the grid

Return type:

int

property lon

Array of long values

Returns:

1D-Array of size width, containing the longitudinal values from left to right

Return type:

numpy.ndarray

property lat

Array of lat values

Returns:

1D-Array of size height, containing the latitudinal values from top to bottom

Return type:

numpy.ndarray

intersecting_cells(other)

crop(new_bounds, bounds_crs=None, buffer_cells=0)

Cut out a slice of data contained within the supplied bounds.

Parameters:

• new_bounds (Tuple(minx, miny, maxx, maxy)) – The bounds defining the area to crop, in (minx, miny, maxx, maxy).

• bounds_crs (pyproj.CRS (optional)) – The bounds defining the extent of the cropped data. The value can be anything accepted by pyproj.CRS.from_user_input().

Returns:

A BoundedGrid containing the data included in the cropped area contained within the bounds.

Return type:

class: BoundedGrid

cell_corners(index: ndarray | None = None) → ndarray

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

to_shapely(index=None, as_multipolygon: bool = False)

Refer to BaseGrid.to_shapely()

Difference with BaseGrid.to_shapely():

index is optional. If index is None (default) the cells containing data are used as the index argument.

See also

BaseGrid.to_shapely(), BoundedRectGrid.to_shapely()

to_crs(crs, resample_method='nearest')

Transforms the Coordinate Reference System (CRS) from the current CRS to the desired CRS. This will modify the cell size and the bounds accordingly.

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.

• resample_method (str) – The resampling method to be used for BoundedGrid.resample().

Returns:

A copy of the grid with modified cell spacing and bounds to match the specified CRS

Return type:

BoundedHexGrid

See also

Examples:

Example: coordinate transformations

Methods:

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

numpy_id_to_grid_id(np_index)

Turn numpy indices that select values from self.data into a GridIndex instance that represents those same cells and can be used on the Grid object.

Parameters:

np_index (numpy.ndarray) – The numpy indices to convert

Returns:

The GridIndex representation of the cells

Return type:

GridIndex

argmax(*args, **kwargs)

argmin(*args, **kwargs)

grid_id_to_numpy_id(index)

max(*args, **kwargs)

mean(*args, **kwargs)

median(*args, **kwargs)

min(*args, **kwargs)

std(*args, **kwargs)

sum(*args, **kwargs)

interp_nodata(*args, **kwargs)

Please refer to interp_nodata().

centroid(index=None)

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

Parameters:

index (tuple) – Index of the cell of which the centroid is to be calculated. The index consists of two integers specifying the nth cell in x- and y-direction. Multiple indices can be specified at once in the form of a list of indices or an Nx2 ndarray, where N is the number of cells.

Returns:

The longitude and latitude of the center of each cell. Axes order if multiple indices are specified: (points, xy), else (xy).

Return type:

numpy.ndarray

Raises:

ValueError – No index parameter was supplied. index can only be None in classes that contain data.

Examples

Cell centers of single index are returned as an array with one dimention:

>>> grid = RectGrid(dx=4, dy=1)
>>> grid.centroid((0, 0))
array([2. , 0.5])
>>> grid.centroid((-1, -1))
array([-2. , -0.5])

Multiple cell indices can be supplied as a list of tuples or as an equivalent ndarray:

>>> grid.centroid([(0, 0), (-1, -1)])
array([[ 2. ,  0.5],
       [-2. , -0.5]])
>>> ids = numpy.array([[0, 0], [-1, -1]])
>>> grid.centroid(ids)
array([[ 2. ,  0.5],
       [-2. , -0.5]])

Note that the center coordinate of the cell is also dependent on the grid’s offset:

>>> grid = RectGrid(dx=4, dy=1, offset = (1, 0.5))
>>> grid.centroid((0, 0))
array([3., 1.])

update(new_data, bounds=None, crs=None, nodata_value=None, shape=None)