docs: technical docs vs user guide; EF calculation and margin EF pages

_parts/custom.css

@@ -125,3 +125,22 @@ body {
   font-size: 0.8rem;
   opacity: 0.7;
 }
+
+/* Home page tracks: technical documentation (brand blue) and user guide (amber).
+   The card tint and top rule tell the two tracks apart. */
+.track-technical .myst-card {
+  background-color: #eaf6fb;
+  border-color: #9fd3e8;
+  border-top: 4px solid var(--cs-brand);
+}
+.track-technical .myst-card:hover {
+  border-color: var(--cs-brand);
+}
+.track-user .myst-card {
+  background-color: #fdf3e7;
+  border-color: #f0c99a;
+  border-top: 4px solid #e08a1e;
+}
+.track-user .myst-card:hover {
+  border-color: #e08a1e;
+}

ee/index.md

@@ -3,31 +3,31 @@ title: "The GHG extension: overview"
 ---
 
 :::{tip} Summary
-The GHG extension attaches each sector's own greenhouse gas emissions to the IO model, as emissions of each gas per dollar of output (`B`). Every country follows the same steps, but the emissions data behind them, and how much detail they carry, depend on the country's tier.
+The GHG extension attaches each sector's own greenhouse gas emissions to the IO model, as CO₂-equivalent emissions of each gas per dollar of output (`B`). Every country follows the same steps, but the emissions data behind them, and how much detail they carry, depend on the country's tier.
 :::
 
 :::{figure} ../figures/diagrams/ghg-pipeline.svg
 :label: fig-ghg-pipeline
-:alt: Seven boxes in a row joined by arrows: 1, source emissions by source sector; 2, split broad sectors; 3, allocate to the 405 common sectors; 4, fill in gas detail where needed, drawn dashed, with a note that it is not needed for the U.S., China, Japan, or the UK; 5, convert to AR6; 6, divide by output, first industry output x and then per commodity output q. The result is B, kilograms of each gas per dollar. A bracket under steps 2 to 4 notes that each country's source totals are kept through them.
+:alt: Seven boxes in a row joined by arrows: 1, source emissions by source sector; 2, split broad sectors; 3, allocate to the 405 common sectors; 4, fill in gas detail where needed, drawn dashed, with a note that it is not needed for the U.S., China, Japan, or the UK; 5, convert to CO₂-equivalent with AR6 GWPs; 6, divide by output, first industry output x and then per commodity output q. The result is B, kilograms of CO₂-equivalent of each gas per dollar. A bracket under steps 2 to 4 notes that each country's source totals are kept through them.
 From source emissions to direct emission intensities (`B`). Every country follows the same steps; step 4 is needed only where a source does not separate every gas.
 :::
 
 ## What the extension adds
 
 The IO model traces the dollars that flow through supply chains. The GHG extension adds what each sector emits while making its output. For each country and sector it records:
 
-- **Emissions** (`E`): kilograms of each gas emitted by the sector in a year.
-- **Direct emission intensities** (`B`): those emissions divided by output, so kilograms of each gas per dollar of output.
+- **Emissions** (`E`): the emissions of each gas by the sector in a year, in kilograms of CO₂-equivalent.
+- **Direct emission intensities** (`B`): those emissions divided by output, so kilograms of CO₂-equivalent of each gas per dollar of output.
 
 `B` holds direct emissions only: what the sector emits from its own fuel use, processes, and other activities. Emissions from the sector's suppliers come in through the supply chain ([`L`](../io/index.md#total-requirements)), not through `B`. For example, the emissions from generating electricity stay with the power sector, and other sectors' purchased electricity reaches them through `L`.
 
-Characterization factors (`C`) then weight each gas by its global warming potential, which gives the direct emission factors `D = C × B` (see [](../reference/notation.md)).
+Each gas is weighted by its global warming potential as its emissions enter the model, so `E` and `B` are already in CO₂-equivalent and no separate weighting step is needed. Adding up the gases in `B` gives the direct emission factors `D` (see [](../reference/notation.md)).
 
 ## Gases and global warming potentials
 
 `B` has a row for each of seven gases or gas groups: carbon dioxide (CO₂), methane (CH₄), nitrous oxide (N₂O), hydrofluorocarbons (HFCs), perfluorocarbons (PFCs), sulfur hexafluoride (SF₆), and nitrogen trifluoride (NF₃).
 
