Core

make_geocube

geocube.api.core.make_geocube(vector_data: str | PathLike | GeoDataFrame, *, measurements: list[str] | None = None, datetime_measurements: list[str] | None = None, output_crs: Any | None = None, resolution: float | Iterable[float] | None = None, align: tuple[float, float] | None = None, geom: str | dict | BaseGeometry | Geometry | None = None, like: Dataset | DataArray | None = None, fill: float = nan, group_by: str | None = None, interpolate_na_method: Literal['linear', 'nearest', 'cubic'] | None = None, categorical_enums: dict[str, list] | None = None, rasterize_function: Callable[[...], ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None] | None = None) Dataset[source]

Rasterize vector data into an xarray object. Each attribute will be a data variable in the xarray.Dataset.

Parameters:
  • vector_data (str, path-like object or geopandas.GeoDataFrame) – A file path to an OGR supported source or GeoDataFrame containing the vector data.

  • measurements (list(str), optional) – Attributes name or list of names to be included. If a list is specified, the attributes will be returned in the order requested. By default all available attributes are included.

  • datetime_measurements (list(str), optional) – Attributes that are temporal in nature and should be converted to the datetime format. These are only included if listed in ‘measurements’.

  • output_crs (Any, optional) – The CRS of the returned data. Can be anything accepted by pyproj.CRS. If no CRS is supplied, the CRS of the stored data is used.

  • resolution (Union[float, Iterable[float]], optional) – A tuple of the spatial resolution of the returned data (Y, X). This includes the direction (as indicated by a positive or negative number). Typically when using most CRSs, the first number would be negative.

  • align (tuple[float, float], optional) – Load data such that point ‘align’ lies on the pixel boundary. Units are in the co-ordinate space of the output CRS. Default is (0,0)

  • geom (Union[str, dict, shapely.geometry.base.BaseGeometry, odc.geo.geom.Geometry], optional) –

    A GeoJSON string for the bounding box of the data used to construct the grid. It defaults to EPSG:4326 if a CRS is not provided. Example of adding CRS:

    {"type": "Polygon", "crs": {"properties": {"name": "EPSG:3857"}}}
    

  • like (xarray.Dataset, optional) –

    Uses the output of a previous load() to form the basis of a request for another product. E.g.:

    gcds = make_geocube(vector_data='my_vector.geopackage', like=other_gcds)
    

  • fill (float, optional) – The value to fill in the grid with for nodata. Default is NaN.

  • group_by (str, optional) – When specified, perform basic combining/reducing of the data on this column.

  • interpolate_na_method ({'linear', 'nearest', 'cubic'}, optional) – This is the method for interpolation to use to fill in the nodata with scipy.interpolate.griddata().

  • categorical_enums (dict, optional) – A dictionary of all categories for the table columns containing categorical data. The categories will be made unique and sorted if they are not already. E.g. {‘column_name’: [‘a’, ‘b’], ‘other_column’: [‘c’, ‘d’]}

  • rasterize_function (function, optional) – Function to rasterize geometries. Other options are available in geocube.rasterize. Default is geocube.rasterize.rasterize_image().

Returns:

Requested data in a xarray.Dataset.

Return type:

xarray.Dataset

rasterize

geocube.rasterize.rasterize_image(*, geometry_array: GeoSeries, data_values: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | IntegerArray, geobox: GeoBox, fill: float, merge_alg: MergeAlg = MergeAlg.replace, filter_nan: bool = False, all_touched: bool = False, **ignored_kwargs) ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None[source]

Rasterize a list of shapes+values for a given GeoBox.

