Jira progress: loading…

WTR-STRS

Water Stress Allocation & Exposure

1. Identity

Loading identity…

Depends on module:

Purpose
Allocates water quantities (withdrawal and/or consumption) to water stress areas (basins/regions) and produces:

• by-area absolute allocations, and
• stress-weighted exposure metrics suitable for risk dashboards and ESRS E3 context.

This engine does not “invent” stress. It applies a versioned stress dataset (e.g., WRI Aqueduct / basin stress index) to water volumes with known geography.

Typical usage

• Withdrawal by stress area (m³)
• Stress-weighted withdrawal/consumption (m³·index)
• Exposure index (unitless) for comparability and trend

---

2. Contract References (ZAR)

2.1 Input Schema

ZAR Address: schema.compute.water.stress.inputs.v1_0_0

Required conceptual fields:

• mode: WITHDRAWAL | CONSUMPTION | BOTH (default WITHDRAWAL)
• alignment: BY_YEAR | BY_INDEX (default BY_YEAR)
• stress_dataset_ref: reference to a registered stress dataset artifact (versioned)
• site_allocations: list of water volumes with geographic identifiers

Each site_allocation conceptually includes:

• period
• site_id
• value
• unit (e.g., m3)
• one geographic key (preferred order):
  • basin_id (preferred)
  • h3_cell / geo_hash
  • lat + lon
  • admin_region_code
• optional:
  • water_type: WITHDRAWAL | CONSUMPTION (if mode=BOTH)
  • source (surface/ground/etc.)
  • confidence (0–1)
  • is_estimate

Input is typically produced upstream by allocating facility water totals to sites (often from MEID_CALC_WATER_AGGR/MEID_CALC_WATER_CONS + facility mapping).

---

2.2 Options Schema

ZAR Address: schema.compute.water.stress.options.v1_0_0

Common options:

• unit_output: default m3
• stress_metric: BASELINE_WATER_STRESS | WATER_DEPLETION | SEASONAL_VARIABILITY (default BASELINE_WATER_STRESS)
• stress_scale: 0_1 | 0_5 | 0_100 (default 0_1)
• missing_geo_policy: ERROR | DROP | ASSIGN_UNKNOWN (default ERROR)
• missing_stress_policy: ERROR | IMPUTE_MEDIAN | ASSIGN_UNKNOWN (default ERROR)
• unknown_bucket_name: default "unknown_area"
• weighting: LINEAR | EXPONENTIAL (default LINEAR)
• rounding: optional digits

---

2.3 Output Schema

ZAR Address: schema.compute.water.stress.output.v1_0_0

Outputs include:

• by_area_abs: map (area_id → series)
• stress_weighted_abs: series
• exposure_index: series
• metadata (dataset version/hash, missing geo counts, imputation flags, scale)

---

3. Accepted Input Shapes

A. Withdrawal allocations with basin IDs (best)

{
  "mode": "WITHDRAWAL",
  "stress_dataset_ref": "DATASET.WATER_STRESS.AQUEDUCT.v1",
  "site_allocations": [
    { "site_id": "PLANT-01", "basin_id": "BASIN-123", "period": 2025, "value": 80000, "unit": "m3" },
    { "site_id": "PLANT-02", "basin_id": "BASIN-777", "period": 2025, "value": 45000, "unit": "m3" }
  ]
}

B. Lat/Lon allocations

{
  "mode": "CONSUMPTION",
  "stress_dataset_ref": "DATASET.WATER_STRESS.AQUEDUCT.v1",
  "site_allocations": [
    { "site_id": "PLANT-01", "lat": 59.91, "lon": 10.75, "period": 2025, "value": 12000, "unit": "m3" }
  ],
  "missing_geo_policy": "ERROR"
}

C. BOTH mode with mixed types

{
  "mode": "BOTH",
  "stress_dataset_ref": "DATASET.WATER_STRESS.AQUEDUCT.v1",
  "site_allocations": [
    { "water_type": "WITHDRAWAL", "site_id": "PLANT-01", "basin_id": "BASIN-123", "period": 2025, "value": 80000, "unit": "m3" },
    { "water_type": "CONSUMPTION", "site_id": "PLANT-01", "basin_id": "BASIN-123", "period": 2025, "value": 12000, "unit": "m3" }
  ]
}

All supported shapes MUST be normalized internally to:

Map<period, Map<area_id, volume_m3>> (+ optional water_type dimension)

---

4. Stress Dataset Resolution (Normative)

The stress_dataset_ref MUST resolve to a versioned artifact that supports queries:

• lookup(basin_id) -> stress_score
• or lookup(lat,lon) -> basin_id -> stress_score
• or lookup(admin_region_code) -> stress_score

