pycropwat 1.1.1.post2

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

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 (8 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
│   │   └── 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
│   ├── 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 (data generated locally)
│   ├── 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
│   ├── 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:

• README.md: Detailed step-by-step documentation of the complete workflow example.
• 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 all 8 Peff methods with GridMET/PRISM precipitation and SSURGO AWC for Arizona, with U.S. vs Global dataset comparisons.
• new_mexico_example.py: A New Mexico workflow comparing all 8 Peff methods using PRISM precipitation with SSURGO AWC and gridMET ETo.
• 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, 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)
ensemble	Ensemble mean of all methods except TAGEM-SuET - 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 Washington State University's 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 × 0.5 × rooting_depth
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 --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 --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 methods, particularly in arid and semi-arid climates where ETo often exceeds precipitation. In our method comparison analyses, TAGEM-SuET consistently produced the lowest effective precipitation estimates. Users should consider this limitation when selecting a method for their application.

Reference: Muratoglu, A., Bilgen, G. K., Angin, I., & Kodal, S. (2023). Performance analyses of effective rainfall estimation methods for accurate quantification of agricultural water footprint. Water Research, 238, 120011.

CLI Example:

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 suet \
    --eto-asset projects/openet/assets/reference_et/conus/gridmet/monthly/v1 \
    --eto-band eto --output ./output

Ensemble - Default (Mean of Methods)

The ensemble method provides a robust estimate by calculating the mean of all methods except TAGEM-SuET, which has been shown to underperform in comparative analyses. The ensemble includes:

1. CROPWAT - FAO standard method
2. FAO/AGLW - Dependable Rainfall (80% exceedance)
3. Fixed Percentage - 70% of precipitation
4. Dependable Rainfall - 75% probability level
5. FarmWest - Pacific Northwest method
6. USDA-SCS - Soil-based method

Formula: Peff_ensemble = (Peff_cropwat + Peff_fao_aglw + Peff_fixed + Peff_dependable + Peff_farmwest + Peff_usda_scs) / 6

💡 Note: The ensemble method requires AWC and ETo assets (same as USDA-SCS) since it internally calculates all component methods. This method is recommended when users want a robust, multi-method average that reduces bias from any single method.

CLI Example:

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 ensemble \
    --awc-asset projects/sat-io/open-datasets/FAO/HWSD_V2_SMU --awc-band AWC \
    --eto-asset projects/openet/assets/reference_et/conus/gridmet/monthly/v1 \
    --eto-band eto --output ./output

Method Comparison

Method	Use Case	Characteristics
CROPWAT	General irrigation planning	Balanced, widely validated
FAO/AGLW	Yield response studies	FAO Dependable Rainfall (80% exceedance)
Fixed Percentage	Quick estimates, calibration	Simple, requires local calibration
Dependable Rainfall	Risk-averse planning	Same as FAO/AGLW, with probability scaling
FarmWest	Pacific Northwest irrigation	Simple, accounts for interception loss
USDA-SCS	Site-specific irrigation planning	Accounts for soil AWC and ETo
TAGEM-SuET	ET-based irrigation planning	Based on P - ETo difference
Ensemble	Robust multi-method estimate	Mean of 6 methods (excludes TAGEM-SuET)

Installation

Quick Install (PyPI)

pip install pycropwat

Or with optional interactive map support:

pip install pycropwat[interactive]

Disk Space Requirements

Component	Size	Notes
Repository (code + docs)	~50 MB	Core package, documentation, and assets
Generated by example scripts:
Examples/RioDelaPlata	~5 GB	ERA5-Land & TerraClimate outputs (2000-2025)
Examples/Arizona	~12 GB	GridMET, PRISM, ERA5-Land & TerraClimate outputs (1985-2025)
Examples/NewMexico	~14 GB	PRISM 8-method outputs (1986-2025)

Note: Large data files (~32 GB) are excluded from the repository via .gitignore. Run the example scripts to generate them locally:

python Examples/south_america_example.py --gee-project your-project-id
python Examples/arizona_example.py --gee-project your-project-id
python Examples/new_mexico_example.py --gee-project your-project-id

Using Conda (Recommended for Development)

# Clone the repository
git clone https://github.com/montimaj/pyCropWat.git
cd pyCropWat

# Create conda environment from environment.yml
conda env create -f environment.yml

# Activate the environment
conda activate pycropwat

# Install the package (registers the 'pycropwat' CLI command)
pip install -e .

# Or with interactive map support (leafmap, localtileserver)
pip install -e ".[interactive]"

