feat: parametrize assessment year to 2020, 2022, or 2024

README.md

@@ -81,7 +81,7 @@ export GOOGLE_APPLICATION_CREDENTIALS="${HOME}/.config/gcloud/application_defaul
 
 ### Running the pipeline
 
-Every stage is scoped by one or more **ISO 3166 alpha-3 country codes**, or by `--backfill` for a global run. Stage 4 additionally takes a `--methodology-name` (`STATISTICAL`, `JURISDICTIONAL_DIRECT` or `JURISDICTIONAL_DIRECT_PROXY`), and stage 5 takes the first two. The example below reproduces Honduras via the statistical leg. Honduras is the cheapest end-to-end run in the corpus: the unit of work is a 10° tile, and it falls inside a single one (`20N_090W`). Swap in `USA` for the jurisdictional-direct leg, which needs the US-only CDL and NASS inputs:
+Every stage is scoped by one or more **ISO 3166 alpha-3 country codes**, or by `--backfill` for a global run. Stage 4 additionally takes a `--methodology-name` (`STATISTICAL`, `JURISDICTIONAL_DIRECT` or `JURISDICTIONAL_DIRECT_PROXY`), and stage 5 takes the first two. Stages 3–5 also take `--assessment-year` (2020, 2022 or 2024; 2020 by default), the year the emissions factors describe and the end of their 20-year lookback. Ingest and harmonize keep every year of each dataset, so they take no year and serve every assessment year alike. The example below reproduces Honduras via the statistical leg. Honduras is the cheapest end-to-end run in the corpus: the unit of work is a 10° tile, and it falls inside a single one (`20N_090W`). Swap in `USA` for the jurisdictional-direct leg, which needs the US-only CDL and NASS inputs:
 
 ```bash
 # 1. Ingest each source dataset for the countries (positional: dataset, then ISO codes).

docs/data.md

@@ -57,7 +57,7 @@ harmonized = xarray.open_zarr("<scratch-root>/<cache-key>.zarr", consolidated=Fa
 
 Written by the `emit` stage; a pipeline output, not a published artifact (see [Access](#access)).
 
-The crop-agnostic, per-pixel LUC emissions produced by the `emit` stage, undiscounted. A conversion is dated to the year its source class ended, `conversion-year`, and each allocation leg discounts the emissions by that year (see [`methodology.md`](methodology.md)).
+The crop-agnostic, per-pixel LUC emissions produced by the `emit` stage for one assessment year, undiscounted. A conversion is dated to the year its source class ended, `conversion-year`, within the 20 years ending at the assessment year, and each allocation leg discounts the emissions by that year (see [`methodology.md`](methodology.md)).
 
 | Variable                                       | Type    | Units           | Description                                                                                                                 |
 | ---------------------------------------------- | ------- | --------------- | --------------------------------------------------------------------------------------------------------------------------- |
@@ -82,7 +82,7 @@ emissions = xarray.open_zarr("<scratch-root>/<cache-key>.zarr", consolidated=Fal
 
 Deposited per data version as `emissions-factors.parquet` (see [Access](#access)).
 
-The final per-(jurisdiction, commodity) table produced by the `trace` stage. Indexed by `(admin_level, admin_id, commodity_id, methodology)`, where `admin_level` is `PROVINCIAL` (World Bank admin-1) or `NATIONAL` (admin-0, summed from provincial rows), `methodology` is `JURISDICTIONAL_DIRECT`, `STATISTICAL` or `JURISDICTIONAL_DIRECT_PROXY`, and `commodity_id` is an integer: the FAOSTAT item code where FAOSTAT has an item, and a negative code of our own where it does not. `commodity_name` holds FAOSTAT's item name (`Maize (corn)`, `Soya beans`), or our own name for a negative code. All three legs use the same codes, so the same crop has the same `commodity_id` in each. Where MapSPAM splits one FAOSTAT item in two, the statistical leg publishes one row: arabica and robusta coffee add together as 656 (`Coffee, green`), and pearl and small millet as 79 (`Millet`). The statistical leg's `OTHER_OILCROPS` (-201) and `OTHER_PULSES` (-202) are MapSPAM groups of several FAOSTAT items, so they take codes of our own, as do the proxy leg's 16 fodder crops (-101 to -116), which FAOSTAT has no item for. [`coverage.md`](coverage.md#crops) lists each leg's crops with their codes.
+The final per-(jurisdiction, commodity) table produced by the `trace` stage. Indexed by `(admin_id, admin_level, assessment_year, commodity_id, methodology)`, where `assessment_year` is the year the factors describe (2020, 2022 or 2024), `admin_level` is `PROVINCIAL` (World Bank admin-1) or `NATIONAL` (admin-0, summed from provincial rows), `methodology` is `JURISDICTIONAL_DIRECT`, `STATISTICAL` or `JURISDICTIONAL_DIRECT_PROXY`, and `commodity_id` is an integer: the FAOSTAT item code where FAOSTAT has an item, and a negative code of our own where it does not. `commodity_name` holds FAOSTAT's item name (`Maize (corn)`, `Soya beans`), or our own name for a negative code. All three legs use the same codes, so the same crop has the same `commodity_id` in each. Where MapSPAM splits one FAOSTAT item in two, the statistical leg publishes one row: arabica and robusta coffee add together as 656 (`Coffee, green`), and pearl and small millet as 79 (`Millet`). The statistical leg's `OTHER_OILCROPS` (-201) and `OTHER_PULSES` (-202) are MapSPAM groups of several FAOSTAT items, so they take codes of our own, as do the proxy leg's 16 fodder crops (-101 to -116), which FAOSTAT has no item for. [`coverage.md`](coverage.md#crops) lists each leg's crops with their codes.
 
 Four rows are not crops. Beef, 867 (`Meat of cattle with the bone, fresh or chilled`), is a livestock commodity: it carries its share of pasture's emissions and area, and production like a crop's. `PASTURE` (-3) keeps the rest of pasture's share, with emissions and area but no production. `DROPPED` (-1) and `UNATTRIBUTED` (-2) appear in every leg and are not commodities at all. `UNATTRIBUTED` holds emissions that count toward the jurisdiction's total but that none of the commodities we model takes, so the commodity rows plus `UNATTRIBUTED` add up to that total. `DROPPED` holds carbon released where, as far as our maps show, the land became neither cropland nor pasture; it does not count toward the total and comes on top of it. `PASTURE`, `DROPPED`, `UNATTRIBUTED` and the fodder crops have no production figure, so none of them has an emissions factor. See "Rows that name no commodity" in [`methodology.md`](methodology.md).
 
@@ -109,4 +109,4 @@ import pandas
 emission_factors = pandas.read_parquet("emissions-factors.parquet")
 ```
 
