Suggested example workflow for user guide

[Rwema25]

Example End-to-End Workflow for the Climate Toolkit

This is a simple “story” a new user can follow to understand the toolkit’s capabilities.

Prerequisites

Before starting, ensure you have:

1. Python Installed: Make sure you have Python installed on your system.

2. Google Earth Engine setup (required for all climate data):

   • Create a free account at earthengine.google.com
   • Install the earthengine-api Python package
   • Authenticate: earthengine authenticate
   • Note your Google Cloud Project ID (used for some operations)

3. Installation:

   pip install -e .

   This installs all CLI commands (prefixed with climate-toolkit-*)

4. Input data: You'll need location coordinates (latitude, longitude). Crop name and date ranges come later.

---

Step 1: Choose a Climate Data Source & Fetch Raw Data

Start by getting climate data for your location.

Command:

climate-toolkit-fetch \
  --source agera_5 \
  --location -1.286,36.817 \
  --start 2020-01-01 \
  --end 2020-12-31 \
  --variables precipitation,max_temperature,min_temperature \
  --output outputs/climate_data.csv

Breakdown of Command Arguments:

• climate-toolkit-fetch: The entry point function.
• --source agera_5: The source of data you want to download.
• --location -1.286,36.817: The coordinates (latitude, longitude) of the location for which you want the data.
• --start 2020-01-01: The start date of the period for which you want to download data (in
  YYYY-MM-DD format).
• --end 2020-12-31: The end date of the period for which you want to download data (in
  YYYY-MM-DD format).
• --variables precipitation,max_temperature,min_temperature: The variable you are interested in. Here, it's precipitation,max_temperature,min_temperature.
  from the agera5 dataset.
• --output outputs/climate_data.csv: The output data format you are interested in. Here, it's CSV.

What happens:

• Downloads historical or observational climate data (e.g., AgERA5, ERA5, CHIRPS) from Google Earth Engine for your location
• Automatically transforms variable names to canonical forms (e.g., source-specific names → precipitation, max_temperature)
• Preprocesses data: standardizes units (mm for rainfall, °C for temperature), fills gaps, applies quality checks
• Returns a clean CSV with daily climate records ready for analysis

Data source options (with coverage):

• AgERA5: 1979–present (recommended for Africa; includes humidity)
• ERA5: 1979–present (global reanalysis; cooler than observations)
• CHIRPS: 1981–present (precipitation-only, satellite-based)
• NASA POWER: 1984–present (coarse resolution; good for remote areas)
• NEX-GDDP: 2006–2100 (climate projections; requires --model and --scenario)

Common pitfall: CHIRPS v2 (discontinued 2016) and TAMSAT can be fragile. Use CHIRPS v3 or AgERA5 for reliability.

---

Step 2: Validate Your Data Against Weather Stations (Optional but Recommended)

Before using gridded data, compare it to real weather station observations.

Step 2a: Discover nearby stations

climate-toolkit-weather-station-download \
  --station-source auto \
  --selection-mode list \
  --station-lat -1.286 \
  --station-lon 36.817 \
  --start 2020-01-01 \
  --end 2020-12-31 \
  --variables precipitation,max_temperature,min_temperature \
  --max-distance-km 100 \
  --report-prefix outputs/weather_station/nearby_candidates \
  --open-report

What happens:

• Searches for NOAA GSOD (Global Surface Observatories) weather stations within 100 km
• Ranks candidates by data coverage and elevation match
• Generates an interactive HTML report showing available stations and their data quality
• Selects the best station(s) automatically or lets you choose manually

Step 2b: Compare gridded vs. station data

climate-toolkit-weather-station-compare \
  --grid-source agera_5 \
  --station-source gsod \
  --station-id 637420 \
  --location -1.286,36.817 \
  --start 2020-01-01 \
  --end 2020-12-31 \
  --output outputs/grid_vs_station_validation.json

What you get:

• Monthly or annual correlation between gridded and station data
• Bias analysis: e.g., "AgERA5 is 15% drier than this station"
• Helps you decide: trust the grid data as-is, or use station override?

When to trust which data:

• Gridded: Good for regional patterns; lacks local variations (microclimates, urban heat)
• Stations: More accurate locally; may have gaps or instrument biases

---

Step 3: Understand Local Climate Patterns (Climatology)

Compute the "normal" climate at your location—the 30-year reference period used in climate analysis.

Command:

climate-toolkit-climatology \
  --location -1.286,36.817 \
  --source agera_5 \
  --start-year 1991 \
  --end-year 2020 \
  --output outputs/climatology_1991_2020.csv

What you get:

