Skip to main content
Jira progress: loading…

DLT

Delta Calculator

1. Identity​

Loading identity…

Depends on module:

  • Purpose: Computes deltas between two values or two time series (e.g., year-over-year absolute change and percent change), with strict alignment rules and deterministic output.

  • Typical usage: GHG.delta_yoy, Energy.delta_yoy, Water.delta_yoy (and any other “Δ vs baseline” method).

Versioning policy

  • MEID is stable (MEID_CALC_DELTA does not change with patch releases).
  • The executable version is governed via ZAR (engine CMI/version + execution_ref digest/tag + build_hash).

The Delta Calculator is a cross-cutting primitive (GHG/Energy/Water all depend on YoY deltas), and sets the “house style” for:

  • contract-first documentation (schemas + invariants),
  • runtime lineage semantics,
  • error handling,
  • and federation proof expectations.

2. Contract References (ZAR)​

2.1. Input Schema​

  • ZAR Address: schema.compute.<domain>.delta.inputs.v1_0_0
  • CMI: auto-resolved via ZAR Registry

Required conceptual fields

  • series_current: time-series or scalar (see accepted shapes below)
  • series_baseline: time-series or scalar
  • delta_mode: ABS (Absolute Value) | PCT (Percentage Change/Percent) | BOTH
  • alignment: BY_YEAR | BY_INDEX (default BY_YEAR)

2.2. Options Schema​

  • ZAR Address: schema.compute.<domain>.delta.options.v1_0_0
  • Typical options:
    • pct_denominator_floor (default: 1e-9)
    • missing_policy: ERROR | SKIP | FILL_ZERO
    • rounding: optional (digits)

2.3. Output Schema​

  • ZAR Address: schema.compute.<domain>.delta.output.v1_0_0
  • Outputs include:
    • delta_abs_series
    • delta_pct_series (if requested)
    • metadata (alignment info, missing counts, etc.)

Note: the schema addresses above are parameterised by <domain> (ghg/energy/water). They all map to the same compute semantics, but keep domain-specific namespaces for clarity and traceability.

3. Accepted Input Shapes​

The engine MUST accept both:

A. Scalar comparison

{
  "series_current": 12000,
  "series_baseline": 12500,
  "delta_mode": "BOTH"
}

B. Time-series as year-value pairs (preferred for reporting)

{
  "series_current": [[2025, 12500], [2026, 12000]],
  "series_baseline": [[2025, 13000], [2026, 12500]],
  "alignment": "BY_YEAR",
  "delta_mode": "ABS"
}

C. Time-series as flat arrays (legacy)

{
  "series_current": [2025, 12500, 2026, 12000],
  "series_baseline": [2025, 13000, 2026, 12500],
  "alignment": "BY_YEAR",
  "delta_mode": "PCT"
}

The engine MUST normalize all supported shapes into an internal canonical representation: Map<period, value>.

4. Compute Semantics (Normative)​

For each aligned period t:

Absolute delta

Δabs(t)=current(t)−baseline(t)Δ_abs(t) = current(t) - baseline(t)

Percent delta

Δpct(t)=(current(t)−baseline(t))/max(∣baseline(t)∣,pctdenominatorfloor)Δ_pct(t) = (current(t) - baseline(t)) / max(|baseline(t)|, pct_denominator_floor)

  • pct_denominator_floor prevents division by zero and unstable blow-ups.
  • Percent delta is a ratio (e.g., 0.05 for +5%). UI/reporting may display as % by multiplying by 100, but the engine output remains a ratio unless the output schema explicitly requires percent units.

5. Alignment Rules (Normative)​

alignment = BY_YEAR

  • Period keys (e.g., years) MUST match between series.
  • Default missing_policy = ERROR.
  • If missing_policy = SKIP, periods missing in either series are omitted from output.
  • If missing_policy = FILL_ZERO, missing values are treated as 0 (discouraged for emissions; allowed only where explicitly enabled).

alignment = BY_INDEX

  • Values are compared in-order.
  • Series lengths MUST match unless missing_policy permits truncation (SKIP).

The output MUST include alignment metadata:

  • aligned_periods
  • missing_in_current
  • missing_in_baseline
  • missing_policy_applied

6. Validation & Error Model​

Runtime validation layers

  1. JSON Schema validation (inputs/options/output contracts)
  2. Engine invariants (enforced at runtime)

Invariants

  • All numeric values must be finite (!NaN, !Inf)
  • If delta_mode includes PCT, pct_denominator_floor > 0

Error codes (suggested)

  • DELTA_INPUT_SHAPE_INVALID
  • DELTA_ALIGNMENT_MISMATCH
  • DELTA_DIVIDE_BY_ZERO_GUARDED (informational if floor applied)
  • DELTA_NON_FINITE_VALUE

Errors MUST be deterministic and include:

  • cmi_short_code of the engine step
  • input period causing failure (where applicable)

7. Dependencies​

MEID_CALC_DELTA should have no required compute dependencies (pure arithmetic), but it depends on:

  • shared runtime utilities for:
  • time-series normalization
  • unit metadata passing
  • schema enforcement adapter (ZAR schema resolver)

In ZAR, these appear as dependencies in the engine’s registry row (CMIs).

8. Federation & Audit Requirements​

To reproduce a delta computation externally, a verifier/partner must be provided:

  • Engine identity: cmi or zar_code for this engine step
  • Engine build proof: execution_ref (immutable digest form preferred) + build_hash
  • Contracts used:
    • inputs schema zar_code/cmi
    • options schema zar_code/cmi
    • output schema zar_code/cmi

The provenance export MUST include a registry snapshot mapping:

  • zar_code → cmi → build_hash/execution_ref/storage_uri

9. Performance Notes​

  • Complexity: O(n)O(n) over number of periods
  • Memory: O(n)O(n) for normalized maps
  • Suitable for batch processing and streaming (if period windows are provided)

10. Methods Served (v1)​

  • GHG.delta_yoy
  • Energy.delta_yoy
  • Water.delta_yoy

(Additional methods may map to this engine without changing MEID; only registry bindings and method registry rows change.)



GitHub RepoRequest for Change (RFC)