climate-data-download 0.1.0

Download and aggregate climate datasets from Google Earth Engine for watershed or polygon AOIs.

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

pip install climate_data_download

For local development:

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:

from climate_data_download import authenticate_ee

authenticate_ee()

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

from climate_data_download import authenticate_ee

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

Basic usage

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

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

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:

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

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

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:

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

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:

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:

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.