• Monthly averages of precipitation, temperature, ET0 (evapotranspiration), etc.
• Seasonal breakdown: Which months are rainy? Dry? Hot?
• Used as a baseline for comparing "normal" vs. "unusual" years

---

Step 4: Detect Rainy Seasons (Season Analysis)

Identify when rainy seasons start and end in your location—critical for crop planning.

Command (auto-detect):

climate-toolkit-seasons \
  --location -1.286,36.817 \
  --source agera_5 \
  --start-year 2015 \
  --end-year 2020 \
  --output outputs/season_summary.json

What happens:

• Uses a water balance algorithm (Hargreaves evapotranspiration) to find when the soil is wet enough for crops
• Outputs for each year: onset date, cessation date, season length, rainfall intensity
• Example output:

  2020: Onset=Mar-15, End=Oct-10, Length=209 days, Total_Rain=800mm
  

What if season detection fails?

• In extremely wet areas (rainforest) or very erratic climates, automatic detection can be unreliable
• Workaround: Use fixed seasons instead (see Step 5)

---

Step 5: Compute Climate Statistics by Season (Statistics Module)

Now compute detailed statistics for each rainy season—the core analysis step.

Command (auto-detected seasons):

climate-toolkit-stats \
  --location "-1.286,36.817" \
  --start-year 2015 \
  --end-year 2020 \
  --source paired \
  --precip-source chirps_v3_daily_rnl \
  --temp-source agera_5 \
  --output outputs/climate_stats_2015_2020.json

Command (fixed seasons, e.g., March–May and October–December):

climate-toolkit-stats \
  --location "-1.286,36.817" \
  --start-year 2015 \
  --end-year 2020 \
  --source paired \
  --precip-source chirps_v3_daily_rnl \
  --temp-source agera_5 \
  --fixed-season "03-01:05-31,10-01:12-31" \
  --output outputs/climate_stats_fixed_seasons.json

What you get:
Per-season statistics including:

• Total seasonal rainfall
• Average & extreme temperatures
• Water balance indicators: NDWS (water stress days), NDWL0 (waterlogging days)
• Human/livestock heat stress indices (Humidex, THI)
• SPEI (drought index) if requested

Choose auto-detect or fixed-season:

• Auto-detect: Adapts to year-to-year variations; use when seasons are regular
• Fixed-season: Same calendar months every year; use when seasons are erratic or for cross-year consistency

---

Step 6: Compare Different Periods (Period Comparison)

See how climate changed between a baseline period and a focal year.

Command:

climate-toolkit-periods \
  --location "-1.286,36.817" \
  --baseline-start-year 2001 \
  --baseline-end-year 2015 \
  --focal-year 2020 \
  --source paired \
  --precip-source chirps_v3_daily_rnl \
  --temp-source agera_5 \
  --output outputs/2020_vs_2001_2015_baseline.json

What you get:

• Side-by-side comparison: Baseline average vs. focal year
• Diffs and percent changes in rainfall, temperature, etc.
• Example: "2020 was 12% drier than the 2001–2015 average"

Use case: Assessing whether a particular year was unusually dry/wet, hot/cool.

---

Step 7: Assess Crop Hazards (Hazard Calculation)

Link climate to specific crop impacts—the final analysis step.

Command:

climate-toolkit-hazards \
  --crop-name Maize \
  --location -1.286,36.817 \
  --start-date 2020-01-01 \
  --end-date 2020-12-31 \
  --source paired \
  --precip-source chirps_v3_daily_rnl \
  --temp-source agera_5 \
  --output outputs/maize_hazards_2020.json

What you get:
Hazard indicators including:

• NDWS (Number of Days Water Stress): Days when crop gets <50% available water
• NDWL0 (Number of Days Waterlogging): Days when soil is oversaturated
• Temperature thresholds: Days >35°C, >40°C (damaging to heat-sensitive crops)
• NDD (Normalized Degree Days): Cumulative heat, normalized to crop requirements
• WRSI (Water Requirement Satisfaction Index): Seasonal water availability as a percentage

Supported crops: Maize, Beans, Sorghum, Millet, Groundnuts, Cassava, Rice

Interpreting results:

• High NDWS → crop likely stressed; yield loss risk
• High NDWL0 → waterlogging damage risk (disease)
• High NTx40 → extreme heat; pollination failures likely

---

Step 8: Compare Projections (Ensemble Workflows)

Use future climate projections (2021–2100) to assess long-term trends.

Command (NEX-GDDP projected hazards):