-They are combined into CO₂-equivalent with 100-year {term}`GWPs <GWP>` from the IPCC's Sixth Assessment Report (AR6) [@forsterEarthsEnergyBudget2021]. Methane is valued two ways: fossil methane, from fuel production and use, at 29.8, and non-fossil methane, from farming and waste, at 27.0. Fossil methane is valued higher because, once it breaks down, it leaves CO₂ that was not already in the atmosphere.
+Each gas is converted to CO₂-equivalent as its emissions are loaded, with 100-year {term}`GWPs <GWP>` from the IPCC's Sixth Assessment Report (AR6) [@forsterEarthsEnergyBudget2021]. Methane is valued two ways: fossil methane, from fuel production and use, at 29.8, and non-fossil methane, from farming and waste, at 27.0. Fossil methane is valued higher because, once it breaks down, it leaves CO₂ that was not already in the atmosphere.
 
 Several sources report emissions as CO₂-equivalent using older GWPs from the Fifth Assessment Report (AR5) [@myhreAnthropogenicNaturalRadiative2013]. These are converted to AR6, gas by gas.
 
@@ -55,7 +55,7 @@ Every country's emissions go through the same steps:
 2. **Split broad sectors where better data exist.** Some sources lump together sectors with very different emissions, such as electricity, gas, and heat, or all of farming. Where other data can separate them, the broad sector is split first, keeping its total.
 3. **Allocate to the common sectors.** For the U.S., each inventory activity is allocated to the industries that emit it. For other countries, each source sector's emissions are allocated to the matching common sectors with {term}`ABSR`, weighted by U.S. emission intensities. The country's total for each source sector is kept.
 4. **Fill in missing gas detail.** Where a source does not separate every gas, the missing split is taken from the U.S. mix for the same sector. This is not needed for the U.S., China, Japan, or the UK, whose sources cover all seven gases.
-5. **Convert to AR6** where the source used other GWPs.
+5. **Convert to CO₂-equivalent** with AR6 GWPs. Sources reported in CO₂-equivalent with other GWPs are converted to AR6.
 6. **Divide by output.** Each industry's emissions are divided by its output (`x`), then converted to commodities using market shares (who makes each commodity), giving `B` per dollar of commodity output (`q`). Emissions data years differ by country; see [](country-tiers.md#ghg-data-years).
 
 [](country-tiers.md) gives the sources and how each step is done for each tier.

factors/calculation.md

