Package 'whep'

Description

Add a new column to an existing tibble with the corresponding code for each name. The codes are assumed to be from those defined by the FABIO model.

Usage

add_area_code(table, name_column = "area_name", code_column = "area_code")

Arguments

Value

A tibble with all the contents of table and an extra column named code_column, which contains the codes. If there is no code match, an NA is included.

Examples

table <- tibble::tibble(
  area_name = c("Armenia", "Afghanistan", "Dummy Country", "Albania")
)

add_area_code(table)

table |>
  dplyr::rename(my_area_name = area_name) |>
  add_area_code(name_column = "my_area_name")

add_area_code(table, code_column = "my_custom_code")

Description

Add a new column to an existing tibble with the corresponding name for each code. The codes are assumed to be from those defined by the FABIO model, which them themselves come from FAOSTAT internal codes. Equivalences with ISO 3166-1 numeric can be found in the Area Codes CSV from the zip file that can be downloaded from FAOSTAT. TODO: Think about this, would be nice to use ISO3 codes but won't be enough for our periods.

Usage

add_area_name(table, code_column = "area_code", name_column = "area_name")

Arguments

Value

A tibble with all the contents of table and an extra column named name_column, which contains the names. If there is no name match, an NA is included.

Examples

table <- tibble::tibble(area_code = c(1, 2, 4444, 3))

add_area_name(table)

table |>
  dplyr::rename(my_area_code = area_code) |>
  add_area_name(code_column = "my_area_code")

add_area_name(table, name_column = "my_custom_name")

Description

Split footprint rows by the area that supplied the final-demand product, using shares from y_mat. This preserves the standard footprint totals while adding a FABIO-viewer style phase: origin product -> product/supplier area -> product -> final-demand area.

This is a compact global-view helper. It does not recompute the full origin-sector by product-sector Leontief cube. Instead, each existing footprint row is allocated over the product-area shares observed in final demand for the same target_area, target_fd, and target_item.

Usage

add_footprint_product_stage(
  footprints,
  y_mat,
  labels,
  fd_labels,
  max_product_areas = 5,
  other_area_name = "Other",
  min_share = 0
)

Arguments

Value

footprints with product_area, product_area_name, product_item, and product_share columns. value is replaced by the split path value.

Examples

# One footprint row of 100, split over the two areas that supply item 20 to
# the final demand of area 1 in the shares observed in `y_mat` (80 / 20).
footprints <- tibble::tibble(
  origin_area = 1L,
  origin_item = 10L,
  target_area = 1L,
  target_area_name = "Target",
  target_item = 20L,
  target_fd = "food",
  value = 100
)

add_footprint_product_stage(
  footprints = footprints,
  y_mat = Matrix::Matrix(c(80, 20), nrow = 2, sparse = TRUE),
  labels = tibble::tibble(
    area_code = c(1L, 2L),
    item_cbs_code = c(20L, 20L)
  ),
  fd_labels = tibble::tibble(area_code = 1L, fd_col = "food")
) |>
  dplyr::select(origin_item, product_area, product_share, value)

Description

Add a new column to an existing tibble with the corresponding code for each commodity balance sheet item name. The codes are assumed to be from those defined by FAOSTAT.

Usage

add_item_cbs_code(
  table,
  name_column = "item_cbs_name",
  code_column = "item_cbs_code"
)

Arguments

Value

A tibble with all the contents of table and an extra column named code_column, which contains the codes. If there is no code match, an NA is included.

Examples

table <- tibble::tibble(
  item_cbs_name = c("Cottonseed", "Eggs", "Dummy Item")
)
add_item_cbs_code(table)

table |>
  dplyr::rename(my_item_cbs_name = item_cbs_name) |>
  add_item_cbs_code(name_column = "my_item_cbs_name")

add_item_cbs_code(table, code_column = "my_custom_code")

Description

Add a new column to an existing tibble with the corresponding name for each commodity balance sheet item code. The codes are assumed to be from those defined by FAOSTAT.

Usage

add_item_cbs_name(
  table,
  code_column = "item_cbs_code",
  name_column = "item_cbs_name"
)

Arguments

Value

A tibble with all the contents of table and an extra column named name_column, which contains the names. If there is no name match, an NA is included.

Examples

table <- tibble::tibble(item_cbs_code = c(2559, 2744, 9876))
add_item_cbs_name(table)

table |>
  dplyr::rename(my_item_cbs_code = item_cbs_code) |>
  add_item_cbs_name(code_column = "my_item_cbs_code")

add_item_cbs_name(table, name_column = "my_custom_name")

Description

Add a new column to an existing tibble with the corresponding code for each production item name. The codes are assumed to be from those defined by FAOSTAT.

Usage

add_item_prod_code(
  table,
  name_column = "item_prod_name",
  code_column = "item_prod_code"
)

Arguments

Value

A tibble with all the contents of table and an extra column named code_column, which contains the codes. If there is no code match, an NA is included.

Examples

table <- tibble::tibble(
  item_prod_name = c("Rice", "Cabbages", "Dummy Item")
)
add_item_prod_code(table)

table |>
  dplyr::rename(my_item_prod_name = item_prod_name) |>
  add_item_prod_code(name_column = "my_item_prod_name")

add_item_prod_code(table, code_column = "my_custom_code")

Description

Add a new column to an existing tibble with the corresponding name for each production item code. The codes are assumed to be from those defined by FAOSTAT.

Usage

add_item_prod_name(
  table,
  code_column = "item_prod_code",
  name_column = "item_prod_name"
)

Arguments

Value

A tibble with all the contents of table and an extra column named name_column, which contains the names. If there is no name match, an NA is included.

Examples

table <- tibble::tibble(item_prod_code = c(27, 358, 12345))
add_item_prod_name(table)

table |>
  dplyr::rename(my_item_prod_code = item_prod_code) |>
  add_item_prod_name(code_column = "my_item_prod_code")

add_item_prod_name(table, name_column = "my_custom_name")

Description

Places the bedding supply from build_residue_bedding_supply() onto the litter-using, non-grazing streams of a split_manure_management() result, in proportion to the nitrogen each of those streams already carries. Grazing deposition (Pasture/Range/Paddock) never receives bedding, which is what keeps its manure the fresh excreta it is.

The result is the input rows plus dm_bedding, n_bedding and c_bedding, which apply_management_losses() then adds to the manure applied to land.

Usage

add_manure_bedding(split, bedding, options = list())

Arguments

Value

The split rows with dm_bedding, n_bedding, c_bedding and method_bedding_mms.

Which systems use litter

IPCC 2019 Refinement Vol. 4 Ch. 10 p. 10.94 defines NbeddingMS as the bedding nitrogen "to be applied for solid storage and deep bedding MMS if known organic bedding usage". WHEP's "Poultry Manure" is the deep-litter system (it takes its EF3 from the IPCC "Poultry Manure - Deep Litter" row), so the IPCC pair is "Solid Storage" and "Poultry Manure" and that is the default. "with_daily_spread" additionally beds "Daily Spread", the manure scraped from a barn and spread the same day, which is bedded in practice but which IPCC does not name; it is selectable rather than default for that reason. Liquid and lagoon systems are excluded under both, since straw cannot be pumped.

Moving bedding onto "Daily Spread" as well spreads the same mass over more nitrogen, so it lowers the bedding placed per tonne of solid-storage manure and raises the applied C:N of the daily-spread stream instead; it moves no total.

Examples

excretion <- tibble::tribble(
  ~year, ~territory, ~sub_territory, ~livestock_category,
  ~n_excretion, ~c_excretion, ~vs_excretion,
  2020L, "203", NA, "Cattle_milk", 100, 1000, 210
)
bedding <- tibble::tibble(
  year = 2020L, territory = "203",
  bedding_dm_t = 50, bedding_c_t = 22, bedding_n_t = 0.3
)
add_manure_bedding(split_manure_management(excretion), bedding)

Description

Adds periodized polity_code information from polity_area_crosswalk to a table with FAOSTAT/FABIO area_code values. If a year column is present, the mapping is year-aware; otherwise the current/default mapping is used.

When no mapped period covers a row's year, another period of the same area is used as a stand-in and mapping_status reports "out_of_span" rather than the crosswalk's "matched"/"manual". Such a row is attributed to a polity that did not exist in that year, so treat it as a coverage gap: either the area needs the missing period added to the crosswalk, or the reporting area outlived (or predates) every polity mapped to it.

Usage

add_polity_code(
  table,
  code_column = "area_code",
  year_column = "year",
  polity_code_column = "polity_code",
  backcast_anchor = 1961L,
  backcast_polity = NULL
)

Arguments

Value

A tibble with added polity metadata columns.

The status vocabulary

mapping_status here is a property of resolving one ⁠(area_code, year)⁠, not the same column as polity_area_crosswalk's, which is a property of a published crosswalk row (whep#637). The resolver carries the selected crosswalk row's own status through, and overwrites it wherever the resolution substituted something for a real period hit:

• "matched" / "manual": the year fell inside the polity's period, and the value is the crosswalk row's own provenance, carried through.

• "backcast_anchor": the row is before backcast_anchor, so it was resolved at the anchor year (or at 2023 under backcast_polity = "present_day"), and the polity live then is not live in the row's own year. That polity is still the honest label – the value is a reconstruction on the anchor year's territory – but the row is no evidence the polity existed then, which is exactly what "matched" asserts. FAOSTAT area 238 reads ETH-1952-1993 from 1850, 102 years before that polity began: "backcast_anchor" for 1850-1951, "matched" from 1952. A pre-anchor row whose anchor polity does cover its own year keeps "matched".

• "out_of_span": no mapped period covered even the anchored year, so a nearest-period stand-in was used.

• "unmapped", or NA: no polity at all, carried through from the crosswalk or left by an area with no applicable period. polity_code is NA too.

"backcast_anchor" and "out_of_span" exist only here, so a tibble carrying either is unambiguously this column and not the crosswalk's. The two still overlap in "matched", "manual" and "unmapped", which is whep#637 and is not resolved here.

Which stand-in is picked