-The `attribute` stage writes an intermediate rollup parquet indexed by `(admin_level, admin_id, commodity_name, methodology)`, where `commodity_name` is the leg's own name for the commodity (a CDL crop for the direct leg, a MapSPAM crop for the statistical leg, a CROPGRIDS crop for the proxy leg, `BEEF_CATTLE` for beef), with the non-derived subset of these columns (`commodity_hectares`, `peatland_commodity_hectares`, `emissions_mt`, `peatland_occupation_emissions_mt`, `forest_emissions_mt`, `grassland_emissions_mt`, `peatland_conversion_emissions_mt`, and the herd's heads: for the statistical leg `production_mt` and the heads at each MapSPAM snapshot, `herd_heads_2000` to `herd_heads_2020`, and for the proxy leg the heads in 2020, `herd_heads_2020`); `trace` maps those names onto `commodity_id`, adding together the rows that share one, joins production and appends the ratio columns (`production_kg`, `yield_kg_per_ha`, `emissions_factor_kgco2e_per_kg`).
+The `attribute` stage writes an intermediate rollup parquet indexed by `(admin_id, admin_level, assessment_year, commodity_name, methodology)`, where `commodity_name` is the leg's own name for the commodity (a CDL crop for the direct leg, a MapSPAM crop for the statistical leg, a CROPGRIDS crop for the proxy leg, `BEEF_CATTLE` for beef), with the non-derived subset of these columns (`commodity_hectares`, `peatland_commodity_hectares`, `emissions_mt`, `peatland_occupation_emissions_mt`, `forest_emissions_mt`, `grassland_emissions_mt`, `peatland_conversion_emissions_mt`, and the herd's heads: for the statistical leg `production_mt` and the heads at each MapSPAM snapshot, `herd_heads_2000` to `herd_heads_2020`, and for the proxy leg the heads in 2020, `herd_heads_2020`); `trace` maps those names onto `commodity_id`, adding together the rows that share one, joins production and appends the ratio columns (`production_kg`, `yield_kg_per_ha`, `emissions_factor_kgco2e_per_kg`).

docs/executive_summary.md

@@ -19,7 +19,7 @@ This document is aimed at readers assessing how the methodology maps to the LSRS
 
 ## Data output
 
-The published deliverable is a single per-(jurisdiction, commodity) table — the **emissions-factors parquet** — indexed by `(admin_level, admin_id, commodity_id, methodology)`, where `admin_level` is `NATIONAL` or `PROVINCIAL`, `admin_id` is the ISO 3166 alpha-3 code nationally and the World Bank admin-1 code provincially, `commodity_id` is the FAOSTAT item code (or a negative code of our own where FAOSTAT has none) with its name in `commodity_name`, and `methodology` is `JURISDICTIONAL_DIRECT`, `STATISTICAL` or `JURISDICTIONAL_DIRECT_PROXY`. Each row carries the headline emissions factor and the quantities behind it; all three legs emit the same columns. The full schema is in [`data.md`](data.md#3-emissions-factors-parquet).
+The published deliverable is a single per-(jurisdiction, commodity) table — the **emissions-factors parquet** — indexed by `(admin_id, admin_level, assessment_year, commodity_id, methodology)`, where `admin_id` is the ISO 3166 alpha-3 code nationally and the World Bank admin-1 code provincially, `admin_level` is `NATIONAL` or `PROVINCIAL`, `assessment_year` is the year the factors describe (2020, 2022 or 2024), `commodity_id` is the FAOSTAT item code (or a negative code of our own where FAOSTAT has none) with its name in `commodity_name`, and `methodology` is `JURISDICTIONAL_DIRECT`, `STATISTICAL` or `JURISDICTIONAL_DIRECT_PROXY`. Each row carries the headline emissions factor and the quantities behind it; all three legs emit the same columns. The full schema is in [`data.md`](data.md#3-emissions-factors-parquet).
 
 | Column                           | Units        | What it is                                                                                                                                          |
 | -------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |