pycropwat 1.2.1
A Python Package for Computing Effective Precipitation Using Google Earth Engine Climate Data
License: MIT
Requires Python: >=3.9
Keywords: earth-engine, precipitation, hydrology, cropwat, effective-precipitation, remote-sensing

# pyCropWat

[![Release](https://img.shields.io/badge/release-v1.2.1-green.svg)](https://github.com/montimaj/pyCropWat/releases)
[![PyPI](https://img.shields.io/pypi/v/pycropwat.svg)](https://pypi.org/project/pycropwat/)
[![Downloads](https://static.pepy.tech/badge/pycropwat/month)](https://pepy.tech/project/pycropwat)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18201619.svg)](https://doi.org/10.5281/zenodo.18201619)
[![GitHub stars](https://img.shields.io/github/stars/montimaj/pyCropWat)](https://github.com/montimaj/pyCropWat/stargazers)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://montimaj.github.io/pyCropWat)
[![GEE](https://img.shields.io/badge/Google%20Earth%20Engine-4285F4?logo=google-earth&logoColor=white)](https://earthengine.google.com/)

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

<p align="center">
  <picture>
    <source srcset="https://raw.githubusercontent.com/montimaj/pyCropWat/main/docs/assets/pyCropWat.gif" type="image/gif">
    <img src="https://raw.githubusercontent.com/montimaj/pyCropWat/main/docs/assets/pyCropWat.png" alt="pyCropWat Logo">
  </picture>
</p>

## 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](#complete-workflow-examples) section below for details.

**Changelog:** See [CHANGELOG.md](https://github.com/montimaj/pyCropWat/blob/main/CHANGELOG.md) for release notes and version history.

## Overview

<table>
<tr>
<td>

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](https://developers.google.com/earth-engine/datasets) or [Community Catalog](https://gee-community-catalog.org/)
- 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

</td>
<td width="200">
<img src="https://raw.githubusercontent.com/montimaj/pyCropWat/main/docs/assets/pyCropWat_logo.png" alt="pyCropWat Logo" width="200">
</td>
</tr>
</table>

### 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](https://farmwest.com/climate/calculator-information/et/effective-precipitation/) 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](https://farmwest.com/climate/calculator-information/et/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.):**
```bash
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):**
```bash
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.](https://www.wcc.nrcs.usda.gov/ftpref/wntsc/waterMgt/irrigation/NEH15/ch2.pdf)

### 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.](https://doi.org/10.1016/j.watres.2023.120011)

**CLI Example:**
```bash
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
```

### PCML (Physics-Constrained Machine Learning)

The PCML method uses pre-computed effective precipitation from a physics-constrained machine learning model trained specifically for the Western United States. Unlike other methods, PCML Peff is retrieved directly from a GEE asset.

**Coverage:**
- **Region**: Western U.S. (17 states: AZ, CA, CO, ID, KS, MT, NE, NV, NM, ND, OK, OR, SD, TX, UT, WA, WY)
- **Temporal**: January 2000 - September 2024 (monthly)
- **Resolution**: ~2 km (native scale retrieved dynamically from GEE asset)
- **GEE Asset**: `projects/ee-peff-westus-unmasked/assets/effective_precip_monthly_unmasked`
- **Band Format**: `bYYYY_M` (e.g., `b2015_9` for September 2015, `b2016_10` for October 2016)

> 📝 **Note:** PCML provides pre-computed Peff values from a trained ML model. When using `--method pcml`, the default PCML asset is automatically used and bands are dynamically selected based on the year/month being processed. The native scale (~2km) is retrieved from the asset using GEE's `nominalScale()` function. **Only annual (water year, Oct-Sep)** effective precipitation fractions are available for PCML, loaded directly from a separate GEE asset (`projects/ee-peff-westus-unmasked/assets/effective_precip_fraction_unmasked`, WY 2000-2024, band format: `bYYYY`).

> 💡 **PCML Geometry Options:**
> - **No geometry provided**: Downloads the entire PCML asset (full Western U.S. - 17 states)
> - **User provides geometry**: PCML data is clipped/subsetted to that geometry. **Note:** Only Western U.S. vectors that overlap with the 17-state extent can be used (e.g., AZ.geojson, pacific_northwest.geojson)

**Reference:** [Hasan, M. F., Smith, R. G., Majumdar, S., Huntington, J. L., Alves Meira Neto, A., & Minor, B. A. (2025). Satellite data and physics-constrained machine learning for estimating effective precipitation in the Western United States and application for monitoring groundwater irrigation. *Agricultural Water Management*, 319, 109821.](https://doi.org/10.1016/j.agwat.2025.109821)

**CLI Example (full Western U.S.):**
```bash
pycropwat process \
    --method pcml \
    --start-year 2000 --end-year 2024 \
    --output ./WesternUS_PCML
```

**CLI Example (subset to specific region):**
```bash
pycropwat process \
    --method pcml \
    --geometry pacific_northwest.geojson \
    --start-year 2000 --end-year 2024 \
    --output ./PacificNW_PCML
```

### Ensemble - Default (Mean of Methods)

The ensemble method provides a robust estimate by calculating the mean of all methods except TAGEM-SuET and PCML. 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:**
```bash
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 |
| **PCML** | Western U.S. applications | ML-based, pre-computed (2000-2024) |
| **Ensemble** | Robust multi-method estimate | Mean of 6 methods (excludes TAGEM-SuET and PCML) |

## Installation

### Quick Install (PyPI)

```bash
pip install pycropwat
```

Or with optional interactive map support:

```bash
pip install pycropwat[interactive]
```

### Disk Space Requirements

| Component | Size | Notes |
|-----------|------|-------|
| Repository (tracked files) | ~50 MB | Core package, documentation, examples, 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 | ~8 GB | PRISM 8-method outputs (1986-2025) |
| Examples/WesternUS_PCML | ~3 GB | PCML effective precipitation outputs |
| Examples/UCRB | ~3 MB | Field-scale analysis outputs |

**Note:** Large generated data files are excluded from the repository via `.gitignore`. 
Run the example scripts to generate them locally:
```bash
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
python Examples/western_us_pcml_example.py --gee-project your-project-id
python Examples/ucrb_example.py --gee-project your-project-id
```

> ⚠️ **UCRB GeoPackage:** The `ucrb_field_effective_precip_intercomparison_geopackage.gpkg` file (~7 GB) is not included in the repository. Contact the authors if you need access to this dataset.

### Using Conda (Recommended for Development)


```bash
# 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)

```bash
# 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

```python
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

```python
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

```python
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:

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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](https://montimaj.github.io/pyCropWat/user-guide/cli/).

## 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)

> **Note:** For the PCML method, fraction files are annual (water year): `effective_precip_fraction_YYYY.tif` (one per year, WY 2000-2024).

### 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](https://github.com/montimaj/pyCropWat/blob/main/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

```bash
# 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

```bash
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

```bash
# Process with GridMET precipitation using USDA-SCS method
pycropwat process --asset IDAHO_EPSCOR/GRIDMET --band pr \
    --gee-geometry users/mont