pyCropWat

A Python Package for Computing Effective Precipitation Using Google Earth Engine Climate Data.

Project Structure

pyCropWat/
├── pycropwat/               # Main package
│   ├── __init__.py          # Package exports
│   ├── core.py              # EffectivePrecipitation class
│   ├── methods.py           # Effective precipitation methods (9 methods)
│   ├── analysis.py          # Temporal aggregation, statistics, visualization
│   ├── utils.py             # Utility functions (geometry loading, GEE init)
│   └── cli.py               # Command-line interface
├── tests/                   # Unit tests
│   ├── __init__.py
│   └── test_core.py
├── docs/                    # MkDocs documentation
│   ├── index.md             # Documentation home
│   ├── installation.md      # Installation guide
│   ├── examples.md          # Usage examples
│   ├── contributing.md      # Contribution guidelines
│   ├── assets/              # Documentation assets
│   │   ├── pyCropWat.png    # Logo image
│   │   ├── pyCropWat.gif    # Animated logo
│   │   ├── pyCropWat_logo.png  # Alternative logo
│   │   └── examples/        # Example output images for docs
│   │       ├── arizona/     # Arizona example figures
│   │       ├── comparisons/ # Dataset comparison figures
│   │       ├── figures/     # Rio de la Plata figures
│   │       ├── method_comparison/  # Method comparison figures
│   │       ├── new_mexico/  # New Mexico example figures
│   │       └── pcml/        # Western U.S. PCML example figures
│   ├── api/                 # API reference
│   │   ├── analysis.md
│   │   ├── cli.md
│   │   ├── core.md
│   │   ├── methods.md
│   │   └── utils.md
│   └── user-guide/          # User guide
│       ├── api.md
│       ├── cli.md
│       └── quickstart.md
├── Examples/                # Example scripts and data
│   ├── README.md                  # Detailed workflow documentation
│   ├── south_america_example.py   # Rio de la Plata workflow script
│   ├── arizona_example.py         # Arizona workflow script
│   ├── new_mexico_example.py      # New Mexico workflow script
│   ├── western_us_pcml_example.py # Western U.S. PCML workflow script
│   ├── ucrb_example.py            # UCRB field-scale workflow script
│   ├── AZ.geojson                 # Arizona boundary GeoJSON
│   ├── NM.geojson                 # New Mexico boundary GeoJSON
├── .github/                 # GitHub configuration
│   └── workflows/
│       ├── docs.yml         # GitHub Pages deployment workflow
│       └── publish.yml      # PyPI publishing workflow
├── CHANGELOG.md             # Release notes
├── MANIFEST.in              # PyPI package manifest
├── mkdocs.yml               # MkDocs configuration
├── environment.yml          # Conda environment file
├── pyproject.toml           # Package configuration
├── requirements.txt         # pip dependencies
├── LICENSE
└── README.md

Note: The Examples/ folder contains complete workflow scripts with detailed documentation in README.md.

• south_america_example.py: A comprehensive Python script demonstrating the complete pyCropWat workflow including data processing, temporal aggregation, statistical analysis, visualization (including anomaly, climatology, and trend maps), and dataset comparison using real Rio de la Plata data.
• arizona_example.py: A U.S.-focused workflow demonstrating 8 Peff methods with GridMET/PRISM precipitation and SSURGO AWC for Arizona, with U.S. vs Global dataset comparisons (excludes PCML).
• new_mexico_example.py: A New Mexico workflow comparing 8 Peff methods using PRISM precipitation with SSURGO AWC and gridMET ETo (excludes PCML).
• AZ.geojson: Arizona boundary GeoJSON for local geometry support.
• NM.geojson: New Mexico boundary GeoJSON for local geometry support.

Note: Output rasters (~32 GB) are not included in the repository. Run the example scripts with a GEE project ID to generate them locally.

See the Complete Workflow Examples section below for details.

Changelog: See CHANGELOG.md for release notes and version history.

Overview

pyCropWat converts precipitation data from any GEE climate dataset into effective precipitation and effective precipitation fraction rasters. It supports:

• Any GEE ImageCollection with precipitation data from the GEE Data Catalog or Community Catalog
• Shapefile, GeoJSON, or GEE FeatureCollection asset for region of interest
• Multiple effective precipitation methods: CROPWAT, FAO/AGLW, Fixed Percentage, Dependable Rainfall, FarmWest, USDA-SCS, TAGEM-SuET, PCML, Ensemble
• Parallel processing using Dask
• Monthly output rasters in GeoTIFF format
• Temporal aggregation: Seasonal, annual, growing season (with cross-year support for Southern Hemisphere), custom date ranges
• Statistical analysis: Climatology, anomalies, trend analysis
• Enhanced exports: NetCDF, Cloud-Optimized GeoTIFF (COG), zonal statistics CSV
• Visualization: Time series plots, maps, climatology charts, anomaly maps, trend maps with significance

Effective Precipitation Methods

pyCropWat supports multiple methods for calculating effective precipitation:

