geocube

geocube acts as a bridge between several key geospatial and array libraries. It combines the interfaces of:

• geopandas (vector data handling)
• xarray (multi-dimensional arrays)
• rioxarray (raster operations)

Under the hood, it is powered by GDAL and utilizes:

• rasterio
• pyogrio
• odc-geo

To contribute to geocube, follow these steps to set up a local development environment:

1. Fork and Clone: Fork the repository on GitHub and clone your fork locally.
2. Virtual Environment: Create a virtual environment and install the package in editable mode with development dependencies.
3. Pre-commit: Install and update pre-commit hooks to ensure code quality.
4. Branching: Create a new branch for your specific bugfix or feature.

$ git clone git@github.com:your_name_here/geocube.git
$ python -m venv geocube_env
$ cd geocube/
$ pip install -e .[dev]
$ pre-commit install
$ pre-commit autoupdate
$ git checkout -b name-of-your-bugfix-or-feature

Before committing your changes, ensure they pass linting (flake8), formatting (black), and the test suite. You can use the provided Makefile commands or run the tools directly.

Using Makefile (Recommended):

$ make check
$ make test

Direct commands (if Makefile is unavailable):

$ flake8 geocube/ test/
$ black --check .
$ pytest

To install geocube using conda, it is recommended to use the conda-forge channel. It is best practice to install the package into a new environment rather than your base environment to ensure stability and easier debugging.

Warning: Avoid using pip install within a conda environment if possible. If a package is missing from conda-forge, consider submitting a recipe instead.

conda config --prepend channels conda-forge
conda config --set channel_priority strict
conda create -n geocube_env geocube
conda activate geocube_env

You can install geocube directly from the GitHub repository using pip:

python -m pip install git+git://github.com/corteva/geocube.git#egg=geocube

GeoCube provides several Jupyter notebooks demonstrating common geospatial processing workflows. You can find specific examples for the following tasks:

• Handling missing data: Managing timestamps with missing data (timestamp_missing_data.ipynb).
• Categorical data: Working with categorical raster values (categorical.ipynb).
• Rasterization:
  • Converting point data to rasters (rasterize_point_data.ipynb).
  • Using custom functions for rasterization (rasterize_function.ipynb).
• Vectorization and Mapping:
  • Converting grids to vector maps (grid_to_vector_map.ipynb).
  • Converting raster data to vector formats (vectorize.ipynb).
• Spatial Statistics: Calculating statistics within specific areas (zonal_statistics.ipynb).

When submitting a pull request for geocube, ensure the following requirements are met:

• Tests: The pull request must include relevant tests.
• Documentation: If adding new functionality, update the documentation. New functionality should be encapsulated in a function with a docstring, and the feature should be added to the list in README.rst.
• Python Compatibility: The code must work for Python versions 3.12, 3.13, and 3.14.

If you are developing on geocube and want to install it in editable mode with development dependencies, follow these steps:

git clone git@github.com:corteva/geocube.git
cd geocube
python -m pip install -e .[dev]

To install the stable release of geocube using pip, run the following command in your terminal:

python -m pip install geocube

The primary entry point for geocube is geocube.api.core.make_geocube. You can use it to rasterize vector files (like GeoPackage) or geopandas.GeoDataFrame objects.

To rasterize a single column from a file, provide the file path to vector_data, specify the column(s) in measurements, and define the pixel resolution.

Once the xarray.Dataset is created, you can export the result using rioxarray's .rio.to_raster() method for GeoTIFFs or xarray's .to_netcdf() method for netCDF files.

from geocube.api.core import make_geocube

out_grid = make_geocube(
    vector_data="path_to_file.gpkg",
    measurements=["column_name"],
    resolution=(-0.0001, 0.0001),
)
# Export to GeoTIFF using rioxarray
out_grid["column_name"].rio.to_raster("my_rasterized_column.tif")

To include time-series data in your cube, specify the attribute names in the datetime_measurements parameter during VectorToCube initialization.

VectorToCube will:

1. Convert the specified columns to pandas.to_datetime.
2. Attempt to convert them to UTC.
3. Localize them to None and cast them to datetime64[ns].
4. If these measurements are used in a grouped context, the resulting xarray.Dataset will include attributes for units ("seconds from 1970-01-01T00:00:00") and set the _FillValue to 0.