The calculation engine
Mappings: connecting your entries to a publisher's rows
Slate's fuels, vehicles and materials don't use any publisher's vocabulary. A reviewed mapping file connects each one to a publisher's exact row, and a gap is written down with its reason instead of filled with a guess.
On this page you'll learn
- What a mapping is, and why it lives in a reviewed file
- What draft, reviewed and approved mean
- How coverage is measured, and what "orphaned" means
- Stored in
factors/data/mappings/*.yaml, one file per publisher- Matching
- Exact, by mapped path. Never by name.
- Statuses
- draft · reviewed · approved
What a mapping says
A mapping says: for this kind of activity, this Slate fuel (or vehicle, refrigerant, material, livestock category, region…) is priced from this publisher path. For example, stationary Diesel maps to EPA's Distillate Fuel Oil No. 2. That is an identity, not an approximation: EPA's mobile table gives "Diesel Fuel" exactly the same 10.21 kg CO₂ per gallon.
Where a publisher's figure has an upstream counterpart, the mapping names it explicitly. It is never derived by stripping a "WTT-" prefix, because one DEFRA upstream heading spans two direct categories and inference would pair them wrongly.
No fuzzy matching
Why this matters
Matching a fuel name against a publisher's category text is the most tempting shortcut and the most dangerous one. It produces a plausible figure nobody can spot as wrong. An unmapped activity raises an error instead.
Real examples of what this protects against: ethane is a gas in Slate, EPA publishes it per liquid gallon, and 1,000 scf priced as gallons came out 293 times too high. Eleven fuels including propane and LPG were once filed as gases and offered in scf, giving results up to 254 times too high. Both were fixed in the mapping and unit layers, not patched in a calculator.
Review status
| Status | Meaning |
|---|---|
| approved | An unambiguous one-to-one match. |
| reviewed | Checked by a reviewer. |
| draft | A judgement call that changes numbers, waiting for a domain reviewer. For example, which DEFRA marine fuel matches residual fuel oil. |
Draft mappings still calculate, and the coverage report lists them separately. IPCC currently has 11 drafts, all substance-identity questions the mapping file itself flags (is Heavy Gas Oil closer to Gas/Diesel Oil or to Other Petroleum Products?).
Coverage
| Bucket | Meaning |
|---|---|
| mapped | Has a mapping to a published value |
| documented gap | Deliberately unmapped, with a written reason |
| orphaned | Mapped to a path that has no value in the release. Urgent: this is what a publisher renaming a category looks like. |
| unmapped | Not investigated yet |
| Publisher | Mapped | Documented gaps | Orphaned | Unmapped | Draft |
|---|---|---|---|---|---|
| UK DEFRA 2026 | 23 | 46 | 0 | 1 | 1 |
| US EPA 2025 | 69 | 0 | 0 | 1 | 0 |
| IPCC 2006 | 56 | 12 | 0 | 0 | 11 |
Supported, mapped, or neither
For a given publisher, an activity is in one of three states, and the middle one is a trap:
| State | On resolve | Effect |
|---|---|---|
| Not supported by the publisher | Boundary | The chain moves on |
| Supported but not mapped | Data gap | The record fails |
| Supported and mapped | Resolves | — |
So adding an activity to a publisher without its mappings is worse than leaving it out. Tests assert, for each publisher, that every supported activity has its mappings.