carbon_intensity

carbon_intensity

CarbonIntensityEvents

CarbonIntensityEvents(
    dataframe: DataFrame,
    emission_factors: dict[str, float],
    *,
    scope_map: dict[str, int] | None = None,
    event_uuid: str = "energy:carbon",
    time_column: str = "systime",
    uuid_column: str = "uuid"
)

Bases: Base

Energy: Carbon Intensity Tracking (Scope 1 & 2)

Converts energy and fuel consumption signals to CO2-equivalent emissions using configurable emission factors. Supports Scope 1 (direct fuel) and Scope 2 (electricity) calculations, plus carbon intensity per unit produced. Designed for CSRD and ISO 14064 reporting.

Supports two data models via constructor parameters:

• Standard (ts-shape default)::

  CarbonIntensityEvents(df, emission_factors={"meter:elec": 0.233})

  expects: systime | uuid | value_double

• Raw CSV::

  CarbonIntensityEvents(df, emission_factors={"sensor_01": 0.233}, time_column="time", uuid_column="id")

emission_factors is a dict mapping signal identifier → kgCO2e per unit of the energy/fuel reading::

emission_factors = {
    "meter:electricity": 0.233,   # kgCO2e/kWh  (UK grid average 2026)
    "meter:gas":         2.034,   # kgCO2e/m³   (natural gas)
}

Each factor's scope is inferred from scope_map. Any uuid not in scope_map defaults to Scope 2.

Methods: - emissions_by_window: CO2e per source per time window. - total_emissions_by_window: Aggregated Scope 1 + 2 per window. - carbon_intensity_per_unit: kgCO2e per unit produced. - emission_factor_audit: Return configured factors for audit trail.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input signal DataFrame.	required
emission_factors	dict[str, float]	Mapping of signal identifier → kgCO2e per unit.	required
scope_map	dict[str, int] | None	Optional mapping of signal identifier → scope (1 or 2). Defaults to Scope 2 for any uuid not in the map.	None
event_uuid	str	UUID assigned to output events.	'energy:carbon'
time_column	str	Name of the timestamp column.	'systime'
uuid_column	str	Name of the signal identifier column.	'uuid'

emissions_by_window

emissions_by_window(
    *,
    scope: int = 0,
    value_column: str = "value_double",
    window: str = "1D"
) -> pd.DataFrame

CO2e emissions per configured source per time window.

Parameters:

Name	Type	Description	Default
scope	int	Filter by scope: 1 = fuel only, 2 = electricity only, 0 = all sources (default).	0
value_column	str	Column containing consumption readings.	'value_double'
window	str	Aggregation window (e.g. '1D', '1h').	'1D'

Returns:

Name	Type	Description
DataFrame	DataFrame	start, uuid, source_uuid, scope, consumption, emission_factor, kgco2e

total_emissions_by_window

total_emissions_by_window(
    *,
    value_column: str = "value_double",
    window: str = "1D"
) -> pd.DataFrame

Aggregate Scope 1 + Scope 2 emissions across all configured meters.

Parameters:

Name	Type	Description	Default
value_column	str	Column containing consumption readings.	'value_double'
window	str	Aggregation window.	'1D'

Returns:

Name	Type	Description
DataFrame	DataFrame	start, uuid, scope1_kgco2e, scope2_kgco2e, total_kgco2e

carbon_intensity_per_unit

carbon_intensity_per_unit(
    counter_uuid: str,
    *,
    value_column: str = "value_double",
    counter_column: str = "value_integer",
    window: str = "1D"
) -> pd.DataFrame

Carbon intensity per unit produced (kgCO2e / unit).

Parameters:

Name	Type	Description	Default
counter_uuid	str	Identifier of the production counter signal.	required
value_column	str	Column containing energy/fuel readings.	'value_double'
counter_column	str	Column containing counter readings.	'value_integer'
window	str	Aggregation window.	'1D'

Returns:

Name	Type	Description
DataFrame	DataFrame	start, uuid, total_kgco2e, units_produced, carbon_intensity, trend

emission_factor_audit

emission_factor_audit() -> pd.DataFrame

Return the configured emission factors for audit and reporting.

Returns:

Name	Type	Description
DataFrame	DataFrame	source_uuid, scope, emission_factor_kgco2e_per_unit