Skip to content

fit_spatial_grid

cellseg_gsontools.grid.fit_spatial_grid(gdf, grid_type='square', **kwargs)

Quick wrapper to fit either a hex or square grid to a geopandas.GeoDataFrame.

Note
  • Hexagonal grid requires the h3 package to be installed.
  • Hexagonal grid only works for a gdf containing one single polygon.

Parameters:

Name Type Description Default
gdf GeoDataFrame

GeoDataFrame to fit grid to.

 required
grid_type str

Type of grid to fit, by default "square".

 'square'
**kwargs Dict[str, Any]

Keyword arguments to pass to grid fitting functions.

 {}

Returns:

Type Description
GeoDataFrame

gpd.GeoDataFrame: Fitted grid.

Raises:

Type Description
ValueError

If grid_type is not one of "square" or "hex".
ImportError

If grid_type is "hex" and the h3 package is not installed.

Examples:

Fit a hexagonal grid to a gdf:

>>> from cellseg_gsontools import read_gdf
>>> from cellseg_gsontools.grid import fit_spatial_grid
>>> # Read in the tissue areas
>>> area_gdf = gpd.read_file("path/to/area.geojson")
>>> # Fit the grid
>>> hex_grid = fit_spatial_grid(area_gdf, grid_type="hex", resolution=9)
>>> hex_grid
gpd.GeoDataFrame

Fit a square grid to a gdf:

>>> from cellseg_gsontools import read_gdf
>>> from cellseg_gsontools.grid import fit_spatial_grid
>>> # Read in the tissue areas
>>> area_gdf = gpd.read_file("path/to/area.geojson")
>>> # Fit the grid
>>> sq_grid = fit_spatial_grid(
...     area_gdf, grid_type="square", patch_size=(256, 256), stride=(256, 256)
... )
>>> sq_grid
gpd.GeoDataFrame
Source code in cellseg_gsontools/grid.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
def fit_spatial_grid(
    gdf: gpd.GeoDataFrame, grid_type: str = "square", **kwargs
) -> gpd.GeoDataFrame:
    """Quick wrapper to fit either a hex or square grid to a `geopandas.GeoDataFrame`.

    Note:
        - Hexagonal grid requires the `h3` package to be installed.
        - Hexagonal grid only works for a gdf containing one single polygon.

    Parameters:
        gdf (gpd.GeoDataFrame):
            GeoDataFrame to fit grid to.
        grid_type (str):
            Type of grid to fit, by default "square".
        **kwargs (Dict[str, Any]):
            Keyword arguments to pass to grid fitting functions.

    Returns:
        gpd.GeoDataFrame:
            Fitted grid.

    Raises:
        ValueError: If grid_type is not one of "square" or "hex".
        ImportError: If grid_type is "hex" and the `h3` package is not installed.

    Examples:
        Fit a hexagonal grid to a gdf:
        >>> from cellseg_gsontools import read_gdf
        >>> from cellseg_gsontools.grid import fit_spatial_grid
        >>> # Read in the tissue areas
        >>> area_gdf = gpd.read_file("path/to/area.geojson")
        >>> # Fit the grid
        >>> hex_grid = fit_spatial_grid(area_gdf, grid_type="hex", resolution=9)
        >>> hex_grid
        gpd.GeoDataFrame

        Fit a square grid to a gdf:
        >>> from cellseg_gsontools import read_gdf
        >>> from cellseg_gsontools.grid import fit_spatial_grid
        >>> # Read in the tissue areas
        >>> area_gdf = gpd.read_file("path/to/area.geojson")
        >>> # Fit the grid
        >>> sq_grid = fit_spatial_grid(
        ...     area_gdf, grid_type="square", patch_size=(256, 256), stride=(256, 256)
        ... )
        >>> sq_grid
        gpd.GeoDataFrame
    """
    allowed = ["square", "hex"]
    if grid_type not in allowed:
        raise ValueError(f"grid_type must be one of {allowed}, got {grid_type}")

    if grid_type == "square":
        grid = grid_overlay(gdf, **kwargs)
    else:
        if not _has_h3:
            raise ImportError("h3 package not installed. Install with `pip install h3`")
        grid = hexgrid_overlay(gdf, **kwargs)

    return grid