https://github.com/worldbank/gee_zonal
Collection of python tools for running zonal stats on Google Earth Engine layers
https://github.com/worldbank/gee_zonal
google-earth-engine zonal-statistics
Last synced: 6 months ago
JSON representation
Collection of python tools for running zonal stats on Google Earth Engine layers
- Host: GitHub
- URL: https://github.com/worldbank/gee_zonal
- Owner: worldbank
- License: other
- Created: 2021-03-03T13:47:50.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-04-11T00:26:06.000Z (6 months ago)
- Last Synced: 2025-04-11T00:26:32.602Z (6 months ago)
- Topics: google-earth-engine, zonal-statistics
- Language: Jupyter Notebook
- Homepage: https://worldbank.github.io/GEE_Zonal/
- Size: 9.55 MB
- Stars: 20
- Watchers: 26
- Forks: 6
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# GEE Zonal
[](https://badge.fury.io/py/gee-zonal)
This python package provides a wrapper function to request temporal and zonal statistics from Google Earth Engine (GEE) datasets.
## Summary
A zonal statistics function was created to ease the process of working with the GEE API. The function can work with any raster data loaded to EE (`ee.ImageCollections` or `ee.Image`) and vector features (`geopandas.GeoDataFrame` or `ee.FeatureCollection`), and returns tabular data.
Statistics can be requested at various temporal resolutions (`original` frequency, `monthly`, or `annual`). The workflow conducts pixel-by-pixel temporal aggregations, before summarizing statistics over target features.
Additionally, the package provides functionality to quickly search the GEE Catalog.
#### [Documentation Pages](https://worldbank.github.io/GEE_Zonal/)
## Installation
The required dependencies are *earthengine-api*, *geopandas*, *geojson*, and *notebook*. The package (and dependencies) can be installed via pip:
```sh
pip install gee_zonal
```
## Setup
The Earth Engine Python API needs to be authenticated with a Google account. First, sign up to Google Earth Engine [here](https://earthengine.google.com/signup/).
Launch a jupyter notebook, and authenticate your account with the ee library.
```python
import ee
ee.Authenticate()
```
You can check that this worked by running `ee.Initialize()`, then import and run the library:
```python
from gee_zonal import ZonalStats, Catalog
```
If the pip installation is not working, you can recreate the environment before and install the package from source:
```sh
conda create -n ee
conda activate ee
conda install -c conda-forge earthengine-api geopandas notebook ipykernel
git clone https://github.com/worldbank/GEE_Zonal.git
python setup.py build
python setup.py install
python -m ipykernel install --user --name ee --display-name "Earth Engine"
```
## Usage
### ZonalStats()
Main class to calculate temporal and zonal statistics using the GEE backend. The object can be initialized with parameters specifying data inputs and the type of aggregation.
```python
import ee
from gee_zonal import ZonalStats
AOIs = ee.FeatureCollection('')
AOIs = ''
zs = ZonalStats(
collection_id = 'LANDSAT/LC08/C01/T1_8DAY_NDVI',
target_features = AOIs,
statistic_type = "all", # all includes min, max, mean, and stddev
frequency = "annual",
temporal_stat = "mean"
)
```
See docstring for more details on the input parameters for `ZonalStats()` and the [example notebook](.docs/examples/zonal_statistics_example.ipynb).
The output statistics can be retrieved directly in the notebook (as a `DataFrame`):
```python
res = zs.runZonalStats()
```
Or retrieved from Google Drive as a csv table if an `output_name` and `output_dir` were specified.
### Catalog()
Inventory of Earth Engine datasets with some functions to search catalog by tags, title, and year / time period
```python
from gee_zonal import Catalog
cat = Catalog()
```
The catalog object contains a `datasets` variable, a `DataFrame` containing a copy of the Earth Engine data catalog, retrieved from [Earth-Engine-Datasets-List](https://github.com/samapriya/Earth-Engine-Datasets-List).
```python
cat.datasets
```
#### Search functions
```python
results = cat.search_tags("ndvi")
results = results.search_by_period(1985, 2021)
results = results.search_title("landsat")
print(results)
```
## Additional Resources
- [geemap](https://geemap.org/): Python library with more functionality to work with GEE.
- [awesome-gee-community-catalog](https://gee-community-catalog.org/): Extended catalog of EE datasets.
## License
[**World Bank Master Community License Agreement**](LICENSE.md).