Skip to content

Water Stress

The /water_stress API call implements comprehensive hydrological analysis for agricultural monitoring and water resource management. It provides four key water indicators calculated using satellite data and climatological analysis, culminating in a composite Water Stress Index that quantifies water availability and stress conditions.

Key Datasets

The water stress analysis leverages the following satellite datasets:

  1. CHIRPS Precipitation: UCSB-CHG/CHIRPS/PENTAD
  2. Resolution: ~5km
  3. Temporal Coverage: 1981-present
  4. Accuracy: ±5mm/day

  5. Usage: Current period precipitation sum for ratio calculation

  6. MODIS Evapotranspiration: MODIS Terra/Aqua (MOD16A2/MYD16A2)

  7. Resolution: 500m
  8. Temporal Coverage: 2000-present
  9. Accuracy: ±15%

  10. Usage: Current and climatological potential evapotranspiration (PET) and actual evapotranspiration (ET)

  11. SMAP Soil Moisture: NASA/SMAP/SPL3SMP_E

  12. Resolution: 9km
  13. Temporal Coverage: 2015-present
  14. Accuracy: ±0.04 m³/m³
  15. Usage: Current and climatological soil moisture for percentile calculation

Water Metrics

1. Precipitation/PET Ratio

Purpose: Measures the balance between water input (precipitation) and atmospheric demand (potential evapotranspiration).

Calculation: 

precipitation_pet_ratio = precipitation_sum / pet_sum

Data Processing:

  • Precipitation: Sum of CHIRPS pentad data for the monitoring period
  • PET: Sum of MODIS PET data for the monitoring period (converted to mm/day)
  • Clamping: Values clamped to [0.1, 10.0] range for stability

Interpretation:

  • > 1.0: More precipitation than PET (wet conditions)
  • < 1.0: Less precipitation than PET (dry conditions)
  • = 1.0: Balanced conditions

2. Soil Moisture Percentile

Purpose: Evaluates current soil moisture conditions relative to historical climatology.

Calculation: 

z_score = (current_soil_moisture - climatology_mean) / climatology_std
soil_moisture_percentile = ((z_score * 0.5) + 0.5) * 100

Data Processing:

  • Current: Mean SMAP soil moisture for monitoring period
  • Climatology: 5-year historical period (2015-2020 or 5 years before current period)
  • Statistical Analysis: Z-score calculation against climatological mean and standard deviation
  • Percentile Conversion: Normal distribution assumption for percentile calculation
  • Range Clamping: Values clamped to [0, 100] range

Interpretation:

  • 0-20%: Extremely dry conditions
  • 20-40%: Below normal moisture
  • 40-60%: Normal moisture conditions
  • 60-80%: Above normal moisture
  • 80-100%: Extremely wet conditions

3. Evapotranspiration Anomaly

Purpose: Measures deviation of current vegetation water use from historical norms.

Calculation: 

et_anomaly = (current_et - climatology_mean) / climatology_std

Data Processing:

  • Current: Mean MODIS ET for monitoring period (converted to mm/day)
  • Climatology: 5-year historical period with mean and standard deviation
  • Standardized Anomaly: Z-score calculation
  • Range Clamping: Values clamped to [-3, 3] standard deviations

Interpretation:

  • Negative values: Below normal evapotranspiration (reduced vegetation activity)
  • Positive values: Above normal evapotranspiration (increased vegetation activity)
  • Magnitude: Indicates severity of deviation from normal conditions

4. Water Stress Index (Composite)

Purpose: Integrated measure of water stress combining all hydrological indicators.

Calculation: 

water_stress_index = (0.4 × precip_stress) + (0.4 × moisture_stress) + (0.2 × et_stress)

Weighting Strategy:

  • Precipitation/PET Ratio: 40% (primary water input indicator)
  • Soil Moisture Percentile: 40% (ground water availability indicator)
  • Evapotranspiration Anomaly: 20% (vegetation response indicator)

