Jira progress: loading…

TRGT-GAP

Distance-to-Target / Gap Calculator Micro Engine

1. Identity

Loading identity…

Depends on module:

• Purpose: Computes distance-to-target (“gap”) between a current metric (actuals or baseline) and a target trajectory/value, returning gap values in absolute terms, percent terms, and optionally a compliance flag.

• Typical usage:

  • ESRS-aligned transition target tracking (E1)
  • KPI target monitoring (energy, water, waste)
  • Inputs to scenario alignment and risk scoring pipelines

Versioning policy

• MEID is stable.
• Target logic versions are governed via ZAR (engine CMI/version + execution_ref + build_hash).

---

2. Contract References (ZAR)

2.1. Input Schema

• ZAR Address: schema.compute.<domain>.target_gap.inputs.v1_0_0

Required conceptual fields

• current: scalar or time-series (actual/observed metric)
• target: scalar or time-series (target metric or target trajectory)
• gap_mode: ABS | PCT | BOTH (default BOTH)
• directionality: LOWER_IS_BETTER | HIGHER_IS_BETTER (default LOWER_IS_BETTER)
• alignment: BY_YEAR | BY_INDEX (default BY_YEAR)

Optional:

• baseline: scalar or time-series (for “% reduction from baseline” style targets)
• target_type: ABSOLUTE | REDUCTION_FROM_BASELINE | INTENSITY (default ABSOLUTE)

---

2.2. Options Schema

• ZAR Address: schema.compute.<domain>.target_gap.options.v1_0_0

Common options:

• pct_denominator_floor (default: 1e-9)
• tolerance_abs (default: 0)
• tolerance_pct (default: 0)
• missing_policy: ERROR | SKIP
• rounding: optional digits

---

2.3. Output Schema

• ZAR Address: schema.compute.<domain>.target_gap.output.v1_0_0

Outputs include:

• gap_abs_series (if ABS or BOTH)
• gap_pct_series (if PCT or BOTH)
• on_track_series (optional boolean per period)
• metadata (alignment, floors applied, tolerances used, directionality)

Note: <domain> is typically ghg, energy, water, waste. Semantics are identical; only namespaces differ.

---

3. Accepted Input Shapes

A. Scalar target gap (absolute + percent)

{
  "current": 12500,
  "target": 12000,
  "gap_mode": "BOTH",
  "directionality": "LOWER_IS_BETTER"
}

B. Time-series current vs target trajectory (preferred)

{
  "current": [[2025, 12500], [2026, 12000], [2027, 11000]],
  "target":  [[2025, 12300], [2026, 11800], [2027, 10800]],
  "gap_mode": "BOTH",
  "alignment": "BY_YEAR",
  "directionality": "LOWER_IS_BETTER"
}

C. Reduction-from-baseline targets

{
  "baseline": [[2020, 15000]],
  "current":  [[2025, 12500]],
  "target":   [[2025, 0.20]],
  "target_type": "REDUCTION_FROM_BASELINE",
  "directionality": "LOWER_IS_BETTER"
}

In example C, target is a reduction fraction (0.20 = 20% reduction) unless schema defines it as percent.

All inputs MUST be normalized internally to:

Map<period, current_value> + Map<period, target_value> (+ optional baseline).

---

4. Compute Semantics (Normative)

4.1. Alignment

For each aligned period t, obtain:

• $C(t)$ = current value
• $T(t)$ = target value

If target_type = REDUCTION_FROM_BASELINE:

• Let B be baseline value (scalar or per-period baseline)
• Interpret $T(t)$ as a reduction fraction (0–1) unless schema specifies percent:

$target_{abs}(t) = B \cdot (1 - T(t))$

• Use target_abs(t) as the target in subsequent calculations.

---

4.2. Absolute gap

Define gap sign so it remains intuitive across directionality:

If directionality = LOWER_IS_BETTER (e.g., emissions):

$gap_{abs}(t) = C(t) - T(t)$

Positive gap means “above target” (bad). Negative means “below target” (good).

If directionality = HIGHER_IS_BETTER (e.g., renewable share targets):

$gap_{abs}(t) = T(t) - C(t)$

Positive gap means “below target” (bad). Negative means “above target” (good).

---

4.3. Percent gap

Percent gap is computed relative to target (default) unless your schema chooses baseline; v1 default is relative to target:

$gap_{pct}(t) = gap_{abs}(t) / max(|T(t)|$, pct_denominator_floor)

• Returned as ratio (0.05 = 5%) unless output schema requires percentage scaling.
• pct_denominator_floor prevents division instability.

---

4.4. On-track flag (optional)

If enabled by output schema or options:

For LOWER_IS_BETTER:

$on_{track}(t) = (C(t) <= T(t) + tolerance_{abs})$

For HIGHER_IS_BETTER:

$on_{track}(t) = (C(t) + tolerance_{abs} >= T(t))$

If percent tolerance is used:

• compare gap_pct(t) to tolerance_pct

---

5. Missing Data Rules (Normative)

• Default missing_policy = ERROR
• If SKIP, periods missing in either current or target are omitted, and omission counts are included in metadata.

Metadata MUST include:

• aligned_periods
• missing_in_current
• missing_in_target
• missing_policy_applied

---

6. Validation & Error Model

Invariants

• Values must be finite
• pct_denominator_floor > 0 if percent mode enabled
• For reduction targets: baseline must exist and be > 0 unless explicitly allowed otherwise
• Directionality must be declared or defaulted deterministically

Error codes (suggested)

• TARGET_GAP_ALIGNMENT_MISMATCH
• TARGET_GAP_MISSING_BASELINE
• TARGET_GAP_INVALID_TARGET_TYPE
• TARGET_GAP_NON_FINITE_VALUE
• TARGET_GAP_DENOMINATOR_ZERO_GUARDED (informational if floor applied)

Errors MUST include:

• engine cmi_short_code
• period/key causing failure

---

7. Dependencies

MEID_CALC_TARGET_GAP is arithmetic but depends on:

• time-series normalization utilities
• schema resolver (ZAR)
• optional unit metadata handling (absolute vs intensity)

Declared via ZAR dependencies.

---

8. Federation & Audit Requirements

To reproduce target-gap outputs externally, the export MUST include:

• Engine identity (cmi or zar_code)
• Engine build proof (execution_ref + build_hash)
• Input/options/output schemas used
• Current series, target series (and baseline if used)
• Directionality, tolerances, and floor settings

Provenance chain MUST show:

… → MEID_CALC_TARGET_GAP → …

with cmi_short_code present in USO tail arrays.

---

9. Performance Notes

• Complexity: $O(n)$ over periods
• Memory: $O(n)$
• Suitable for batch reporting and KPI monitoring

---

10. Methods Served (v1)

• GHG.target_gap
• Energy.target_gap (if configured)
• Water.target_gap (if configured)
• Waste.target_gap (if configured)

Downstream engines that commonly consume this output:

• MEID_SCEN_GHG_ALIGN
• risk/scoring engines in climate transition modules

---