Skip to content

Home

ETHOS.GeoKit logo Logo für Forschungszentrum Juelich - Juelich System Analysis
Name Version Tests Pytest Coverage Docstring Style Documentation Coverage
Conda Recipe Conda Version Tests codecov NumPy docstring style Documentation Coverage

Documentation Overview

ETHOS.GeoKit is a Python toolkit for efficiently handling geospatial data and spatial operations. Its main advantage is the seamless combination of raster and vector data: through the RegionMask and Extent objects, datasets in different formats, resolutions, and coordinate reference systems are integrated into the context of a single region of interest — without the manual CRS, extent, and resolution bookkeeping this normally requires. It is scientifically reviewed and published.

ETHOS.GeoKit equally supports the individual building blocks on their own, so it works just as well for pure raster or pure vector tasks: - Reading, writing, and mutating vector and raster datasets - Manipulating and translating geometries between coordinate systems - Warping and resampling raster data, and sampling values at point locations - Converting between raster and vector representations (rasterize / polygonize) - Seamlessly integrating multiple raster and vector datasets within a region through the RegionMask object

New here? See Why ETHOS.GeoKit? for how it compares to GDAL, GeoPandas, and Rasterio — and how much less code it takes to achieve the same result.

ETHOS.GeoKit is part of the ETHOS (Energy Transformation PatHway Optimization Suite). ETHOS.GeoKit is, for example, directly used in GLAES and RESKit.

Installation

If you just want to use ETHOS.GeoKit, install it from Conda Forge. To download and execute all the examples or develop the source code, install it from source. Both installations require conda or mamba, which can be used interchangeably. We recommend the Miniforge installer. Please remove other conda installers if you decide to use miniforge. Having multiple conda installs on your machine will likely cause issues.

The easiest way to install ETHOS.GeoKit into a new environment is from conda-forge:

conda create -n geokit -c conda-forge geokit

Or into an existing environment with:

conda install -c conda-forge geokit

Installation from Source

  1. Clone the repository and navigate to it:
git clone https://github.com/FZJ-IEK3-VSA/geokit.git
cd geokit
  1. (Optional) Switch to the development branch:
git checkout dev
  1. Create a new environment:
conda env create --file requirements-dev
conda activate geokit
pip install . --no-deps
  1. (Alternative) Update an existing environment:
conda env update --file requirements-dev -n <ENVIRONMENT-NAME>
conda activate geokit
pip install . --no-deps

Getting Started

The best way to learn ETHOS.GeoKit is through hands-on examples. This documentation includes:

  • Example notebooks in the Examples folder demonstrating real-world use cases
  • Detailed guides in the example_articles folder explaining key concepts
  • API documentation providing comprehensive reference information
  • Source code in the geokit folder for advanced users

Start with the Introduction to ETHOS.GeoKit to understand the fundamentals, or jump directly to the capability area that interests you most.

Citation

If you use or reference ETHOS.GeoKit in your research, please cite our SoftwareX article:

Ishmam, S., Belina, J., Winkler, C., Weinand, J. M., Pflugradt, N., Heinrichs, H., & Linßen, J. (2026). ETHOS.GeoKit: A Python toolkit for analyzing and altering geospatial data for energy systems modeling and beyond. SoftwareX, 35, 102870. https://doi.org/10.1016/j.softx.2026.102870

@article{ishmam2026geokit,
  title   = {{ETHOS.GeoKit}: A {P}ython toolkit for analyzing and altering geospatial data for energy systems modeling and beyond},
  author  = {Ishmam, Shitab and Belina, Julian and Winkler, Christoph and Weinand, Jann M. and Pflugradt, Noah and Heinrichs, Heidi and Lin{\ss}en, Jochen},
  journal = {SoftwareX},
  volume  = {35},
  pages   = {102870},
  year    = {2026},
  publisher = {Elsevier},
  doi     = {10.1016/j.softx.2026.102870}
}

Contributions and Support

All contributions are welcome: - If you have a question, want to report a bug, or have a feature request, please open an Issue. We will then take care of the issue as soon as possible. - If you want to contribute with additional features or code improvements, open a Pull request.

License

MIT License

Active developers: Christoph Winkler, Shitab Ishmam, Julian Belina, Noah Pflugradt, Heidi Heinrichs, Jochen Linßen, Detlef Stolten

Alumni: David Severin Ryberg, Martin Robinius, Stanley Risch, Julian Schönau, Rachel Maier, David Franzmann

You should have received a copy of the MIT License along with this program.
If not, see https://opensource.org/licenses/MIT

About Us

We are the Institute of Climate and Energy Systems – Jülich Systems Analysis (ICE-2) at the Forschungszentrum Jülich. Our work focuses on independent, interdisciplinary research in energy, bioeconomy, infrastructure, and sustainability. We support a just, greenhouse gas–neutral transformation through open models and policy-relevant science.

Code of Conduct

Please respect our code of conduct.

Acknowledgment

This work was supported by the Helmholtz Association under the Joint Initiative "Energy System 2050: A Contribution of the Research Field Energy".

Helmholtz Logo