| Name | yirgacheffe JSON |
| Version |
1.10.0
JSON |
| download |
| home_page | None |
| Summary | Abstraction of gdal datasets for doing basic math operations |
| upload_time | 2025-11-01 17:18:41 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
gdal
gis
geospatial
declarative
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Yirgacheffe: a declarative geospatial library for Python to make data-science with maps easier
[](https://github.com/quantifyearth/yirgacheffe/actions)
[](https://yirgacheffe.org)
[](https://pypi.org/project/yirgacheffe/)
## Overview
Yirgacheffe is a declarative geospatial library, allowing you to operate on both raster and polygon geospatial datasets without having to do all the tedious book keeping around layer alignment or dealing with hardware concerns around memory or parallelism. you can load into memory safely.
Example common use-cases:
* Do the datasets overlap? Yirgacheffe will let you define either the intersection or the union of a set of different datasets, scaling up or down the area as required.
* Rasterisation of vector layers: if you have a vector dataset then you can add that to your computation and yirgaceffe will rasterize it on demand, so you never need to store more data in memory than necessary.
* Do the raster layers get big and take up large amounts of memory? Yirgacheffe will let you do simple numerical operations with layers directly and then worry about the memory management behind the scenes for you.
* Parallelisation of operations over many CPU cores.
* Built in support for optionally using GPUs via [MLX](https://ml-explore.github.io/mlx/build/html/index.html) support.
## Installation
Yirgacheffe is available via pypi, so can be installed with pip for example:
```SystemShell
$ pip install yirgacheffe
```
## Documentation
The documentation can be found on [yirgacheffe.org](https://yirgacheffe.org/)
## Simple examples:
Here is how to do cloud removal from [Sentinel-2 data](https://browser.dataspace.copernicus.eu/?zoom=14&lat=6.15468&lng=38.20581&themeId=DEFAULT-THEME&visualizationUrl=U2FsdGVkX1944lrmeTJcaSsnoxNMp4oucN1AjklGUANHd2cRZWyXnepHvzpaOWzMhH8SrWQo%2BqrOvOnu6f9FeCMrS%2FDZmvjzID%2FoE1tbOCEHK8ohPXjFqYojeR9%2B82ri&datasetId=S2_L2A_CDAS&fromTime=2025-09-09T00%3A00%3A00.000Z&toTime=2025-09-09T23%3A59%3A59.999Z&layerId=1_TRUE_COLOR&demSource3D=%22MAPZEN%22&cloudCoverage=30&dateMode=SINGLE), using the [Scene Classification Layer](https://custom-scripts.sentinel-hub.com/custom-scripts/sentinel-2/scene-classification/) data:
```python
import yirgaceffe as yg
with (
yg.read_raster("T37NCG_20250909T073609_B06_20m.jp2") as vre2,
yg.read_raster("T37NCG_20250909T073609_SCL_20m.jp2") as scl,
):
is_cloud = (scl == 8) | (scl == 9) | (scl == 10) # various cloud types
is_shadow = (scl == 3)
is_bad = is_cloud | is_shadow
masked_vre2 = yg.where(is_bad, float("nan"), vre2)
masked_vre2.to_geotiff("vre2_cleaned.tif")
```
or a species' [Area of Habitat](https://www.sciencedirect.com/science/article/pii/S0169534719301892) calculation:
```python
import yirgaceffe as yg
with (
yg.read_raster("habitats.tif") as habitat_map,
yg.read_raster('elevation.tif') as elevation_map,
yg.read_shape('species123.geojson') as range_map,
):
refined_habitat = habitat_map.isin([...species habitat codes...])
refined_elevation = (elevation_map >= species_min) & (elevation_map <= species_max)
aoh = refined_habitat * refined_elevation * range_polygon * area_per_pixel_map
print(f'Area of habitat: {aoh.sum()}')
```
## Citation
If you use Yirgacheffe in your research, please cite our paper:
> Michael Winston Dales, Alison Eyres, Patrick Ferris, Francesca A. Ridley, Simon Tarr, and Anil Madhavapeddy. 2025. Yirgacheffe: A Declarative Approach to Geospatial Data. In *Proceedings of the 2nd ACM SIGPLAN International Workshop on Programming for the Planet* (PROPL '25). Association for Computing Machinery, New York, NY, USA, 47–54. https://doi.org/10.1145/3759536.3763806
<details>
<summary>BibTeX</summary>
```bibtex
@inproceedings{10.1145/3759536.3763806,
author = {Dales, Michael Winston and Eyres, Alison and Ferris, Patrick and Ridley, Francesca A. and Tarr, Simon and Madhavapeddy, Anil},
title = {Yirgacheffe: A Declarative Approach to Geospatial Data},
year = {2025},
isbn = {9798400721618},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
url = {https://doi.org/10.1145/3759536.3763806},
doi = {10.1145/3759536.3763806},
abstract = {We present Yirgacheffe, a declarative geospatial library that allows spatial algorithms to be implemented concisely, supports parallel execution, and avoids common errors by automatically handling data (large geospatial rasters) and resources (cores, memory, GPUs). Our primary user domain comprises ecologists, where a typical problem involves cleaning messy occurrence data, overlaying it over tiled rasters, combining layers, and deriving actionable insights from the results. We describe the successes of this approach towards driving key pipelines related to global biodiversity and describe the capability gaps that remain, hoping to motivate more research into geospatial domain-specific languages.},
booktitle = {Proceedings of the 2nd ACM SIGPLAN International Workshop on Programming for the Planet},
pages = {47–54},
numpages = {8},
keywords = {Biodiversity, Declarative, Geospatial, Python},
location = {Singapore, Singapore},
series = {PROPL '25}
}
```
</details>
## Thanks
Thanks to discussion and feedback from my colleagues, particularly Alison Eyres, Patrick Ferris, Amelia Holcomb, and Anil Madhavapeddy.
Inspired by the work of Daniele Baisero in his AoH library.
Raw data
{
"_id": null,
"home_page": null,
"name": "yirgacheffe",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "gdal, gis, geospatial, declarative",
"author": null,
"author_email": "Michael Dales <mwd24@cam.ac.uk>",
"download_url": "https://files.pythonhosted.org/packages/d2/47/dc958117c338d73aa81f2c0b3860f445907a27e34d23edf0b6c9b21fa152/yirgacheffe-1.10.0.tar.gz",
"platform": null,
"description": "# Yirgacheffe: a declarative geospatial library for Python to make data-science with maps easier\n\n[](https://github.com/quantifyearth/yirgacheffe/actions)\n[](https://yirgacheffe.org)\n[](https://pypi.org/project/yirgacheffe/)\n\n\n## Overview\n\nYirgacheffe is a declarative geospatial library, allowing you to operate on both raster and polygon geospatial datasets without having to do all the tedious book keeping around layer alignment or dealing with hardware concerns around memory or parallelism. you can load into memory safely.\n\nExample common use-cases:\n\n* Do the datasets overlap? Yirgacheffe will let you define either the intersection or the union of a set of different datasets, scaling up or down the area as required.\n* Rasterisation of vector layers: if you have a vector dataset then you can add that to your computation and yirgaceffe will rasterize it on demand, so you never need to store more data in memory than necessary.\n* Do the raster layers get big and take up large amounts of memory? Yirgacheffe will let you do simple numerical operations with layers directly and then worry about the memory management behind the scenes for you.\n* Parallelisation of operations over many CPU cores.\n* Built in support for optionally using GPUs via [MLX](https://ml-explore.github.io/mlx/build/html/index.html) support.\n\n## Installation\n\nYirgacheffe is available via pypi, so can be installed with pip for example:\n\n```SystemShell\n$ pip install yirgacheffe\n```\n\n## Documentation\n\nThe documentation can be found on [yirgacheffe.org](https://yirgacheffe.org/)\n\n## Simple examples:\n\nHere is how to do cloud removal from [Sentinel-2 data](https://browser.dataspace.copernicus.eu/?zoom=14&lat=6.15468&lng=38.20581&themeId=DEFAULT-THEME&visualizationUrl=U2FsdGVkX1944lrmeTJcaSsnoxNMp4oucN1AjklGUANHd2cRZWyXnepHvzpaOWzMhH8SrWQo%2BqrOvOnu6f9FeCMrS%2FDZmvjzID%2FoE1tbOCEHK8ohPXjFqYojeR9%2B82ri&datasetId=S2_L2A_CDAS&fromTime=2025-09-09T00%3A00%3A00.000Z&toTime=2025-09-09T23%3A59%3A59.999Z&layerId=1_TRUE_COLOR&demSource3D=%22MAPZEN%22&cloudCoverage=30&dateMode=SINGLE), using the [Scene Classification Layer](https://custom-scripts.sentinel-hub.com/custom-scripts/sentinel-2/scene-classification/) data:\n\n```python\nimport yirgaceffe as yg\n\nwith (\n yg.read_raster(\"T37NCG_20250909T073609_B06_20m.jp2\") as vre2,\n yg.read_raster(\"T37NCG_20250909T073609_SCL_20m.jp2\") as scl,\n):\n is_cloud = (scl == 8) | (scl == 9) | (scl == 10) # various cloud types\n is_shadow = (scl == 3)\n is_bad = is_cloud | is_shadow\n\n masked_vre2 = yg.where(is_bad, float(\"nan\"), vre2)\n masked_vre2.to_geotiff(\"vre2_cleaned.tif\")\n```\n\nor a species' [Area of Habitat](https://www.sciencedirect.com/science/article/pii/S0169534719301892) calculation:\n\n```python\nimport yirgaceffe as yg\n\nwith (\n yg.read_raster(\"habitats.tif\") as habitat_map,\n yg.read_raster('elevation.tif') as elevation_map,\n yg.read_shape('species123.geojson') as range_map,\n):\n refined_habitat = habitat_map.isin([...species habitat codes...])\n refined_elevation = (elevation_map >= species_min) & (elevation_map <= species_max)\n aoh = refined_habitat * refined_elevation * range_polygon * area_per_pixel_map\n print(f'Area of habitat: {aoh.sum()}')\n```\n\n## Citation\n\nIf you use Yirgacheffe in your research, please cite our paper:\n\n> Michael Winston Dales, Alison Eyres, Patrick Ferris, Francesca A. Ridley, Simon Tarr, and Anil Madhavapeddy. 2025. Yirgacheffe: A Declarative Approach to Geospatial Data. In *Proceedings of the 2nd ACM SIGPLAN International Workshop on Programming for the Planet* (PROPL '25). Association for Computing Machinery, New York, NY, USA, 47\u201354. https://doi.org/10.1145/3759536.3763806\n\n<details>\n<summary>BibTeX</summary>\n\n```bibtex\n@inproceedings{10.1145/3759536.3763806,\n author = {Dales, Michael Winston and Eyres, Alison and Ferris, Patrick and Ridley, Francesca A. and Tarr, Simon and Madhavapeddy, Anil},\n title = {Yirgacheffe: A Declarative Approach to Geospatial Data},\n year = {2025},\n isbn = {9798400721618},\n publisher = {Association for Computing Machinery},\n address = {New York, NY, USA},\n url = {https://doi.org/10.1145/3759536.3763806},\n doi = {10.1145/3759536.3763806},\n abstract = {We present Yirgacheffe, a declarative geospatial library that allows spatial algorithms to be implemented concisely, supports parallel execution, and avoids common errors by automatically handling data (large geospatial rasters) and resources (cores, memory, GPUs). Our primary user domain comprises ecologists, where a typical problem involves cleaning messy occurrence data, overlaying it over tiled rasters, combining layers, and deriving actionable insights from the results. We describe the successes of this approach towards driving key pipelines related to global biodiversity and describe the capability gaps that remain, hoping to motivate more research into geospatial domain-specific languages.},\n booktitle = {Proceedings of the 2nd ACM SIGPLAN International Workshop on Programming for the Planet},\n pages = {47\u201354},\n numpages = {8},\n keywords = {Biodiversity, Declarative, Geospatial, Python},\n location = {Singapore, Singapore},\n series = {PROPL '25}\n}\n```\n\n</details>\n\n## Thanks\n\nThanks to discussion and feedback from my colleagues, particularly Alison Eyres, Patrick Ferris, Amelia Holcomb, and Anil Madhavapeddy.\n\nInspired by the work of Daniele Baisero in his AoH library.\n",
"bugtrack_url": null,
"license": null,
"summary": "Abstraction of gdal datasets for doing basic math operations",
"version": "1.10.0",
"project_urls": {
"Changelog": "https://yirgacheffe.org/latest/changelog/",
"Homepage": "https://yirgacheffe.org/",
"Issues": "https://github.com/quantifyearth/yirgacheffe/issues",
"Repository": "https://github.com/quantifyearth/yirgacheffe.git"
},
"split_keywords": [
"gdal",
" gis",
" geospatial",
" declarative"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "50c8f9dcca521f95187779d9ba692c6adf1f5a7223c83e83f87c5061609cb7c5",
"md5": "22f42bf84ba7ac44f6faa42aef0eaf7c",
"sha256": "bcc5433645d475ca92e0e9965fa935d10713436e46a25bdda66a16c04168e27a"
},
"downloads": -1,
"filename": "yirgacheffe-1.10.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "22f42bf84ba7ac44f6faa42aef0eaf7c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 52050,
"upload_time": "2025-11-01T17:18:40",
"upload_time_iso_8601": "2025-11-01T17:18:40.492892Z",
"url": "https://files.pythonhosted.org/packages/50/c8/f9dcca521f95187779d9ba692c6adf1f5a7223c83e83f87c5061609cb7c5/yirgacheffe-1.10.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d247dc958117c338d73aa81f2c0b3860f445907a27e34d23edf0b6c9b21fa152",
"md5": "3bdd75d3c27c1468b2f3e5f54c359ff8",
"sha256": "5e6ededdd744b7f4fa8bcfe692a02daf27cd79a81553afdc7c6a3deac255db5d"
},
"downloads": -1,
"filename": "yirgacheffe-1.10.0.tar.gz",
"has_sig": false,
"md5_digest": "3bdd75d3c27c1468b2f3e5f54c359ff8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 78022,
"upload_time": "2025-11-01T17:18:41",
"upload_time_iso_8601": "2025-11-01T17:18:41.851375Z",
"url": "https://files.pythonhosted.org/packages/d2/47/dc958117c338d73aa81f2c0b3860f445907a27e34d23edf0b6c9b21fa152/yirgacheffe-1.10.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-01 17:18:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "quantifyearth",
"github_project": "yirgacheffe",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "yirgacheffe"
}
