Metadata-Version: 2.4
Name: climate_data_download
Version: 0.1.0
Summary: Download and aggregate climate datasets from Google Earth Engine for watershed or polygon AOIs.
Author: Kayode Adebayo
License: MIT
Project-URL: Homepage, https://github.com/Kaysharp-cloud/climate_data_download
Project-URL: Repository, https://github.com/Kaysharp-cloud/climate_data_download
Project-URL: Issues, https://github.com/Kaysharp-cloud/climate_data_download/issues
Keywords: climate,google-earth-engine,earth-engine,gee,prism,daymet,gridmet,hydrology,geospatial
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Hydrology
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: earthengine-api>=0.1.390
Requires-Dist: geemap>=0.32.0
Requires-Dist: geopandas>=0.14.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: matplotlib>=3.7.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Dynamic: license-file

# climate_data_download

`climate_data_download` is a small Python package for extracting climate data from Google Earth Engine over a watershed or polygon shapefile. It was designed for hydrology, water resources, climate, and environmental data workflows.

The package currently includes built-in support for:

- PRISM monthly: `OREGONSTATE/PRISM/ANm`
- PRISM daily: `OREGONSTATE/PRISM/ANd`
- Daymet daily: `NASA/ORNL/DAYMET_V4`
- GRIDMET daily: `IDAHO_EPSCOR/GRIDMET`
- Custom Earth Engine ImageCollections

For PRISM, the package automatically uses `AN81` through 2020 and `AN91` from 2021 onward. For Daymet and GRIDMET, no PRISM-style `dataset_type` filter is applied.

## Installation

```bash
pip install climate_data_download
```

For local development:

```bash
git clone https://github.com/Kaysharp-cloud/climate_data_download.git
cd climate_data_download
pip install -e .[dev]
```

## Earth Engine setup

Before using the package, you need access to Google Earth Engine and must authenticate once:

```python
from climate_data_download import authenticate_ee

authenticate_ee()
```

If your Earth Engine setup requires a Google Cloud project ID:

```python
from climate_data_download import authenticate_ee

authenticate_ee(project="your-earth-engine-project-id")
```

## Basic usage

```python
from climate_data_download import authenticate_ee, run_gee_climate_workflow

authenticate_ee()

shp_path = "Big_sioux_SD_watershed/Big_sioux_SD_watershed.shp"

result = run_gee_climate_workflow(
    shp_path=shp_path,
    variables=["ppt"],
    start_year=1996,
    end_year=2025,
    dataset_key="prism_monthly",
)

raw_df = result["raw_df"]
annual_df = result["annual_df"]

print(raw_df.head())
print(annual_df.head())
```

By default, the function returns both:

- `raw_df`: daily or monthly watershed-average values, depending on the dataset
- `annual_df`: annual watershed-average values

Nothing is saved, plotted, or mapped by default.

## PRISM monthly precipitation, Tmax, and Tmin

```python
result = run_gee_climate_workflow(
    shp_path=shp_path,
    variables=["ppt", "tmax", "tmin"],
    start_year=1996,
    end_year=2025,
    dataset_key="prism_monthly",
)

raw_df = result["raw_df"]
annual_df = result["annual_df"]
```

For PRISM precipitation, monthly `ppt` values are summed to annual precipitation. Temperature variables are averaged to annual values.

## PRISM daily

```python
result = run_gee_climate_workflow(
    shp_path=shp_path,
    variables=["ppt", "tmax", "tmin"],
    start_year=1996,
    end_year=2025,
    dataset_key="prism_daily",
)
```

Daily extraction across many decades can be slow because each daily image is reduced over the AOI. If you only need annual values and the long-term raster, use:

```python
result = run_gee_climate_workflow(
    shp_path=shp_path,
    variables=["ppt", "tmax", "tmin"],
    start_year=1996,
    end_year=2025,
    dataset_key="prism_daily",
    compute_raw=False,
)
```

## Daymet daily

```python
result = run_gee_climate_workflow(
    shp_path=shp_path,
    variables=["prcp", "tmax", "tmin"],
    start_year=1996,
    end_year=2024,
    dataset_key="daymet_daily",
)
```

## GRIDMET daily

```python
result = run_gee_climate_workflow(
    shp_path=shp_path,
    variables=["pr", "tmmx", "tmmn"],
    start_year=1996,
    end_year=2025,
    dataset_key="gridmet_daily",
    convert_gridmet_temp_to_c=True,
)
```

By default, GRIDMET `tmmx` and `tmmn` are converted from Kelvin to Celsius.

## Optional map, plots, CSV, and GeoTIFF

These are off by default. Turn them on only when needed:

```python
result = run_gee_climate_workflow(
    shp_path=shp_path,
    variables=["ppt", "tmax", "tmin"],
    start_year=1996,
    end_year=2025,
    dataset_key="prism_monthly",
    show_map=True,
    show_plots=True,
    save_csv=True,
    csv_folder="climate_csv_outputs",
    csv_prefix="big_sioux_prism_monthly",
    save_tiff_local=True,
    local_tiff_folder="climate_tiff_outputs",
    local_tiff_name="big_sioux_prism_monthly_long_term_1996_2025.tif",
)
```

The GeoTIFF is the long-term annual average image. For multiple variables, it is exported as a multi-band GeoTIFF.

## Custom Earth Engine ImageCollection

```python
result = run_gee_climate_workflow(
    shp_path=shp_path,
    dataset_key="custom",
    collection_id="YOUR/GEE/IMAGE_COLLECTION_ID",
    variables=["your_precip_band", "your_temp_band"],
    start_year=2001,
    end_year=2020,
    time_step="daily",
    scale=5000,
    aggregation_rules={
        "your_precip_band": "sum",
        "your_temp_band": "mean",
    },
)
```

If your custom dataset requires year-specific property filters, pass a callable:

```python
def my_yearly_filter(year):
    if year <= 2020:
        return {"version": "old"}
    return {"version": "new"}

result = run_gee_climate_workflow(
    shp_path=shp_path,
    dataset_key="custom",
    collection_id="YOUR/GEE/IMAGE_COLLECTION_ID",
    variables=["precip"],
    start_year=1990,
    end_year=2025,
    time_step="monthly",
    scale=5000,
    aggregation_rules={"precip": "sum"},
    yearly_property_filters=my_yearly_filter,
)
```

## Return object

The function returns a dictionary with:

```python
result["raw_df"]
result["annual_df"]
result["raw_collection"]
result["annual_collection"]
result["long_term_image"]
result["aoi_gdf"]
result["aoi_fc"]
result["aoi"]
result["map"]
result["aggregation_rules"]
```

## Notes

- The package does not download climate data automatically at import time.
- You must have a working Earth Engine account.
- Large daily extractions can take time and it is advisable to download in chunks if you are considering downloading daily dataset for a long period of time. Use `compute_raw=False` if annual outputs are enough.
- For a shapefile, keep `.shp`, `.shx`, `.dbf`, and `.prj` together in the same folder.

## License

MIT License.
