Skip to content

Add Google Earth Engine accessor for satellite imagery (#53) - #76

Open
KarnakOza wants to merge 2 commits into
fccoelho:mainfrom
KarnakOza:feature/gee-accessor
Open

Add Google Earth Engine accessor for satellite imagery (#53)#76
KarnakOza wants to merge 2 commits into
fccoelho:mainfrom
KarnakOza:feature/gee-accessor

Conversation

@KarnakOza

Copy link
Copy Markdown

📋 Description

Adds a Google Earth Engine (GEE) accessor providing satellite-imagery-derived
indicators for epidemiological modeling, as requested in #53.

  • Implement GoogleEarthEngineAccessor with get_ndvi, get_ndwi,
    get_built_up_index, and get_built_up_change methods, covering the
    use cases in 🛰️ Add Google Earth Engine accessor (Satellite imagery) #53 (vegetation coverage/breeding sites, urban density,
    informal settlement growth)
  • Register earthengine-api as an optional extra and add the entry point
    so the accessor is discoverable via the standard source registry
  • Add tests covering initialization, list_countries, and indicator
    sign/range sanity checks against real-world reference points
  • Raise a clear ValueError when no cloud-free Landsat imagery is
    available for a given area/date range, instead of a cryptic
    band-not-found error

🎯 Type of Change

  • 🌍 New data source

🔗 Related Issues

Closes #53

🧪 Testing

  • Tests added for new functionality
  • Tests pass locally (pytest)
  • Tested on sample data

Test commands:

pytest tests/test_accessors.py -k GoogleEarthEngine -v

📊 Data Source Details

  • Name: Google Earth Engine
  • URL: https://earthengine.google.com/
  • Geographic Coverage: Global (planetary-scale satellite imagery)
  • Update Frequency: Varies by sensor (Landsat 8 ~16 days, Sentinel-2 ~5 days)
  • Authentication Required: Yes — free Google account + Earth Engine
    registration at https://signup.earthengine.google.com/, plus a linked
    GEE Cloud Project (set via EE_PROJECT env var or project= argument)

Example usage:

from epidatasets.sources.google_earth_engine import GoogleEarthEngineAccessor

gee = GoogleEarthEngineAccessor(project="your-gee-project-id")
ndvi = gee.get_ndvi(lon=-46.63, lat=-23.55, start_date='2021-03-01', end_date='2021-03-31')

📚 Documentation

  • README.md updated
  • Docstrings added/updated
  • API documentation updated (mkdocstrings page added)

✅ Checklist

Code Quality

  • Code follows the project's style guidelines
  • Self-review of code completed
  • Code is well-commented, particularly in hard-to-understand areas

Functionality

  • Code works as expected
  • Edge cases handled appropriately (no-imagery-found case)
  • Error messages are user-friendly
  • No hardcoded credentials or sensitive data

🌍 Impact Assessment

Who will benefit:

  • Researchers modeling vector-borne disease risk using vegetation/water/
    urban-density proxies
  • Public health teams needing satellite-derived environmental indicators
    without a separate GEE integration

Breaking changes:

  • None

🔄 Testing Evidence

>>> from epidatasets.sources.google_earth_engine import GoogleEarthEngineAccessor
>>> gee = GoogleEarthEngineAccessor(project="ee-karnakoza3")
>>> gee.get_ndvi(lon=-46.63, lat=-23.55, start_date='2021-03-01', end_date='2021-03-31')
0.10143420182597954
>>> gee.get_built_up_index(lon=-46.63, lat=-23.55, start_date='2021-03-01', end_date='2021-03-31')
0.0044230300576192
>>> gee.get_built_up_index(lon=-62.5, lat=-4.0, start_date='2021-01-01', end_date='2021-12-31')
-0.1926545981623303

Validated NDBI sign convention against known land cover: positive for
dense urban core (São Paulo), negative for Amazon rainforest — confirming
the built-up index behaves correctly across contrasting terrain.

Karnak Oza and others added 2 commits July 11, 2026 23:38
- Implement GoogleEarthEngineAccessor with NDVI, NDWI, NDBI, and NDBI-change methods covering the use cases in fccoelho#53 (vegetation coverage/breeding sites, urban density, informal settlement growth)
- Register earthengine-api as an optional extra and add entry point so the accessor is discoverable via the standard source registry
- Add tests covering initialization, list_countries, and indicator sign/range sanity checks against real-world reference points
- Raise a clear ValueError when no cloud-free Landsat imagery is available for a given area/date range, instead of a cryptic band-not-found error

Closes fccoelho#53
@fccoelho

Copy link
Copy Markdown
Owner

👋 PR Review Reminder

This pull request has been open for over a week without review.

Maintainers will review soon! If you need immediate feedback, feel free to tag us.

Thanks for your contribution! 🙏

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

🛰️ Add Google Earth Engine accessor (Satellite imagery)

2 participants