The emission_factor table

The factor itself: one lineage per publisher, spanning releases and years, with the values attached separately.

Fields#

field type required example meaning
id uuid yes The row's own identifier. Consumers address a factor by its slug, not by this.
publisher_id uuid yes The publisher this belongs to.
factor_source_id text yes The source-anchored identity: 'ademe//36284//Combustion//Combustion', 'exiobase//p06.5//WE'. Frozen per-source recipe (keys.py RECIPE SPEC).
slug text yes ef-ademe-electricite-reseau-france-a1b2c3d4 The published, permanent identifier. Frozen when the factor is first minted and never re-derived; a superseded slug keeps resolving through the alias table.
activity_src_id text yes Groups the region / unit / boundary variants that are the same activity. Stable across releases.
activity_main text yes ONE language per factor, and which one is a retrieval decision rather than a display preference: open_ef.activity_search embeds this column verbatim, while what a reader is shown is resolved per field from emission_factor_text. The rule is the publisher's own language wherever the source shipped a name. Where the adapter GENERATES the name instead, it stores English (the catalogue's default read language) and dates that choice in the library's docs/ef-libraries/.md, unless the generated English would collapse distinctions the native name keeps, which is a declared exemption dated in the same file. That is the ispra-versus-japan_moe case: ispra stores its generated English, japan_moe stayed Japanese while its English named 1,475 of 1,663 factors 'Electricity'. Audited advisory by name_column_language.
activity_detail text The qualifier the publisher adds to the activity name, where there is one.
activity_full text yes Electricite - reseau France continentale The full activity name: the main activity, plus the detail when there is one. This is the search keyword.
description text The publisher's own prose about the factor (preferred-language copy of the description text term). Never a restatement of a typed column: a boundary name or a category path belongs in system_boundary / activity_classification, where a consumer can query it.
usage_definition text A written what-this-covers / when-to-use / caveats paragraph. Ours, not the publisher's, and labelled as generated.
publisher_sector text Flat convenience: top + leaf LABELS of the PUBLISHER'S OWN tree, which is why they carry the prefix: the same string means different things in two libraries and no two libraries share a value. The cross-library axis is open_ef_category, which lives in activity_classification (scheme = 'open_ef_category') and is served as factors_flat.category / .sub_category; it deliberately has no column here, because a factor carries N classification rows across schemes and levels. The typed hierarchy with native codes is open_ef.activity_classification.
publisher_sub_sector text
boundary_profile jsonb This factor's own answers to the boundary questions, the most specific layer: it overrides what the publisher states for the factor's category or library and the boundary defaults. Sparse: an absent term is not established here, never excluded. factors_flat.boundary_scope serves the merged answer.
region_code text yes Where the factor applies, at whatever grain the publisher modelled: a country, a subdivision, a modelled aggregate.
region_origin text yes source / assigned / inferred
region_raw text Denormalized latest-value raw region, for quick retrieval without a join.
unit_code text yes The canonical unit the value is expressed per.
unit_family text yes mass/energy/volume/monetary/...
basis_kind text yes Tier-3 basis annotation: 'canonical' (unit basis self-describing) or 'context_dependent' (the printed unit does not say what "1 unit" is, so a value is producible only through a validated per-line query-time bridge, never a blind conversion). A context-dependent factor carries a basis-qualified unit_code (kg_n, m2_nfa) so a plain-kg/m2 query cannot blind-match it. reference_basis is the structured descriptor (the generalized reference product), required when context_dependent; its kind is a closed vocabulary validated at ingest (ingest.vocabulary). A canonical factor carries none, except a gas volume on l, whose gas_volume descriptor names the publisher's metering conditions (MOD-0010).
reference_basis jsonb For a unit that is not self-describing (a mass of nutrient, a qualified area), what the basis actually is and what a conversion would need.
system_boundary text yes What this factor counts: see the system boundary vocabulary. The single most important field for deciding whether two numbers may be compared.
system_boundary_origin text yes Whether the boundary was stated by the publisher, assigned by us, inferred, or is genuinely unknown.
system_boundary_raw text The literal source boundary token when system_boundary is a semantic aggregate (EN 15804 'A1-A3' -> cradle_to_gate keeps 'A1-A3' here); NULL when the code already is the raw token. A pure annotation.
parent_id uuid Set on a decomposition child (a stage or contribution of another factor), always together with parent_relation: both or neither. Aggregate only over rows where this is null, or you will double-count. Null is not evidence that a factor has no parts: it means either that the publisher printed no separable envelope, or that its parts were published in a shape we do not link.
parent_relation text How the child sits under its parent, and it follows the arithmetic rather than the publisher's wording. sums_to_parent means the siblings of that split exhaust the parent, so they may be summed within one split: and never added to the parent itself. contained_by_parent means the child is one itemised slice of a larger envelope whose remainder was not published, so it may never be summed with anything.
root_id uuid yes The top of this factor's parent chain, stored: its own id when parent_id is NULL, else its parent's root_id. Lets a served list group every part under its top-level factor without walking parent_id per row (plan FRN-0013). Kept by the two writers of parent_id -- the loader re-roots a publisher after linking, a mint cascades the demoted members' subtrees to the new parent (db_open_ef.roots); mint-* --refresh never rewrites it. Not a CHECK: the loader links, then re-roots, in two statements.
is_derived boolean yes TRUE when open_ef COMPUTED this headline by summing a whole-group exact cover of reconciling children, rather than transcribing a number the publisher printed. It exists because one total cannot serve both reporting conventions: under the GHG Protocol combustion is Scope 1 and well-to-tank is Scope 3.3, reported apart and never added on one line, while ISO 14083 / GLEC require exactly that sum. The flag does not pick the convention, the tree does: the total is the parent-less row (factors_flat names that flag is_top_parent), its parts are its sums_to_parent children. On a summed total the value row says the same thing again on co2e_origin ('summed_from_children'), deliberately: two independent columns, so a consumer reading either half cannot mistake a derived row for a published one. It is TRUE on every estimated factor too (is_estimated, below): a part no publisher printed, whose value row says 'estimated_from_reference', or a total that includes one. So NOT is_derived leaves out the estimated parts as well as the totals; NOT is_estimated leaves out only the estimates. It is TRUE on a differenced part as well (MOD-0049): a child the publisher printed both operands of, parent total and sibling, whose value row says 'differenced_from_parent' because open-climate.ai subtracted them. And on an apportioned part (MOD-0071): a child the publisher printed the total and the share of, whose value row says 'apportioned_from_parent' because open-climate.ai multiplied them.
is_estimated boolean yes TRUE when open-climate.ai computed this factor's values by a RULE from published figures, most often the publisher's own value times a reference ratio, because the publisher never printed this part: the transmission-and-distribution or fuel-chain leg of an electricity factor whose publisher prints generation only, or the well-to-tank leg of a fuel whose publisher prints combustion only. The figures are the region's own, a model of it, a broader region's or another country's supply chain. Narrower than is_derived, which it implies (CHECK below): a derived total sums the publisher's own printed slices, an estimated leg is a number no publisher printed. The leg's value row says it again on co2e_origin ('estimated_from_reference'). A parent with an estimated child is estimated too, and its value row says 'summed_from_children'.
is_epd boolean yes TRUE when this factor is (a module of) an Environmental Product Declaration: a third-party-verified declaration a named declarant publishes for one product or product group (EN 15804 / ISO 14025). Set by the ADAPTER at ingest, refreshed on re-ingest like any annotation. ÖKOBAUDAT: every ILCD subType except generic dataset, whose rows are the database's own modelled background data (Sphera / GaBi), which no manufacturer declared. A supplier link is NOT the same thing: a supplier-specific grid tariff (miterd, japan_moe) names a company and is no EPD, and an industry EPD's declarant is a trade association. Served as factors_flat.is_epd, an explorer facet.
gas_species text The one gas this factor is a kilogram of, when it is a release of a single named substance (MOD-0019): DESNZ Kyoto protocol products - HFC-134a, MfE HFC-125 (R-125). A key of ingest/gwp_species.py (HFC-134a, PFC-14, SF6, CO2 ...), set by the ADAPTER from a closed map and refreshed on re-ingest like any annotation. NULL for everything else, blends included: R-404A is a mixture with no one GWP. Such a factor's number IS the species' GWP under its native vintage, so it is what lets the AR6 twin convert a row that has no per-gas leg to un-weight; the value must still equal the tabled GWP or it stays unconverted. Only a fugitive per-kg factor may carry one (CHECK below).
supplier_id uuid The named counterparty, where the factor describes one.
labels jsonb {lang: text}: denormalized passport
last_ingest_version bigint yes Change tracking: the ingest_run.ingest_version that last mutated this factor's annotation layer. Lets a consumer sync "what changed since" with no diffing (WHERE last_ingest_version > :last_seen). Re-stamped with updated_at on every annotation refresh (loader; one rule, both fields).
created_at timestamp yes When the row was first written.
updated_at timestamp When the row was last rewritten.

Referenced by#

activity_classification.factor_id, emission_factor.parent_id, emission_factor.root_id, emission_factor_alias.emission_factor_id, emission_factor_text.factor_id, emission_factor_value.emission_factor_id, external_factor_map.emission_factor_id, factor_release_presence.emission_factor_id, route_default.factor_id, unit_conversion.emission_factor_id.

Notes#

Identity is source-anchored: (publisher, factor_source_id) and nothing else. Everything readable here beyond that pair (the activity prose, region, unit, boundary, classifications) is a harmonisation annotation: improving one never re-keys the factor, and never changes a published slug.