# Verify installation
pycropwat --help

From Source (pip)

# Clone the repository
git clone https://github.com/montimaj/pyCropWat.git
cd pyCropWat

# Create and activate a virtual environment (optional but recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package (registers the 'pycropwat' CLI command)
pip install -e .

# Or with interactive map support (leafmap, localtileserver)
pip install -e ".[interactive]"

# Verify installation
pycropwat --help

Note: After running pip install -e ., the pycropwat command will be available globally in your environment. Do not use ./pycropwat - just use pycropwat directly.

Optional Dependencies:

• pip install -e ".[interactive]" - Adds leafmap and localtileserver for interactive HTML maps
• pip install -e ".[dev]" - Adds development tools (pytest, black, ruff)
• pip install -e ".[docs]" - Adds documentation tools (mkdocs)

## Requirements

- Python >= 3.9
- Google Earth Engine account and authentication
- Dependencies: earthengine-api, numpy, xarray, rioxarray, geopandas, shapely, dask

### Conda Environment

The `environment.yml` file provides a complete conda environment with all dependencies:

```bash
# Create environment
conda env create -f environment.yml

# Activate environment
conda activate pycropwat

# Update existing environment
conda env update -f environment.yml --prune

# Remove environment
conda env remove -n pycropwat

Usage

Python API

from pycropwat import EffectivePrecipitation

# Initialize the processor with a local file
ep = EffectivePrecipitation(
    asset_id='ECMWF/ERA5_LAND/MONTHLY_AGGR',
    precip_band='total_precipitation_sum',
    geometry_path='path/to/region.geojson',
    start_year=2015,
    end_year=2020,
    precip_scale_factor=1000,  # ERA5 precipitation is in meters, convert to mm
    gee_project='your-gee-project'  # Optional
)

# Or use a GEE FeatureCollection asset for the study area
ep = EffectivePrecipitation(
    asset_id='ECMWF/ERA5_LAND/MONTHLY_AGGR',
    precip_band='total_precipitation_sum',
    gee_geometry_asset='projects/my-project/assets/study_boundary',
    start_year=2015,
    end_year=2020,
    precip_scale_factor=1000
)

# Use alternative effective precipitation methods
ep = EffectivePrecipitation(
    asset_id='ECMWF/ERA5_LAND/MONTHLY_AGGR',
    precip_band='total_precipitation_sum',
    gee_geometry_asset='projects/my-project/assets/study_boundary',
    start_year=2015,
    end_year=2020,
    precip_scale_factor=1000,
    method='fao_aglw'  # Options: 'cropwat', 'fao_aglw', 'fixed_percentage', 'dependable_rainfall', 'farmwest', 'usda_scs', 'suet', 'ensemble'
)

# Process with parallel execution (using dask)
results = ep.process(
    output_dir='./output',
    n_workers=4,
    months=[6, 7, 8]  # Optional: process only specific months
)

# Or process sequentially (useful for debugging)
results = ep.process_sequential(output_dir='./output')

Temporal Aggregation & Analysis

from pycropwat import TemporalAggregator, StatisticalAnalyzer, Visualizer

# Temporal aggregation
agg = TemporalAggregator('./output')

# Annual total
annual = agg.annual_aggregate(2020, method='sum', output_path='./annual_2020.tif')

# Seasonal aggregate (JJA = June-July-August)
summer = agg.seasonal_aggregate(2020, 'JJA', method='sum')

# Growing season - Northern Hemisphere (April-October, same year)
growing_nh = agg.growing_season_aggregate(2020, start_month=4, end_month=10)

# Growing season - Southern Hemisphere (October-March, cross-year)
# Aggregates Oct 2020 - Mar 2021 when start_month > end_month
growing_sh = agg.growing_season_aggregate(2020, start_month=10, end_month=3)

# Multi-year climatology
climatology = agg.multi_year_climatology(2000, 2020, output_dir='./climatology')

# Statistical analysis
stats = StatisticalAnalyzer('./output')

# Calculate anomaly
anomaly = stats.calculate_anomaly(2020, 6, clim_start=1990, clim_end=2020, 
                                   anomaly_type='percent')

# Trend analysis (returns slope in mm/year and p-value)
slope, pvalue = stats.calculate_trend(start_year=2000, end_year=2020, month=6)

# Zonal statistics
zonal_df = stats.zonal_statistics('./zones.shp', 2000, 2020, output_path='./zonal_stats.csv')

# Visualization
viz = Visualizer('./output')
viz.plot_time_series(2000, 2020, output_path='./timeseries.png')
viz.plot_monthly_climatology(2000, 2020, output_path='./climatology.png')
viz.plot_raster(2020, 6, output_path='./map_2020_06.png')

# Interactive map (requires leafmap or folium: pip install leafmap)
viz.plot_interactive_map(2020, 6, output_path='./interactive_map.html')

# Dataset comparison
viz.plot_comparison(2020, 6, other_dir='./terraclimate_output', 
                    labels=('ERA5', 'TerraClimate'), output_path='./comparison.png')
viz.plot_scatter_comparison(2000, 2020, other_dir='./terraclimate_output',
                            labels=('ERA5', 'TerraClimate'), output_path='./scatter.png')
viz.plot_annual_comparison(2000, 2020, other_dir='./terraclimate_output',
                           labels=('ERA5', 'TerraClimate'), output_path='./annual_comparison.png')

Export Options

from pycropwat import export_to_netcdf, export_to_cog

# Export to NetCDF (single file with time dimension)
export_to_netcdf('./output', './effective_precip.nc')

# Convert to Cloud-Optimized GeoTIFF
export_to_cog('./output/effective_precip_2020_06.tif', './cog_2020_06.tif')

Command Line Interface

pyCropWat provides a subcommand-based CLI for all functionality:

pycropwat <command> [OPTIONS]

Available Commands:

Command	Description
process	Calculate effective precipitation from GEE climate data
aggregate	Temporal aggregation (annual, seasonal, growing season)
analyze	Statistical analysis (anomaly, trend, zonal statistics)
export	Export to NetCDF or Cloud-Optimized GeoTIFF
plot	Create visualizations (time series, climatology, maps)

Process Command Examples

# Process ERA5-Land data (actual working example)
pycropwat process --asset ECMWF/ERA5_LAND/MONTHLY_AGGR \
                  --band total_precipitation_sum \
                  --gee-geometry projects/ssebop-471916/assets/Riodelaplata \
                  --start-year 2000 --end-year 2025 \
                  --scale-factor 1000 --scale 4000 \
                  --workers 32 --output ./Examples/RioDelaPlata/RDP_ERA5Land

# Use alternative effective precipitation method
pycropwat process --asset ECMWF/ERA5_LAND/MONTHLY_AGGR \
                  --band total_precipitation_sum \
                  --gee-geometry projects/my-project/assets/study_area \
                  --start-year 2020 --end-year 2023 \
                  --scale-factor 1000 \
                  --method fao_aglw --output ./outputs

# List available methods
pycropwat --list-methods

# Process TerraClimate data (actual working example)
pycropwat process --asset IDAHO_EPSCOR/TERRACLIMATE \
                  --band pr \
                  --gee-geometry projects/ssebop-471916/assets/Riodelaplata \
                  --start-year 2000 --end-year 2025 \
                  --workers 32 --output ./Examples/RioDelaPlata/RDP_TerraClimate

# Process with local shapefile
pycropwat process --asset ECMWF/ERA5_LAND/MONTHLY_AGGR \
                  --band total_precipitation_sum \
                  --geometry roi.geojson \
                  --start-year 2015 --end-year 2020 \
                  --scale-factor 1000 --output ./output

Aggregate Command Examples

# Annual total
pycropwat aggregate --input ./output --type annual --year 2020 --output ./annual_2020.tif

# Seasonal (summer)
pycropwat aggregate --input ./output --type seasonal --year 2020 --season JJA --output ./summer_2020.tif

# Growing season (April-October)
pycropwat aggregate --input ./output --type growing-season --year 2020 \
                    --start-month 4 --end-month 10 --output ./growing_2020.tif

# Multi-year climatology
pycropwat aggregate --input ./output --type climatology \
                    --start-year 2000 --end-year 2020 --output ./climatology/

Analyze Command Examples

# Calculate anomaly
pycropwat analyze anomaly --input ./output --year 2020 --month 6 \
                          --clim-start 1990 --clim-end 2020 --output ./anomaly_2020_06.tif

# Calculate trend
pycropwat analyze trend --input ./output --start-year 2000 --end-year 2020 \
                        --trend-method sen --output ./trend/

# Zonal statistics
pycropwat analyze zonal --input ./output --zones ./regions.shp \
                        --start-year 2000 --end-year 2020 --output ./zonal_stats.csv

Export Command Examples

# Export to NetCDF
pycropwat export netcdf --input ./output --output ./data.nc

# Convert to Cloud-Optimized GeoTIFF
pycropwat export cog --input ./effective_precip_2020_06.tif --output ./cog_2020_06.tif

Plot Command Examples

# Time series plot
pycropwat plot timeseries --input ./output --start-year 2000 --end-year 2020 --output ./timeseries.png

# Monthly climatology bar chart
pycropwat plot climatology --input ./output --start-year 2000 --end-year 2020 --output ./climatology.png

# Single month map
pycropwat plot map --input ./output --year 2020 --month 6 --output ./map_2020_06.png

# Interactive map (requires leafmap: pip install leafmap)
pycropwat plot interactive --input ./output --year 2020 --month 6 --output ./map.html

# Compare two datasets (e.g., ERA5 vs TerraClimate)
pycropwat plot compare --input ./era5_output --other-input ./terraclimate_output \
                       --year 2020 --month 6 --label1 ERA5 --label2 TerraClimate \
                       --output ./comparison.png

# Scatter plot for validation
pycropwat plot scatter --input ./era5_output --other-input ./terraclimate_output \
                       --start-year 2000 --end-year 2020 --output ./scatter.png

# Annual comparison bar chart
pycropwat plot annual-compare --input ./era5_output --other-input ./terraclimate_output \
                              --start-year 2000 --end-year 2020 --output ./annual.png

CLI Arguments

Global Options

Argument	Description
--help	Show help message
--version	Show version number
--list-methods	List available effective precipitation methods

Process Command Arguments

Argument	Short	Required	Default	Description
--asset	-a	Yes	-	GEE ImageCollection asset ID
--band	-b	Yes	-	Precipitation band name
--geometry	-g	No*	-	Path to shapefile or GeoJSON
--gee-geometry	-G	No*	-	GEE FeatureCollection asset ID
--start-year	-s	Yes	-	Start year (inclusive)
--end-year	-e	Yes	-	End year (inclusive)
--output	-o	Yes	-	Output directory
--scale-factor	-f	No	1.0	Conversion factor to mm
--scale	-r	No	Native	Output resolution in meters
--workers	-w	No	4	Number of parallel workers
--months	-m	No	All	Specific months to process
--project	-p	No	None	GEE project ID
--method	-	No	ensemble	Peff method: cropwat, fao_aglw, fixed_percentage, dependable_rainfall, farmwest, usda_scs, suet, ensemble
--percentage	-	No	0.7	Percentage for fixed_percentage method
--probability	-	No	0.75	Probability for dependable_rainfall method
--sequential	-	No	False	Process sequentially
--verbose	-v	No	False	Verbose output

* Either --geometry or --gee-geometry must be provided.

For full CLI documentation, run pycropwat <command> --help or see the CLI Reference.

Output Files

The package generates two GeoTIFF files per month:

1. effective_precip_YYYY_MM.tif - Effective precipitation (mm)
2. effective_precip_fraction_YYYY_MM.tif - Effective precipitation fraction (0-1)

Output Resolution

• Default (no --scale): Uses the native resolution of the input dataset
  • ERA5-Land: ~11 km (0.1°)
  • TerraClimate: ~4 km (1/24°)
  • CHIRPS: ~5.5 km (0.05°)
• With --scale: Reprojects to the specified resolution in meters (e.g., --scale 1000 for 1 km)

Large Region Handling

For large study areas or high-resolution outputs that exceed GEE's pixel limits (262,144 pixels per request), pyCropWat automatically:

1. Estimates pixel count for the region
2. Splits large regions into smaller tiles (max 256×256 pixels per tile)
3. Downloads each tile separately from GEE
4. Mosaics the tiles back together in memory (no temp files)
5. Resizes to match the target resolution

This applies to precipitation, AWC, and ETo data downloads. No configuration required - it's handled automatically.

Important: Units

The CROPWAT formula is calibrated for precipitation in millimeters (mm). The output effective precipitation is always in mm, provided you use the correct --scale-factor to convert input precipitation to mm first.

The formula constants (125, 250, 0.2, 0.1) are specifically designed for mm units:

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

Warning: If you pass precipitation in wrong units (e.g., ERA5 in meters without --scale-factor 1000), the results will be incorrect because the 250mm threshold won't match properly.

Temporal Aggregation

pyCropWat automatically sums all images within each month to compute monthly total precipitation, regardless of the input data's temporal resolution:

• Monthly data (ERA5, TerraClimate): Uses the single monthly image directly
• Daily data (CHIRPS/DAILY): Sums all ~30 daily images → monthly total
• Sub-daily data (GPM IMERG): Sums all timesteps → monthly total

This ensures the CROPWAT formula always receives the correct monthly precipitation totals.

Common GEE Climate Assets

Global Precipitation Datasets

Asset ID	Precipitation Band	Scale Factor	Spatial Resolution	Temporal Resolution
ECMWF/ERA5_LAND/MONTHLY_AGGR	total_precipitation_sum	1000	~11 km (0.1°)	Monthly
ECMWF/ERA5/MONTHLY	total_precipitation	1000	~27 km (0.25°)	Monthly
IDAHO_EPSCOR/TERRACLIMATE	pr	1	~4 km (1/24°)	Monthly
UCSB-CHG/CHIRPS/DAILY	precipitation	1	~5.5 km (0.05°)	Daily
UCSB-CHG/CHIRPS/PENTAD	precipitation	1	~5.5 km (0.05°)	5-day (Pentad)
NASA/GPM_L3/IMERG_V06	precipitation	1	~11 km (0.1°)	Half-hourly
projects/climate-engine-pro/assets/ce-ag-era5-v2/daily	Precipitation_Flux	1	~9 km (0.1°)	Daily

U.S.-Specific Precipitation Datasets

Asset ID	Precipitation Band	Scale Factor	Spatial Resolution	Description
IDAHO_EPSCOR/GRIDMET	pr	1	~4 km	University of Idaho GridMET daily meteorological data
projects/sat-io/open-datasets/OREGONSTATE/PRISM_800_MONTHLY	ppt	1	~800 m	Oregon State PRISM high-resolution monthly precipitation

USDA-SCS Method Required Datasets

For the USDA-SCS method, you need AWC (Available Water Capacity) and ETo (Reference ET) data:

Region	Dataset Type	Asset ID	Band	Notes
U.S.	AWC	projects/openet/soil/ssurgo_AWC_WTA_0to152cm_composite	(single band)	SSURGO soil data
U.S.	ETo	projects/openet/assets/reference_et/conus/gridmet/monthly/v1	eto	GridMET monthly ETo
Global	AWC	projects/sat-io/open-datasets/FAO/HWSD_V2_SMU	AWC	FAO HWSD v2
Global	ETo	projects/climate-engine-pro/assets/ce-ag-era5-v2/daily	ReferenceET_PenmanMonteith_FAO56	ERA5-based (use --eto-is-daily)

Complete Workflow Examples

The Examples/ directory contains comprehensive workflow scripts demonstrating pyCropWat capabilities:

1. Rio de la Plata Basin Example (Global)

📖 Script: Examples/south_america_example.py

Demonstrates the complete pyCropWat workflow comparing ERA5-Land and TerraClimate data for South America.

For detailed step-by-step documentation, see Examples/README.md

What the Example Does

The script performs a comprehensive 6-step workflow:

1. Process Effective Precipitation - Downloads and calculates effective precipitation from ERA5-Land and TerraClimate via GEE
2. Temporal Aggregation - Creates annual totals, growing season aggregations (Apr-Sep), and monthly climatology
3. Statistical Analysis - Computes percent anomalies, trends (Sen's slope), and zonal statistics
4. Visualization - Generates time series plots, climatology charts, static maps, and interactive HTML maps
5. Dataset Comparison - Creates side-by-side comparison plots, scatter plots, annual charts, and zonal comparisons
6. NetCDF Export - Exports data to CF-compliant NetCDF format

Running the Example

# Navigate to the Examples directory
cd Examples/

# Run analysis only (using existing pre-processed data)
python south_america_example.py --analysis-only

# Run full workflow with GEE processing (requires authentication)
python south_america_example.py --gee-project your-project-id --workers 8

# Force reprocess all data from GEE
python south_america_example.py --force-reprocess --gee-project your-project-id --workers 8

Configuration

Parameter	Value
Study Area	Rio de la Plata Basin (GEE Asset: projects/ssebop-471916/assets/Riodelaplata)
Time Period	2000-2025
Climatology Period	2000-2020
Datasets	ERA5-Land, TerraClimate
Sample Zones	Eastern RDP (Uruguay, SE Brazil), Western RDP (N Argentina, Paraguay)

---

2. Arizona USDA-SCS Example (U.S.)

📖 Script: Examples/arizona_example.py

Demonstrates the USDA-SCS method with U.S.-specific AWC and ETo datasets for Arizona, comparing GridMET and PRISM precipitation data.

USDA-SCS Method Configuration

The Arizona example uses these U.S.-based GEE datasets:

Dataset	GEE Asset ID	Band
Precipitation (GridMET)	IDAHO_EPSCOR/GRIDMET	pr
Precipitation (PRISM)	projects/sat-io/open-datasets/OREGONSTATE/PRISM_800_MONTHLY	ppt
AWC (SSURGO)	projects/openet/soil/ssurgo_AWC_WTA_0to152cm_composite	(single band)
ETo (GridMET)	projects/openet/assets/reference_et/conus/gridmet/monthly/v1	eto

What the Example Does

1. Process Effective Precipitation - Uses USDA-SCS method with SSURGO AWC and GridMET ETo
2. Compare Precipitation Sources - GridMET (~4km) vs PRISM (~800m)
3. Arizona-Specific Aggregation - Monsoon season (Jul-Sep), winter season (Jan-Feb)
4. Zonal Statistics - Central AZ, Southern AZ, Northern AZ regions
5. Dataset Comparison - GridMET vs PRISM scatter plots, zonal comparisons

Running the Example

cd Examples/

# Run analysis only (if data already processed)
python arizona_example.py --analysis-only

# Run full workflow with GEE processing
python arizona_example.py --gee-project your-project-id --workers 8

# Force reprocess
python arizona_example.py --force-reprocess --gee-project your-project-id

CLI Equivalent

# Process with GridMET precipitation using USDA-SCS method
pycropwat process --asset IDAHO_EPSCOR/GRIDMET --band pr \
    --gee-geometry users/montimajumdar/AZ \
    --start-year 2000 --end-year 2024 --scale 4000 \
    --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 \
    --workers 8 --output ./AZ_GridMET_USDA_SCS

# Process with PRISM precipitation
pycropwat process --asset projects/sat-io/open-datasets/OREGONSTATE/PRISM_800_MONTHLY --band ppt \
    --gee-geometry users/montimajumdar/AZ \
    --start-year 2000 --end-year 2024 --scale 4000 \
    --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 \
    --workers 8 --output ./AZ_PRISM_USDA_SCS

Configuration

Parameter	Value
Study Area	Arizona (GEE Asset: users/montimajumdar/AZ)
Time Period	2000-2024
Climatology Period	2000-2020
Precipitation Datasets	GridMET, PRISM
AWC Dataset	SSURGO (OpenET)
ETo Dataset	GridMET Monthly (OpenET)
Rooting Depth	1.0 m
Sample Zones	Central AZ (Phoenix), Southern AZ (Tucson), Northern AZ (Flagstaff)

---

Output Structure

Running the example creates organized outputs:

Examples/
├── south_america_example.py   # Rio de la Plata workflow script
├── arizona_example.py         # Arizona workflow script
├── new_mexico_example.py      # New Mexico workflow script
├── AZ.geojson                         # Arizona boundary GeoJSON
├── NM.geojson                         # New Mexico boundary GeoJSON
├── README.md                          # Detailed documentation
├── RioDelaPlata/                      # Rio de la Plata region
│   ├── RDP_ERA5Land/                     # Monthly effective precipitation (ERA5-Land)
│   │   ├── effective_precip_YYYY_MM.tif
│   │   └── effective_precip_fraction_YYYY_MM.tif
│   ├── RDP_TerraClimate/                 # Monthly effective precipitation (TerraClimate)
│   │   ├── effective_precip_YYYY_MM.tif
│   │   └── effective_precip_fraction_YYYY_MM.tif
│   ├── analysis_inputs/                  # Downloaded input data
│   │   ├── RDP_ERA5Land/
│   │   │   └── precip_YYYY_MM.tif
│   │   └── RDP_TerraClimate/
│   │       └── precip_YYYY_MM.tif
│   └── analysis_outputs/
│       ├── annual/                        # Annual totals by dataset
│       │   ├── ERA5Land/
│       │   └── TerraClimate/
│       ├── climatology/                   # Monthly climatology (2000-2020)
│       │   ├── ERA5Land/
│       │   │   └── climatology_2000_2020_month_MM.tif
│       │   └── TerraClimate/
│       ├── anomalies/                     # Percent anomalies
│       │   ├── ERA5Land/
│       │   │   └── anomaly_YYYY_MM.tif
│       │   └── TerraClimate/
│       ├── trend/                         # Trend analysis
│       │   ├── ERA5Land/
│       │   │   ├── trend_slope_2000_2025_annual.tif
│       │   │   └── trend_pvalue_2000_2025_annual.tif
│       │   └── TerraClimate/
│       ├── figures/                       # Visualizations by dataset
│       │   ├── ERA5Land/
│       │   │   ├── time_series.png
│       │   │   ├── monthly_climatology.png
│       │   │   ├── anomaly_map_YYYY_MM.png
│       │   │   ├── climatology_map_MM.png
│       │   │   ├── trend_maps.png
│       │   │   └── trend_map_with_significance.png
│       │   └── TerraClimate/
│       ├── comparisons/                   # Dataset comparisons
│       └── method_comparison/             # Peff method comparison
└── Arizona/                           # Arizona region
    ├── AZ_GridMET_USDA_SCS/               # GridMET U.S. dataset
    │   ├── effective_precip_YYYY_MM.tif
    │   └── effective_precip_fraction_YYYY_MM.tif
    ├── AZ_PRISM_USDA_SCS/                 # PRISM U.S. dataset
    ├── AZ_ERA5Land_USDA_SCS/              # ERA5-Land global dataset
    ├── AZ_TerraClimate_USDA_SCS/          # TerraClimate global dataset
    ├── analysis_inputs/                   # Downloaded input data (precip, AWC, ETo)
    │   ├── AZ_GridMET_USDA_SCS/
    │   │   ├── precip_YYYY_MM.tif
    │   │   ├── awc.tif
    │   │   └── eto_YYYY_MM.tif
    │   └── ...                            # Other datasets
    └── analysis_outputs/
        ├── annual/
        ├── climatology/
        │   └── {dataset}/
        │       └── climatology_1985_2020_month_MM.tif
        ├── anomalies/
        │   └── {dataset}/
        │       └── anomaly_YYYY_MM.tif
        ├── trend/
        │   └── {dataset}/
        │       ├── trend_slope_1985_2025_annual.tif
        │       └── trend_pvalue_1985_2025_annual.tif
        ├── figures/
        │   └── {dataset}/
        │       ├── time_series.png
        │       ├── monthly_climatology.png
        │       ├── anomaly_map_YYYY_MM.png
        │       ├── climatology_map_MM.png
        │       ├── trend_maps.png
        │       └── trend_map_with_significance.png
        ├── comparisons/
        ├── us_vs_global/                  # U.S. vs Global dataset comparison
        └── method_comparison/             # All 6 Peff methods comparison

Example Outputs

The following visualizations are generated by the complete workflow example using real Rio de la Plata basin data:

Time Series & Climatology

Left: Monthly effective precipitation time series (2000-2025). Right: Monthly climatology showing seasonal patterns.

Spatial Maps

Left: Winter dry season (June 2023). Center: Summer wet season (January 2023). Right: El Niño event (December 2015).

Dataset Comparison (ERA5-Land vs TerraClimate)

Side-by-side comparison of ERA5-Land and TerraClimate effective precipitation with difference map.

Left: Scatter plot comparison with R², RMSE, and bias statistics. Right: Annual totals comparison.

Zonal statistics comparison between ERA5-Land and TerraClimate for Eastern and Western Rio de la Plata regions.

Anomaly, Climatology & Trend Maps

Left: Percent anomaly (January 2023). Center: January climatology (2000-2020). Right: Long-term trend with significance stippling (p < 0.05).

Trend analysis panel showing slope (mm/year) and p-value maps side by side.

Method Comparison

Comparison of all 8 effective precipitation methods: CROPWAT, FAO/AGLW, Fixed Percentage (70%), Dependable Rainfall (80%), FarmWest, USDA-SCS, TAGEM-SuET, and Ensemble.

Theoretical response curves for different effective precipitation methods.

---

Arizona USDA-SCS Example Outputs

The Arizona workflow (Examples/arizona_example.py) demonstrates U.S.-specific datasets with the USDA-SCS method:

Time Series & Climatology

GridMET USDA-SCS effective precipitation for Arizona: time series (left) and monthly climatology (right).

Anomaly, Climatology & Trend Maps

Left: August 2023 anomaly (monsoon season). Center: August climatology (monsoon peak). Right: Long-term trend with significance stippling.

Trend analysis panel for Arizona showing slope and p-value maps.

U.S. vs Global Dataset Comparison

Comparison of U.S. datasets (GridMET, PRISM) vs Global datasets (ERA5-Land, TerraClimate) for Arizona.

---

New Mexico 8-Method Comparison Example Outputs

The New Mexico workflow (Examples/new_mexico_example.py) compares all 8 effective precipitation methods using PRISM data:

Mean Annual Comparison (1986-2025)

Mean annual effective precipitation (1986-2025) for all 8 methods: CROPWAT, FAO/AGLW, Fixed 70%, Dependable Rainfall, FarmWest, USDA-SCS, TAGEM-SuET, and Ensemble.

Method Curves

Theoretical response curves for all 8 effective precipitation methods using New Mexico typical values (AWC=120mm/m, ETo=200mm/month).

For more examples and detailed API usage, see the Examples documentation.

Google Earth Engine Authentication

Before using pyCropWat, authenticate with Google Earth Engine:

earthengine authenticate

Or in Python:

import ee
ee.Authenticate()
ee.Initialize(project='your-project-id')

Citation

If you use pyCropWat in your research, please cite:

@software{pycropwat,
  author = {Majumdar, Sayantan and ReVelle, Peter and Pearson, Christopher and Nozari, Soheil and Huntington, Justin L. and Smith, Ryan G.},
  title = {pyCropWat: A Python Package for Computing Effective Precipitation Using Google Earth Engine Climate Data},
  year = {2026},
  url = {https://github.com/montimaj/pyCropWat},
  doi = {10.5281/zenodo.18201620}
}

Effective Precipitation Method References

• Muratoglu, A., Bilgen, G. K., Angin, I., & Kodal, S. (2023). Performance analyses of effective rainfall estimation methods for accurate quantification of agricultural water footprint. Water Research, 238, 120011. https://doi.org/10.1016/j.watres.2023.120011

• Smith, M. (1992). CROPWAT: A computer program for irrigation planning and management (FAO Irrigation and Drainage Paper No. 46). Food and Agriculture Organization of the United Nations. https://www.fao.org/sustainable-development-goals-helpdesk/champion/article-detail/cropwat/en

Funding

This work was supported by a U.S. Army Corps of Engineers grant (W912HZ25C0016) for the project "Improved Characterization of Groundwater Resources in Transboundary Watersheds using Satellite Data and Integrated Models."

Principal Investigator: Dr. Ryan Smith (Colorado State University)

Co-Principal Investigators:

• Dr. Ryan Bailey (Colorado State University)
• Dr. Justin Huntington (Desert Research Institute)
• Dr. Sayantan Majumdar (Desert Research Institute)
• Mr. Peter ReVelle (Desert Research Institute)

Research Scientist:

• Dr. Soheil Nozari (Colorado State University)

Roadmap

The following features have been implemented or are under consideration for future releases:

✅ Implemented (v1.0.x)

📊 Temporal Aggregation

• ✅ Seasonal summaries (DJF, MAM, JJA, SON)
• ✅ Annual totals with statistics
• ✅ Growing season aggregations based on crop calendars
• ✅ Custom date range aggregations

📈 Statistical Analysis

• ✅ Long-term climatology (e.g., 30-year normals)
• ✅ Anomaly detection (absolute, percent, standardized)
• ✅ Trend analysis using linear regression or Theil-Sen/Mann-Kendall
• ✅ Zonal statistics for polygons

🔄 Additional Effective Precipitation Methods

• ✅ FAO/AGLW method
• ✅ Fixed percentage method (configurable percentage)
• ✅ Dependable rainfall (FAO method at different probability levels)

📤 Enhanced Export Options

• ✅ NetCDF output for time-series analysis
• ✅ Cloud-Optimized GeoTIFFs (COGs)
• ✅ Zonal statistics CSV export by polygon

📉 Visualization

• ✅ Built-in plotting functions for time series
• ✅ Monthly climatology bar charts
• ✅ Raster map visualization
• ✅ Interactive maps (folium/leafmap integration)
• ✅ Comparison plots between datasets (side-by-side, scatter, annual)

🚧 Planned for Future Releases

🌾 Crop Water Requirements

• Crop coefficient (Kc) integration for different crop types/stages
• Net irrigation requirement (ETc - Peff) calculations
• Crop calendar support for region-specific growing seasons

📈 Advanced Analysis

• Drought indices (SPI, SPEI) integration
• Direct cloud storage export (GCS, S3)

✅ Validation Tools

• Station data comparison module
• Cross-dataset validation (e.g., ERA5 vs TerraClimate)
• Uncertainty quantification

💧 Water Balance Extension

• Evapotranspiration integration (from MODIS, SSEBop, OpenET)
• Simple water balance (P - ET - Runoff)

Have a feature request? Please submit your ideas via GitHub Issues. We welcome community contributions and feedback!

License

This project is licensed under the MIT License - see the LICENSE file for details.