The calculation engine
Factor resolution: how a source is chosen
Every calculator that needs a factor asks the same function for it. That function walks your organisation's list of publishers in order, and treats "this publisher doesn't cover that" very differently from "this should be here and isn't".
On this page you'll learn
- How the source chain is walked for each record
- The two kinds of failure, and why they behave differently
- How a fallback is labelled so it can't hide in a report
- Function
resolve_factor(FactorRequest), shared by every calculator- Configured in
- Settings → Emission Factors, "Factor source order"
- On a data gap
- Try every remaining source in the chain before giving up
- Fuzzy matching
- None, anywhere
What a calculator asks for
A calculator packages what it knows into a FactorRequest: the kind of activity (for example stationary_combustion), the fuel or material, the unit you entered, the facility and its country or province, the transaction date and the reporting year. It never names a publisher. A test walks every calculator's source code and fails the build if any of them passes one directly.
Walking the chain
- 1
Read the organisation's source order
For example
UK_DEFRA → US_EPA → UN_IPCC. An organisation can also set a different order for one kind of activity. - 2
Pick the release
For the first publisher, find the edition that serves this kind of activity, then the release covering the transaction date, honouring any pin for the reporting year.
- 3
Find the mapping
Look up how this fuel or material is mapped onto the publisher's own activity path. No name matching.
- 4
Read the value
Read the published row for that path and the unit basis it's published on.
- 5
Stop, or move on
If it resolved, stop. Otherwise, whether the publisher simply doesn't cover this, or should have had the figure and didn't, try the next one in the chain. Only once every configured publisher has been tried does the record stop with an error.
Two kinds of failure
| Kind | Examples | What happens |
|---|---|---|
| Publication boundary | DEFRA has no overseas electricity; EPA has no well-to-tank factors; the publisher has no release loaded for this date | Always move to the next publisher. The row is labelled a fallback. |
| Data gap | The fuel isn't mapped for this publisher; the mapped row has no value; the value is blank in the source | Also moves to the next publisher. The row is still labelled a fallback. Stops with an error only once nothing left in the chain can serve it. |
Why this matters
There is no setting that stops the chain early on a data gap: with one source configured, a gap has nowhere to fall through to and the record errors; with more than one, every remaining source is tried first. A fallback is never silent either way. The Factor Source column marks it "(fallback)" whenever the answer didn't come from the organisation's first choice, so a mixed-source report is always visible on the row itself.
If every publisher in the chain hit a boundary, the answer is the same for every record of that kind. Optional components such as well-to-tank then skip quietly instead of writing an identical error onto thousands of rows. A direct calculation still gets a visible row, and the message names the fix.
Two labels on every row
Source selection
How the publisher was chosen:
policy:UK_DEFRAif it was your first choice,fallback:US_EPAif an earlier one declined. The Factor Source column shows "(fallback)" from this.Resolution method
How the publisher found the factor in its own data. For US electricity, which step of the eGRID chain answered, such as utility grid region or state lookup. The resolver never overwrites this.
A worked example
- Ask UK DEFRA for Boston grid electricity
- boundary: no overseas grid
- Ask US EPA
- eGRID subregion NEWE
- Source selection recorded
fallback:US_EPA- Priced on
- eGRID2023 rev 2, NEWE
The same company's Manchester office resolves at the first step and records policy:UK_DEFRA.
The full trace is kept
Every publisher asked, and what each said, is stored on the row as its resolution trace. The provenance panel shows it classified as boundary, configuration (nothing imported) or data gap, so the one that means something is wrong stands out. See Provenance.