The engine MUST record in metadata:

• dataset identifier + version
• dataset hash (if provided by ZAR)
• stress_metric used
• stress_scale used

---

5. Compute Semantics (Normative)

Let:

• $V(a,t)$ be volume allocated to area $a$ at period $t$ (after unit normalization)
• $S(a)$ be stress score for area $a$ after scaling to $[0,1]$ unless otherwise configured

5.1. Scaling stress score

If dataset provides $S_{raw}(a)$ in a different scale, map to $S(a)$:

• If stress_scale = 0-5 (Stress values in $[0, 5]$ (e.g. WRI Aqueduct Baseline Water Stress classes)):

$S(a) = \frac{S_{raw}(a)}{5}$

• If stress_scale = 0-100 (Stress values in $[0, 100]$ (percentage- or index-style datasets)):

$S(a) = \frac{S_{raw}(a)}{100}$

• If already 0-1: $S(a) = S_{raw}(a)$

---

5.2. Allocation by area (absolute)

For each area $a$ and period $t$:

$W_{\mathrm{by_area}}(a,t) = V(a,t)$

---

5.3. Stress-weighted absolute volume

If weighting = LINEAR:

$W_{\mathrm{stress_weighted}}(t) = \sum_{a} V(a,t)\cdot S(a)$

If weighting = EXPONENTIAL (v1 optional, more “risk sensitive”):

$W_{\mathrm{stress_weighted}}(t) = \sum_{a} V(a,t)\cdot S(a)^\gamma$

Where $\gamma > 1$ is a dataset/option parameter (default $\gamma=2$ if enabled).

---

5.4. Exposure index (unitless)

Define total volume:

$W_{\mathrm{total}}(t) = \sum_{a} V(a,t)$

Exposure index:

$I_{\mathrm{exposure}}(t)=\frac{W_{\mathrm{stress_weighted}}(t)}{\max(W_{\mathrm{total}}(t), \epsilon)}$

Where $\epsilon$ is a small constant to avoid division instability.

This yields a normalized exposure score in $[0,1]$ under linear weighting and bounded stress scores.

---

6. Missing Geo / Missing Stress Handling (Normative)

6.1. Missing geography

If a record lacks any usable geo key:

• ERROR: fail
• DROP: omit and record in metadata
• ASSIGN_UNKNOWN: map to unknown_bucket_name area

6.2. Missing stress score for an area

If $S(a)$ cannot be resolved:

• ERROR: fail
• IMPUTE_MEDIAN: set $S(a)$ to dataset median and record imputation
• ASSIGN_UNKNOWN: map to unknown_bucket_name with a configurable default stress (v1: discouraged)

Metadata MUST include:

• missing_geo_count
• missing_stress_count
• imputed_stress_count
• list/samples of affected site_ids (bounded)

---

7. Validation & Error Model

Invariants

• Values must be finite
• Units must be convertible to unit_output
• Stress dataset must resolve
• At least one geo identifier must be present per record under default policy
• Stress scores must be within expected scale after conversion (0..1) unless schema allows otherwise

Error codes (suggested)

• WATER_STRESS_DATASET_NOT_FOUND
• WATER_STRESS_GEO_MISSING
• WATER_STRESS_LOOKUP_FAILED
• WATER_STRESS_SCALE_INVALID
• WATER_STRESS_NON_FINITE_VALUE

Errors MUST include:

• engine cm`i_short_code
• site_id, period, and geo context

---

8. Dependencies

MEID_CALC_WATER_STRESS depends on:

• schema resolver (ZAR)
• unit conversion capability (delegated)
• stress dataset resolver (artifact referenced by stress_dataset_ref)
• optional geo-to-basin resolver (if lat/lon provided)

Declared via ZAR dependencies.

---

9. Federation & Audit Requirements

To reproduce stress allocation externally, the export MUST include:

• engine identity (cmi or zar_code)
• engine build proof (execution_ref + build_hash)
• input/options/output schemas used
• all site allocations with geo keys
• stress dataset artifact reference/version/hash
• stress metric, scaling, weighting settings
• missing-geo and missing-stress policies and any imputations performed

Provenance chain MUST show:

… → MEID_CALC_WATER_STRESS → …

with cmi_short_code recorded in USO tail arrays.

---

10. Performance Notes

• Complexity: $O(n_{alloc})$ plus stress lookups
• Memory: $O(|T| \times |A|)$
• Stress lookups should be cached by area_id for speed

---

11. Methods Served (v1)

• Water.withdrawal.by_stress_area.abs
• Water.withdrawal.stress_weighted.abs
• Water.consumption.by_stress_area.abs
• Water.consumption.stress_weighted.abs
• Water.stress.exposure_index

---