Method	Description
cropwat	CROPWAT method from FAO
fao_aglw	FAO/AGLW Dependable Rainfall (80% exceedance)
fixed_percentage	Simple fixed percentage method (configurable, default 70%)
dependable_rainfall	FAO Dependable Rainfall at specified probability level
farmwest	FarmWest method: Peff = (P - 5) × 0.75
usda_scs	USDA-SCS method with AWC and ETo (requires GEE assets)
suet	TAGEM-SuET method: P - ETo with 75mm threshold (requires ETo asset)
pcml	Physics-Constrained ML (Western U.S. only, Jan 2000 - Sep 2024); no geometry = full Western U.S., or provide geometry to subset
ensemble	Ensemble mean of all methods except TAGEM-SuET and PCML - default (requires AWC and ETo assets)

CROPWAT

The effective precipitation is calculated using the CROPWAT method (Smith, 1992; Muratoglu et al., 2023):

• If precipitation ≤ 250 mm: Peff = P × (125 - 0.2 × P) / 125
• If precipitation > 250 mm: Peff = 0.1 × P + 125

FAO/AGLW Formula (Dependable Rainfall)

The FAO Land and Water Division (AGLW) Dependable Rainfall formula from FAO Irrigation and Drainage Paper No. 33, based on 80% probability exceedance:

• If precipitation ≤ 70 mm: Peff = max(0.6 × P - 10, 0)
• If precipitation > 70 mm: Peff = 0.8 × P - 24

Fixed Percentage Method

A simple method assuming a constant fraction of precipitation is effective:

• Peff = P × f where f is the effectiveness fraction (default: 0.7 or 70%)

Dependable Rainfall Method

The FAO Dependable Rainfall method (same as FAO/AGLW) estimates rainfall at a given probability level (default 80%):

• If precipitation ≤ 70 mm: Peff = max(0.6 × P - 10, 0)
• If precipitation > 70 mm: Peff = 0.8 × P - 24

A probability scaling factor is applied:

• 50% probability: ~1.3× base estimate (less conservative)
• 80% probability: 1.0× base estimate (default)
• 90% probability: ~0.9× base estimate (more conservative)

FarmWest Method

A simple empirical formula used by the FarmWest program:

• Peff = max((P - 5) × 0.75, 0)

Assumes the first 5 mm is lost to interception/evaporation, and 75% of the remaining precipitation is effective.

Reference: FarmWest - Effective Precipitation

USDA-SCS Method (with AWC and ETo)

The USDA Soil Conservation Service method that accounts for soil water holding capacity and evaporative demand:

1. Calculate soil storage depth: d = AWC × MAD × rooting_depth (MAD = Maximum Allowable Depletion, default 0.5)
2. Calculate storage factor: sf = 0.531747 + 0.295164×d - 0.057697×d² + 0.003804×d³
3. Calculate effective precipitation: Peff = sf × (P^0.82416 × 0.70917 - 0.11556) × 10^(ETo × 0.02426)
4. Peff is clamped between 0 and min(P, ETo)

Required GEE Assets:

Region	AWC Asset	ETo Asset
U.S.	projects/openet/soil/ssurgo_AWC_WTA_0to152cm_composite	projects/openet/assets/reference_et/conus/gridmet/monthly/v1 (band: eto)
Global	projects/sat-io/open-datasets/FAO/HWSD_V2_SMU (band: AWC)	projects/climate-engine-pro/assets/ce-ag-era5-v2/daily (band: ReferenceET_PenmanMonteith_FAO56, use --eto-is-daily)

CLI Example (U.S.):

pycropwat process --asset ECMWF/ERA5_LAND/MONTHLY_AGGR --band total_precipitation_sum \
    --gee-geometry projects/my-project/assets/study_area \
    --start-year 2015 --end-year 2020 --scale-factor 1000 \
    --method usda_scs \
    --awc-asset projects/openet/soil/ssurgo_AWC_WTA_0to152cm_composite \
    --eto-asset projects/openet/assets/reference_et/conus/gridmet/monthly/v1 \
    --eto-band eto --rooting-depth 1.0 --mad-factor 0.5 --output ./output

CLI Example (Global):

pycropwat process --asset ECMWF/ERA5_LAND/MONTHLY_AGGR --band total_precipitation_sum \
    --gee-geometry projects/my-project/assets/study_area \
    --start-year 2015 --end-year 2020 --scale-factor 1000 \
    --method usda_scs \
    --awc-asset projects/sat-io/open-datasets/FAO/HWSD_V2_SMU --awc-band AWC \
    --eto-asset projects/climate-engine-pro/assets/ce-ag-era5-v2/daily \
    --eto-band ReferenceET_PenmanMonteith_FAO56 --eto-is-daily \
    --rooting-depth 1.0 --mad-factor 0.5 --output ./output

Reference: USDA SCS (1993). Chapter 2 Irrigation Water Requirements. Part 623 National Engineering Handbook.

TAGEM-SuET Method (with ETo)

The TAGEM-SuET (Türkiye'de Sulanan Bitkilerin Bitki Su Tüketimleri - Turkish Irrigation Management and Plant Water Consumption System) method calculates effective precipitation based on the difference between precipitation and reference evapotranspiration:

• If P ≤ ETo: Peff = 0
• If P > ETo and (P - ETo) < 75: Peff = P - ETo
• Otherwise: Peff = 75 + 0.0011×(P - ETo - 75)² + 0.44×(P - ETo - 75)

⚠️ Note: Studies have shown that the TAGEM-SuET method tends to underperform compared to other metho