Normalization:

  • All components normalized to [0, 1] range
  • Weights sum to 100% (0.4 + 0.4 + 0.2 = 1.0)
  • Final result clamped to [0, 1] range

Interpretation:

  • 0.0-0.3: Low water stress (good conditions)
  • 0.3-0.6: Moderate water stress
  • 0.6-1.0: High water stress (poor conditions)

Key Considerations

See below a list of key considerations to keep in mind when using the /water_stress endpoint:

  1. Climatology Period: The system uses a 5-year climatology period ending 1 year before the current monitoring period. For periods before 2015, it uses a 1-year climatology to ensure data availability.

  2. Data Quality: The results are as consistent as the input data quality. CHIRPS precipitation data has ±5mm/day accuracy, MODIS ET has ±15% accuracy, and SMAP soil moisture has ±0.04 m³/m³ accuracy.

  3. Spatial Resolution: The final water stress index combines data from different resolutions (5km precipitation, 500m ET, 9km soil moisture), which may affect local-scale accuracy.

  4. Temporal Coverage: SMAP soil moisture data is only available from 2015 onwards, which limits historical analysis capabilities.

  5. Masking: The system automatically excludes water bodies and built-up areas from analysis to focus on agricultural and natural landscapes.

  6. Performance Optimization: The system uses combined reducers and fixed climatology periods to optimize Earth Engine operations and improve processing speed.

Parameters and Headers

Required Parameters

  • filename (string): The filename/collection identifier for the plot data
  • date (string): End date for the monitoring period (YYYY-MM-DD format)

Optional Parameters

  • start_date (string): Start date for the monitoring period (YYYY-MM-DD format). Defaults to 1 year before the end date.
  • overlap_threshold (float): Overlap threshold for plot deduplication (0.0-1.0). Default: 0.5
  • stat_type (string): Statistical region type for aggregation. Default: "admin_area"

Headers

  • Authorization: Bearer token for authentication
  • Content-Type: application/json

API Response

The /water_stress endpoint returns a JSON response containing:

{
  "uuid": "unique-identifier",
  "precipitation_pet_ratio": 1.25,
  "soil_moisture_percentile": 65.4,
  "evapotranspiration_anomaly": 0.8,
  "water_stress_index": 0.35,
  "thumbnail_url": "https://storage.googleapis.com/bucket/water_metrics_thumbnail.png",
  "monitoring_start": "2023-01-01",
  "monitoring_end": "2023-12-31",
  "ingestion_date": "2024-01-15T10:30:00Z"
}

Response Fields

  • precipitation_pet_ratio: Ratio of precipitation to potential evapotranspiration
  • soil_moisture_percentile: Soil moisture percentile (0-100)
  • evapotranspiration_anomaly: Standardized ET anomaly (-3 to +3)
  • water_stress_index: Composite water stress index (0-1)
  • thumbnail_url: URL to visualization thumbnail
  • monitoring_start/end: Date range for the analysis period
  • ingestion_date: Timestamp when the analysis was performed

Use Cases

Agricultural Monitoring

  • Drought Detection: Low soil moisture percentiles and high water stress index indicate drought conditions
  • Irrigation Planning: ET anomalies help optimize irrigation schedules and water allocation
  • Crop Yield Prediction: Water stress indicators correlate with yield potential and crop health

Climate Analysis

  • Trend Analysis: Long-term changes in water availability patterns and climate impacts
  • Extreme Event Detection: Identification of unusual hydrological conditions and climate anomalies
  • Climate Change Impact: Assessment of changing water patterns over time

Water Resource Management

  • Reservoir Management: ET anomalies inform water release decisions and storage planning
  • Groundwater Monitoring: Soil moisture trends indicate recharge patterns and aquifer health
  • Flood Risk Assessment: High precipitation/PET ratios indicate flood potential and water surplus