Skip to main content
Jira progress: loading…

GHG-AGGR

GHG Aggregation Calculator

1. Identity​

Loading identity…

Depends on module:

  • Purpose: Aggregates greenhouse gas emissions across scopes and categories into absolute totals, ensuring strict alignment with GHG Protocol and ESRS E1 semantics.

  • Typical usage:

    • Total company emissions
    • Scope-level totals (Scope 1, 2, 3)
    • Combined Scope 1+2 / Scope 1+2+3 views
    • Inputs to intensity, delta, target, and scenario engines

Versioning policy

  • MEID is stable.
  • Aggregation logic versioning is governed via ZAR (engine CMI/version + execution_ref + build_hash).

2. Contract References (ZAR)​

2.1. Input Schema​

  • ZAR Address: schema.compute.ghg.abs.inputs.v1_0_0

Required conceptual fields

  • scope1: scalar or time-series (optional)
  • scope2: scalar or time-series (optional)
  • scope2_method: LOCATION | MARKET (default: LOCATION)
  • scope3: object or array of category entries (optional)
  • include_scopes: array (["S1","S2","S3"] default all)
  • alignment: BY_YEAR | BY_INDEX (default BY_YEAR)

At least one scope MUST be provided.

2.2. Options Schema​

  • ZAR Address: schema.compute.ghg.abs.options.v1_0_0

Common options:

  • missing_scope_policy: ERROR | TREAT_AS_ZERO | EXCLUDE
  • scope3_category_policy: SUM_ALL | INCLUDE_LIST | EXCLUDE_LIST
  • scope3_categories_include: list (if INCLUDE_LIST)
  • scope3_categories_exclude: list (if EXCLUDE_LIST)
  • unit: default tCO2e
  • rounding: optional digits

2.3. Output Schema​

  • ZAR Address: schema.compute.ghg.abs.output.v1_0_0

Outputs include:

  • ghg_total
  • ghg_scope1
  • ghg_scope2
  • ghg_scope3
  • metadata (policies applied, scope completeness, category coverage)

3. Accepted Input Shapes​

A. Scalar aggregation

{
  "scope1": 1200,
  "scope2": 800,
  "scope3": {
    "cat1": 300,
    "cat6": 150
  }
}

B. Time-series (preferred)

{
  "scope1": [[2025, 1200], [2026, 1180]],
  "scope2": [[2025, 800], [2026, 760]],
  "scope3": {
    "cat1": [[2025, 300], [2026, 280]],
    "cat6": [[2025, 150], [2026, 140]]
  },
  "alignment": "BY_YEAR"
}

C. Scope 3 as array (legacy-friendly)

{
  "scope3": [
    {"category": "cat1", "values": [[2025, 300]]},
    {"category": "cat6", "values": [[2025, 150]]}
  ]
}

All inputs MUST be normalized internally to:

Map<period, { scope1?, scope2?, scope3{category -> value} }>

4. Compute Semantics (Normative)​

For each aligned period t:

4.1. Scope-level totals​

  • S1(t)S1(t) = scope1(t)scope1(t) if provided
  • S2(t)S2(t) = scope2(t)scope2(t) if provided (location or market per option)
  • S3(t)S3(t) = ΣΣ scope3_category_values (t)(t) subject to category policy

4.2. Total emissions​

GHG_TOTAL(t) = Σ included scopes (S1, S2, S3)

4.3. Scope inclusion rules​

  • Only scopes listed in include_scopes are included
  • Missing scopes handled per missing_scope_policy

5. Scope 3 Category Rules (Normative)​

Category handling

  • Categories MUST be identified using canonical Scope 3 category codes (Cat1–Cat15)
  • If SUM_ALL: all provided categories are summed
  • If INCLUDE_LIST: only listed categories are summed
  • If EXCLUDE_LIST: all except listed categories are summed

Completeness metadata

The engine MUST report:

  • scope3_categories_present
  • scope3_categories_expected (if provided by context)
  • scope3_coverage_ratio

6. Alignment Rules​

BY_YEAR

  • All scope series must align on the same period keys
  • Missing values handled per missing_scope_policy

BY_INDEX

  • Ordered comparison
  • Series length mismatches handled per policy

Output metadata MUST include:

  • aligned_periods
  • missing_scopes
  • policies_applied

7. Validation & Error Model​

Invariants

  • All numeric values must be finite
  • Units must be convertible to tCO2e
  • No negative emissions unless explicitly allowed by schema (default: not allowed)

Error codes (suggested)

  • GHG_AGGR_NO_SCOPES_PROVIDED
  • GHG_AGGR_ALIGNMENT_MISMATCH
  • GHG_AGGR_INVALID_CATEGORY_CODE
  • GHG_AGGR_NON_FINITE_VALUE

Errors MUST include:

  • engine cmi_short_code
  • scope/category causing failure
  • period (if applicable)

8. Dependencies​

MEID_CALC_GHG_AGGR depends on:

  • time-series normalization utilities
  • schema resolver (ZAR)
  • optional Scope 3 category reference table (registry/dataset)
  • unit conversion utilities (if mixed units allowed)

Dependencies are declared via ZAR registry CMIs.

9. Federation & Audit Requirements​

To reproduce a GHG aggregation externally, the bundle MUST include:

  • Engine identity (cmi or zar_code)
  • Engine build proof (execution_ref + build_hash)
  • Input/options/output schemas used
  • Input emission values per scope/category
  • Scope 2 method used (location/market)
  • Scope 3 category inclusion/exclusion policy

Provenance chain MUST show:

… → MEID_CALC_GHG_AGGR → …

with cmi_short_code present in USO tails.

10. Performance Notes​

  • Complexity: O(n×c)O(n × c) where nn = periods, cc = Scope 3 categories
  • Memory: O(n×c)O(n × c)
  • Suitable for batch processing and reporting pipelines

11. Methods Served (v1)​

  • GHG.abs
  • GHG.scope1.abs
  • GHG.scope2.abs
  • GHG.scope3.abs
  • GHG.total.abs

Downstream engines relying on this output:

  • MEID_CALC_GHG_INT
  • MEID_CALC_DELTA
  • MEID_CALC_TARGET_GAP
  • MEID_SCEN_GHG_ALIGN


GitHub RepoRequest for Change (RFC)