@@ -0,0 +1,117 @@
+---
+title: "Calculating the emission factors"
+---
+
+:::{tip} Summary
+The emission factors are the model's total emission factors (`N`): the CO₂e emitted across the whole supply chain per dollar of each commodity, by the country that produces it. This page follows the calculation from the matrices of [the IO model](../io/index.md) and [the GHG extension](../ee/index.md) to the published producer-price (PRO) and purchaser-price (PUR) factors for each year.
+:::
+
+:::{figure} ../figures/diagrams/ef-pipeline.svg
+:label: fig-ef-pipeline
+:alt: D and B, in CO2e, and L feed step 1. Step 1 calculates the total emission factors, M equals B times L by gas and N equals D times L in total. Step 2 forms regional averages and fills gaps. Step 3 re-prices to each year, 2024, 2025 and 2026, giving the producer-price factors. Step 4 multiplies by phi, the producer share of the purchaser price, giving the purchaser-price factors. Notes say steps 1 and 2 are in 2024 U.S. dollars at producer price, step 3 uses U.S. price indexes, step 4 uses U.S. trade and transport margins, and margin emissions are published separately.
+From the model matrices to the published factors. The base calculation is in 2024 dollars; each year's factors are re-priced from it. `φ` is the producer share of the purchaser price.
+:::
+
+## From the model to total emission factors
+
+The IO model gives the total requirements `L`, the output needed from every sector in every country per dollar of final demand (see [](../io/index.md#total-requirements)). The GHG extension gives the direct emission intensities `B`, the emissions of each gas a sector emits per dollar of its own output (see [](../ee/index.md)). Each gas is weighted by its 100-year GWP from the IPCC AR6 as its emissions enter the model, so `B` is already in kg CO₂e per dollar, one row per gas (see [](../ee/index.md#gases-and-global-warming-potentials)). Adding up its rows gives the direct emission factors `D`, what a sector emits itself per dollar.
+
+The total emission factors take one step: multiplying by `L` traces each sector's direct emissions through every round of suppliers.
+
+- `M = B × L` gives the total emission factors by gas. A column of `M` gives, for \$1 of one commodity from one country, the CO₂e of each gas emitted anywhere in its supply chain. These are the gas columns of the release.
+- `N = D × L`, which equals the sum of the rows of `M`, gives the total emission factors. This is the Total GHGs column of the release.
+
+For the 65 countries in Tiers 0 to 2 and the rest-of-world region, `L` is solved once for the whole multi-region table, so `M` follows supply chains across every border in the table. Each column of `N` is one commodity produced in one country, so a factor describes where a product is made, not where it is bought.
+
+The factors are per dollar of commodity output at producer price, in 2024 U.S. dollars, the model's base year. They include every upstream supplier, but not the trade and transport services between the producer and the buyer, which are handled in [](#purchaser-price) and [](margins.md).
+
+The direct emission factors `D` are part of the model but are not published as a separate table.
+
+## Tier 3 countries
+
+The 83 Tier 3 countries are not part of the multi-region table, so their factors are calculated one country at a time, from the template described in [](../io/country-tiers.md#tier-3-no-io-tables) and [](../ee/country-tiers.md#tier-3-template-emissions). Each country's domestic inputs carry its own direct emission intensities through its domestic total requirements, `(I − Adom)⁻¹`. Its imported inputs carry China's total emission factors from the multi-region table. The two parts are added to give the country's `M`.
+
+## Regional and global averages
+
+The release has a factor for each of 21 regions and one global average (`GLOB`). For each sector and each gas, a regional factor is the average of its member countries' factors, weighted by each country's output of that sector in 2024 dollars (`q`):
+
+`N_region = Σ (N_country × q_country) ÷ Σ q_country`
+
+Only countries in Tiers 0 to 2 have output data in the model, so Tier 3 countries are not included in the weighted average, even where they belong to the region. A region with no Tier 0 to 2 member uses the simple average of its members' factors instead. The global average is weighted the same way over every Tier 0 to 2 country. The rest-of-world region is used only inside the model and is not published.
+
+## Filling missing country factors
+
+A few country–sector combinations have a total factor of exactly zero, because the source tables have no output or no emissions for that sector in that country. A zero factor would understate emissions for anyone buying from that sector, so it is treated as missing: the country's factor is replaced by its region's factor, or by the global average where the regional factor is also zero. The replacement applies to every gas.
+
+(reporting-years)=
+## From the base year to each reporting year
+
+Every source in the model is first brought to 2024 dollars: values are converted to U.S. dollars at the data year's exchange rate and re-priced to 2024 with a U.S. price index (see [](../io/country-tiers.md)). The model therefore produces 2024 factors, per 2024 dollar.
+
+The factors for 2025 and 2026 are re-priced from the 2024 factors, sector by sector:
+
+`N_t = N_2024 × PI(2024) ÷ PI(t)`
+
+where `PI` is the sector's price index and `t` is the year. When a sector's prices rise, each dollar buys less of its output, so the factor per dollar falls. The emissions behind the factors are the same; only the dollar they are expressed in changes. Each year's factors are therefore in current dollars of that year.
+
+The price index is the U.S. Bureau of Economic Analysis chain-type price index for gross output by industry (2017 = 100), mapped to the 405 sectors. The 2026 value is the average of the quarters published at the time of the release. Sectors without their own index keep a constant price. The same U.S. index is applied to every country, region and the global average.
+
+(purchaser-price)=
+## From producer to purchaser price
+
+A purchaser pays more than the producer receives: wholesale, retail and transport businesses add their margins on the way to the buyer. Each dollar at purchaser price therefore contains less of the product itself. The purchaser-price factor converts the producer-price factor to this larger dollar:
+
+`N_PUR = N_PRO × φ`, where `φ = 1 ÷ (1 + Σ A_margin)`
+
+Here `A_margin` holds the margins paid on each commodity, in dollars of margin per dollar of the commodity at producer price, one row per margin sector, and `φ` is the producer share of the purchaser price.
+
+- **Margins come from the U.S.** `A_margin` is built from U.S. margin data, on the industry-average margins paid by industries and business investment. The same `φ` is applied to every country, region and the global average (see the [key assumptions](../io/country-tiers.md#currency) for the IO tables).
+- **Services and electricity have `φ = 1`.** They carry no trade margins, so their producer- and purchaser-price factors are the same.
+- **Each year has its own `φ`.** The margin coefficients are re-priced to each year with the price indexes of the margin sector and of the commodity, so `φ` changes slightly from year to year.
+
+The purchaser-price factor covers the emissions of making the product only. The emissions of the margin services themselves, such as running warehouses, stores and trucks, are not added to it; they are prepared as separate [margin emission factors](margins.md).
+
+## Rounding
+
+Published factors are rounded to three significant figures. Total GHGs is rounded from the unrounded total, so it may not equal the sum of the rounded gas values.
+
+:::{important} Key assumptions
+:class: dropdown
+**2025 and 2026 factors reflect price changes only**
+
+- **Assumption:** The supply chains and emission intensities of the 2024 model also describe 2025 and 2026. The factors for those years differ from 2024 only by the change in each sector's price.
+- **Why we make it:** Input-output tables and emissions data for 2025 and 2026 are not yet available for any country.
+- **How it affects results:** Real changes after 2024, such as a cleaner electricity grid or a shift in where inputs are bought, are not captured in the 2025 and 2026 factors.
+
+**One U.S. price index for every country**
+
+- **Assumption:** Each sector's U.S. price change applies to that sector in every country.
+- **Why we make it:** Consistent sector-level price indexes in U.S. dollars are not available for every country and year.
+- **How it affects results:** Where prices in a country moved differently from U.S. prices, or its exchange rate against the dollar changed, its factors for 2025 and 2026 could be too high or too low.
+
+**U.S. margins in purchaser prices**
+
+- **Assumption:** The U.S. share of trade and transport margins in each commodity's purchaser price applies in every country.
+- **Why we make it:** Margin data comparable to the U.S. tables are not available for every country.
+- **How it affects results:** Where a country's margins differ from the U.S., its purchaser-price factors could be too high or too low. Producer-price factors are not affected.
+
+**Gross-output weights for regional averages**
+
+- **Assumption:** A region's factor for a sector is the average of its member countries' factors weighted by their output of that sector, using only countries in Tiers 0 to 2.
+- **Why we make it:** Output is the best available measure of how much of a sector's supply each country provides, and it is available only for countries with IO tables.
+- **How it affects results:** The regional factor reflects the region's largest producers. Where a region's Tier 3 members produce differently from its Tier 0 to 2 members, their purchases are better represented by their own country factors.
+:::
+
+:::{seealso} Learn more
+- Calculating total requirements and multipliers: the standard textbook on IO analysis [@millerInputoutputAnalysisFoundations2022]
+- How BEA builds the U.S. IO accounts, including margins and price bases [@beaConceptsMethodsUS2009]
+- How to choose between producer and purchaser price: [](user-guidance.md#choose-between-purchaser-and-producer-price)
+- What each published table contains: [](whats-in-a-release.md)
+:::
+
++++
+
+:::{div}
+:class: page-status
+Applies to: 2026-rc.1 · Last reviewed: 2026-rc.1
+:::