Parameters:
  • geometry_array (geopandas.GeoSeries) – A geometry array of points.

  • data_values (Union[NDArray, pandas.arrays.IntegerArray]) – Data values associated with the list of geojson shapes

  • geobox (odc.geo.geobox.GeoBox) – Transform of the resulting image.

  • fill (float) – The value to fill in the grid with for nodata.

  • merge_alg (rasterio.enums.MergeAlg, optional) – The algorithm for merging values into one cell. Default is MergeAlg.replace.

  • filter_nan (bool, optional) – If True, will remove nodata values from the data before rasterization. Default is False.

  • all_touched (bool, optional) – Passed to rasterio.features.rasterize. If True, all pixels touched by geometries will be burned in. If false, only pixels whose center is within the polygon or that are selected by Bresenham’s line algorithm will be burned in.

  • **ignored_kwargs – These are there to be flexible with additional rasterization methods and will be ignored.

Returns:

The vector data in the rasterized format.

Return type:

numpy.ndarray or None

geocube.rasterize.rasterize_points_griddata(*, geometry_array: GeoSeries, data_values: ndarray[tuple[int, ...], dtype[_ScalarType_co]], grid_coords: dict[str, ndarray[tuple[int, ...], dtype[_ScalarType_co]]], fill: float, method: str = 'nearest', rescale: bool = False, filter_nan: bool = False, **ignored_kwargs) ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None[source]

This method uses scipy.interpolate.griddata to interpolate point data to a grid.

Parameters:
  • geometry_array (geopandas.GeoSeries) – A geometry array of points.

  • data_values (list) – Data values associated with the list of geojson shapes

  • grid_coords (dict) – Output from rioxarray.rioxarray.affine_to_coords

  • fill (float) – The value to fill in the grid with for nodata.

  • method ({'linear', 'nearest', 'cubic'}, optional) – The method to use for interpolation in scipy.interpolate.griddata.

  • rescale (bool, optional) – Rescale points to unit cube before performing interpolation. Default is false.

  • filter_nan (bool, optional) – If True, will remove nodata values from the data before rasterization. Default is False.

  • **ignored_kwargs – These are there to be flexible with additional rasterization methods and will be ignored.

Returns:

:class:`numpy.ndarray`

Return type:

An interpolated numpy.ndarray.

geocube.rasterize.rasterize_points_radial(*, geometry_array: GeoSeries, data_values: ndarray[tuple[int, ...], dtype[_ScalarType_co]], grid_coords: dict[str, ndarray[tuple[int, ...], dtype[_ScalarType_co]]], method: str = 'linear', filter_nan=False, **ignored_kwargs) ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None[source]

This method uses scipy.interpolate.Rbf to interpolate point data to a grid.

Parameters:
  • geometry_array (geopandas.GeoSeries) – A geometry array of points.

  • data_values (list) – Data values associated with the list of geojson shapes

  • grid_coords (dict) – Output from rioxarray.rioxarray.affine_to_coords

  • method (str, optional) – The function to use for interpolation in scipy.interpolate.Rbf. {‘multiquadric’, ‘inverse’, ‘gaussian’, ‘linear’, ‘cubic’, ‘quintic’, ‘thin_plate’}

  • filter_nan (bool, optional) – If True, will remove nodata values from the data before rasterization. Default is False.

  • **ignored_kwargs – These are there to be flexible with additional rasterization methods and will be ignored.

Returns:

:class:`numpy.ndarray`

Return type:

An interpolated numpy.ndarray.

vectorize

geocube.vector.vectorize(data_array: DataArray) GeoDataFrame[source]

Added in version 0.4.0.

Powered by: rasterio.features.shapes()

Convert 2D xarray.DataArray into a geopandas.GeoDataFrame.

The nodata, CRS, and transform of the xarray.DataArray are determined using rioxarray.

Helpful references:

Parameters:

data_array (xarray.DataArray) – Input 2D DataArray raster.

Return type:

geopandas.GeoDataFrame

show_versions

geocube.show_versions()[source]

Added in version 0.0.12.

Print useful debugging information

Example

> python -c “import geocube; geocube.show_versions()”

exceptions

This contains exceptions for GeoCube.

exception geocube.exceptions.GeoCubeError[source]

Bases: RuntimeError

Base GeoCube exception class.

exception geocube.exceptions.VectorDataError[source]

Bases: GeoCubeError

This is for errors in the vector data passed into GeoCube.