A period that has not started yet is preferred over one that has already ended, and only then is the nearest in years taken. Ranking by distance alone split one reporting area's series between two entities at whichever year the arithmetic flipped: FAOSTAT area 178 Eritrea read ERI-1889-1952 (the Italian colonial administration) up to 1972 and ERI-1993-2025 from 1973, and area 273 Montenegro split at 1961 between MNE-1913-1918 and MNE-2006-2025 on a one-year margin. Preferring the not-yet-started period keeps each area on one entity and agrees with the back-cast anchor, whose purpose is to avoid resolving back-cast rows onto a larger historical-extent period. Set options(whep.polity_stand_in = "nearest") to restore ranking by distance alone; it changes 235 of the crosswalk's 46,640 ⁠(area, year)⁠ pairs over 1850-2025, all of them areas 178 and 273 (whep#705).

Which territory a back-cast row names

A row before backcast_anchor has two territorial references, and they differ wherever a territory changed after the anchor (whep#748). Its level is the area's value at the anchor, walked backwards by fill_proxy_growth(), so it describes the anchor year's territory. Its year-on-year movement is a ratio of LUH2 land keyed on present-day ISO3, so it describes today's territory. polity_anchor_drift() reports where the two differ. backcast_polity chooses which one the label names:

• "anchor" (default): the polity live at backcast_anchor, the territory of the level. Area 238 Ethiopia reads ETH-1952-1993, which includes Eritrea, from 1850 to 1992.

• "present_day": the polity live in 2023, the territory of the movement and the reference year polity_anchor_drift() measures against. Area 238 reads ETH-1993-2025 from 1850 to 1960, ETH-1952-1993 from 1961 to 1992 and ETH-1993-2025 after. An area with no polity live in 2023, such as 15 Belgium-Luxembourg or 248 Yugoslav SFR, keeps its anchor polity, because there is no present-day territory to name.

Either way the row's mapping_status is "backcast_anchor" where the polity named is not live in the row's own year. Neither choice moves a value of the table being labelled or a polity_area_code bucket: over the crosswalk's 1850-1960 grid, "present_day" relabels 5,106 ⁠(area, year)⁠ pairs of 46 areas and leaves every bucket where it was. A consumer that joins on reporting_polity_code follows the label it is given.

Without an explicit argument the session option options(whep.backcast_polity = ) decides, and it is the same switch every published output's reporting_polity_code and partner_polity_code follow, so one setting relabels them all consistently.

See Also

polity_coverage_gaps(), which reports the "out_of_span" and "backcast_anchor" rows of an already-built table, whose published columns no longer carry mapping_status.

Examples

# The same area code resolves to different polities in different years:
# area 16 reports as East Pakistan before 1971 and as Bangladesh after it.
tibble::tibble(area_code = c(16L, 16L), year = c(1965L, 2000L)) |>
  add_polity_code() |>
  dplyr::select(area_code, year, polity_code, polity_name, mapping_status)

# Without a year column the current/default mapping is used.
add_polity_code(tibble::tibble(area_code = 231L), year_column = NULL) |>
  dplyr::select(area_code, polity_code, polity_name)

Description

The schema of admin_coverage.csv, which run_spatialize() writes beside run_metadata.yaml whenever a run requests a depth. One row per container x item x year, saying which admin source constrained it and at what grain. The populated table is produced by the T25 resolver; until a run is wired to one, the file is written with this header and no rows, so a reader can tell "no coverage was granted" from "the file was never written".

It IS the resolver's own coverage schema, returned rather than restated: this function had a second, hand-written list of names (source, tier, grain, and a character not_shipped) where resolve_admin_shares() emits resolved_source, resolved_tier, resolved_grain and a logical, so handing the resolver's table to the writer aborted on three missing columns, and the writer's subset would have dropped the resolution audit trail (resolved_indicator, resolved_nuts_version, resolution_rule) from the file.

Usage

admin_coverage_prototype()

Value

A zero-row tibble with the report's columns.

Examples

admin_coverage_prototype()

Description

The 79 classes of the crops dimension shared by the apro_cpshr and apro_cpnhr_h dataflows, each mapped to its WHEP item_prod_code or recorded as dropped. See admin_source_vocabularies for the columns, the mapping kinds and the rules encoded here.

Usage

admin_items_eurostat

Format

A tibble with one row per Eurostat crop class and the eight ⁠admin_items_*⁠ columns of admin_source_vocabularies.

Source

Eurostat dissemination API (https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1), dataflows apro_cpshr, apro_cpnhr_h, apro_mt_ls_r and ef_lsk_poultry; IBGE SIDRA aggregate metadata (https://servicodados.ibge.gov.br/api/v3/agregados), tables 5457, 3939 and 94; Ronchetti, G. et al. (2024). Harmonized European Union subnational crop statistics reveal climate impacts and crop cultivation shifts. Earth System Science Data, 16, 1623-1649. doi:10.5194/essd-16-1623-2024; USDA National Agricultural Statistics Service, Quick Stats bulk downloads (https://www.nass.usda.gov/datasets/).

See Also

admin_source_vocabularies, crops_eurostat

Examples

head(admin_items_eurostat)

Description

The nine crop classes of release 2025.01 of the JRC harmonised EU subnational crop statistics. Two of them, "Total wheat" and "Total barley", are aggregates of members the same release also publishes, so summing all nine would double-count wheat and barley; the aggregates bind and their members are recorded but never summed alongside them. See admin_source_vocabularies for the columns, the mapping kinds and the rules encoded here.

Usage

admin_items_jrc

Format

A tibble with one row per JRC crop class and the eight ⁠admin_items_*⁠ columns of admin_source_vocabularies.

Source

Eurostat dissemination API (https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1), dataflows apro_cpshr, apro_cpnhr_h, apro_mt_ls_r and ef_lsk_poultry; IBGE SIDRA aggregate metadata (https://servicodados.ibge.gov.br/api/v3/agregados), tables 5457, 3939 and 94; Ronchetti, G. et al. (2024). Harmonized European Union subnational crop statistics reveal climate impacts and crop cultivation shifts. Earth System Science Data, 16, 1623-1649. doi:10.5194/essd-16-1623-2024; USDA National Agricultural Statistics Service, Quick Stats bulk downloads (https://www.nass.usda.gov/datasets/).

See Also

admin_source_vocabularies

Examples

head(admin_items_jrc)

Description

The Quick Stats SHORT_DESC crop series the subnational spatialization reads, each mapped to its WHEP item_prod_code. See admin_source_vocabularies for the columns, the mapping kinds and the rules encoded here.

Usage

admin_items_nass

Format

A tibble with one row per NASS series and the eight ⁠admin_items_*⁠ columns of admin_source_vocabularies.

Source

Eurostat dissemination API (https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1), dataflows apro_cpshr, apro_cpnhr_h, apro_mt_ls_r and ef_lsk_poultry; IBGE SIDRA aggregate metadata (https://servicodados.ibge.gov.br/api/v3/agregados), tables 5457, 3939 and 94; Ronchetti, G. et al. (2024). Harmonized European Union subnational crop statistics reveal climate impacts and crop cultivation shifts. Earth System Science Data, 16, 1623-1649. doi:10.5194/essd-16-1623-2024; USDA National Agricultural Statistics Service, Quick Stats bulk downloads (https://www.nass.usda.gov/datasets/).

See Also

admin_source_vocabularies

Examples

head(admin_items_nass)

Description

The 72 categories of classification 782 of SIDRA table 5457 (Producao Agricola Municipal), each mapped to its WHEP item_prod_code or recorded as dropped. Category "0" is the all-crops total and is dropped as such. See admin_source_vocabularies for the columns, the mapping kinds and the rules encoded here.

Usage

admin_items_sidra

Format

A tibble with one row per SIDRA crop category and the eight ⁠admin_items_*⁠ columns of admin_source_vocabularies.

Source

Eurostat dissemination API (https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1), dataflows apro_cpshr, apro_cpnhr_h, apro_mt_ls_r and ef_lsk_poultry; IBGE SIDRA aggregate metadata (https://servicodados.ibge.gov.br/api/v3/agregados), tables 5457, 3939 and 94; Ronchetti, G. et al. (2024). Harmonized European Union subnational crop statistics reveal climate impacts and crop cultivation shifts. Earth System Science Data, 16, 1623-1649. doi:10.5194/essd-16-1623-2024; USDA National Agricultural Statistics Service, Quick Stats bulk downloads (https://www.nass.usda.gov/datasets/).

See Also

admin_source_vocabularies

Examples

head(admin_items_sidra)

Description

The zero-row tibble admin_shares_schema() describes: the declared columns, in the declared order, each with the declared type. Built with empty_table_from_schema(), so it passes check_table_schema() by construction and cannot drift from the schema. See admin_shares_schema() for the full column-by-column contract.

Usage

admin_shares_prototype()

Value

A zero-row tibble with the admin-shares contract's columns, in contract order.

Examples

admin_shares_prototype()
nrow(check_table_schema(admin_shares_prototype(), admin_shares_schema()))

Description

Declare, as data, the shared row shape every admin-shares reader emits and every admin-shares consumer reads: one subnational administrative unit's reported value and its share of the FAOSTAT container's total, for one ⁠(item_prod_code, indicator_used, year)⁠. Readers emit source-native identifiers and never resolve names to WHEP codes here; a later resolution step reconciles those once. Unresolved rows keep level_polity_code == NA visibly rather than being dropped.

There are two measurement columns, value and share, and a row must carry at least one of them. value may be missing wherever share is present, which is a first-class case created by a publication consent and not a gap to be filled; see the section below before writing anything that assumes an absolute value is there.

admin_shares_schema() is the check_table_schema() contract itself; admin_shares_prototype() is the zero-row tibble it implies, and the two cannot drift apart because the prototype is built from the schema with empty_table_from_schema().

Usage

admin_shares_schema()

Value

A schema list, as documented in check_table_schema(): closed (extra_columns = "forbid"), keyed on ⁠(area_code, level_polity_code, level, item_prod_code, species_group, indicator_used, year)⁠.

Admin-shares table

One row per ⁠(area_code, level_polity_code, level, item_prod_code, species_group, indicator_used, year)⁠:

• area_code: FAOSTAT-style area code of the container – the polity the subnational units sum into, not the unit itself.

• level_polity_code: the polity code resolved at the row's granted depth (level); NA when that depth is not yet resolved to a polity.

• level: administrative depth granted for this row, a positive integer (1L is the container's direct subnational units).

• item_prod_code: WHEP production-item code (see add_item_prod_code() / add_item_prod_name()) on a crop row; NA on a livestock row.

• species_group: the livestock group a livestock row counts, in the vocabulary build_gridded_livestock() allocates in ("cattle_dairy", "pigs", "sheep_goats", ...); NA on a crop row. A row names exactly one of item_prod_code and species_group.

• indicator_used: which indicator this row's value anchors to, one of "area_harvested", "area_planted_or_sown", "area_main", "area_cultivated", "production", "yield" for a crop row, or "head_count" (live animals, head) for a livestock row.

• year: calendar year of the observation.

• value: the unit's own reported value for indicator_used, in the source's native unit. NA on a row whose source is consented to ship shares only – see Shares-only rows below. Never invented.

• share: the unit's own value divided by the admin sum across sibling units for the same ⁠(area_code, level, item_prod_code, indicator_used, year)⁠, taken by the row's own producer over its own units. NA where the producer ships values and that sum has not been taken. This package does not fill it in at load: a share derived here from the values in the same table would make the seam gate's value-versus-share identity (R/admin_shares_gate.R, tier A) true by construction, and an identity that cannot fail detects nothing.

• source: dataset label of the row's producer, e.g. "USDA_NASS", "Eurostat_apro_cpshr", "Eurostat_apro_cpnhr_h", "Eurostat_apro_mt_ls_r", "Eurostat_ef_lsk_poultry", "IBGE_PAM", "IBGE_PPM", "JRC_subnational_crops", or a tier-2/3 admin-statistics family label. Documented here, not enforced as a closed vocabulary: later tiers add sources this list cannot enumerate in advance, unlike indicator_used, grain and treatment_year, which the contract does close. A caller may therefore put any label here, and resolve_admin_shares() will rank it. Where the vocabulary is closed is at the pin boundary: every source in the assembled admin-shares pin must be declared before read_admin_shares() will hand it over, because that artifact carries sources whose values are withheld by a publication consent and an undeclared label is indistinguishable from a new one.

• tier: data tier of the source, 1L-3L.

• grain: the reporting geography's fineness, one of "admin1", "admin2", "admin3", in that ascending order. Stored as character rather than an R ordered factor: check_table_schema()'s type vocabulary (R/table_schema.R) has no factor type, so the ordering is carried by the vocabulary's declared order rather than by the column's R class. A caller needing genuine ordered comparisons can do factor(grain, levels = c("admin1", "admin2", "admin3"), ordered = TRUE).

• concept_break: whether the item concept changed where this row's source or grain took over from another.

• nuts_version: the NUTS nomenclature version the row's geography was coded under, NA outside NUTS geographies.

• source_native_id: the row's identifier exactly as the reader found it in the source; NA for a row with no native identifier, e.g. one derived rather than read (such as a residual).

• source_native_name: the row's name exactly as the reader found it, diagnostic only – never joined or matched on.

• source_id: the producer's immutable identifier, in row_evidence()'s vocabulary (R/row_evidence.R) – the same value space as source, so an admin-shares table can be handed to the row-evidence family without renaming.

• source_version: version or vintage of that source, NA when the producer has none, exactly as row_evidence() documents it.

• recorded_at: when the row was recorded, as an ISO 8601 UTC string ("2026-01-01T00:00:00Z"), the same stamp shape row_evidence() writes.

• treatment_year: how this row's year was obtained, one of "observed", "interpolated", "carried". Reserved for the gap rule; this contract only names the vocabulary.

• treatment_value: how the row's value was obtained, "observed" (reported by the unit) or "reconstructed" (derived by the source, e.g. from a national total). NA when the source does not say, which is every source today; it is never defaulted to "observed".

• value_flag: a free-text data-quality flag, NA when the row is clean.

Shares-only rows

A row may carry share and no value. That is not a defect, not a missing observation and not a gap for a later step to fill: it is what a publication consent produces, and the contract admits it on purpose.

The Latin American subnational panel of Infante-Amate, Urrego-Mesa, Badia-Miro and Aguilera ships to WHEP as derived shares only – 875,514 rows over 142 first-level units of Argentina, Bolivia, Brazil, Chile, Colombia and Mexico – under the co-author agreement of 2026-09-02 recorded in inst/extdata/admin_stats_pins_manifest.csv. Its source values are withheld until that panel's own publication, so WHEP may carry each unit's share of its container's total and nothing else. Five of those six countries have no other subnational evidence in this package. Demanding a value would therefore not have improved the data: it would have dropped five countries out of the subnational constraint while every balance and conservation check still passed.

A synthetic value is forbidden, in both the forms that tempt:

• value = 0 satisfies the contract and then enters the allocation as a reported area of zero – a claim the source never made, and one that a downstream reader cannot tell from a real zero.

• a value back-computed as ⁠share * national total⁠ satisfies it too, and additionally reconstructs the quantity the consent withheld.

Neither is acceptable, and finding either in code is a defect to report rather than a shortcut to reuse. A shares-only row travels as a shares-only row: resolve_admin_shares() ranks candidates on indicator, grain, tier and run length, none of which reads value, and allocate_level_crops() (R/spatialize_levels.R) carries a "share_normalised" denominator for exactly this case.

What the contract does still refuse is a row carrying neither measurement: ensure_admin_shares() and resolve_admin_shares() abort on one with class whep_error_admin_no_measure, because such a row constrains nothing and would enter an allocation as an invisible abstention.

It equally refuses a non-finite value or share, with class whep_error_admin_nonfinite. NaN is not a missing measurement: it is what a 0/0 leaves behind, and since is.na(NaN) is TRUE every is.na(value) branch downstream would read it as the consented shares-only case above. Inf is refused with it, which no schema bound catches either – check_table_schema() guards min and max with !is.na(values), and value has no maximum.

Examples

admin_shares_schema()

# A schema-conformant table: two sibling units of one container.
rows <- tibble::tibble(
  area_code = c(840L, 840L),
  level_polity_code = c("USA-IOWA", "USA-ILLINOIS"),
  level = c(1L, 1L),
  item_prod_code = c(44L, 44L),
  indicator_used = c("area_harvested", "area_harvested"),
  year = c(2020L, 2020L),
  value = c(1000000, 800000),
  share = c(0.42, 0.34),
  source = c("USDA_NASS", "USDA_NASS"),
  tier = c(1L, 1L),
  grain = c("admin1", "admin1"),
  concept_break = c(FALSE, FALSE),
  nuts_version = NA_character_,
  source_native_id = c("19", "17"),
  source_native_name = c("Iowa", "Illinois"),
  source_id = c("USDA_NASS", "USDA_NASS"),
  source_version = c("2021-05", "2021-05"),
  recorded_at = "2026-01-01T00:00:00Z",
  treatment_year = c("observed", "observed"),
  value_flag = NA_character_
)
nrow(check_table_schema(rows, admin_shares_schema()))

# A shares-only pair, as a consented source ships it: `share` present,
# `value` absent, and the contract satisfied.
consented <- rows |>
  dplyr::mutate(
    value = NA_real_,
    share = c(0.79, 0.21),
    source = "admin-stats-latam",
    source_id = "admin-stats-latam",
    tier = 3L
  )
nrow(check_table_schema(consented, admin_shares_schema()))

Description

Seven tables mapping the crop and livestock classes the subnational admin-statistics readers return – verbatim, in each publisher's own identifiers – onto WHEP's own item and species vocabularies. Four cover crops (⁠admin_items_*⁠) and three cover livestock (⁠admin_species_*⁠); the JRC dataset publishes no livestock, so it has no species table.

The tables are vocabulary, not data: they say what a source class means in WHEP terms and, where it means nothing exactly, that it is dropped and why. Nothing here converts, sums or reads a value.

Format

The four ⁠admin_items_*⁠ tables share eight columns:

• source: the reader's own source label ("USDA_NASS", "Eurostat", "IBGE_PAM", "JRC_subnational_crops").

• source_table: the dataflow, dump or release the class belongs to. "apro_cpshr|apro_cpnhr_h" where the two Eurostat crop dataflows share one vocabulary.

• class_key: the table's unique key, the source class code where the publisher issues one and the class name where it does not.

• source_class_code, source_class_name: the class exactly as the source publishes it. The code is NA for JRC and NASS, neither of which issues one.

• item_prod_code: the WHEP items_prod_full key, as character. NA on a dropped class.

• mapping_kind, mapping_reason: as described above.

The three ⁠admin_species_*⁠ tables carry the same columns with item_prod_code replaced by two:

• species_group: the WHEP livestock functional type of inst/extdata/livestock_mapping.csv ("cattle_dairy", "pigs", "sheep_goats", ...). NA where the class maps to no single group.

• constrains: for an "aggregate" class that maps to no single group, the "+"-joined set of groups whose sum it constrains, for example "cattle_dairy+cattle_non_dairy". NA on every other kind, which the builder enforces.

Mapping kinds

mapping_kind takes five values, and the distinction between the first four is what stops a source total being counted twice:

• "exact": one source class, one WHEP target.

• "aggregate": a total the publisher ships alongside its own members. The aggregate binds; its members are never summed alongside it.

• "member": one of those members. It is recorded so the class is accounted for rather than silently absent, and is not summed.

• "sum_member": one of several classes that do sum to the WHEP target, the publisher shipping no aggregate for them.

• "dropped": no exact WHEP counterpart. The class is never folded into a near neighbour; mapping_reason says what it is and why it could not be mapped, so a coverage report can count it.

Every row that is not "exact" carries a mapping_reason, and the builder aborts on one that does not.

The rules these tables encode

The tables decide nothing. They are the data form of the vocabulary rules fixed for the subnational spatialization, and each row's mapping_reason names the rule it applies:

• Crops. Where a publisher ships an aggregate class, that aggregate binds and its members are never summed alongside it. Maize is grain maize only, silage and forage maize excluded. A source rice area is paddy and binds item_prod_code 27. A class with no exact WHEP counterpart is dropped and counted, never folded into a near neighbour.

• Livestock. A published dairy series binds dairy cattle, and non-dairy is the total minus the dairy series, the unit-year being refused where that difference is negative. A combined sheep-and-goats class constrains their sum. Published reference dates are accepted as they are, which is why the NASS hog inventory keeps its 1 December date. A combined poultry class constrains the sum of the poultry groups.

Where the class lists come from

Each table enumerates the classes its source actually serves, taken from the source itself rather than from a reader's defaults:

• Eurostat: the crops dimension of apro_cpshr and apro_cpnhr_h (identical 79-class vocabularies), the animals dimension of apro_mt_ls_r (47 classes) and of ef_lsk_poultry (9 classes), read off the dissemination API on 2026-09-04.

• IBGE SIDRA: classification 782 of table 5457 (72 categories, one of them the all-crops total) and classification 79 of table 3939 (10 herd types), from the servicodados.ibge.gov.br metadata endpoint on 2026-09-04, plus table 94, whose single series is milked cows.

• JRC: the nine crop classes of release 2025.01 of the harmonised EU subnational crop statistics, as inst/scripts/prepare_jrc_subnational.R measured them on the pinned archive.

• USDA NASS: the Quick Stats SHORT_DESC series read_admin_stats_nass() requests, plus the silage-maize series the maize rule excludes. This is deliberately not an inventory of the NASS vocabulary: Quick Stats keys tens of thousands of series on SHORT_DESC, the bulk dump is the only complete listing of them, and no offline copy of it ships with this package.

crops_eurostat is the older, label-only Eurostat crop table (13 green fodder and root-crop codes, no WHEP target). It is left as it is; admin_items_eurostat is the vocabulary that carries the mapping, and covers those 13 codes among its 79.

Source

Eurostat dissemination API (https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1), dataflows apro_cpshr, apro_cpnhr_h, apro_mt_ls_r and ef_lsk_poultry; IBGE SIDRA aggregate metadata (https://servicodados.ibge.gov.br/api/v3/agregados), tables 5457, 3939 and 94; Ronchetti, G. et al. (2024). Harmonized European Union subnational crop statistics reveal climate impacts and crop cultivation shifts. Earth System Science Data, 16, 1623-1649. doi:10.5194/essd-16-1623-2024; USDA National Agricultural Statistics Service, Quick Stats bulk downloads (https://www.nass.usda.gov/datasets/).

See Also

read_admin_stats_nass(), read_admin_stats_eurostat(), read_admin_stats_sidra(), items_prod_full, crops_eurostat.

Description

The 47 classes of the animals dimension of apro_mt_ls_r and the nine of ef_lsk_poultry, each mapped to its WHEP species_group, to the set of groups whose sum it constrains, or recorded as a member of a binding aggregate. See admin_source_vocabularies for the columns, the mapping kinds and the rules encoded here.

Usage

admin_species_eurostat

Format

A tibble with one row per Eurostat animal class and the nine ⁠admin_species_*⁠ columns of admin_source_vocabularies.

Source

Eurostat dissemination API (https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1), dataflows apro_cpshr, apro_cpnhr_h, apro_mt_ls_r and ef_lsk_poultry; IBGE SIDRA aggregate metadata (https://servicodados.ibge.gov.br/api/v3/agregados), tables 5457, 3939 and 94; Ronchetti, G. et al. (2024). Harmonized European Union subnational crop statistics reveal climate impacts and crop cultivation shifts. Earth System Science Data, 16, 1623-1649. doi:10.5194/essd-16-1623-2024; USDA National Agricultural Statistics Service, Quick Stats bulk downloads (https://www.nass.usda.gov/datasets/).

See Also

admin_source_vocabularies

Examples

head(admin_species_eurostat)

Description

The Quick Stats inventory series the subnational spatialization reads, each mapped to its WHEP species_group or to the set of groups whose sum it constrains. See admin_source_vocabularies for the columns, the mapping kinds and the rules encoded here.

Usage

admin_species_nass

Format

A tibble with one row per NASS series and the nine ⁠admin_species_*⁠ columns of admin_source_vocabularies.

Source

Eurostat dissemination API (https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1), dataflows apro_cpshr, apro_cpnhr_h, apro_mt_ls_r and ef_lsk_poultry; IBGE SIDRA aggregate metadata (https://servicodados.ibge.gov.br/api/v3/agregados), tables 5457, 3939 and 94; Ronchetti, G. et al. (2024). Harmonized European Union subnational crop statistics reveal climate impacts and crop cultivation shifts. Earth System Science Data, 16, 1623-1649. doi:10.5194/essd-16-1623-2024; USDA National Agricultural Statistics Service, Quick Stats bulk downloads (https://www.nass.usda.gov/datasets/).

See Also

admin_source_vocabularies

Examples

head(admin_species_nass)

Description

The ten herd types of classification 79 of SIDRA table 3939 (Pesquisa da Pecuaria Municipal), plus the milked-cow series of table 94, which is the only dairy split IBGE publishes for that herd. See admin_source_vocabularies for the columns, the mapping kinds and the rules encoded here.

Usage

admin_species_sidra

Format

A tibble with one row per SIDRA herd type, plus one for table 94, and the nine ⁠admin_species_*⁠ columns of admin_source_vocabularies.

Source

Eurostat dissemination API (https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1), dataflows apro_cpshr, apro_cpnhr_h, apro_mt_ls_r and ef_lsk_poultry; IBGE SIDRA aggregate metadata (https://servicodados.ibge.gov.br/api/v3/agregados), tables 5457, 3939 and 94; Ronchetti, G. et al. (2024). Harmonized European Union subnational crop statistics reveal climate impacts and crop cultivation shifts. Earth System Science Data, 16, 1623-1649. doi:10.5194/essd-16-1623-2024; USDA National Agricultural Statistics Service, Quick Stats bulk downloads (https://www.nass.usda.gov/datasets/).

See Also

admin_source_vocabularies

Examples

head(admin_species_sidra)

Description

Sums gridded grass availability to polity (country, or subnational where available) totals, splitting each cell's grass by the cell's land-area share in each polity so border cells are attributed proportionally. The polity grass supply ceiling for feed allocation.

Usage

aggregate_grass_to_polity(
  grass,
  cell_polity,
  polity_validity = c("keep", "flag", "drop")
)

Arguments

Value

A tibble with area_code, year and grass_avail_dm_t, plus reporting_polity_out_of_span when polity_validity = "flag". This output carries no reporting-polity columns, so the flag is attached directly rather than derived from them.

Examples

grass <- build_grass_availability(method = "lpjml", example = TRUE)
cp <- tibble::tibble(
  lon = grass$lon,
  lat = grass$lat,
  area_code = 1L,
  polity_frac = 1
)
aggregate_grass_to_polity(grass, cp)

Description

Sum a per-cell land quantity onto the compartments of a granted-depth country grid, giving the per-unit extent E_u(t) the seam back-cast modulates shares with:

$E_u(t) = \sum_c E_c(t) \times f(c, u)$

where f(c, u) is cell_area_frac, the unit's share of the physical cell on the land basis. The gridded tables are the ones already in memory for the spatialization engine, so no LUH2 archive is re-read here: read_luh2_landuse() is never called, and the identity between the extent that modulates a share and the extent that weights cells within a unit holds by construction rather than by assertion. What the construction cannot prove is which LUH2 vintage the caller's tables came from; the prep-side provenance stamp on those tables carries that.

Usage

aggregate_unit_extent(
  gridded,
  country_grid,
  quantity,
  extent_by = NULL,
  container_frac = NULL,
  residual_code = NULL,
  tolerance = 1e-08
)

Arguments

Value

A tibble: area_code, level_polity_code, level, the extent_by columns, year, extent_ha and extent_basis (the weight * column terms behind the row, +-joined in a stable order). One row per unit, key and year for which at least one compartment of that unit met a gridded cell.

Mirroring the engine's land quantity

R/spatialize.R:337-405 builds the crop weight from cropland_ha = i.cropland_ha * cell_area_frac; a type-aware run replaces that with type_ha * cell_area_frac joined on ⁠(lon, lat, luh2_type)⁠, zeroes cells with no row for the crop's type, and restores total cropland for a whole ⁠(area_code, item_prod_code)⁠ group whose type potential sum(harvest_fraction * cropland_ha) is not positive. R/spatialize_livestock.R:358-405 builds the livestock weight from pasture_ha + rangeland_ha (pasture), rangeland_ha (rangeland), cropland_ha (cropland) or 0.5 * (pasture_ha + rangeland_ha) + 0.5 * cropland_ha (mixed), also times cell_area_frac.

This function mirrors the cell_area_frac multiplication and the compartment sum. Which land column stands for a given item or species group is the caller's choice, declared through quantity: a character vector applies one weighted column set to every row, a lookup table applies a different set per key. The engine's whole-group fallback to total cropland turns on harvest_fraction, a within-unit weight rather than a land extent, so the caller evaluates it and passes the resulting per-item choice in the lookup; the choice comes back on extent_basis, so the land quantity behind each row is recorded rather than inferred.

Territory basis

country_grid is used exactly as given, unfiltered by edge validity. That is the t0-geometry convention of the plan's seam section: shares and E_u are defined on the t0 unit set with t0 geometry held fixed, so a unit whose containment edge starts after a back-cast year still contributes its t0 cells at that year. Pass the layer already filtered to the t0 reference year (.filter_country_grid_year()) when the t0 geometry differs from the delivered layer.

Examples

grid <- tibble::tibble(
  lon = c(10.25, 10.75, 10.75),
  lat = 40.25,
  area_code = 900L,
  level_polity_code = c("A1", "A1", "A2"),
  level = 1L,
  cell_area_frac = c(1, 0.3, 0.5)
)
cells <- tibble::tibble(
  lon = c(10.25, 10.75),
  lat = 40.25,
  year = 1900L,
  cropland_ha = c(1000, 1200)
)
# A1 = 1000 * 1 + 1200 * 0.3 = 1360; A2 = 1200 * 0.5 = 600.
aggregate_unit_extent(cells, grid, "cropland_ha")

Description

Turn a long-format extension table into the dense per-sector numeric vector that compute_footprint() expects, ordered to match a single year's labels from build_io_model(). Sectors absent from the extension are filled with zero, and extension rows outside the model are dropped. Rows sharing an ⁠(area_code, item_cbs_code)⁠ are summed.

Usage

align_extension(extension, labels, year, value_col = "impact_u")

Arguments

Value

A numeric vector with one entry per row of labels, ordered by the label index.

Examples

extension <- tibble::tibble(
  year = 2000L,
  area_code = 1L,
  item_cbs_code = 10L,
  impact_u = 5
)
labels <- tibble::tibble(
  index = 1:2,
  area_code = c(1L, 1L),
  item_cbs_code = c(10L, 20L)
)
align_extension(extension, labels, 2000L)

Description

Push grazing land forward along the feed chain instead of tracing it backward through a Leontief inverse. Grass is not traded, so the multi-regional input-output footprint leaks the grazing land that meat and dairy consumption actually drives (the feed-conversion columns make the system non-productive). This function hands every tonne of grazing land forward in two mass-conserving steps:

1. pool each country's grazing land and split it across the grazing animals that fed there, in proportion to their forage intake;

2. split each animal's share across its output products in proportion to production mass, landing the land on the meat and milk items that are actually traded.

The result is a direct-land extension keyed by livestock output item, ready to route to consumers with compute_footprint_balance(). Because each step redistributes a total without creating or destroying it, the country-level land total is conserved whenever an animal fed and produced an output there. Land fed to animals that produced no eligible output item is set aside and reported via a warning rather than silently dropped.

Usage

allocate_grazing_to_products(
  grass_land,
  grazer_intake,
  livestock_production,
  products = c("all", "meat_milk")
)

Arguments

Value

A tibble with year, area_code, item_cbs_code (a livestock output item), value (grazing land allocated to it) and method_allocation (the chosen products).

Examples

grass_land <- tibble::tibble(
  year = 2010L, area_code = 1L, value = 100
)
grazer_intake <- tibble::tibble(
  year = 2010L,
  area_code = 1L,
  live_anim_code = c(960L, 976L),
  value = c(75, 25)
)
livestock_production <- tibble::tibble(
  year = 2010L,
  area_code = 1L,
  live_anim_code = c(960L, 960L, 976L),
  item_cbs_code = c(2848L, 2731L, 2732L),
  value = c(90, 10, 5)
)
allocate_grazing_to_products(
  grass_land, grazer_intake, livestock_production
)

Description

The two-level allocation: a national total is split across the administrative units of its container by reported harvested-area shares, and each unit's target is then spread across that unit's cells by the gridded pattern the engine already uses, under one capacity ceiling, in ONE pass per country. Items with no statistics travel in the same pass on pattern-implied unit shares, so a constrained country is allocated at one grain and a cell's capacity is shared by everything in it.

Usage

allocate_level_crops(
  country_areas,
  crop_patterns,
  gridded_cropland,
  allocation_layer,
  admin_shares = NULL,
  config = list()
)

Arguments

Value

A list of seven tibbles:

• allocation: the gridded rows, at unit grain, exactly the build_gridded_landuse() schema plus level_polity_code.

• targets: one row per ⁠(year, area_code, level_polity_code, item_prod_code)⁠ with share, target_ha, irrigated_target_ha, rainfed_target_ha, irrigation_clipped_ha and the regime, method_crop_alloc.

• coverage: one row per ⁠(year, area_code, item_prod_code)⁠ with n_units, n_units_reporting, coverage, admin_sum, residual_target_ha, discrepancy_ha and the denominator basis.

• breach: the capacity excess per ⁠(year, area_code, level_polity_code, item_prod_code, mc_basis)⁠.

• straddle: per unit and item, n_cells, straddle_sibling, straddle_foreign and cell_limited.

• conservation: allocated against target, at container and unit grain. The container's target is the NATIONAL total, so hectares that became no unit's target are visible here as well as in coverage$dropped_ha; the unit rows are warned about only where their container reconciles, which is the sibling-absorption failure they exist to see.

• bridges: per ⁠(area_code, item_prod_code, treatment)⁠, how many years of the shares were not observed and the longest contiguous run of them, so a 60-year LUH2 bridge is visible rather than merely legal (decision T31(e)).

The composite key and where it must be carried

A granted-depth compartment is identified by ⁠(area_code, level_polity_code)⁠: the container's integer reporting code, which every area_code-typed join, add_area_name() and the area_key switch keep working on, plus the unit's polity code from the containment edge (NA at level 0). The pair travels through the whole chain, and these are the places that had to learn it:

.compartment_id_cols()

already appends level_polity_code (T12), so every capacity, redistribution and CFT grouping keyed on it followed for free.

The engine's national-table join and share denominators

.spatialize_year() joined country_areas to the grid on ⁠(area_code, item_prod_code)⁠ and formed rf_pot_sum / ir_pot_sum / rainfed_sum / irrigated_sum on the same pair. Both now use .alloc_target_cols(), the grain the NATIONAL TABLE is keyed at. That is the load-bearing distinction: the key comes from the targets, never from the grid, because a unit-keyed grid under a container-keyed national table is the pattern-implied case and must stay one national total.

The LUH2 type-potential fallback

type_pot decides per group whether a crop has any of its LUH2 type to sit in; grouped on the container it would let one unit's type cropland keep another unit out of the whole-group fallback.

.redistribute_country_dt()

.crop_group was item_prod_code alone. It is now the target grain inside the country, so the logit passes and the final rescale conserve each (unit, item). This is the grouping error the machine criterion pins: with the item alone, a unit whose cells are too small has its excess pushed across the border into a sibling, the two units' targets swap, and every national total still reconciles.

.warn_unallocated_crops()

reports at the target grain, so a unit that cannot place its target is visible instead of being averaged into its container's success.

The capacity ceiling

.capacity_bases() keys the unit multi-cropping factor on ⁠(area_code, level_polity_code)⁠.

Two places do not carry it, for stated reasons. .redistribute_countries_dt() still iterates area_code: it is a memory bound on the per-country working set, and the compartment key is inside each subset, so splitting further would only make the chunks smaller. .compartment_interval_groups() stays on ⁠(lon, lat, area_code)⁠ because polycell_id – and, at depth, the unit code – changes at a succession, which is exactly what its open-ended-interval test must see across.

What binds, and what is only measured

• The national total binds. Admin statistics set the within-country shape and nothing else; a yield or production row never binds (decision T31(i)) and is dropped, counted, by build_level_crop_targets().

• The reported share binds inside the country. Where a unit's target does not fit its cells, the target wins and the ceiling gives way; the excess is measured per unit, at both multi-cropping bases, and returned in breach (decisions T31(c), T31(g)).

• Partial coverage raises a RESIDUAL pseudo-unit carrying national - admin_sum, supported by the non-reporting units' cells only. With complete coverage there is no residual: the reported units rescale proportionally and the leftover is a diagnostic, refused only beyond both tolerances (decisions T31(a), T31(d)).

See Also

build_level_crop_targets(), build_allocation_layer(), build_gridded_landuse().

Examples

# Two units of container 1 (Armenia), one cell each, one crop.
layer <- tibble::tribble(
  ~lon,  ~lat, ~area_code, ~level_polity_code, ~level, ~cell_area_frac,
  0.25, 50.25,         1L, "A-A1-1900-2100",       1L,               1,
  0.75, 50.25,         1L, "A-A2-1900-2100",       1L,               1
)
shares <- tibble::tribble(
  ~area_code, ~level_polity_code, ~item_prod_code, ~year, ~value,
          1L, "A-A1-1900-2100",               15L, 2000L,     150,
          1L, "A-A2-1900-2100",               15L, 2000L,     100
) |>
  dplyr::mutate(level = 1L, indicator_used = "area_harvested")
out <- allocate_level_crops(
  country_areas = tibble::tibble(
    year = 2000L, area_code = 1L, item_prod_code = 15L,
    harvested_area_ha = 250
  ),
  crop_patterns = tibble::tibble(
    lon = c(0.25, 0.75), lat = 50.25, item_prod_code = 15L,
    harvest_fraction = c(0.5, 0.5)
  ),
  gridded_cropland = tibble::tibble(
    lon = c(0.25, 0.75), lat = 50.25, year = 2000L,
    cropland_ha = c(1000, 1000)
  ),
  allocation_layer = layer,
  admin_shares = shares
)
out$targets[c("level_polity_code", "target_ha", "method_crop_alloc")]

Description

Distributes the manure nitrogen, carbon and volatile solids that survive management (the output of apply_management_losses()) across cropland crops and grassland, with a local agronomic cap and an explicit overflow path. The collected/housed manure fills cropland up to each crop's cap (weighted by West-2014 receptivity by default), the surplus spills onto grassland up to the grassland cap, and any residual beyond all reachable sinks follows the disposal_method. The in-situ grazing stream is deposited on grassland where it falls, uncapped. Carbon and volatile solids ride along with each stream at its post-storage bundle ratio, so mass is conserved by construction.

Usage

allocate_manure_to_land(applied, gridded = list(), options = list())

Arguments

Value

A tibble with one row per allocation target: year, territory, sub_territory, land_use ("Cropland"/"Grassland"/"Disposal"/ "Unallocated"), crop, source_stream ("collected"/"grazing"), manure_type ("Excreta"/"Solid"/"Liquid", carried from applied when present; each allocated row's N/C/VS is split across the manure_types in proportion to their share of the cell's collected N, so the capacity-filling math itself stays pooled), applied_n, applied_c, applied_vs, over_cap and the method_allocation, method_cap and disposal_method provenance columns. The N split by manure_type is exact (mass-conserving per type); applied_c and applied_vs are split by the SAME N-proportional share, not by each manure_type's own C:N/VS:N ratio, so a per-manure_type carbon or volatile-solids figure does not reflect that type's actual composition (e.g. solid vs. liquid manure have materially different C:N). Callers needing manure-type-specific carbon/VS (e.g. CH4 potential by system) should not rely on the manure_type-broken-out applied_c/ applied_vs columns without accounting for this.

Examples

applied <- tibble::tribble(
  ~year, ~territory, ~sub_territory, ~stream, ~manure_type,
  ~applied_n, ~applied_c, ~applied_vs,
  2020L, "203", NA, "collected", "Solid", 80, 800, 40,
  2020L, "203", NA, "grazing", "Excreta", 20, 380, 12
)
crops <- tibble::tribble(
  ~year, ~territory, ~sub_territory, ~crop, ~manure_n_receptivity, ~crop_n_cap,
  2020L, "203", NA, "44", 6, 50,
  2020L, "203", NA, "15", 4, 40
)
allocate_manure_to_land(applied, list(crops = crops))

Description

Moves the manure nitrogen that a cell could not place locally (its surplus above the local cropland and grassland caps) to nearby same-polity cells that still have room, on the 0.5-degree grid. Each source offers its surplus to its single-ring (king-move) neighbours in proportion to their remaining room; a sink that is over-subscribed by several sources is filled only to its room and the rejected manure returns to the sources as residual. This is the resolution-robust, mass-conserving analogue of the room-weighted first-ring redistribution of an earlier regional historical reconstruction; cross-polity transport is not allowed. Carbon and volatile solids ride along with each nitrogen flow at the source cell's bundle ratio.

Usage

allocate_manure_transport(source_cells, sink_cells, options = list())

Arguments

Value

A tibble with one row per landing site: year, territory, sub_territory (the sink cell for transported manure, the source cell for residual), applied_n, applied_c, applied_vs, kind ("transported" or "residual") and method_transport. The "residual" rows are the un-transportable surplus handed back for local disposal.

Examples

source_cells <- tibble::tribble(
  ~year, ~territory, ~sub_territory, ~surplus_n, ~surplus_c, ~surplus_vs,
  2020L, "203", "1.5_40", 10, 90, 6
)
sink_cells <- tibble::tribble(
  ~year, ~territory, ~sub_territory, ~room_n,
  2020L, "203", "1_40", 4,
  2020L, "203", "2_40", 6
)
allocate_manure_transport(source_cells, sink_cells)

Description

Lookup table giving the AMG humification coefficient h (the fraction of carbon inputs entering the active pool) as a function of the carbon input type. Rows are matched in ascending match_order against the lowercased input type using the pattern regular expression; the last row (input type "default", with a missing pattern) is the fallthrough.

Usage

amg_h_by_input_type

Format

A tibble with columns:

match_order

Integer matching priority (lower is tried first).

input_type

Canonical input type label (e.g. "green_manure", "manure", "residue", "default").

pattern

Regular expression matched against the lowercased input type; NA for the fallthrough row.

h

Humification coefficient (fraction of input carbon stabilised).

Source

Saffih-Hdadi, K. & Mary, B. (2008). Modeling consequences of straw residues export on soil organic carbon. Soil Biology and Biochemistry, 40(3), 594-607. doi:10.1016/j.soilbio.2007.08.022.

Examples

amg_h_by_input_type

Description

Maps live animal CBS items to their livestock classifications, process codes, and associated product items used in livestock modeling.

Usage

animals_codes

Format

A tibble where each row corresponds to one live animal CBS item. It contains the following columns:

• Item_Code: Numeric FAOSTAT item code for the live animal.

• item_cbs: Name of the CBS item (e.g., "Cattle", "Asses").

• proc_code: Short process code used internally (e.g., "p092").

• proc: Descriptive process name (e.g., "Asses").

• item_cbs_code: Numeric CBS item code (often equal to Item_Code).

• Farm_class: Broad farm classification grouping the animal. One of "Cattle", "Dairy_cows", "Monogastric", "Sheep_goats", "Bees", "Game".

• Item_product: Name of the primary product derived from this animal, if applicable (e.g., milk for dairy cows).

• Item_Code_product: Numeric FAOSTAT code for the associated product item.

• Liv_prod_cat: Livestock product category the animal belongs to.

• Graniv_grazers: Broad feeding behaviour classification. One of "Grazers", "Granivores", "Bees", "Game".

• Livestock_name: Internal livestock identifier used across datasets (e.g., "Cattle", "Dairy_cows", "Asses").

• Animal_class: Fine-grained animal class, including production type distinctions (e.g., "Broilers", "Hens", "Hogs", "Dairy_cows").

• Item_FAOmanure: Name of the corresponding FAOSTAT manure management item.

• Item_Code_FAOmanure: Numeric code of the FAOSTAT manure management item.

• Cat_Labour: Labour category used in labour-related analyses. One of "Cattle", "Equines", "Dairy_cows", "Birds", "Small_ruminants", "Pigs", "Bees".

• Cat_FAO1: Top-level FAO category. Currently always "Animal".

• item_bouwman: Item name used in Bouwman et al. livestock datasets.

Source

Derived from FAOSTAT data and internal livestock classification work.

Examples

head(animals_codes)

Description

Nets the nitrogen surviving manure management onto the field, applying the IPCC 2019 management-loss fractions to the collected/housed streams from split_manure_management(): applied_n = n_stream * (1 - FracLossMS) where FracLossMS = FracGasMS + FracLeachMS + EF3 + FracN2MS. The grazing (pasture/range/paddock) stream is deposited in situ and keeps its full nitrogen (its in-situ soil losses belong to the soil stage). Indirect N2O is reported as a labelled sub-flux of the already-removed volatilized and leached nitrogen (the same N is not removed twice). Carbon applied to the field is c_stream * (1 - c_loss_fraction), the stream's carbon less what its management system mineralises in storage, and the volatile solids are scaled by the same ratio. The applied C:N is therefore a RESULT of that loss rather than an imposed cap. Loss fractions and their sources are in inst/extdata/manure/manure_storage_c_loss.csv: nothing for grazing or daily spread, which have no storage stage; 0.420 of initial carbon for solid storage and 0.424 for poultry litter (Pardo et al. 2015, doi:10.1111/gcb.12806); 0.110 (cattle) and 0.128 (pigs) for slurry, derived from Kupper et al. 2020 (doi:10.1016/j.agee.2020.106963) using this package's own 0.47 kg C per kg volatile solids.

Until whep#1006 this was a cap, ⁠pmin(c_stream, applied_n * post-storage C:N)⁠, which produced a loss only as a side effect of holding the applied C:N down. That made the loss depend on the excreted composition rather than on the storage system: when excreted carbon moved, the reported loss for cattle solid storage fell from 40.3% to 6.9% with no coefficient changing.

Usage

apply_management_losses(split, options = list())

Arguments

Value

The input rows with manure_type, applied_n, applied_c, applied_vs, n_volatilized, n_leached, n2o_direct_n, n2_n, n2o_indirect_n, c_lost, vs_destroyed, n_bedding, c_bedding, method_losses, method_bedding_c, method_indirect_n2o and method_direct_n2o.

Bedding

When the rows carry n_bedding and c_bedding (from add_manure_bedding()), the straw bedded under housed animals is part of the manure that reaches the field, and the applied C:N is the C:N of the bedded farmyard manure rather than of the excreta alone. Without those columns nothing changes: they default to zero and every number is the excreta-only one.

Nitrogen follows IPCC 2019 Refinement Vol. 4 Ch. 10 Eq. 10.34 (p. 10.94) exactly: NbeddingMS sits outside the (1 - FracLossMS) term, because "mineralization of nitrogen compounds in beddings occurs more slowly compared to manure and the concentration of ammonia fraction in organic beddings is negligible", so "both volatilization and leaching losses during storage of bedding are assumed to be zero" (p. 10.93). Bedding nitrogen therefore raises applied_n one-for-one and raises none of the loss side-streams.

Carbon has no IPCC rule at all – manure CO2 is out of scope there – so bedding_c_loss selects it. "same_as_excreta" (default) applies the stream's own storage carbon-loss fraction to the bedding carbon too: the 0.420 for solid storage comes from Pardo et al. 2015 (doi:10.1111/gcb.12806, Table 2), a systematic review of whole manure heaps, and a heap in solid storage in practice already contains its litter, so the measured loss is a whole-heap loss. "none" keeps every gram of bedding carbon, mirroring the zero storage loss IPCC gives bedding nitrogen; it is the upper bound on applied carbon and raises the applied carbon of a bedded solid-storage stream by ⁠0.420 / (1 - 0.420) = 72%⁠ of the bedding carbon relative to the default.

Volatile solids stay excreta-only under both, so the Tier 2 methane engine in build_livestock_ghg_extension() is untouched. IPCC 2019 Ch. 10 does ask for bedding to be combined with volatile solids when estimating manure methane; that is a separate change to a separate engine and is not made here.

Examples

excretion <- tibble::tribble(
  ~year, ~territory, ~sub_territory, ~livestock_category,
  ~n_excretion, ~c_excretion, ~vs_excretion,
  2020L, "203", NA, "Cattle_milk", 100, 1900, 60
)
apply_management_losses(split_manure_management(excretion))

Description

Build-time gate over a footprint result, intended for use in a pipeline or regression test. Aborts when the footprint over-traces any origin sector (embodied pressure exceeds the source, which should never happen) or when the global share of untraced pressure exceeds max_rel_loss. A regression that silently loses or inflates pressure then fails loudly instead of shipping.

Usage

assert_footprint_invariants(
  footprint,
  extensions,
  labels,
  x_vec,
  max_rel_loss = 0.05
)

Arguments

Value

Invisibly, the one-row summary from summarise_conservation(). Called for its side effect of aborting on violation.

Examples

z_mat <- matrix(c(0, 5, 10, 0), nrow = 2)
x_vec <- c(100, 200)
y_mat <- matrix(c(85, 195), ncol = 1)
extensions <- c(50, 30)
labels <- tibble::tibble(
  area_code = c(1L, 1L),
  item_cbs_code = c(1L, 2L)
)
fp <- compute_footprint(
  x_vec = x_vec, y_mat = y_mat, extensions = extensions,
  labels = labels, z_mat = z_mat
)
assert_footprint_invariants(fp, extensions, labels, x_vec)

Description

Build-time gate over a Parquet artifact. Aborts when check_parquet_integrity() reports any anomaly, so a corrupt multi-gigabyte cube fails loudly at the moment it is written instead of being read back truncated for months (whep#531).

Usage

assert_parquet_integrity(path, deep = FALSE)

Arguments

Value

Invisibly, path. Called for its side effect of aborting on violation.

Examples

path <- tempfile(fileext = ".parquet")
nanoparquet::write_parquet(data.frame(x = 1:10), path)
assert_parquet_integrity(path)
unlink(path)

Description

Build-time gate over a tabular artifact. Aborts when check_table_schema() reports any "error" diagnostic and warns when it reports only "warning" ones, so a table that has silently lost a column, changed type or gained duplicate keys fails at the moment it is produced instead of downstream. Returns its input, so it can sit inside a pipeline without changing the value that flows through.

Usage

assert_table_schema(data, schema, arg = "data")

Arguments

Value

Invisibly, data, unchanged. Called for its side effect of aborting on violation.

Examples

schema <- list(
  columns = list(
    list(name = "year", type = "integer"),
    list(name = "value", type = "double", min = 0)
  ),
  key = "year"
)
data <- tibble::tibble(year = c(2000L, 2001L), value = c(1, 2))
assert_table_schema(data, schema)

Description

Store a provenance record (from record_provenance()) on an object as an attribute, so the result travels together with its lineage. Retrieve it later with get_provenance().

Usage

attach_provenance(x, provenance)

Arguments

Value

x, unchanged except for an added whep_provenance attribute.

Examples

prov <- record_provenance(
  aliases = "bilateral_trade",
  recorded_at = as.POSIXct("2026-01-01", tz = "UTC")
)
result <- attach_provenance(tibble::tibble(value = 1), prov)
get_provenance(result)

Description

Store a scope record (from footprint_scope()) on an object as an attribute, so the result carries its goal-and-scope with it.

Usage

attach_scope(x, scope)

Arguments

Value

x, unchanged except for an added whep_scope attribute.

Examples

scope <- footprint_scope("cropland", "ha", "FABIO-MRIO")
result <- attach_scope(tibble::tibble(value = 1), scope)
get_scope(result)

Description

Distribute each country's FAOSTAT-reported fallow area among its crops using a precomputed allocation weight, adding the result to each crop's cropped physical area. The weight is typically gridded_fallow_weights(), which puts fallow on rainfed dryland cereals and rainfed monsoon rice and keeps it off irrigated/continuous systems.

The fallow magnitude comes from fallow_total (FAOSTAT "Land with temporary fallow", item 6640) — reported separately from temporary meadows/pastures, so it isolates real fallow from fodder.

Usage

attribute_fallow_to_crops(cropgrids, fallow_total, alloc_weight)

Arguments

Value

A tibble with area_code, item_cbs_code, physical_ha (cropped physical area plus attributed fallow), and harvested_ha.

Examples

cropgrids <- tibble::tribble(
  ~area_code, ~item_cbs_code, ~physical_ha, ~harvested_ha,
  1L, 2511L, 500, 500,
  1L, 2807L, 400, 400
)
fallow_total <- tibble::tribble(~area_code, ~fallow_ha, 1L, 200)
# all weight on wheat -> the 200 ha reported fallow goes to wheat
alloc_weight <- tibble::tribble(
  ~area_code, ~item_cbs_code, ~weight,
  1L, 2511L, 1,
  1L, 2807L, 0
)
attribute_fallow_to_crops(cropgrids, fallow_total, alloc_weight)

Description

Complete an admin-shares table to the full year range of its extent and fill the pre-seam years by modulating each unit's seam-year share with its own land extent, the plan's decision-7 back-cast:

$\tilde{s}_u(t) = s_u(t_0) \frac{E_u(t)}{E_u(t_0)}, \qquad s_u(t) = \frac{\tilde{s}_u(t)}{\sum_v \tilde{s}_v(t)}$

The first step is fill_proxy_growth() with the extent as proxy, the same machinery .fill_pre_faostat() (R/build_production.R:3008) uses to back-cast the national totals these shares split, so the two compose. The second is a per-year renormalisation over the t0 unit set, the residual pseudo-unit included when the shares carry one.

Nothing here is a fallback: a year the rules cannot resolve is refused with a diagnostic and keeps share = NA, never a carried value.

Two things the plan's seam section names are deliberately not here. Pre-seam irrigation needs no separate treatment: the unit irrigated target is built from the engine's own annual ir_potential (R/spatialize.R:420), whose LUH2 irrigated_ha varies every year, pre-seam years included, so it moves with the same extent that modulates the area share. And the within-unit weight regime per ⁠(unit, item, year)⁠ is the allocation's to record, not this function's: treatment here says how a share was obtained, while the regime says which weight then spread it inside the unit.

Usage

backcast_admin_shares(
  shares,
  extent,
  seam = NULL,
  binding_indicator = "area_harvested",
  settings = list()
)

Arguments

Value

A list of four tibbles:

• shares: the input rows plus the completed year set for the t0 unit sets, with two added columns. treatment is "observed" for a row that arrived in shares, "backcast_t0_geometry" for a row this function produced, "luh2_clamped" where t0 lies beyond the extent's last year so E_u(t0) is the clamped last slice, and NA for a completed row nothing filled, whose reason is in diagnostics. gap_rule records the interior-gap setting. A produced row carries its anchor's provenance columns, value = NA (no reported value exists) and treatment_year = NA (reserved for the interior-gap rule), so produced rows deliberately sit outside the closed admin_shares_schema(); the "observed" subset on the contract columns still conforms.

• diagnostics: one row per event, with the series and unit keys, year where the event is year-specific, diagnostic from a closed vocabulary and free-text detail.

• counters: every vocabulary member with its count, zeros included.

• settings: the one-row record of what this call was run with.

Territory basis

Shares and E_u are defined on the t0 unit set with t0 geometry held fixed, the read_luh2_landuse() snapshot convention and the analogue of mapping_status == "backcast_anchor". Every row produced that way carries treatment = "backcast_t0_geometry", so a unit whose containment edge starts after a back-cast year still gets a row at that year, on its t0 cells.

Translating those rows onto the partition valid at t through the containment-edge lineage – an earlier unit that later split taking the sum of its t0-descendants' modulated shares – happens before the rows enter the engine and is not implemented here. It is a follow-up, because the relation it needs is succession (which unit became which), while polity_containment carries containment (member_code, container_code, start_year, end_year, basis) only: nothing in the delivered data says a unit starting in one year descends from one that ended the year before. Until it lands, a container whose partition changed inside the back-cast window is back-cast on its t0 partition, which treatment states on every row.

Zero cases

Post-processing applied after the fill, which itself leaves such positions NA (.fg_fill_backward_vec() keeps a fill only where the result is finite and positive). The plan's four cases, with precedence (a) over (b):

• (a) E_u(t0) == 0 with s_u(t0) > 0: hold s_u(t0) outside the renormalisation, siblings renormalised to 1 - s_u(t0). Holding it inside would anti-modulate the unit. Counter zero_extent_t0_held.

• (b) E_u(t) == 0 at a back-cast year of a unit not held by (a): share 0 there, its mass going to the siblings through the renormalisation. Counter zero_extent_year_zeroed.

• (c) the renormalisable sum is zero while there is mass to distribute: the year is refused for that series and all its units left NA. Counter zero_sum_year_refused.

• (d) E_u(t0) == 0 with no positive s_u(t0): nothing to hold and no mass to move, so the unit contributes 0. Counter zero_extent_t0_no_share.

Case (b) counts every zero-extent back-cast year, including the ones inside a year (c) then refuses: both statements are true of such a year, and (c) is what decides the output.

A zero year also breaks the growth chain: fill_proxy_growth() telescopes a product of consecutive growth factors, so it cannot reach the years beyond the break and leaves them NA even though the ratio above is perfectly well defined there. Those positions are completed from that ratio directly – the same expression, not a second method – and every one is counted (direct_ratio_repair). Where the chain is intact the two agree to machine precision, which the tests assert.

Interior gaps

The fill window ends at t0, so no gap between two observed years is ever filled: such rows are completed, left NA and counted (interior_gap_refused, trailing_gap_refused). That is the placeholder default until T31(e) decides the rule; it is recorded on every row in gap_rule and in settings. max_gap and max_gap_linear are passed straight to fill_proxy_growth() so that decision needs no API change. Today max_gap bounds the back-cast run itself – a longer run is left unfilled and counted (max_gap_exceeded), because fill_proxy_growth()'s gap test governs the leading run as well as the interior ones – while max_gap_linear cannot bite, there being no interior run inside the window.

Examples

shares <- tibble::tibble(
  area_code = 900L,
  level = 1L,
  item_prod_code = 15L,
  indicator_used = "area_harvested",
  level_polity_code = c("A1", "A2"),
  year = 1902L,
  share = c(0.6, 0.4),
  treatment_year = "observed"
)
extent <- tibble::tibble(
  area_code = 900L,
  level_polity_code = rep(c("A1", "A2"), each = 3),
  level = 1L,
  year = rep(1900:1902, times = 2),
  extent_ha = c(800, 900, 1000, 600, 550, 500)
)
out <- backcast_admin_shares(shares, extent)
out$shares[, c("level_polity_code", "year", "share", "treatment")]

Description

RAS-balance an inter-industry flow matrix toward the product-balance margin. The row target is intermediate use, $u = X - \text{rowSums}(Y)$; the column target keeps the original column composition, rescaled so its total matches $\sum u$.

When the balanced system is productive (the spectral radius of $A$ is below 1), $(I - A) X = Y$ holds and the footprint conserves – the case for the productive systems in the examples and tests.

Caveat for physical agriculture: livestock feed conversion makes some columns of $A$ sum well above 1 (many tonnes of feed per tonne of product), so the balanced system is not productive. Balancing to faithful margins does not remove that, and the traced footprint then over-traces rather than conserving (on the real 2010 model, by about 15%). RAS therefore does not, on its own, fix the grassland under-tracing; always verify with check_footprint_conservation().

Pass the result as z_mat to compute_footprint() with a large max_column_sum (e.g. 1e12) and conserve_extensions = FALSE.

Usage

balance_io_flows(z_mat, x_vec, y_mat, max_iter = 1000L, tol = 1e-06)

Arguments

Value

The balanced flow matrix.

Examples

z_mat <- matrix(c(1, 4, 2, 3), nrow = 2)
x_vec <- c(10, 10)
y_mat <- c(3, 3)
balance_io_flows(z_mat, x_vec, y_mat)

Description

Reconcile a non-negative matrix to prescribed row and column sums using the RAS (biproportional / iterative proportional fitting) algorithm: alternately rescale rows then columns until both margins are matched, preserving the matrix's structure (zero pattern and relative magnitudes). The row and column targets must have equal totals.

Works on dense and sparse (Matrix) inputs, staying in the input representation so it is efficient for both small dense tables and large sparse input-output systems. (The same core also balances the bilateral trade matrices.) For matrices with negative entries the signed GRAS variant is needed and is not implemented here.

Usage

balance_ras(x, target_rows, target_cols, max_iter = 1000L, tol = 1e-09)

Arguments

Value

The balanced matrix, in the same representation as x (dense in, dense out; sparse in, sparse out).

Examples

m <- matrix(c(1, 2, 3, 4), nrow = 2)
balance_ras(m, target_rows = c(10, 20), target_cols = c(12, 18))

Description

Provides dry-matter, nutrient, and energy conversion coefficients for agricultural products and residues. Used to convert fresh-matter production quantities into biomass flows, nutrient budgets, and energy content.

Usage

biomass_coefs

Format

A tibble where each row corresponds to one product or item. It contains 63 columns:

• Code: Item code (character), corresponding to FAOSTAT production codes.

• Name_biomass: Item name as used in biomass accounting.

• Equiv: Reference equivalence item used when coefficients are borrowed from another similar commodity (e.g., "Wheat" for oats).

• Category: Broad commodity category (e.g., "Cereals, other", "Barley", "Vegetables").

• Product_kgDM_kgFM: Product dry-matter content in kg DM per kg fresh matter.

• Residue_kgDM_kgFM: Residue dry-matter content in kg DM per kg fresh matter of product.

• Conventional_kgDM_ha: Conventional yield in kg dry matter per hectare.

• Organic_kgDM_ha: Organic yield in kg dry matter per hectare.

• GE_product_edible_portion_MJ_kgFM: Gross energy of the edible portion in MJ per kg fresh matter.

• GE_product_residue_MJ_kgFM: Gross energy of the residue in MJ per kg fresh matter (may be character due to source formatting).

• GE_product_MJ_kgFM: Gross energy of the whole product in MJ per kg fresh matter.

• GE_residue_MJ_kg: Gross energy of the residue in MJ per kg.

• kg_product_kg_aerial_biomass: Fraction of aerial biomass that is product (harvest index, kg/kg).

• kg_residue_kg_aerial_biomass_FM: Fraction of aerial biomass that is residue, on fresh matter basis.

• kg_residue_kg_product_FM: Ratio of residue to product on fresh matter basis.

• Carcass_to_LW: Carcass-to-live-weight ratio (livestock only; logical placeholder for crop items).

• Edible_portion: Edible fraction of the product (kg edible / kg fresh matter).

• N_kgN_kgFM: Nitrogen content in kg N per kg fresh matter.

• Lipids_g_kgFM: Lipid content in g per kg fresh matter.

• Carbohydrates_g_kgFM: Carbohydrate content in g per kg fresh matter.

• Calcium_mg_kgFM: Calcium content in mg per kg fresh matter.

• VitaminA_microg_kgFM: Vitamin A content in micrograms per kg fresh matter.

N_kgN_kgFM is the food-composition nitrogen density of the edible part, and is what build_food_supply() turns into protein. Its provenance is weak and worth knowing before trusting a row. Upstream it sits under the ⁠NUTRIENTS IN EDIBLE PART⁠ group header with the four columns above, but the workbook's Sources sheet has no column for any of the five: its columns run from kg_residue_kg_product_FM straight to Product_kgN_kgDM, so the whole nutrition block is undocumented at source (#500 section 6, #1074). Most rows are a VLOOKUP into the workbook's food-composition sheet Conversores_Dieta, the same sheet that fills the four columns above; that sheet derives its own nitrogen column as Proteinas / (6.25 * 1000). The derivation is missing for exactly its five cereal rows – Wheat, Oats, Rye, Maize and Rice – which carry a Proteinas value but no nitrogen, so for those five the lookup was replaced by the agronomic Product_kgN_kgDM * Product_kgDM_kgFM. Other rows, ⁠Vegetables, other⁠, Olive and Honey among them, hold a bare literal. Those eight are the ones #1096 tracks; what became of each is below.

Wheat was the largest consequence. It carried 0.018951324393104405 kg N per kg, 118.45 g of protein per kg at N x 6.25, which is exactly Product_kgN_kgDM * Product_kgDM_kgFM – the agronomic whole-grain nitrogen the Sources sheet attributes to FEDNA 2016, a feed table. Applied to a commodity-balance food quantity that is the wheat-grain equivalent of the milled products people eat, that counts the bran and germ protein milling diverts away from food.

It now carries 0.01488 kg N per kg, i.e. 93 g of protein per kg: the flour basis. The value is read from the workbook cell, not recalled: Biomass_coefs.xlsx, sheet Conversores_Dieta, row 4, labelled ⁠Harina de Trigo⁠ (wheat flour) and keyed to Name_biomass = "Wheat", column Proteinas = 93 g/kg. That row is where this table already takes the wheat lipids (12 g/kg), carbohydrates (800 g/kg), calcium (150 mg/kg) and vitamin A (0) from – all four ship today – so the wheat nutrition block was flour composition everywhere except protein, and the change makes the row internally consistent rather than importing a foreign number.

Neither 118.45 nor 93 has a Sources entry, so 93 is corroborated, not cited upstream. What "flour basis" means numerically is protein per kg of grain equivalent, which is flour protein times the milling extraction rate, so the published tables were read on that basis:

• FAO, Food composition tables for international use, 2nd ed., Rome, 1953, https://www.fao.org/4/x5557e/x5557e04.htm (FAO flags it as historical). Medium wheat: whole meal 12.2 g/100 g at 100% extraction, flour 11.7 at 85%, 10.9 at 72% – so 99.4 and 78.5 g per kg of grain equivalent, which bracket 93.

• USDA FoodData Central 168894 (SR Legacy), "Wheat flour, white, all-purpose, enriched, bleached": protein 10.33 g/100 g, so 103.3 g per kg of flour, 72-88 g per kg of grain equivalent at 70-85% extraction.

• FAO, Technical conversion factors for agricultural commodities, Rome, https://www.fao.org/fileadmin/templates/ess/documents/methodology/tcf.pdf – its per-country ⁠Flour of Wheat⁠ extraction rates run 70-97% with a median of 75%, which is why no single flour figure maps to one grain-equivalent density.

The oracle is FAOSTAT FBS itself, which builds its protein the same way: composition factors on the products eaten, over the standardised primary-equivalent quantity that WHEP's food_t also is (FAO, Food balance sheets: a handbook, section III, https://www.fao.org/4/X9892E/X9892e03.htm). For item 2511 its World row (area 5000) implies 91.71-93.15 g/kg over 2010-2023, 92.99 in 2010; summed instead over the 171 countries reporting both elements it is 94.96-96.90, 96.60 in 2010. So 93 lands within 0.02% of the World row and 3.7% below the country sum, where 118.45 was above both: 27.4% above the World row and 22.6% above the country sum (whep#796).

One global coefficient cannot carry the extraction pattern country by country: FBS's own per-country implied density for 2511 in 2010 spans 41-115 g/kg (q10 69, median 81, q90 90), so 93 is the mass-weighted world point of that distribution and leaves the median country high. The previous value stays selectable as build_food_supply(protein_basis = "product_nitrogen"), which reads the agronomic route directly and returns exactly 0.11844577745690253 kg protein per kg; the choice is recorded per row in method_protein_basis.

The other seven rows were settled one by one (#1096), by the same test as wheat: does the row's own Conversores_Dieta entry, the one that already fills its other nutrients, carry a protein value, and does following it agree with the FBS oracle? The oracle ratios below are WHEP world food protein over the FBS World row (area 5000), 2010, on a real build.

• Olive now carries 0.00128 (8 g protein/kg), from row 39 ⁠Aceituna de mesa⁠ (table olive), whose lipids 200, carbohydrates 10, calcium 630, vitamin A 220 and edible portion 0.8 are the values already shipped. The bare literal 0.0038 it replaces put olive protein at 3.23x FBS; at 0.00128 it is 1.09x.

• Rye now carries 0.016 (100 g/kg), from row 6 ⁠Harina de Centeno⁠ (rye flour), whose lipids 19.3, carbohydrates 597 and calcium 270 are already shipped – the wheat case exactly, flour basis. The agronomic 0.01367 it replaces was 0.90x FBS; 0.016 is 1.06x.

• Honey now carries 0.0008 (5 g/kg), carbohydrates 780 g/kg and calcium 50 mg/kg, from row 36 Miel. Its block had been a hand-typed placeholder (protein 0, carbohydrate 1000 g/kg, calcium 0) that matched no row and put 1000 g of carbohydrate in 785 g of dry matter; protein and carbohydrate from Miel sum to exactly that dry matter. At 5 g/kg honey is 1.69x FBS, where it was zero. Only the protein moves a computed number: nothing in the package reads the carbohydrate or calcium columns.

• Oats and Maize are unchanged, on the agronomic value. Their rows, 5 ⁠Avena grano⁠ 117 g/kg and 7 ⁠Harina de Maiz⁠ 87 g/kg, move away from the FBS density (72.6 and 62.2 g/kg, country sum) where the agronomic 83.8 and 78.0 are closer, so following the row would be consistency at the cost of accuracy. Open for an expert.

• Rice is unchanged: its basis was settled in #751/#755.

• ⁠Vegetables, other⁠ is unchanged and moves no food number: no item_cbs_code bridges to it (⁠Vegetables, Other⁠ 2605 reaches Artichoke through items_full). Its row 113 would give 33.3 g/kg against the literal's 14.0, and neither is checked.

All three new values are the workbook's own composition figures, which, like the rest of this block, have no Sources entry: they are corroborated by the FBS oracle, not cited upstream. The workbook copy read was afsetools/inst/extdata/Biomass_coefs.xlsx; upstream still carries the old values in Coefs and should follow.

The tree-nut rows Almonds, Walnut and Hazelnut pair a kernel nitrogen density with an Edible_portion that now refers to the nut in shell (whep#797). FBS item 2551 ⁠Nuts and products⁠ is a quantity in shell, and it reaches Almonds through items_full; with an Edible_portion of 1 the shell was counted as food, 200 g of protein per kg against an FBS density of 46.6, 4.3x. The edible fraction is FAO's own food-composition factor for the FBS, in-shell protein over shelled protein per 100 g (FAO, Food balance sheets: a handbook, Rome, 2001, Annex I, https://www.fao.org/docrep/pdf/011/x9892e/x9892e00.pdf, PDF page 65): almonds 8.0 / 20.0 = 0.4, walnuts 6.4 / 14.3 = 0.4476, hazelnuts 6.0 / 13.0 = 0.4615. The shelled figures are this table's own kernel densities to within 8% (20.0, 14.0, 14.1 g/100 g). FAO's Technical conversion factors for agricultural commodities (https://www.fao.org/fileadmin/templates/ess/documents/methodology/tcf.pdf) corroborates the range: its per-country shelled-from-unshelled extraction rates run 30-65% for almonds (median 35), 35-70% for walnuts (median 40) and 40-50% for hazelnuts (median 50). Nuts now carry 80 g of protein per kg, 1.7x FBS. What remains is the basket: 2551 covers ten species and FAO's in-shell factors for them run from 1.8 (chestnuts) to 10.3 (pistachios), so one representative species cannot match it (whep#1453). Only the protein moves: the energy columns are not scaled by Edible_portion.

The ten ⁠Edible_*⁠ and ⁠NonEdible_*⁠ nutrient columns below are empty in every row, upstream in the source workbook as well as here, so no edible/non-edible nutrient split can be read from them (#361). Use Edible_portion with N_kgN_kgFM or Product_kgN_kgDM to derive an edible basis instead, as build_food_supply() does.

• Edible_kgDM_kgFM: Edible dry matter in kg per kg fresh matter. Empty.

• Edible_kgC_kgFM: Edible carbon in kg C per kg fresh matter. Empty.

• Edible_N_kgFM: Edible nitrogen in kg N per kg fresh matter. Empty.

• Edible_kgP_kgFM: Edible phosphorus in kg P per kg fresh matter. Empty.

• Edible_K_kgFM: Edible potassium in kg K per kg fresh matter. Empty.

• NonEdible_kgDM_kgFM: Non-edible dry matter, kg per kg fresh matter. Empty.

• NonEdible_kgC_kgFM: Non-edible carbon in kg C per kg fresh matter. Empty.

• NonEdible_kgN_kgFM: Non-edible nitrogen in kg N per kg fresh matter. Empty.

• NonEdible_kgP_kgFM: Non-edible phosphorus, kg P per kg fresh matter. Empty.

• NonEdible_kgK_kgFM: Non-edible potassium, kg K per kg fresh matter. Empty.

• Product_kgN_kgDM: Nitrogen content of product in kg N per kg dry matter.

The synthetic feed-additive rows take this column from the FEDNA feed tables as crude protein divided by 6.25, the same way Threonine, Tryptophan, Valine and Urea still do. Methionine carried 0.1143 instead, which is 21.7% above the most nitrogen the molecule can hold: methionine is C5H11NO2S with one nitrogen atom, so its mass fraction is 14.007 over 149.208, or 0.0939 kg N per kg. It is now FEDNA's DL-Metionina entry, 58.5% crude protein and better than 99% purity, giving 0.0936 (whep#931; https://fundacionfedna.org/ingredientes-para-piensos). The alternative is the other commercial methionine source, the hydroxy analogue FEDNA lists as HIDROXI-ANAL MET, which is C5H10O3S and holds no nitrogen at all; it is the value the retired pin carried. That items_full$FEDNA names HIDROXI-ANAL MET for this item is not evidence for the analogue: that column is a feed-table stand-in, not a product identity (see items_full, whep#1131).

The upstream workbook records no source for the 28 feed-additive rows, so their provenance is kept in inst/extdata/harmonization/biomass_coefs_additive_sources.csv, one row per additive with the entry it was read from in the FEDNA 2019 tables (⁠Tablas FEDNA 2019.xlsx⁠, v. 15.01.2021, linked from https://fundacionfedna.org/ingredientes-para-piensos) or an explicit "assumed, unverified" status (whep#1074). Lysine is FEDNA's L-Lisina HCl, 94.4% crude protein, 0.1510; it carried 0.2015, above even the free base's 0.1916. ⁠Ammonium chloride⁠ is FEDNA's Cloruro amonico, 163.6% crude protein, 0.2618. ⁠Choline chloride⁠ is FEDNA's Cloruro colina 60, whose 52% choline gives 0.0699 through the choline cation's nitrogen fraction, 14.007 over 104.173; FEDNA books its crude protein as zero because choline nitrogen is not protein, not because it is absent. Both carried 0, so their nitrogen was missing from the balance. Phytase and Enzimes keep an unsourced 0.116, now marked as assumed; their fresh-matter N_kgN_kgFM of 0.16 now follows this column.

• Product_kgP_kgDM: Phosphorus content of product in kg P per kg dry matter.

• Product_kgK_kgDM: Potassium content of product in kg K per kg dry matter.

• Product_kgC_kgDM: Carbon content of product in kg C per kg dry matter.

• Residue_kgN_kgDM: Nitrogen content of residue in kg N per kg dry matter.

For the wood and forest rows this column prices two physically different quantities through one cell. create_n_prov_destiny() sends the harvested Wood item to ⁠Average wood⁠, and also relabels the residue production of forest and shrubland land as Firewood, which resolves to the same row. Harvested wood is stemwood; forest residue is branches, bark and foliage.

The shipped value is assumed, unverified. No value the upstream workbook has carried for these rows has a citation that can be opened: the beech anchor's source cell begins ChatGPT., the conifer anchor's two citations do not resolve as written, and the holm-oak anchor's cell is blank (whep#932). The anchors can still be placed against an independent compilation. Thurner et al. (2025) pool 1048 stem, 599 branch, 267 root and 5944 leaf nitrogen measurements for boreal and temperate trees – the woody ones almost entirely from 192 literature studies – and report medians, in kg N per kg dry matter, of 0.0010 in stem sapwood, 0.0035 in branches, 0.0060 in roots and 0.0167 in leaves. Against those, ⁠Average wood⁠'s 0.0030 is 0.86 of the branch median and 3.0 times the stem median – a branch concentration – while the retired pin's 0.00095 is 0.95 of the stem median, a stemwood one.

So the gap whep#932 records is not two estimates of one quantity in disagreement; it is the 3.5-fold gap between stem and branch tissue, and whichever single number the cell carries is wrong by about that factor for one of its two uses. The same ordering appears in the trembling-aspen budget of Morrison and Foster (1979, reproduced in Hacker 2005, "Effects of Logging Residue Removal on Forest Sites"), where stemwood holds 84 kg N in 119 t of dry matter, 0.00071 kg N per kg, against 0.0042 for bark, 0.0049 for branches and 0.024 for foliage. So this cell is left as published and create_n_prov_destiny() does not read it for wood by default: with wood_n_method = "tissue" it prices Wood at the stem median 0.0010 and Firewood at the branch median 0.0035 (whep#932); "single" reads this cell for both. tests/testthat/test_biomass_coefs_wood_provenance.R holds the comparison and fails if either side of it drifts.

Thurner, M., Yu, K., Manzoni, S., Prokushkin, A., Thurner, M. A., Wang, Z., and Hickler, T. (2025). Nitrogen concentrations in boreal and temperate tree tissues vary with tree age/size, growth rate, and climate. Biogeosciences 22(5), 1475-1493. doi:10.5194/bg-22-1475-2025.

• Residue_kgP_kgDM: Phosphorus content of residue in kg P per kg dry matter.

• Residue_kgK_kgDM: Potassium content of residue in kg K per kg dry matter.

• Residue_kgC_kgDM: Carbon content of residue in kg C per kg dry matter.

• Residue_humified_kgC_kgC: Humification coefficient of residue carbon (fraction of residue C stabilised as soil organic matter).

• MgDM_m3: Megagrams dry matter per cubic metre (bulk density proxy).

• Root_humified_kgC_kgC: Humification coefficient for root carbon.

• Root_mass_kgC_kgDM: Root carbon mass in kg C per kg crop dry matter.

• Residue_C_N: Carbon-to-nitrogen ratio of the residue.

• Root_kgN_kgDM: Nitrogen content of roots in kg N per kg root dry matter.

• GE_Roots_MJ_kgDM: Gross energy of roots in MJ per kg dry matter.

• Fiber_g_kgFM: Dietary fibre content in g per kg fresh matter.

• SFA_g_kgFM: Saturated fatty acid content in g per kg fresh matter.

• MUFA_g_kgFM: Monounsaturated fatty acid content in g per kg fresh matter.

• PUFA_g_kgFM: Polyunsaturated fatty acid content in g per kg fresh matter.

• PUFA_n3_g_kgFM: Omega-3 PUFA content in g per kg fresh matter.

• Iron_mg_kgFM: Iron content in mg per kg fresh matter.

• Zinc_mg_kgFM: Zinc content in mg per kg fresh matter.

• Magnesium_mg_kgFM: Magnesium content in mg per kg fresh matter.

• Cadmium_microg_kgFM: Cadmium content in micrograms per kg fresh matter.

• VitaminB12_microg_kgFM: Vitamin B12 content in micrograms per kg fresh matter.

• VitaminD_microg_kgFM: Vitamin D content in micrograms per kg fresh matter.

• Folate_microg_kgFM: Folate content in micrograms per kg fresh matter.

• VitaminC_mg_kgFM: Vitamin C content in mg per kg fresh matter.

• VitaminE_mg_kgFM: Vitamin E content in mg per kg fresh matter.

• Flavonoids_mg_kgFM: Flavonoid content in mg per kg fresh matter.

• Carotenoids_mg_kgFM: Carotenoid content in mg per kg fresh matter.

Details

This is the single source of biomass coefficients in the package. Until #489 a biomass_coefs pin frozen at ⁠20250728T082553Z⁠ was also readable through whep_read_file(); it was a narrowed 2025 export that disagreed with this table on 12 of their 36 shared columns, so the same commodity carried different nitrogen coefficients depending on which path read it. The pin has been retired and all callers now read this dataset.

Five runtime-dead below-ground fields were retired from this legacy table: BG_Biomass_kgDM_ha, Root_Shoot_ratio, Root_kgC_kgDM, Rhizodeposits_mass_kgC_kgDM, and Rhizodeposits_N_kgN_kgRootN. Their related item-keyed fields in bio_coefs are, respectively, bg_biomass_dm_kg_ha, root_shoot_ratio, root_c_kgdm, rhizodeposit_mass_c_kgdm, and rhizodeposit_n_kgn_krootn. This is not a universal one-to-one row mapping. calculate_crop_roots() uses ipcc_root_coefs$bg_ref_dm_t_ha and ipcc_root_coefs$rs_default when they are available, with the corresponding bio_coefs fields as fallbacks. root_c_kgdm and rhizodeposit_n_kgn_krootn are direct calculation inputs. rhizodeposit_mass_c_kgdm is an integrity and documentation component that is already included in root_c_kgdm, rather than a separate runtime input.

Three all-caps rows of the source spreadsheet are section headers rather than commodities and are dropped at ingestion (#752): ⁠TRANSFORMED PRODUCTS⁠ and ⁠AGRO-INDUSTRY BYPRODUCTS⁠ are empty, and ⁠ANIMAL PRODUCTS⁠ holds the VLOOKUP column-index vector the upstream Coefs sheet addresses by absolute position, which read as data claims an Edible_portion of 4.

The ⁠Aquatic Plants⁠ row is WHEP's own, not the upstream workbook's, which has no seaweed row: items_full bridged CBS item 2775 to a placeholder name that matched nothing, so its feed mass dropped out of feed availability and its food mass carried no protein or energy (whep#970). Two sources fill it, one per use:

• Food (N_kgN_kgFM, GE_product_MJ_kgFM, Lipids_g_kgFM, Edible_portion): FAO's own composition factor for the item, read from FAO, Food balance sheets: a handbook, Rome, 2001, Annex I "Food composition in terms of retail weight", row ⁠AQUATIC PLANTS⁠, PDF page 68 (printed 64), https://www.fao.org/docrep/pdf/011/x9892e/x9892e00.pdf: 54 kcal, 2.8 g protein and 0.6 g fat per 100 g of the commodity as recorded, i.e. fresh. So nitrogen is 2.8 / 100 / 6.25 = 0.00448 kg per kg, the energy cell holds 540 kcal, 2.25936 MJ, per kg, and Edible_portion is 1 because FAO applies the factor to the recorded quantity directly. The energy is FAO's dietary energy, not bomb-calorimeter gross energy: it is what build_food_supply() turns into energy_kcal_cap_day, against FBS element 664. Oracle: FAOSTAT FBS item 2775, World (area 5000), 2010, implies 26.5 g protein per kg (element 671 over element 5142), 5.5% below the 2001 factor; and 372 kcal per kg, so current FBS uses a lower energy factor than the 2001 table.

• Feed (Product_kgDM_kgFM, Product_kgN_kgDM): Heuze, V., Tran, G., Giger-Reverdin, S., Lessire, M. and Lebas, F. (2017), Seaweeds (marine macroalgae), Feedipedia, INRAE, CIRAD, AFZ and FAO, https://feedipedia.org/node/78, table "Laminaria and Saccharina seaweeds" (fresh): dry matter 15.4% as fed (SD 3.6, range 9.7-22.5, n = 56), crude protein 9.8% of DM (n = 50), so 0.01568 kg N per kg DM. It is the only fresh-seaweed table on that page; the others are dried meals at 85-93% DM, which would put fresh mass at nearly its own dry weight.

The two disagree on nitrogen per kg of fresh matter – 0.00448 against 0.154 x 0.01568 = 0.00241 – because FAO's factor covers the whole aquatic-plant basket and Feedipedia's table covers kelps only. Protein differs widely across that basket: McHugh, D. J. (2003), A guide to the seaweed industry, FAO Fisheries Technical Paper 441, chapter 8, https://www.fao.org/4/y4765e/y4765e0b.htm, puts nori (Porphyra) at 30-50% protein and Laminaria at about 10%. Each value is kept on the use it was published for. Product_kgC_kgDM and the remaining columns are left empty: no source was read for them.

Source

Compiled from multiple sources including FAO food composition data, crop physiology literature, and IPCC Tier 1 coefficients.

Examples

head(biomass_coefs)

Description

Assembles the physical agricultural land support that build_n_inputs() allocates its non-crop-specific nitrogen terms over: per grid cell, polity, year and CBS item, the hectares of agricultural land available to receive nitrogen. Cropland hectares come from the LUH2-derived type_cropland surface, split among crops by the static crop_patterns composition (normalised within each cell, so the cell's physical cropland area is apportioned rather than inflated by multicropping). Grassland hectares come from read_luh2_landuse()'s gridded grassland class and are all carried on CBS 3000, with no intensive/extensive split inferred. Both sides are split across border polities by the same cell_polity crosswalk.

Years with cropland but no grassland coverage (a grassland source that runs short of the cropland surface, as "luh2" does after 2015) keep their cropland support and raise a warning naming the affected years; supply data$grassland_ha to cover them.

Usage

build_ag_land_support(
  years = NULL,
  grassland = c("gridded_pasture", "luh2", "none"),
  polity_validity = c("keep", "flag", "drop"),
  data = list(),
  example = FALSE
)

Arguments

Value

A tibble with lon, lat, area_code, item_cbs_code, year, land_use ("cropland" or "grassland") and positive area_ha, plus the polity columns below, plus reporting_polity_out_of_span when polity_validity = "flag".

Polity columns

Every area-keyed output carries the polity its area_code resolves to in that row's year:

• polity_area_code: The numeric key rows are AGGREGATED on, for the matrix workflows. It is a bucket, not an identity: use reporting_polity_code to say which territory a row belongs to.

• reporting_polity_code: The polity itself, e.g. ESP-1846-1914. It is year-aware, so the same area_code resolves to different polities in different years, which is the point of the crosswalk.

• reporting_polity_name: Its name. It can differ from the area's own name where the area folds into an aggregate.

• reporting_polity_has_geometry: Whether the polity has a polygon in the WHEP polity database, for callers that need to map or intersect it. FALSE is a documented gap upstream, not an error.

Rows whose area_code resolves to no polity keep the columns with NA rather than being dropped, so a gap is visible instead of silent.

Rows before the back-cast anchor year resolve to the polity live in that anchor year rather than to the polity live in the row's own year, because WHEP's pre-anchor series are back-cast onto the anchor-year territory. See add_polity_code() for the reasoning. Where that polity is not live in the row's own year – 41.5% of the pre-1961 ⁠(area, year)⁠ cells – add_polity_code() says so as mapping_status == "backcast_anchor", and polity_coverage_gaps() reports it as gap_kind == "backcast_anchor". These columns do not say so either way.

A row whose year no mapped period covers is resolved to the NEAREST period of the same area instead, so reporting_polity_code can name a polity that did not exist in that row's year – FAOSTAT bucket 206 "Sudan (former)" keeps reporting after SUD-1956-2011 ends, and its post-2011 rows carry that code. These columns do not say so: add_polity_code() reports such a row as mapping_status == "out_of_span", and that column is dropped here so that adding it does not change the schema of every area-keyed output at once. polity_coverage_gaps() reports the stand-in rows of a built table, and options(whep.polity_mapping_status = "flag") (or "status") carries the signal on the outputs themselves. Both are opt-in; the default is no extra column.

Examples

build_ag_land_support(example = TRUE)

Description

Decision 10's allocation layer: ONE country grid in which each country is represented at exactly one depth. A container listed in granted arrives as its granted-depth units and as nothing else; every other country arrives as its level-0 row. The engines see a single grid and need no depth logic.

Usage

build_allocation_layer(grid0, grid_deep, granted)

Arguments

Value

grid0-shaped tibble with level_polity_code and level, carrying the ragged-coverage diagnostic in its "ragged_coverage" attribute and the unclaimed-land report in its "unclaimed_land" attribute (each a zero-row tibble when nothing was found).

The two-part assertion

(a), a one-sided abort

The shares of one physical cell may never EXCEED 1, within 1e-8, at any one year: the sum is taken over the rows valid together, once per epoch the layer carries, and a layer with no validity intervals is one epoch and therefore the unconditional sum T37 agreed on. Summing ACROSS epochs was the defect: two successive polities each hold their cell whole and never coexist, so every succession of the year-aware level-0 read – the USSR, Yugoslavia, Sudan, Czechoslovakia – summed to 2 and no year-aware grid could be combined with a granted depth. A sum above 1 is ground claimed twice – a container kept beside its own units – and is invisible downstream because every national total still reconciles, so it aborts with class whep_alloc_layer_not_partition. A sum BELOW 1 is not an error: it is land inside the cell that no reporting polity claims, the same unclaimed ground the year-aware level-0 read leaves out, and it is reported rather than refused (see the unclaimed-land section). A compartment holding two different shares of one cell IN ONE EPOCH is a contradiction rather than a share that moves, and is refused with class whep_alloc_layer_varying_share; a share that differs between two DISJOINT intervals of one compartment is now read at each of them, which is what the year-aware level-0 read produces on real data.

(b), a diagnostic

For every granted country: no container-keyed row survives anywhere, and per cell AND EPOCH the unit shares reproduce the country's level-0 share in that same epoch. Both sides are swept together per (cell, container), so neither is ever compared against a total taken across every epoch of the other. The epochs read are those of the container's own depth in the cell – from its first unit row to its last, gaps inside it included – because outside that span the layer holds no units for it at all and the 2015 snapshot claims every year, which is the vintage question open at T31(j) rather than anything the units did; land the layer then leaves unclaimed is reported by the other attribute. A container with no unit row in a cell at all is reported over its level-0 span. Rows that fail are RETURNED, in the "ragged_coverage" attribute, and are never back-filled with the container – back-filling would restore exactly the fold this feature removes. (b) failing is not by itself a defect: level 0 is a fixed 2015 snapshot while granted depths are year-filtered by edge validity, and how the two coexist is open at T31(j).

Unclaimed land

A cell whose shares fall short of 1 holds land that no reporting polity claims. That is a real state of the grid and not corruption: on the ⁠20260825T102349Z-1a0eb⁠ polycell support, the level-0 grid at the 2015 snapshot has 37 such cells out of 66,709 – the worst claimed to 0.0116 at (20.75, 42.75) – and the year-aware read leaves whole cells out on top of that, which is what validation/spatialize_grid_vintage.R sizes per year. Aborting on the shortfall would stop every granted-depth run on real data; ignoring it would hide land that no national total accounts for. So it is measured and returned, ONE ROW PER (CELL, EPOCH) that falls short, in the "unclaimed_land" attribute: lon, lat, start_year, end_year (NA for a bound the layer never gave), claimed_share, unclaimed_share, and unclaimed_ha. A caller reads that attribute to learn how much land is unclaimed, where, AND WHEN.

The epoch is in the report because a cell is not one claim: it is short in the years it is short. Judging each cell at its fullest epoch instead – the moment the double-claim check has to read – forgives a cell short only before one of its holders existed, but by the same line of code it also hides a cell that goes short in a LATER epoch, which is what a granted depth ending before its container produces, and it turned an abort into silence. So every epoch is read.

WHICH YEARS ARE READ is a second question, and reading each cell between its own first claim and its last answered it wrongly. A depth stops covering its container either by holding a smaller share or by holding NO ROW – which is what a real deep grid produces, since a unit has no rows outside its validity – and in the second case the cell's last claim IS the depth's end, so the window closed exactly where the silence began. On the ⁠20260825T102349Z-1a0eb⁠ support, a depth for area_code 33 that reproduces its level-0 shares exactly but stops in 1990 left 7,810 of the 8,109 cells it still holds after 1990 in neither report – 826.5 Mha of land, each cell counted once – and 0 ragged rows. It is now 0 cells.

The window is therefore the union of the layer's span in the cell and the level-0 span of the granted containers holding it: the same rule at both ends, so a depth that starts late is caught like one that ends early, and a cell the depth never reaches at all is read over the level-0 span alone. It widens only to years level 0 itself states – a row carrying no validity interval (the 2015 snapshot, which has no time dimension) gives no bound to fall short of, and the window then stops at the layer's own.

The ragged-coverage report does NOT widen with it, and the asymmetry is deliberate. This report asks what the LAYER claims, where absence is a fact whatever grid0's vintage; assertion (b) COMPARES two grids, and outside a container's depth span it would be comparing year-scoped units against a level 0 that may claim every year by having no time dimension at all – the open vintage question at T31(j), not a defect of the units. So the land a stopped depth leaves is reported here, once, rather than twice or not at all.

unclaimed_ha is NA where the layer carries no land_area_ha at all – never 0, which would deny the shortfall. For an epoch no compartment claims, the shortfall is instead read from base: grid0's own row for the granted container, in that same cell and on its own interval, which .level_cell_segments(shares, base) already receives base for and which carries a measurement rather than an absence. unclaimed_ha is NA there only when base itself gives no matching land for the epoch – no base was supplied (a direct caller of the internal .level_unclaimed_ha()), or the container's own row carries no land_area_ha either. Every hectare figure this function reports assumes land_area_ha on each row already equals cell_area_frac times the cell's whole land; that is a contract on the CALLER's grid0 and grid_deep, not something re-derived or checked here, so a layer whose two disagree reports the column's stated value. The attribute is always present; it is a zero-row tibble when every cell is fully claimed in every epoch, and also on the no-grant path, which returns grid0 unexamined.

See Also

read_level_country_grid().

Examples

grid0 <- tibble::tribble(
  ~lon,  ~lat, ~area_code, ~cell_area_frac,
  10.25, 40.25,       900L,             0.6,
  10.25, 40.25,       901L,             0.4
)
grid_deep <- tibble::tribble(
  ~lon,  ~lat, ~area_code, ~level_polity_code, ~level, ~cell_area_frac,
  10.25, 40.25,       900L, "A-A1-1900-2100",      1L,             0.25,
  10.25, 40.25,       900L, "A-A2-1900-2100",      1L,             0.35,
  10.25, 40.25,       901L, NA_character_,         0L,             0.4
)
granted <- tibble::tibble(area_code = 900L, level = 1L)
build_allocation_layer(grid0, grid_deep, granted)

Description

Reconstruct per-cell soil-organic-carbon stock trajectories: run the selected turnover model to equilibrium under the earliest per-land-use carbon inputs, open each land-use class at the stock init selects, march forward on yearly per-cell per-land-use areas applying the model annual update plus a carbon-conserving land-use-change transfer, and derive the soil-organic-nitrogen change from the carbon rate via asymmetric soil carbon-to-nitrogen ratios.

Usage

build_carbon_balance(
  model = c("hsoc", "rothc", "icbm", "amg", "century", "lpjml"),
  init = c("own_equilibrium", "cell_average"),
  resolution = c("grid", "polity"),
  polity_validity = c("keep", "flag", "drop"),
  data = list(),
  years = NULL,
  crop_groups = list(),
  class_water = c("cell", "regime"),
  density_basis = c("renormalised", "static"),
  method_grazing = c("whep", "lpjml"),
  method_som_cn = c("justes_2009", "nicolardot_2001", "century"),
  method_input_cn = c("known_crops", "require_all"),
  block_years = 10L,
  example = FALSE
)

Arguments

Details

polity_validity governs this function's own output. The internal get_soc_climate_drivers read it falls back on always keeps its rows: the march needs a climate modifier for every cell-year it steps through, so dropping driver rows for an anachronistic polity label would break the trajectory rather than relabel it. The driver read therefore warns on its own key space (whep#462) while this argument decides the fate of the balance rows.

Value

A tibble keyed by (lon, lat, area_code, land_use, year) at "grid" resolution (or (area_code, year) at "polity"), with stock_mgc_ha, mineralization_mgc_ha, c_input_mgc_ha, luc_transfer_mgc_ha, luc_transfer_mgc, rate_mgc_ha, son_change_kgn_ha, area_ha, and one column per method choice that moves a number: method_soc, method_soc_init, method_class_water, method_area_basis, method_grazing, method_som_cn and method_input_cn and method_crop_groups. All of them survive the "polity" roll-up, which additionally carries input_land_ha (the land the land-use input gave that polity-year) and modelled_land_frac (area_ha / input_land_ha, the share of it the densities in the same row are a mean over); see the coverage section below. Plus the polity columns below, plus reporting_polity_out_of_span when polity_validity = "flag".

Memory, and why the span is built in blocks

Built in one pass, every stage holds the whole span at once, and two of them hold many times the table they return: the monthly climate read peaks at about 15 times its output and the output tail at 5 to 6 times its own (whep#1287). block_years bounds both by the block instead. Measured on the real grid as the process's peak committed memory, with the carbon inputs supplied, and the output identical in every case:

The single pass grows by about 0.8 GB per year of span. A blocked build grows only by what it must keep: the output (about 0.12 GB per year at "grid") and the carbon inputs (about 0.08 GB per year), which are read once over the whole span because a year-scoped production and commodity build returns different rows for the same years (whep#833, whep#834). From 1961-1966 to 1961-1972 the 3-year build rose 1.20 GB, against 1.17 GB for those two terms. Each year added to the block costs about 0.5 GB.

Extrapolated linearly from these points to 1931-2023 (not measured there), one pass would need about 80 GB, 10-year blocks about 33 GB and 3-year blocks about 29 GB, while the span-wide carbon-input read that precedes the blocks is extrapolated in whep#1287 to 45-55 GB. The default of 10 years keeps the blocks below that read, which is then the build's peak; every block re-reads the static cell support, clay and climate series, at 3 to 4 minutes a block, so 3-year blocks would cost about an hour more over 1931-2023 to save about 4 GB that the carbon-input read has already spent.

Nothing about the carbon itself is decided per block. The balance opens from the first year it marches, and the year-less equilibrium-climate normal is read only then; the check that every cell carries every year runs across block boundaries; and each warning and message the class table and the output tail raise is gathered over the blocks and raised once for the whole span, as a single pass raises it. Messages the land-use and climate readers raise about their own read are raised by each block's read.

The land-use-change ledger closes on mass, not on density

luc_transfer_mgc_ha is the carbon a class received (positive) or gave up (negative) through land-use change, per hectare of the class's CURRENT area. A class whose area falls to zero still gives up its whole stock – the balance carries the row at zero area and moves the carbon into the growing classes – but at zero hectares that outflow has no per-hectare expression, so it is reported as 0 and sum(luc_transfer_mgc_ha * area_ha) over a cell-year is then positive by exactly the vanished stock. luc_transfer_mgc is the same transfer as a signed mass in Mg C, on every row including the vanished one, and sums to zero within every cell-year (and, at "polity" resolution, is the summed mass). Check conservation on the mass column.

Soil depth

Every carbon and nitrogen density this function reports – stock_mgc_ha, mineralization_mgc_ha, c_input_mgc_ha, luc_transfer_mgc_ha, rate_mgc_ha and son_change_kgn_ha – is a 0-30 cm topsoil quantity, not a whole-profile one. The depth is a property of the model family, not a free choice: HSOC comes from Aguilera et al. (2018), which states that "the model was applied to the 0-30 cm layer of the soil"; the humification fractions in residue_humification are that paper's Table 2; and the RothC/HSOC climate modifier rescales RothC's own 0-23 cm maximum topsoil-moisture-deficit expression to 30 cm (soc_rate_modifier_rothc(soil_depth_m = 0.3)).

Comparing this output against a whole-profile soil-carbon product is therefore a category error. LPJmL's soilc, in particular, reports carbon over its top 3 m and is roughly three times a topsoil stock; global 0-30 cm references such as GSOCmap are the valid comparators. Stating this is not pedantry – an unstated depth convention is what made a chain of contradictory diagnoses possible (whep#799).

Spatial support

Every default reader on the carbon path – the land-use areas, the carbon inputs, the climate drivers and the clay – resolves its cell-to-polity table through one polycell support (read_polycell_support()), read at a static reference year. A cell shared between polities therefore delivers to each only the land it holds there, and no reader can be left on a different crosswalk: half the path on one footprint and half on another would surface as an ordinary climate-coverage warning from the modifier join, not as an error. Land the reporting vocabulary cannot key (no area_code) is reported and dropped, never folded into another polity's.

A polity total covers the modelled land, not the polity

The climate drivers are on the LPJmL run's grid, a coarser land mask than LUH2's, so land outside it has no climate modifier and leaves the balance. A "polity" row is therefore an area-weighted mean over the hectares that survived, and modelled_land_frac is the share of the polity-year's land that did: read it before quoting a national stock or trend. It is not a quality flag on the hectares that are there – they are modelled exactly as before – and no value in this output changes because of it.

Measured at 2010 against the pinned lpjml-soc-hydrology grid, which drops 296.5 Mha of LUH2 land over 7,070 cell-polity compartments: global coverage is 0.977, 149 of 193 polities are below 1, 51 are below 0.9, and 12 carry no row at all – Antigua and Barbuda, Bahrain, Barbados, Dominica, Grenada, Macao, Malta, Mauritius, Saint Kitts and Nevis, Saint Lucia, Singapore and Tonga, whose land is entirely outside the grid. Worst of those that survive: Cabo Verde 0.22, Rest of World 0.31, Vanuatu 0.32, Bahamas 0.32, Cyprus 0.35, Somalia 0.72 (18.0 Mha), the Philippines 0.73 (7.7 Mha), Greece 0.76 (3.1 Mha). A warning names the polities that vanish, because no column on the output can: they have no row to carry one.

The land is reported rather than gap-filled, and that is a decision with evidence behind it (whep#1166). The run grid holds 58,795 cells against CRU TS's 67,420 land cells, and what it excludes is fractional-land coastal and island cells: median land fraction 0.14, against 0.998 inside the grid. CRU still carries temperature, PET and precipitation for 5,981 of the 6,847 cells that go – 291.5 of the 296.5 Mha – so a climate could be assembled there without LPJmL. The carbon input could not: 261.4 of those 296.5 Mha are natural (214.8) and grassland (46.6), whose input is the LPJmL net carbon flux, and this package holds no second source for it. Filling the climate alone would march 261.4 Mha on a zero-filled carbon input, draining its whole opening stock – the failure whep#1146 named, which today reaches 0.212 ha globally. Filling the input as well means asserting a productivity for land the model was never run on. Only a rerun on a land mask matching LUH2's puts real carbon on those hectares.

What this balance does not cover

The balance runs on the LPJmL grid, because the climate drivers do. That grid is a coarser land mask than LUH2's, so not every LUH2 hectare is in the output. On the default readers at 2010, 7,079 cell-polity compartments carrying 296.8 Mha of LUH2 land – 30.4 Mha cropland, 46.6 Mha grassland, 214.9 Mha natural, 4.8 Mha urban – have no climate driver and are dropped, with a warning naming the hectares and the worst-hit polities. The loss is essentially a coastline, so it is negligible globally (1.4% of grassland, 2.6% of natural land) and large for maritime polities: 31.6% of Greece's grassland, 25.3% of the Philippines', 22.7% of Somalia's, 17.8% of Indonesia's, 12.8% of the United Kingdom's, 12.5% of Italy's. A national SOC total from this function is a total over the modelled hectares, not over the polity.

Dropped is not the same as marched at zero. A class with LUH2 area but no carbon-input row IS kept, at zero input (that is what makes urban dilute rather than deflate the cell), and whep#1146 read the coverage gap as that case. It is not: measured against the lpjml-grass-natural-net-c pin and the real climate table, every one of those 46.6 Mha of grassland is dropped for want of a climate driver, and the grassland actually marching on a zero-filled input is 0.212 ha globally at 2010. Both quantities are reported at run time rather than left to be re-derived.

The support is keyed on the polity_area_crosswalk polity_area_code bucket, because that is what every national table the path joins to carries: .aggregate_to_polities() groups on that column and renames it area_code. Sudan and South Sudan therefore report together under 206, as they do in the production and CBS series. The fold is read through the live crosswalk, so options(whep.unfold_rest_of_world) and any future un-fold of 206 (whep#680) move the grid and the national tables together rather than separating them (whep#1168).

Polity columns

Every area-keyed output carries the polity its area_code resolves to in that row's year:

• polity_area_code: The numeric key rows are AGGREGATED on, for the matrix workflows. It is a bucket, not an identity: use reporting_polity_code to say which territory a row belongs to.

• reporting_polity_code: The polity itself, e.g. ESP-1846-1914. It is year-aware, so the same area_code resolves to different polities in different years, which is the point of the crosswalk.

• reporting_polity_name: Its name. It can differ from the area's own name where the area folds into an aggregate.

• reporting_polity_has_geometry: Whether the polity has a polygon in the WHEP polity database, for callers that need to map or intersect it. FALSE is a documented gap upstream, not an error.

Rows whose area_code resolves to no polity keep the columns with NA rather than being dropped, so a gap is visible instead of silent.

Rows before the back-cast anchor year resolve to the polity live in that anchor year rather than to the polity live in the row's own year, because WHEP's pre-anchor series are back-cast onto the anchor-year territory. See add_polity_code() for the reasoning. Where that polity is not live in the row's own year – 41.5% of the pre-1961 ⁠(area, year)⁠ cells – add_polity_code() says so as mapping_status == "backcast_anchor", and polity_coverage_gaps() reports it as gap_kind == "backcast_anchor". These columns do not say so either way.

A row whose year no mapped period covers is resolved to the NEAREST period of the same area instead, so reporting_polity_code can name a polity that did not exist in that row's year – FAOSTAT bucket 206 "Sudan (former)" keeps reporting after SUD-1956-2011 ends, and its post-2011 rows carry that code. These columns do not say so: add_polity_code() reports such a row as mapping_status == "out_of_span", and that column is dropped here so that adding it does not change the schema of every area-keyed output at once. polity_coverage_gaps() reports the stand-in rows of a built table, and options(whep.polity_mapping_status = "flag") (or "status") carries the signal on the outputs themselves. Both are opt-in; the default is no extra column.

Source

Aguilera, E., Guzman, G. I., Alvaro-Fuentes, J., Infante-Amate, J., Garcia-Ruiz, R., Carranza-Gallego, G., Soto, D. & Gonzalez de Molina, M. (2018). A historical perspective on soil organic carbon in Mediterranean cropland (Spain, 1900-2008). Science of the Total Environment, 621, 634-648. doi:10.1016/j.scitotenv.2017.11.243; land-use-change carbon transfer ported from an earlier regional historical reconstruction.

Examples

build_carbon_balance(example = TRUE)

Description

Build the carbon-input layer build_carbon_balance() consumes, keyed by ⁠(lon, lat, area_code, year, land_use)⁠. The cropland class aggregates the per-crop cropland inputs from build_soil_carbon_inputs() to the class grain: the class carbon density is the harvested-area-weighted mean of the per-crop densities, and the humification fraction is the carbon-mass-weighted mean of the per-crop fractions (mass = density times area). The grassland and natural classes come from build_grass_natural_carbon_inputs() unchanged.

Usage

build_carbon_inputs(
  resolution = c("grid", "polity"),
  data = list(),
  years = NULL,
  crop_groups = list(),
  density_basis = c("renormalised", "static"),
  method_grazing = c("whep", "lpjml"),
  method_unspatialized = c("fodder_pattern", "reallocate", "drop"),
  method_input_cn = c("known_crops", "require_all"),
  method_crop_weights = c("spatialized", "static"),
  method_manure_placement = c("livestock", "crop_area"),
  example = FALSE
)

Arguments

Value

A tibble keyed by ⁠(lon, lat, area_code, year, land_use)⁠ at "grid" resolution (or ⁠(area_code, year, land_use)⁠ at "polity"), with c_input_mgc_ha_yr, humified_fraction, method_c_input, and method_unspatialized, method_input_cn, method_crop_weights and method_manure_placement (all NA on the grassland and natural classes, which are neither spatialized from polity-crop totals nor collapsed from crops), for land_use in "cropland", "grassland" and "natural", plus the polity columns below. Cropland groups also carry the regime split, NA on the single "cropland" class and on grassland and natural:

• method_regime: the crop_groups$regime rule, "yield_split" or "area_split".

• method_regime_split: the split rules of the class's crop parts, sorted and joined by "|": "yield_ratio" (part yields from the regime yield ratio), "trivial_rainfed_only" and "trivial_irrigated_only" (the crop has one regime in the cell), "no_ratio" (no ratio for the cell-crop-year), "area_no_production" (no national yield), "area_no_components" (the per-crop layer has no residue and root densities), "area_split" (asked for) and "no_regime_share" (no irrigated share; booked rainfed). The last five keep the crop's own densities on both parts.

• method_residue_regime: how the parts' residue and root were set, joined the same way: "part_yield" (re-evaluated at a rainfed part's yield), "part_yield_irrigation_terms" (re-evaluated at an irrigated part's yield, with the model's irrigation terms) or "crop_density" (the crop's own density).

• yield_split_c_share: the share of the class's carbon input from crop parts re-evaluated at the part yields of the regime yield ratio (rule "yield_ratio").

• method_regime_cn: how the parts' input C:N was formed, joined the same way: "part_input_cn" (from the part's own components' carbon and nitrogen) or "crop_input_cn" (the crop's, where the per-crop layer carries no component nitrogen).

Polity columns

Every area-keyed output carries the polity its area_code resolves to in that row's year:

• polity_area_code: The numeric key rows are AGGREGATED on, for the matrix workflows. It is a bucket, not an identity: use reporting_polity_code to say which territory a row belongs to.

• reporting_polity_code: The polity itself, e.g. ESP-1846-1914. It is year-aware, so the same area_code resolves to different polities in different years, which is the point of the crosswalk.

• reporting_polity_name: Its name. It can differ from the area's own name where the area folds into an aggregate.

• reporting_polity_has_geometry: Whether the polity has a polygon in the WHEP polity database, for callers that need to map or intersect it. FALSE is a documented gap upstream, not an error.

Rows whose area_code resolves to no polity keep the columns with NA rather than being dropped, so a gap is visible instead of silent.

Rows before the back-cast anchor year resolve to the polity live in that anchor year rather than to the polity live in the row's own year, because WHEP's pre-anchor series are back-cast onto the anchor-year territory. See add_polity_code() for the reasoning. Where that polity is not live in the row's own year – 41.5% of the pre-1961 ⁠(area, year)⁠ cells – add_polity_code() says so as mapping_status == "backcast_anchor", and polity_coverage_gaps() reports it as gap_kind == "backcast_anchor". These columns do not say so either way.

A row whose year no mapped period covers is resolved to the NEAREST period of the same area instead, so reporting_polity_code can name a polity that did not exist in that row's year – FAOSTAT bucket 206 "Sudan (former)" keeps reporting after SUD-1956-2011 ends, and its post-2011 rows carry that code. These columns do not say so: add_polity_code() reports such a row as mapping_status == "out_of_span", and that column is dropped here so that adding it does not change the schema of every area-keyed output at once. polity_coverage_gaps() reports the stand-in rows of a built table, and options(whep.polity_mapping_status = "flag") (or "status") carries the signal on the outputs themselves. Both are opt-in; the default is no extra column.

Source

Cropland inputs from build_soil_carbon_inputs(); grassland and natural inputs from build_grass_natural_carbon_inputs(); assembled per the WHEP historical carbon-balance design.

Examples

build_carbon_inputs(example = TRUE)

Description

Compute prices for all commodity balance sheet items, including processed products and crop residues. Prices are derived from trade data, with special handling for items without direct trade prices (palm kernels, soy hulls, brans, etc.). Crop residue prices are estimated as a fraction of the product price: only primary crops and grassland bear residues, routed to straw (cereals and pulses), firewood (woody crops) or other crop residues. Crops whose herbaceous/woody habit is unknown take the herbaceous default and are reported in a warning.

Usage

build_cbs_prices(
  cbs,
  trade_prices = NULL,
  residue_price_factor = 0.1,
  example = FALSE
)

Arguments

Value

A tibble with columns:

• year: Integer year.

• element: "import" or "export".

• item_cbs_code: Numeric CBS item code.

• price: Price in KDollars per tonne.

Examples

build_cbs_prices(example = TRUE)

Description

Reduce CRU TS monthly near-surface temperature to a mean annual temperature (MAT) per 0.5-degree land cell and year, and classify each cell into the IPCC manure-management climate zone ("Cool", "Temperate", "Warm") that climate_mcf is keyed on. This is the per-cell replacement for the single hardcoded "Temperate" zone the manure CH4 model falls back to when no zone is supplied.

CRU TS covers 1901 onwards, so years outside its span cannot be measured. They are not dropped and not silently given a measured year's value: the 30-year climatology at the nearest end of the record is held constant across them and stamped in method_climate_zone with its own label (for example "climatology_1901_1930"), so a reader can tell a backcast zone from a measured one without reading this code. Holding an early-record climatology constant backwards is an assumption, not an observation.

Usage

build_cell_climate_zone(
  years = NULL,
  cru_dir = NULL,
  data = NULL,
  example = FALSE
)

Arguments

Value

A tibble with one row per cell and year:

• lon, lat: Cell centre coordinates (0.5-degree grid).

• year: Calendar year.

• mean_annual_temp_c: Mean annual near-surface air temperature (degrees Celsius), the mean of the twelve monthly CRU values.

• climate_zone: IPCC zone, "Cool", "Temperate" or "Warm".

• method_climate_zone: "cru_ts_annual" for a measured year, or "climatology_<first>_<last>" for a held climatology.

Source

CRU TS (Climatic Research Unit, University of East Anglia; Harris, Osborn & Jones 2020, Scientific Data, doi:10.1038/s41597-020-0453-3). Zone cuts: IPCC 2006 Guidelines Vol.4 Ch.3, adopted by the 2019 Refinement Vol.4 Ch.10.

Examples

build_cell_climate_zone(example = TRUE)

Description

Classify each cell, polity, commodity balance item, water regime and year of WHEP's own crop land use as IPCC 2019 wet or dry, the classes the Tier 1 managed-soil factors are keyed on.

A zone is tropical where the mean annual temperature exceeds 18 degC and there are at most 7 frost days per year (IPCC 2019 Refinement, Volume 4, Chapter 3, Figure 3A.5.2, p. 3.48). A tropical row is wet where its annual water exceeds 1000 mm; any other row is wet where its annual water divided by potential evapotranspiration (PET) exceeds 1; every other row is dry. Both tests are strict, so a value of exactly 1 or exactly 1000 mm is dry (Volume 4, Chapter 11, Table 11.1, footnote 4, p. 11.13). Footnote 4 bases the disaggregation on long-term averages, so by default the inputs are averaged over the 30 years ending in each year before they are classified.

The water term is precipitation plus, on irrigated rows, the irrigation depth of the row's crops (water = "precip_irrig", the default), or precipitation alone (water = "precip"). Rainfed rows get no irrigation.

Usage

build_cell_moisture_regime(
  years = NULL,
  window = c("trailing_30", "annual", "normal"),
  water = c("precip_irrig", "precip"),
  data = NULL,
  config = list(),
  example = FALSE
)

Arguments

Details

Inputs:

• Climate comes from CRU TS: annual mean temperature, precipitation, PET and ground-frost days. CRU ships PET as a mean daily rate in mm per day, which is multiplied by the days of each month and summed over the year. CRU's frost count is synthetic: CRU derives it from the gridded minimum temperature. Years before the CRU record (1901) hold the 1901-1930 climatology, and years after it hold the climatology of its last 30 years. A cell of WHEP's crop land that holds no value of a CRU variable in any year (all four for a cell off CRU's land mask, mostly coastal and island cells; fewer for a cell CRU maps for some variables only) takes that variable's whole record from its nearest CRU land cell by great-circle distance between cell centres, among the cells that hold it in every year read. One donor supplies every variable the cell lacks, and the cell keeps the variables it has; a variable with gaps is not lent but left to the classifier, which reports the years without it. The distance is climate_fill_km, and a message of class whep_moisture_regime_nearest_climate counts the cells by the variables they took. The cell's own water term, irrigation included, is then applied.

• Irrigation depth is LPJmL's applied irrigation per crop stand, pooled to the commodity balance item by WHEP's irrigated hectares. LPJmL's paddy water on its rainfed rice stand is not counted: rainfed rows get none.

Value

A tibble with one row per lon, lat, area_code, item_cbs_code, water_regime and year where WHEP has hectares of that regime, carrying the window-mean mat_c, frost_days, prec_mm, pet_mm and irrig_mm, water_mm, moisture_ratio, tropical, moisture_regime ("wet", "dry" or NA), method_moisture_regime, climate_fill_km (the distance to the CRU cell whose climate variables a cell lacking some took, NA for a cell with all of its own), method_irrig_depth, lpjml_crop and the LPJmL vintage columns lpjml_version, lpjml_git_hash and lpjml_run, plus the polity columns below.

An irrigated row's irrigation is averaged over the window years in which WHEP irrigates that land, its climate over the whole window; a row irrigated in fewer than all of them carries ⁠irrig_years_<n>of<m>⁠ in method_moisture_regime. Where WHEP irrigates a crop the LPJmL run has no irrigated stand of in the cell, in a year the run covers, the depth is the crop's LPJmL depth averaged over the polity's cells that have the stand, weighted by WHEP's irrigated hectares, and method_irrig_depth says why: lpjml_landuse_vintage for a cell on the LPJmL grid (the run's land-use forcing differs from WHEP's there) or no_lpjml_cell for one outside it, with the suffix ⁠_world_mean⁠ where the polity has no such stand and the world's mean is used. A message of class whep_moisture_regime_stand_gap counts these rows and hectares by cause; its diagnosis field lists every case.

Irrigation depth stamps

method_irrig_depth holds the least direct method over the window years of the row's irrigation record, one of:

• lpjml_airrig_stand: the item's own LPJmL crop has an irrigated stand in the cell.

• lpjml_crop_proxy: another named LPJmL crop stands in for the item, as mapped in regime_yield_crop_mapping (fodder crops, for example).

• lpjml_others_proxy: the item sits on LPJmL's composite "others" stand of minor crops.

• lpjml_landuse_vintage: WHEP irrigates the crop in a cell of the LPJmL grid where the run has no irrigated stand of it, because the run's land-use forcing predates WHEP's current land use. The depth is the crop's mean over the polity's cells that have the stand, weighted by WHEP's irrigated hectares.

• no_lpjml_cell: the same fill for a cell outside the LPJmL grid.

• lpjml_landuse_vintage_world_mean and no_lpjml_cell_world_mean: the two fills above where the polity has no such stand that year, so the world's mean over the cells that have it is used.

• rainfed_regime: a rainfed row, zero by definition.

• NA: water = "precip", where there is no irrigation term.

A stamp carries two optional additions. The suffix ⁠_recycled_climate⁠ follows any of the seven LPJmL-derived methods above when a window year precedes 1901, because LPJmL recycles the 1901-1930 weather before its forcing starts. The field ⁠;outside_run_<n>of<m>_<fill>⁠ follows it when n of the window's m years lie outside the LPJmL run: those years take the mean of the series' own window years inside the run (⁠<fill>⁠ is series_mean) or, where it has none, its country's mean for the balance item (country_mean).

Moisture regime stamps

method_moisture_regime joins these fields with ⁠;⁠, in this order:

• ipcc2019_wet_dry: the rule.

• The window: annual, trailing_30 or ⁠normal_<first>_<last>⁠.

• The water term: precip or precip_irrig.

• Optional ⁠climatology_<first>_<last>_<n>of<m>⁠: n of the window's m years lie outside the CRU record and took the held climatology of the years ⁠<first>⁠ to ⁠<last>⁠.

• Optional ⁠irrig_years_<n>of<m>⁠: an irrigated row whose land is irrigated in n of the window's m years. Its irrigation is the mean of those n years and its climate the mean of all m.

• Optional ⁠nearest_cru_cell=<col>[+<col>...]⁠: the cell lacks these CRU climate variables (mat_c, frost_days, prec_mm, pet_mm) and took them from its nearest CRU land cell, climate_fill_km away; its other variables are its own.

• Optional, on an unclassified row (moisture_regime is NA): ⁠missing=<col>[+<col>...]⁠, the inputs whose window mean is unavailable, and pet_not_positive, a window-mean PET of zero. Nothing is zero-filled.

Errors

The function aborts, with these condition classes, when:

• whep_moisture_regime_years: years is NULL, empty or has a missing value.

• whep_moisture_regime_config: config has an unknown entry, or max_rows is not one positive number.

• whep_moisture_regime_period: normal_period is not a run of consecutive whole years.

• whep_moisture_regime_columns, whep_moisture_regime_empty, whep_moisture_regime_key, whep_moisture_regime_climate: an input table lacks a required column, has no rows, has a duplicated or missing key, or carries more than one climate for a cell-year; or no cell of the climate holds, in every year read, a variable that a cell lacks.

• whep_moisture_regime_domain: an input holds a negative precipitation, PET, frost count or irrigation depth, more than 366 frost days, a water_regime other than "rainfed" or "irrigated", or irrigation on a rainfed row.

• whep_moisture_regime_lpjml_grid: data$crop_depth has stand gaps but no data$lpjml_grid is supplied.

• whep_moisture_regime_stand_mapping: an irrigated production item has no LPJmL crop band.

• whep_moisture_regime_stand_no_mean: a crop has no irrigated LPJmL stand anywhere that year, so there is no depth to fill from.

• whep_moisture_regime_outside_run: an irrigated series-year outside the LPJmL run has no depth of its own or of its country to fill from.

• whep_absent_input: precipitation, PET, the irrigated hectares or the irrigation depth of the irrigated rows is absent, missing or all zero.

• ⁠whep_lpjml_irrig_depth_*⁠: the LPJmL irrigation depth layer rejects the regime areas, the run or its output cubes, or the pinned layer.

Messages of class whep_moisture_regime_unclassified, whep_moisture_regime_area_years and whep_moisture_regime_nearest_climate report rows left without a regime, window years the regime areas do not cover and cells that took climate variables from their nearest CRU cell.

Polity columns

Every area-keyed output carries the polity its area_code resolves to in that row's year:

• polity_area_code: The numeric key rows are AGGREGATED on, for the matrix workflows. It is a bucket, not an identity: use reporting_polity_code to say which territory a row belongs to.

• reporting_polity_code: The polity itself, e.g. ESP-1846-1914. It is year-aware, so the same area_code resolves to different polities in different years, which is the point of the crosswalk.

• reporting_polity_name: Its name. It can differ from the area's own name where the area folds into an aggregate.

• reporting_polity_has_geometry: Whether the polity has a polygon in the WHEP polity database, for callers that need to map or intersect it. FALSE is a documented gap upstream, not an error.

Rows whose area_code resolves to no polity keep the columns with NA rather than being dropped, so a gap is visible instead of silent.

Rows before the back-cast anchor year resolve to the polity live in that anchor year rather than to the polity live in the row's own year, because WHEP's pre-anchor series are back-cast onto the anchor-year territory. See add_polity_code() for the reasoning. Where that polity is not live in the row's own year – 41.5% of the pre-1961 ⁠(area, year)⁠ cells – add_polity_code() says so as mapping_status == "backcast_anchor", and polity_coverage_gaps() reports it as gap_kind == "backcast_anchor". These columns do not say so either way.

A row whose year no mapped period covers is resolved to the NEAREST period of the same area instead, so reporting_polity_code can name a polity that did not exist in that row's year – FAOSTAT bucket 206 "Sudan (former)" keeps reporting after SUD-1956-2011 ends, and its post-2011 rows carry that code. These columns do not say so: add_polity_code() reports such a row as mapping_status == "out_of_span", and that column is dropped here so that adding it does not change the schema of every area-keyed output at once. polity_coverage_gaps() reports the stand-in rows of a built table, and options(whep.polity_mapping_status = "flag") (or "status") carries the signal on the outputs themselves. Both are opt-in; the default is no extra column.

Source

IPCC (2019), 2019 Refinement to the 2006 IPCC Guidelines for National Greenhouse Gas Inventories, Volume 4: Chapter 3, Figure 3A.5.2 (p. 3.48); Chapter 11, Table 11.1, footnote 4 (p. 11.13).

CRU TS version 4.09 (files ⁠cru_ts4.09.1901.2024.<var>.dat.nc⁠), Climatic Research Unit, University of East Anglia.

Examples

build_cell_moisture_regime(example = TRUE)

Description

Reads the cell-polity fraction table (lon, lat, area_code, polity_frac) and adds cell_area_ha, computed from latitude with the same 0.5-degree cell-area formula used across the package (see build_grass_availability_lpjml()). This assembles the data$cell_polity contract that every Module C function (e.g. build_n_deposition(), build_human_n(), get_soc_climate_drivers()) expects as a required input.

Usage

build_cell_polity(
  polity_fraction_path = NULL,
  area_key = c("grid", "polity_area"),
  version = NULL,
  example = FALSE,
  year = NULL,
  reporting_areas = NULL
)

Arguments