climate-toolkit-hazards-ensemble \
  --crop-name Maize \
  --location -1.286,36.817 \
  --source nex_gddp \
  --model MPI-ESM1-2-LR \
  --scenario ssp245 \
  --start-year 2050 \
  --end-year 2060 \
  --output outputs/maize_hazards_2050_2060_ensemble.json

What you get:

• Hazards under climate change scenarios
• Compare baseline (1991–2020) vs. future (2050–2060, 2080–2100)
• Assess crop viability in future climate

Available projections:

• Models: MPI-ESM1-2-LR, GFDL-ESM4, TaiESM1, FGOALS-g3, CMCC-CM2-SR5 (10+ total)
• Scenarios: SSP1-2.6, SSP2-4.5, SSP5-8.5 (low, medium, high emissions)

---

Complete Workflow Example: Maize Suitability in Nairobi

# 1. Fetch climate data
climate-toolkit-fetch \
  --source agera_5 \
  --location -1.286,36.817 \
  --start 2015-01-01 --end 2020-12-31

# 2. Validate against nearby weather stations (optional)
climate-toolkit-weather-station-download \
  --station-source auto --selection-mode list \
  --station-lat -1.286 --station-lon 36.817 \
  --start 2015-01-01 --end 2020-12-31 \
  --report-prefix outputs/nairobi_stations

# 3. Compute climatology baseline
climate-toolkit-climatology \
  --location -1.286,36.817 --source agera_5 \
  --start-year 1991 --end-year 2020

# 4. Detect historical rainy seasons
climate-toolkit-seasons \
  --location -1.286,36.817 --source agera_5 \
  --start-year 2015 --end-year 2020

# 5. Compute climate statistics
climate-toolkit-stats \
  --location -1.286,36.817 \
  --start-year 2015 --end-year 2020 \
  --source paired --precip-source chirps_v3_daily_rnl --temp-source agera_5

# 6. Compare 2020 to baseline
climate-toolkit-periods \
  --location -1.286,36.817 \
  --baseline-start-year 2001 --baseline-end-year 2015 --focal-year 2020 \
  --source paired --precip-source chirps_v3_daily_rnl --temp-source agera_5

# 7. Assess maize hazards in 2020
climate-toolkit-hazards \
  --crop-name Maize \
  --location -1.286,36.817 \
  --start-date 2020-01-01 --end-date 2020-12-31 \
  --source paired --precip-source chirps_v3_daily_rnl --temp-source agera_5

# 8. Project maize hazards to 2050
climate-toolkit-hazards-ensemble \
  --crop-name Maize \
  --location -1.286,36.817 \
  --source nex_gddp --model MPI-ESM1-2-LR --scenario ssp245 \
  --start-year 2050 --end-year 2060

Assumptions & Ambiguities Found in Codebase

1. Google Earth Engine project ID: Required for some operations but not always clear when. Suggestion: Make it always optional with sensible fallback or require upfront.

2. "Auto" source selection: Defaults to chirps_v3_daily_rnl (precip) + agera_5 (temperature). Not documented anywhere. Users find out by trial/error.

3. Custom station CSV format: Documentation missing. Users provide invalid CSVs and get cryptic FileNotFoundError. Solution: Add example CSV template to repo.

4. Fixed-season format ambiguity: Two formats exist ("MM-DD:MM-DD" vs. comma-separated). Not clear which CLI accepts which. Needs standardization.

5. TAMSAT reliability: Code comments warn it's "fragile," but it's still selectable. Should probably be marked deprecated or removed from default recommendations.

6. CHIRPS v2 vs. v3: Confusing naming. v2 is chirps_v2, v3 is chirps_v3_daily_rnl. Old v2 ended 2016.

7. Ensemble functions not in main __init__.py: Ensemble statistics, periods, hazards are CLI-only, not exposed in public Python API. Users assuming they can from climate_tookit import analyze_climate_statistics_ensemble will fail. Either expose them or clearly document CLI-only.

8. Cache directory behavior: Assumed to live in outputs/cache/... but default is undocumented. Users don't know cache is reused or where to clear it.

[Sammyjoseph999]

Added in #104 as docs/example_workflow.md — an 8-step new-user walkthrough (fetch -> validate -> climatology -> seasons -> stats -> periods -> hazards -> NEX-GDDP ensemble) plus a complete Nairobi/Maize example, linked from the README. Commands were corrected to the actual CLI flags (e.g. fetch --lat/--lon; hazards positional crop with --date-from/--date-to; periods --baseline-start/--baseline-end; hazards-ensemble --models/--scenarios/--model-workers) so they run as written. The GEE project-id / install / source-naming ambiguities from the issue are folded into the guide's notes.