climate-data-download 0.1.0__tar.gz

climate_data_download-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kayode Adebayo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

climate_data_download-0.1.0/PKG-INFO

@@ -0,0 +1,274 @@
+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.

climate_data_download-0.1.0/README.md

@@ -0,0 +1,238 @@
+# 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.

climate_data_download-0.1.0/climate_data_download/__init__.py

@@ -0,0 +1,29 @@
+"""Utilities for downloading and aggregating climate data from Google Earth Engine."""
+
+from .core import (
+    aggregate_collection_to_annual_image,
+    authenticate_ee,
+    build_annual_collection,
+    build_climate_collection,
+    infer_aggregation_rule,
+    make_long_term_average_image,
+    read_aoi_from_shapefile,
+    run_gee_climate_workflow,
+)
+from .datasets import CLIMATE_DATASETS, get_dataset_config, list_supported_datasets
+
+__all__ = [
+    "CLIMATE_DATASETS",
+    "aggregate_collection_to_annual_image",
+    "authenticate_ee",
+    "build_annual_collection",
+    "build_climate_collection",
+    "get_dataset_config",
+    "infer_aggregation_rule",
+    "list_supported_datasets",
+    "make_long_term_average_image",
+    "read_aoi_from_shapefile",
+    "run_gee_climate_workflow",
+]
+
+__version__ = "0.1.0"