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.

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

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.

Usage

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

Arguments

Value

A tibble with added polity metadata columns.

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)

Arguments

Value

A tibble with area_code, year and grass_avail_dm_t.

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

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.

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

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"), applied_n, applied_c, applied_vs, over_cap and the method_allocation, method_cap and disposal_method provenance columns.

Examples

applied <- tibble::tribble(
  ~year, ~territory, ~sub_territory, ~stream,
  ~applied_n, ~applied_c, ~applied_vs,
  2020L, "ESP", NA, "collected", 80, 800, 40,
  2020L, "ESP", NA, "grazing", 20, 380, 12
)
crops <- tibble::tribble(
  ~year, ~territory, ~sub_territory, ~crop, ~manure_n_receptivity, ~crop_n_cap,
  2020L, "ESP", NA, "barley", 6, 50,
  2020L, "ESP", NA, "wheat", 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 Spain's room-weighted first-ring redistribution (Calc_OA_redistribution); 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, "ESP", "1.5_40", 10, 90, 6
)
sink_cells <- tibble::tribble(
  ~year, ~territory, ~sub_territory, ~room_n,
  2020L, "ESP", "1_40", 4,
  2020L, "ESP", "2_40", 6
)
allocate_manure_transport(source_cells, sink_cells)

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 applied_n times the post-storage manure C:N (the solid/liquid/excreta value for the stream's management system), so the applied C:N reflects storage, not fresh excreta; the carbon and volatile-solids storage losses follow from that.

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 and method_losses.

Examples

excretion <- tibble::tribble(
  ~year, ~territory, ~sub_territory, ~livestock_category,
  ~n_excretion, ~c_excretion, ~vs_excretion,
  2020L, "ES", 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

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

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 68 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").

• BG_Biomass_kgDM_ha: Below-ground biomass in kg dry matter per hectare.

• Root_Shoot_ratio: Ratio of root to aerial biomass (dimensionless).

• 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.

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

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

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

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

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

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

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

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

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

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

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

• 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.

• 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_kgC_kgDM: Root plus rhizodeposit carbon in kg C per kg root dry matter.

• Root_humified_kgC_kgC: Humification coefficient for root carbon.

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

• Rhizodeposits_mass_kgC_kgDM: Rhizodeposit carbon 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.

• Rhizodeposits_N_kgN_kgRootN: Rhizodeposit nitrogen as a fraction of root nitrogen.

• 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.

Source

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

Examples

head(biomass_coefs)

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.

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

Construct commodity balance sheets (CBS) from raw FAOSTAT data. This is a convenience wrapper that chains the three pipeline steps:

1. .read_cbs() — read & reformat FAOSTAT CBS data.

2. .fix_cbs() — processing calibration, trade imputation, destiny filling, and final balancing.

3. .qc_cbs() — flag data-quality anomalies.

Usage

build_commodity_balances(
  primary_all,
  start_year = 1850,
  end_year = 2023,
  smooth_carry_forward = FALSE,
  example = FALSE,
  historical_data = NULL,
  .fixed_data = NULL
)

Arguments

Value

A tibble in long format with columns: year, legacy numeric area_code, numeric polity_area_code, reporting_polity_code, reporting_polity_name, reporting_polity_has_geometry, item_cbs_code, element (e.g. "production", "import", "food"), value, source, and fao_flag.

Examples

build_commodity_balances(example = TRUE)

Description

Estimates a time series of a quantity over a fixed set of territorial boundaries — the polities active in ref_year — from data reported under the changing historical boundaries of each data year.

Country borders change over time, so there is no raw constant-territory series: a 1900 figure for "Austria-Hungary" is not a figure for present-day Austria. This function estimates one by spatial reallocation (dasymetric areal interpolation):

1. For each data year, the value reported by each source polity is spread over that polity's own extent for that year across a regular grid, weighted by a covariate density (e.g. gridded cropland or population; uniform = plain areal weighting).

2. The grid is then re-aggregated to the ref_year target boundaries: a target's estimate is the sum of grid mass falling inside it.

3. Target territory not covered by any source with data in that year is imputed — its grid cells still carry covariate mass, so they are filled at a donor intensity (value per unit covariate) rather than left at zero. The fraction of a target's covariate mass that had to be imputed is reported as imputed_share, an honest confidence signal.

The estimate is only as good as the covariate: supply the same gridded surface used elsewhere in WHEP spatialization (cropland for crop output, population for demographic series, livestock density for animals). With covariate = NULL the method reduces to area-weighted areal interpolation.

Usage

build_constant_territory_series(
  data,
  ref_year,
  polities = NULL,
  covariate = NULL,
  resolution = 25000,
  donor = c("regional", "none"),
  crs_equal_area = 6933,
  max_cells = 2e+06,
  verbose = TRUE
)

Arguments

Value

A tibble, one row per (ref_year-target, data year):

• target_polity_code, year

• value: constant-territory estimate (covered + imputed)

• covered: mass from cells overlapping a source with data

• imputed: mass added for uncovered cells

• imputed_share: covariate fraction imputed (0 = fully observed)

• n_sources: number of source polities contributing that year

Examples

# Self-contained toy: two adjacent square polities. Only "P1" reports a
# value in 1900, so when the series is rebuilt onto the boundaries active in
# `ref_year` 2000 (both polities), "P2" is imputed from "P1"'s intensity.
make_square <- function(xmin, ymin, side) {
  sf::st_polygon(list(rbind(
    c(xmin, ymin),
    c(xmin + side, ymin),
    c(xmin + side, ymin + side),
    c(xmin, ymin + side),
    c(xmin, ymin)
  )))
}
polities <- sf::st_sf(
  polity_code = c("P1", "P2"),
  start_year = c(1800L, 1800L),
  end_year = c(2025L, 2025L),
  geometry = sf::st_sfc(
    make_square(0, 0, 2),
    make_square(2, 0, 2),
    crs = 4326
  )
)
reported <- tibble::tibble(
  year = 1900L,
  polity_code = "P1",
  value = 100
)
build_constant_territory_series(
  reported,
  ref_year = 2000,
  polities = polities,
  resolution = 50000,
  verbose = FALSE
)

Description

Convert gridded crop harvested area into per-crop physical land area and aggregate it to commodity-balance items, producing a land extension keyed by ⁠(year, area_code, item_cbs_code)⁠ for the FABIO footprint model.

The gridded land-use pipeline (build_gridded_landuse()) distributes FAOSTAT harvested area across grid cells; per-crop totals therefore conserve to harvested area, which over-counts multi-cropped land and under-counts fallow. This function turns that harvested area into physical occupied land:

• "cropland_apportion" (default): within each cell, the cell's physical cropland (cropland_ha, from LUH2) is split across crops in proportion to their share of the cell's harvested area. Per-crop physical area then conserves to physical cropland rather than to harvested area, capturing both double-cropping (scaled down) and fallow (resting land charged to the crops the rotation supports) at the resolution of the grid.

• "intensity_divide": each crop's harvested area is divided by the cell multi-cropping intensity (mc_rainfed, mc_irrigated). Requires multicropping.

Unlike a single country-level cropping-intensity factor applied uniformly to every crop, both methods distribute physical cropland by the actual spatial pattern of each crop.

Coverage note: with "cropland_apportion" the per-country crop total is bounded by the LUH2 cropland layer, which can under-represent perennial or plantation crops (e.g. oil palm, rubber) classified outside cropland; such crops may receive less land than a harvested-area baseline implies.

Usage

build_crop_land_extension(
  gridded_crops,
  gridded_cropland,
  items_prod_full = whep::items_prod_full,
  method = c("cropland_apportion", "intensity_divide"),
  multicropping = NULL
)

Arguments

Value

A tibble with columns year, area_code, item_cbs_code, impact_u (physical land area in hectares), and method_land (the chosen method).

Examples

gridded_crops <- tibble::tribble(
  ~lon, ~lat, ~year, ~area_code, ~item_prod_code, ~rainfed_ha, ~irrigated_ha,
  0.25, 50.25, 2000L, 1L, 15L, 600, 0,
  0.25, 50.25, 2000L, 1L, 27L, 200, 0,
  0.75, 50.25, 2000L, 1L, 15L, 400, 0
)
gridded_cropland <- tibble::tribble(
  ~lon, ~lat, ~year, ~cropland_ha,
  0.25, 50.25, 2000L, 1000,
  0.75, 50.25, 2000L, 500
)
items <- tibble::tribble(
  ~item_prod_code, ~item_cbs_code,
  15L, 2511L,
  27L, 2805L
)
build_crop_land_extension(gridded_crops, gridded_cropland, items_prod_full = items)

Description

Estimate IPCC 2019 Tier 1 nitrous-oxide emissions from nitrogen applied to managed soils, as a footprint extension keyed by ⁠(year, area_code, item_cbs_code)⁠ in kilograms of carbon-dioxide equivalent (CO2e). This is the soil-N2O analogue of build_livestock_ghg_extension() and feeds build_footprint() / compute_footprint() the same way.

Three nitrogen inputs to soil are included:

• Synthetic fertiliser (F_SN): FAOSTAT reports it only as a country total (tonnes N per area_code per year), so it is allocated to crops in proportion to each crop's harvested area within the country-year (from get_primary_production()).

• Applied manure (F_ON): FAOSTAT "Manure applied to soils (N content)" country total, allocated to crops by harvested area as for F_SN.

• Crop residues (F_CR): the dry matter of above-ground residues returned to soil (from get_primary_residues(), net of the removed fraction) times the crop's residue nitrogen content (IPCC 2019 Table 11.1a).

N2O is then estimated with IPCC 2019 Refinement (Vol 4, Ch 11) Tier 1 factors (climate-aggregated): direct EF1 = 0.010; indirect via volatilisation EF4 = 0.010 applied to the volatilised fraction (FracGASF = 0.11 for synthetic, FracGASM = 0.21 for manure; crop residues do not volatilise, Eq 11.9); indirect via leaching FracLEACH = 0.24 times EF5 = 0.011. N2O-N is converted to N2O by 44/28 and to CO2e with the chosen GWP100.

Manure deposited by grazing animals (F_PRP, which uses the grazing EF3 on pasture) and below-ground residue N are further Tier 1 inputs not yet included.

Usage

build_crop_soil_n2o_extension(
  gwp = c("ar6", "ar5", "ar4"),
  residue_removed_frac = 0.45,
  data = list(),
  example = FALSE
)

Arguments

Value

A tibble with columns year, area_code, item_cbs_code, impact_u (soil N2O in kilograms CO2e) and method_soil_n2o.

Examples

build_crop_soil_n2o_extension(example = TRUE)

Description

Convert FAOSTAT harvested area into per-crop physical cropland using CROPGRIDS, then return a land extension keyed by ⁠(year, area_code, item_cbs_code)⁠ for the FABIO footprint model.

CROPGRIDS (Tang et al. 2024) reports, per crop and country, both harvested area and crop (physical) area for 2020. Their ratio is a genuinely per-crop multi-cropping correction — e.g. rice ~0.81 (heavily double-cropped), most other crops ~0.95-1.0 (single-cropped) — which a single country-level cropping-intensity factor, or a cell-level apportionment by harvested share, cannot reproduce. This function applies that per-(area, item) physical / harvested ratio to WHEP harvested area in each year: $physical = harvested \times (physical_{cg} / harvested_{cg})$.

Note: CROPGRIDS physical area is the land where each crop actually grows; it excludes fallow land (unlike fallow-inclusive cropland-apportionment), so totals are typically a few percent below harvested area.

Coverage: crops absent from CROPGRIDS (notably the FAOSTAT fodder items and a few minor crops) have no physical/harvested ratio and fall back to a ratio of 1 (physical = harvested, no multi-cropping correction). The share of harvested area hitting this fallback is reported via a warning.

Usage

build_cropgrids_land_extension(
  harvested = NULL,
  cropgrids = NULL,
  source = c("cropgrids", "cropgrids_fallow"),
  max_ratio = 1.5,
  min_cropgrids_ha = 100
)

Arguments

Value

A tibble with columns year, area_code, item_cbs_code, impact_u (physical land area in hectares), and method_land.

Examples

harvested <- tibble::tribble(
  ~year, ~area_code, ~item_cbs_code, ~harvested_ha,
  2000L, 33L, 2511L, 1000,
  2000L, 33L, 2807L, 500
)
cropgrids <- tibble::tribble(
  ~area_code, ~item_cbs_code, ~physical_ha, ~harvested_ha,
  33L, 2511L, 990, 1000,
  33L, 2807L, 400, 500
)
build_cropgrids_land_extension(harvested, cropgrids)

Description

Construct the detailed bilateral trade matrix (DTM) from the FAOSTAT Detailed Trade Matrix pin. Reports trade flows between pairs of countries with their trade shares, aggregated to polity level and mapped to CBS item codes.

Optionally extends the time series by joining with commodity balance sheet years and gap-filling country shares via linear interpolation.

Usage

build_detailed_trade(
  raw_trade = NULL,
  cbs = NULL,
  min_share = 1e-04,
  extend_time = FALSE,
  example = FALSE
)

Arguments

Value

A tibble with columns:

• year: Integer year.

• area_code: Numeric polity code of the reporter country.

• area_code_partner: Numeric polity code of the partner country.

• element: Either "import" or "export".

• item_cbs_code: Numeric CBS item code.

• unit: Measurement unit ("tonnes" or "heads").

• value: Trade quantity.

• country_share: Share of total trade for this partner.

Examples

build_detailed_trade(example = TRUE)

Description

Aggregate GLEAM 3.0 on-farm (direct) and feed-production (embedded) energy use into a footprint extension keyed by ⁠(year, area_code, item_cbs_code)⁠, expressed in kilograms of carbon-dioxide equivalent (CO2e). This is the energy slice of the livestock greenhouse-gas basket and is designed to be summed with build_livestock_ghg_extension() (enteric and manure CH4/N2O), which keys on the same live-animal sectors.

The GLEAM energy emission factors are expressed per kilogram of live weight (see gleam_energy_use_ef), which is well defined for meat but not for milk or eggs, so the extension covers meat only: bovine (item_cbs_code 961 non-dairy cattle and 946 buffalo), sheep (976) and goat (1016), pig (1049 and 1051) and broiler-chicken (1053) meat. Milk and eggs keep their CH4/N2O but get no energy CO2.

For each meat group the live weight produced is recovered from FAOSTAT carcass production divided by a GLEAM dressing fraction (gleam_dressing_percentages), multiplied by a per-country energy intensity (embedded + direct), and then attributed to the contributing live-animal sectors in proportion to their slaughtered head counts. Because GLEAM reports its factors by production system and climate zone but the package has no country-level system or climate shares, the intensities are collapsed to one value per country by an unweighted mean across systems and climate zones; this choice is recorded in method_energy.

Usage

build_energy_co2_extension(method = c("gleam"), data = list(), example = FALSE)

Arguments

Value

A tibble with columns year, area_code, item_cbs_code, impact_u (energy-use emissions in kilograms CO2e) and method_energy (e.g. "GLEAM_3.0_energy_meat").

Examples

build_energy_co2_extension(example = TRUE)

Description

Turn per-crop harvested-derived physical area into a fallow-inclusive physical land extension whose arable-crop total reconciles to FAO's physical Arable land and whose perennial-crop total reconciles to FAO's physical Permanent crops (get_arable_permanent_land()), per ⁠(area_code, year)⁠.

This is the FAO-land-base analogue of build_cropgrids_land_extension()(source = "cropgrids_fallow"). The existing method takes the fallow magnitude from FAOSTAT "Temporary fallow" (item 6640, a sparse and, for many rain-fed economies, absent series) applied to a single CROPGRIDS 2020 snapshot. Here the fallow magnitude is the physical arable land that carried no harvest in that specific year, ⁠FAO Arable land - sum(cropped arable physical)⁠, so a drought year's resting cropland is charged to the crops whose rotation it supports and the arable-crop footprint totals match FAO's land survey in every year (see the Tunisia/Portugal motivation in get_arable_permanent_land()).

Reconciliation, per ⁠(area_code, year)⁠:

• Arable crops (items_prod_full$Herb_Woody != "Woody"): rotational fallow max(0, arable_ha - S) (with S the cropped arable physical total) is distributed with attribute_fallow_to_crops() using fallow_weights, so the arable total reaches arable_ha. Where the cropped physical already exceeds arable_ha (heavy multi-cropping, or inflated fodder harvested area) there is no fallow to add and the arable crops are scaled down to arable_ha instead, the physical-container correction. Either way the arable total equals FAO arable_ha by construction.

• Perennial crops (Herb_Woody == "Woody") receive no fallow and are scaled so their total equals FAO permanent_ha, preserving the within-group physical pattern. A positive target without a corresponding arable crop row or positive perennial base area is reported as an error because it cannot be reconciled without inventing a crop allocation.

This is the crop-side default of the land-balance footprint (build_land_balance_footprint()).

Usage

build_fao_arable_fallow_extension(
  harvested = NULL,
  arable_permanent = NULL,
  base_extension = NULL,
  fallow_weights = NULL,
  temporary_grassland = NULL,
  items_prod_full = whep::items_prod_full
)

Arguments

Value

A tibble with columns year, area_code, item_cbs_code, impact_u (fallow-inclusive physical land in hectares), and method_land ("fao_arable_fallow").

Temporary grassland (no double-count)

FAO's Arable land total includes temporary meadows and pastures — temporary grassland is part of cropland, not grassland. That land is also reported separately as CBS 3002 (⁠Temporary grassland⁠) by build_grassland_land_extension(), so summing both extensions naively would count it twice. Pass that grassland occupation as temporary_grassland and its CBS 3002 is netted out of the arable target before reconciling ordinary crops, enforcing the invariant per ⁠(area_code, year)⁠ ⁠ordinary crop occupation (incl. fallow) + CBS 3002 = FAO Arable land⁠. The land-balance footprint (build_land_balance_footprint()) does exactly this, passing the grassland occupation it has already built. When temporary_grassland is NULL (default) the grassland occupation extension is built internally so netting still happens — correct but slow, since that build reruns much of the pipeline; supply the table to avoid the rebuild. Where modelled CBS 3002 exceeds FAO Arable land (survey vs. fodder-reconstruction mismatch) the arable target is clamped at 0 and a warning is emitted.

Examples

harvested <- tibble::tribble(
  ~year, ~area_code, ~item_cbs_code, ~harvested_ha,
  2020L, 1L, 2511L, 300, # wheat (arable)
  2020L, 1L, 2560L, 100 # coconuts (perennial)
)
base_extension <- tibble::tribble(
  ~year, ~area_code, ~item_cbs_code, ~impact_u,
  2020L, 1L, 2511L, 300,
  2020L, 1L, 2560L, 100
)
arable_permanent <- tibble::tribble(
  ~area_code, ~year, ~arable_ha, ~permanent_ha,
  1L, 2020L, 500, 100
)
items <- tibble::tribble(
  ~item_cbs_code, ~Herb_Woody,
  2511L, "Herbaceous",
  2560L, "Woody"
)
temporary_grassland <- tibble::tribble(
  ~area_code, ~year, ~item_cbs_code, ~impact_u,
  1L, 2020L, 3002L, 100 # temporary grassland netted out of arable
)
build_fao_arable_fallow_extension(
  harvested, arable_permanent, base_extension,
  temporary_grassland = temporary_grassland,
  items_prod_full = items
)

Description

Estimate the dry-matter feed demand of each livestock category: the first stage of get_feed_intake(), exposed on its own. Demand is national, per ⁠(year, area_code, livestock_category)⁠, and is computed before any matching against feed supply, so it can be audited or reused (for example in land or nitrogen footprints) independently of the allocation.

Usage

build_feed_demand(
  demand_tier = c("ipcc", "fcr"),
  by = c("category", "feed_type"),
  example = FALSE
)

Arguments

Value

With by = "category", a tibble with one row per ⁠(year, area_code, livestock_category)⁠:

• year: The year of the demand.

• area_code: The country code. For code details see e.g. add_area_name().

• livestock_category: The feed-demand grouping of livestock (e.g. Cattle_milk, Cattle_meat, Pigs, Poultry).

• demand_dm_t: Dry-matter feed demand in tonnes.

• method_demand: The demand method(s) used, e.g. ipcc_tier2_energy, bouwman_fcr or krausmann_per_head (a +-joined set for a mixed category whose animals used different methods).

With by = "feed_type", the demand split across feed types as the redistribute_feed() feed_demand contract: year, territory, sub_territory, livestock_category, item_cbs_code, feed_group, feed_quality, demand_dm_t, fixed_demand.

Examples

build_feed_demand(example = TRUE)
build_feed_demand(example = TRUE, by = "feed_type")

Description

Runs the redistribute_feed local path (0.5-degree cell grain) one year at a time, so the per-cell allocation stays within memory and the full multi-year run is restartable. By default it sources pinned LPJmL-derived grass availability and pinned gridded livestock inputs. Pass run_dir, grass_availability, grass_availability_path, or input_dir to use custom local inputs instead.

Usage

build_feed_intake_local(
  years = NULL,
  out_dir = NULL,
  demand_tier = c("ipcc", "fcr"),
  feed_mode = c("historical", "scenario"),
  overwrite = FALSE,
  example = FALSE,
  run_dir = NULL,
  input_dir = NULL,
  grass_availability = NULL,
  grass_availability_path = NULL
)

Arguments

Value

When out_dir is NULL, a tibble in the get_feed_intake() contract plus a sub_territory (0.5-degree cell) column. Otherwise, invisibly, the written file paths.

Examples

build_feed_intake_local(example = TRUE)

Description

Trace a long-format environmental extension table through the supply chain for one or more years and return a tidy footprint. This wraps the three steps that the footprint driver scripts used to repeat inline: build (or reuse) the input-output model with build_io_model(), align the extension to each year's sector labels with align_extension(), and trace it with compute_footprint().

The extension table is the output of any ⁠build_*_extension()⁠ builder, such as build_grassland_land_extension() or build_livestock_ghg_extension(): rows keyed by year, area_code and item_cbs_code, with the pressure magnitude in value_col.

Usage

build_footprint(
  extension,
  years = NULL,
  io = NULL,
  method = c("mass", "value"),
  value_col = "impact_u",
  ...
)

Arguments

Value

A tibble of footprint flows as returned by compute_footprint(), with an added year column.

Examples

io <- tibble::tibble(
  year = 2000L,
  Z = list(matrix(c(0, 5, 10, 0), nrow = 2)),
  X = list(c(100, 200)),
  Y = list(matrix(c(85, 195), ncol = 1)),
  labels = list(tibble::tibble(
    index = 1:2,
    area_code = c(1L, 1L),
    item_cbs_code = c(1L, 2L)
  )),
  fd_labels = list(tibble::tibble(area_code = 1L, fd_col = "food"))
)
extension <- tibble::tibble(
  year = 2000L,
  area_code = 1L,
  item_cbs_code = c(1L, 2L),
  impact_u = c(50, 30)
)
build_footprint(extension, io = io)

Description

Multi-method wrapper for the grass forage supply ceiling that feeds allocation. The default lpjml method reads pinned LPJmL-derived managed-grassland net primary production/availability unless custom artifact data, a custom artifact path, or run_dir points to local inputs; coefficient applies a per-area grass-yield coefficient and is not yet implemented (it needs a grass_yield_coef dataset).

Usage

build_grass_availability(method = c("lpjml", "coefficient"), ...)

Arguments

Value

A tibble of grass availability with a method_grass column recording the method used.

Examples

build_grass_availability(method = "lpjml", example = TRUE)

Description

Reads managed-grassland net primary production/availability (the LPJmL grassland CFT) from the pinned WHEP artifact by default. Pass availability or availability_path to use a custom already-derived artifact; pass run_dir to read a finished local LPJmL run instead and convert NPP to grazable above-ground dry-matter availability, the forage supply ceiling for feed allocation. Availability is the production flux, not the realised grazing off-take (the off-take is the intake-validation target, not the supply).

Usage

build_grass_availability_lpjml(
  run_dir = NULL,
  years = NULL,
  first_year = 1901L,
  shares = grass_access_shares(),
  example = FALSE,
  availability = NULL,
  availability_path = NULL
)

Arguments

Value

A tibble with lon, lat, year, grass_npp_gc_m2, grass_avail_dm_t_ha and grass_avail_dm_t.

Examples

build_grass_availability_lpjml(example = TRUE)

Description

Produce a grassland land extension keyed by ⁠(year, area_code, item_cbs_code)⁠, replacing the grassland rows that used to come from the external land_fp pin.

Two area sources are available, selected with source:

• "luh2" (default): permanent and temporary grassland area (item_cbs 3000 and 3002, LUH2 pasture and rangeland) taken from build_primary_production(). This shares the gridded LUH2 land-use basis used by the crop land extensions and by livestock spatialisation. Rotational fallow (item_cbs 3003) is excluded because the cropgrids_fallow crop extension already attributes fallow to crops, so counting it here too would double count it.

• "faostat_pasture": FAOSTAT "Permanent meadows and pastures" area (Land Use item 6655), the statistics-based basis comparable to most published footprint studies.

Two metrics are available, selected with grassland_metric:

• "occupation" (default): the full grassland area is charged as occupied land.

• "active_grazing": grassland is capped at the area implied by actual grazing intake (the "grass" feed in get_feed_intake()) divided by a usable grass yield, so ungrazed or marginal rangeland is not charged.

Usage

build_grassland_land_extension(
  source = c("luh2", "faostat_pasture"),
  grassland_metric = c("occupation", "active_grazing"),
  usable_grass_yield_dm_t_ha = 2.06,
  data = list(),
  example = FALSE
)

Arguments

Value

A tibble with columns year, area_code, item_cbs_code, impact_u (grassland area in hectares) and method_grassland (the chosen metric).

Examples

build_grassland_land_extension(example = TRUE)

Description

End-to-end grazing-land footprint for one year on real WHEP data. Grazing land (the grassland extension) is pushed forward onto livestock meat and milk via allocate_grazing_to_products(), then routed to consuming countries through the bilateral meat-trade network with compute_footprint_balance(). This attributes grazing land to the meat and dairy consumption that drives it – the chain the Leontief footprint leaks because grass is non-productive and not traded.

The inputs are assembled from build_grassland_land_extension(), get_feed_intake(), get_primary_production() and get_bilateral_trade(). Supply any of them through data to reuse cached inputs or to test without remote reads.

intake_basis selects the intake that splits grazing land across animals. The default "grazer_forage" uses every grazing animal's grass plus roughage-residue intake, because the feed model classes the forage of major extensive-grazing countries (for example Australia, the United States and Argentina) as residues rather than grass; keying on the "grass" feed type alone would silently strip that land. "grass" reproduces the narrower grass-feed basis for sensitivity analysis. Land in countries with no grazer intake at all cannot be attributed and is reported via a warning.

Usage

build_grazing_feed_footprint(
  year,
  products = c("all", "meat_milk"),
  intake_basis = c("grazer_forage", "grass"),
  data = list(),
  example = FALSE
)

Arguments

Value

A tibble with area_code (consuming country), item_cbs_code (meat or milk item), value (embodied grazing land) and method ("grazing_feed_allocation").

Examples

build_grazing_feed_footprint(example = TRUE)

Description

Disaggregate country-level FAOSTAT crop harvested areas to a 0.5-degree grid. This reproduces the core spatialization workflow of the LandInG toolbox, adapted to WHEP conventions and tidy data structures.

The algorithm follows three main steps:

1. Each crop's country total is distributed to grid cells proportionally to a spatial reference pattern (e.g. Monfreda) weighted by gridded cropland extent (e.g. LUH2/HYDE).

2. If total allocated harvested area in any cell exceeds its capacity (cropland times multi-cropping suitability), excess is iteratively redistributed using a logit-based transformation.

3. Individual crops are aggregated into crop functional types (CFTs).

Usage

build_gridded_landuse(
  country_areas,
  crop_patterns,
  gridded_cropland,
  country_grid,
  config = list()
)

Arguments

Value

A tibble with gridded crop (or CFT) harvested areas. Columns:

• lon, lat: Cell centre coordinates.

• year: Integer year.

• area_code: WHEP polity code for this cell compartment.

• polity_area_code, reporting_polity_code, reporting_polity_name, reporting_polity_has_geometry: Polity metadata for area_code.

• polycell_id, cell_id: Preserved when supplied in country_grid.

• crop_name or cft_name: Crop or CFT identifier.

• rainfed_ha: Rainfed harvested area in the cell.

• irrigated_ha: Irrigated harvested area in the cell.

Methodology

This function reimplements the spatial crop allocation from the LandInG toolbox (Ostberg et al. 2023, doi:10.5194/gmd-16-3375-2023) with the following extensions:

• LUH2 crop-functional-type constraints (type_cropland + type_mapping parameters) restrict each crop to cells containing its LUH2 type (c3ann, c4ann, c3per, c3nfx). LandInG allocates to total cropland without type constraints.

• MIRCA2000 crop-specific irrigated fractions (Portmann et al. 2010) for irrigation distribution, falling back to LUH2-proportional allocation.

Data sources

• Country areas: FAOSTAT QCL via build_primary_production

• Crop patterns: EarthStat / Monfreda et al. (2008)

• Gridded cropland: LUH2 v2h (Hurtt et al. 2020)

• Irrigation: MIRCA2000 (Portmann et al. 2010) + LUH2

Examples

# Minimal example with toy data
country_areas <- tibble::tribble(
  ~year, ~area_code, ~item_prod_code, ~harvested_area_ha,
  2000L, 1L, 15L, 1000
)
crop_patterns <- tibble::tribble(
  ~lon, ~lat, ~item_prod_code, ~harvest_fraction,
  0.25, 50.25, 15L, 0.6,
  0.75, 50.25, 15L, 0.4
)
gridded_cropland <- tibble::tribble(
  ~lon, ~lat, ~year, ~cropland_ha,
  0.25, 50.25, 2000L, 800,
  0.75, 50.25, 2000L, 500
)
country_grid <- tibble::tribble(
  ~lon, ~lat, ~area_code,
  0.25, 50.25, 1L,
  0.75, 50.25, 1L
)
build_gridded_landuse(
  country_areas, crop_patterns, gridded_cropland, country_grid,
  config = list(years = 2000L)
)

Description

Disaggregate country-level FAOSTAT livestock stocks and emissions to a 0.5-degree grid. Each species group uses a tailored spatial proxy:

• Ruminants (cattle, buffalo, sheep/goats, equines): LUH2 managed pasture (pastr) plus rangeland (range), optionally weighted by a static manure-intensity reference (West et al. 2014).

• Confined animals (pigs, poultry): LUH2 aggregate cropland, reflecting intensive farming co-location with crop production.

• Range specialists (camels): LUH2 rangeland only.

• Mixed (other animals): 50/50 blend of pasture and cropland.

For each country, year, and species group the function distributes the national total proportionally to cell-level proxy weights:

$\text{cell} = \frac{w_i}{\sum_{j \in \text{country}} w_j} \times T_{\text{country}}$

where $w_i$ is the proxy weight in cell $i$ (land-use hectares times optional reference-pattern intensity) and $T$ is the country total (heads or emissions).

Methodology

Livestock spatialization is not covered by LandInG (Ostberg et al. 2023), which focuses on crops only. The approach here extends the LandInG framework by using the same LUH2-based spatial proxies (pasture, rangeland, cropland) for livestock distribution.

Country-level data comes from build_primary_production() (stocks) and the faostat-emissions-livestock pin (CH4/N2O emissions), with predecessor redistribution and pre-1961 backfill already applied.

The Zenodo livestock density input (Heinke 2025, doi:10.5281/zenodo.14946695) provides an alternative calibrated LSU/ha reference for use with the glw_density parameter.

Data sources and references

Usage

build_gridded_livestock(
  livestock_data,
  gridded_pasture,
  gridded_cropland,
  country_grid,
  species_proxy = NULL,
  manure_pattern = NULL,
  glw_density = NULL,
  grass_productivity = NULL,
  years = NULL
)

Arguments

Value

A tibble with gridded livestock data. Columns:

• lon, lat: Cell centre coordinates.

• area_code: WHEP polity code for this cell compartment.

• polity_area_code, reporting_polity_code, reporting_polity_name, reporting_polity_has_geometry: Polity metadata for area_code.

• polycell_id, cell_id: Preserved when supplied in country_grid.

• year: Integer year.

• species_group: Livestock functional type.

• heads: Allocated live animal count.

• Any additional numeric columns from livestock_data (e.g. enteric_ch4_kt, manure_ch4_kt).

Examples

# Minimal example with toy data
livestock_data <- tibble::tribble(
  ~year, ~area_code, ~species_group, ~heads,
  2000L,         1L,       "cattle",   5000
)
gridded_pasture <- tibble::tribble(
  ~lon,  ~lat,  ~year, ~pasture_ha, ~rangeland_ha,
   0.25, 50.25, 2000L,         600,           200,
   0.75, 50.25, 2000L,         400,           100
)
gridded_cropland <- tibble::tribble(
  ~lon,  ~lat,  ~year, ~cropland_ha,
   0.25, 50.25, 2000L,          800,
   0.75, 50.25, 2000L,          500
)
country_grid <- tibble::tribble(
  ~lon,  ~lat, ~area_code,
   0.25, 50.25,         1L,
   0.75, 50.25,         1L
)
build_gridded_livestock(
  livestock_data, gridded_pasture, gridded_cropland, country_grid
)

Description

Per-crop land occupation in hectare-years (the LCA m2*year convention): the land-time each crop's production ties up, $occupation_i = harvested_i \times L_i/12 + fallow_i$.

The first term is active growing occupation — harvested area times mean cycle length $L_i$ (months, from MIRCA2000). Because it uses harvested area, a field double-cropped twice contributes both cycles, and a long-cycle perennial contributes close to a full year. The second term is the rotational fallow attributed to the crop, which occupies land the whole year while it rests.

This is "active" occupation: land is charged only while a crop is growing on it or resting in its rotation, so the national total falls below physical cropland area (which also counts off-season idle). It is distinct from, and complementary to, the physical-area extensions (build_cropgrids_land_extension()): those measure the field area each crop holds; this measures how much land-time each crop's activity occupies. Short single-cropped crops and intensively double-cropped staples occupy less land-time per hectare than long-cycle and perennial crops.

Usage

build_hayr_land_extension(
  harvested = NULL,
  fallow = NULL,
  season = NULL,
  base = c("cropgrids_fallow", "cropgrids")
)

Arguments

Value

A tibble with columns year, area_code, item_cbs_code, impact_u (land occupation in hectare-years), and method_land.

Examples

harvested <- tibble::tribble(
  ~year, ~area_code, ~item_cbs_code, ~harvested_ha,
  2000L, 1L, 2807L, 200, # rice, double-cropped (two harvests per field)
  2000L, 1L, 2511L, 100 # wheat, single-cropped
)
season <- tibble::tribble(
  ~item_cbs_code, ~season_months,
  2807L, 5,
  2511L, 8
)
fallow <- tibble::tribble(
  ~year, ~area_code, ~item_cbs_code, ~fallow_ha,
  2000L, 1L, 2511L, 20
)
build_hayr_land_extension(harvested, fallow, season)

Description

Construct a multi-regional input-output (MRIO) model from supply-use tables, bilateral trade, and commodity balance sheets. Uses the industry technology assumption to derive symmetric product-by-product tables.

The resulting matrices follow the FABIO methodology (Bruckner et al., 2019). Rows and columns of Z represent (country, item) pairs. Each entry Z[i,j] gives the intermediate flow from sector i to sector j.

Usage

build_io_model(
  supply_use = NULL,
  bilateral_trade = NULL,
  cbs = NULL,
  years = NULL,
  endogenize_losses = FALSE,
  method = c("mass", "value"),
  prices = NULL
)

Arguments

Value

A tibble with one row per year and list-columns:

• Z: Inter-industry flow matrix (product-by-product).

• Y: Final demand matrix.

• X: Total output vector.

• labels: Tibble mapping row/column indices to area_code, item_cbs_code, and reporting polity metadata.

• fd_labels: Tibble mapping each Y column to its area_code (consuming polity), fd_col (demand category, e.g. "food"), and reporting polity metadata. Pass to compute_footprint() as fd_labels to get a target_fd column in the footprint output.

Examples

su <- build_supply_use(example = TRUE)
btd <- get_bilateral_trade(example = TRUE)
cbs <- get_wide_cbs(example = TRUE)
build_io_model(su, btd, cbs)

Description

End-to-end land-balance footprint for one year on real WHEP data: assemble production (primary crop production plus grass dry-matter derived from grassland area times yield), the bilateral trade network, and the crop-plus-grassland direct-land extension, then trace land to consumers with compute_footprint_balance(). This is the independent, non-Leontief estimator for stress-testing the multi-regional input-output footprint via compare_footprint_methods().

Grass items (item_cbs_code 3000 and 3002) are barely traded, so their land stays with the producing country: the balance, unlike the input-output model, does not route grass through the grass-to-livestock chain. Any production, trade or extension supplied explicitly is used as-is instead of being built, which is useful for reusing cached inputs or for testing.

Usage

build_land_balance_footprint(
  year,
  production = NULL,
  trade = NULL,
  extension = NULL,
  example = FALSE
)

Arguments

Value

A tibble as returned by compute_footprint_balance().

Examples

build_land_balance_footprint(example = TRUE)

Description

Aggregate per-animal IPCC livestock emissions into a footprint extension keyed by ⁠(year, area_code, item_cbs_code)⁠, expressed in kilograms of carbon-dioxide equivalent (CO2e). This bridges the cohort-level emissions pipeline (calculate_livestock_emissions()) to the input-output grain used by build_io_model() and compute_footprint(), exactly like build_grassland_land_extension() does for land.

Live-animal head counts come from get_primary_production(), are bridged to IPCC species with prepare_livestock_emissions(), and the resulting enteric and manure emissions are converted to CO2e and summed back to the live-animal commodity sector (item_cbs_code, e.g. 961 for non-dairy cattle), which is itself a sector in build_io_model().

Two IPCC tiers are available, selected with tier:

• 1 (default): Tier 1 regional emission factors (IPCC 2019). It needs only species, country and head counts, so it is complete for every country in get_primary_production(). It covers enteric and manure methane and manure N2O (direct and indirect, from default per-head nitrogen excretion rates).

• 2: Tier 2 cohort energy balance (IPCC 2019). It derives enteric CH4 and manure N2O from a per-animal energy and nitrogen balance, for finer resolution, but requires cohort weight and diet inputs. Animals whose emissions cannot be resolved (missing diet or energy data) are dropped with a warning rather than entering the footprint as NA. Its per-head enteric and manure emissions now sit in the same range as the Tier 1 regional factors. Tier 1 remains the default because it is complete for every country in get_primary_production(), whereas Tier 2 needs cohort and diet inputs.

The CO2e conversion uses 100-year global warming potentials selected with gwp:

• "ar6" (default): IPCC AR6 (2021) Table 7.15, biogenic CH4 = 27, N2O = 273.

• "ar5": IPCC AR5 (2013), CH4 = 28, N2O = 265 (no climate-carbon feedback).

• "ar4": IPCC AR4 (2007), CH4 = 25, N2O = 298.

Usage

build_livestock_ghg_extension(
  tier = 1,
  gwp = c("ar6", "ar5", "ar4"),
  data = list(),
  example = FALSE
)

Arguments

Value

A tibble with columns year, area_code, item_cbs_code, impact_u (livestock emissions in kilograms CO2e) and method_ghg (the chosen tier and GWP standard, e.g. "IPCC_2019_Tier1_AR6").

Examples

build_livestock_ghg_extension(example = TRUE)

Description

Top-level driver that traces the nitrogen, carbon and volatile solids in realised feed intake (the redistribute_feed() result) through livestock excretion, manure management and application to soil by land use and crop, plus the management-loss side-streams. It chains estimate_n_excretion(), split_manure_management(), apply_management_losses() and allocate_manure_to_land(); at the "subnational" resolution it additionally spills each cell's un-placeable surplus to neighbouring cells with allocate_manure_transport() before local disposal. Every method choice is recorded in a ⁠method_*⁠ provenance column and the nitrogen balance (excreted = applied + management losses) is conserved.

Usage

build_livestock_nutrient_flows(
  intake,
  resolution = "national",
  methods = list(),
  gridded = NULL
)

Arguments

Value

A named list with applied (manure applied per ⁠land_use x crop (x cell)⁠ with all ⁠method_*⁠ provenance columns), losses (management-loss side-streams per polity) and excretion (the per-category excretion totals).

Examples

intake <- tibble::tribble(
  ~year, ~territory, ~sub_territory, ~livestock_category,
  ~item_cbs_code, ~feed_quality, ~intake_dm_t,
  2020L, "ESP", NA, "Cattle_milk", 2513L, "high_quality", 200,
  2020L, "ESP", NA, "Cattle_milk", NA, "grass", 600
)
gridded <- list(
  crops = tibble::tribble(
    ~year, ~territory, ~sub_territory, ~crop, ~manure_n_receptivity, ~crop_n_cap,
    2020L, "ESP", NA, "barley", 6, 200,
    2020L, "ESP", NA, "wheat", 4, 200
  )
)
build_livestock_nutrient_flows(intake, gridded = gridded)

Description

Compute prices for primary production items. Export trade prices are preferred; when unavailable, production value prices (gross production value divided by quantity) are used as fallback. Gaps are filled via linear interpolation.

Usage

build_primary_prices(
  primary_prod,
  value_of_production = NULL,
  trade_prices = NULL,
  example = FALSE
)

Arguments

Value

A tibble with columns:

• year: Integer year.

• item_prod_code: Production item code (character).

• price: Price in KDollars per tonne.

Examples

build_primary_prices(example = TRUE)

Description

Construct the full primary production dataset from raw FAOSTAT inputs. This is a convenience wrapper that chains the pipeline steps:

1. .read_production() — read & reformat FAOSTAT data.

2. .fix_production() — apply Global-ported corrections.

3. .dedup_production() — keep one value per key across sources.

4. .qc_production() — flag data-quality anomalies on the surviving (deduplicated) values.

Usage

build_primary_production(
  start_year = 1850,
  end_year = 2023,
  smooth_carry_forward = FALSE,
  example = FALSE,
  show_duplicates = FALSE,
  historical_data = NULL,
  .raw_data = NULL
)

Arguments

Value

A tibble with the same columns as get_primary_production(): year, legacy numeric area_code, numeric polity_area_code, reporting_polity_code, reporting_polity_name, reporting_polity_has_geometry, item_prod_code, item_cbs_code, live_anim_code, unit, value, and source. Item names can be recovered via add_item_prod_name() and related helpers. When show_duplicates = TRUE, returns a wide tibble with one column per source showing the competing values.

Examples

build_primary_production(example = TRUE)

Description

Extract the final calibrated processing coefficients from the CBS building pipeline. These can be used independently for footprint calculations.

Usage

build_processing_coefs(
  cbs,
  start_year = 1850,
  end_year = 2023,
  example = FALSE
)

Arguments

Value

A tibble with columns: year, area_code, item_cbs_code_to_process, value_to_process, item_cbs_code_processed, initial_conversion_factor, initial_value_processed, conversion_factor_scaling, final_conversion_factor, final_value_processed.

Examples

build_processing_coefs(example = TRUE)

Description

Turns the feed destiny of crop residues into the feed_avail contract consumed by redistribute_feed(): maps each crop to its residue commodity item, applies a feed-availability loss, and aggregates to year / territory / residue item.

Usage

build_residue_feed_avail(x, loss_fraction = 0.15, feed_scale = "national")

Arguments

Value

A tibble with the redistribute_feed() feed_avail columns: year, sub_territory, item_cbs_code, feed_group, feed_quality ("residues"), avail_dm_t and feed_scale.

Examples

tibble::tibble(
  item_prod_code = "15", year = 2000, sub_territory = "ESP",
  residue_feed_dm_t = 50
) |>
  build_residue_feed_avail()

Description

Create a table with processes, their inputs (use) and their outputs (supply).

Usage

build_supply_use(example = FALSE)

Arguments

Value

A tibble with the supply and use data for processes. It contains the following columns:

• year: The year in which the recorded event occurred.

• area_code: The code of the country where the data is from. For code details see e.g. add_area_name().

• proc_group: The type of process taking place. It can be one of:

  • crop_production: Production of crops and their residues, e.g. rice production, coconut production, etc.

  • husbandry: Animal husbandry, e.g. dairy cattle husbandry, non-dairy cattle husbandry, layers chickens farming, etc.

  • animal_draught: Annual useful work energy generated by draft animals.

  • slaughtering: Slaughter of live animals into meat, edible offals, raw animal fats, and hides/skins.

  • processing: Derived subproducts obtained from processing other items. The items used as inputs are those that have a non-zero processing use in the commodity balance sheet. See get_wide_cbs() for more details. In each process there is a single input. In some processes like olive oil extraction or soyabean oil extraction this might make sense. Others like alcohol production need multiple inputs (e.g. multiple crops work), so in this data there would not be a process like alcohol production but rather a virtual process like 'Wheat and products processing', giving all its possible outputs. This is a constraint because of how the data was obtained and might be improved in the future. See get_processing_coefs() for more details.

• proc_cbs_code: The code of the main item in the process taking place. Together with proc_group, these two columns uniquely represent a process. The main item is predictable depending on the value of proc_group:

  • crop_production: The code is from the item for which seed usage (if any) is reported in the commodity balance sheet, except for field co-products where the process uses the field aggregate item. For example, rice production uses the rice code, while seed cotton production uses the seed cotton code and supplies both cottonseed and cotton lint.

  • husbandry: The code of the farmed animal, e.g. bees for beekeeping, non-dairy cattle for non-dairy cattle husbandry, etc.

  • slaughtering: The code of the live animal being slaughtered, e.g. non-dairy cattle for cattle slaughter.

  • processing: The code of the item that is used as input, i.e., the one that is processed to get other derived products. This uniquely defines a process within the group because of the nature of the data that was used, which you can see in get_processing_coefs().

  For code details see e.g. add_item_cbs_name().

• item_cbs_code: The code of the item produced or used in the process. Note that this might be the same value as proc_cbs_code, e.g., in rice production process for the row defining the amount of rice produced or the amount of rice seed as input, but it might also have a different value, e.g. for the row defining the amount of straw residue from rice production. For code details see e.g. add_item_cbs_name().

• type: Can have two values:

  • use: The given item is an input of the process.

  • supply: The given item is an output of the process.

• value: Quantity in the item's own unit. Most items are measured in tonnes; live animals are measured in heads; animal draught is measured as annual useful work energy (TJ).

Examples

build_supply_use(example = TRUE)

Description

Compute global prices of traded items from FAOSTAT trade data. For each item and element (import/export), the price is KDollars / tonnes aggregated across all countries.

Usage

build_trade_prices(raw_trade = NULL, example = FALSE)

Arguments

Value

A tibble with columns:

• year: Integer year.

• item_trade: Trade item name.

• item_code_trade: Numeric FAOSTAT trade item code.

• element: "import" or "export".

• kdollars: Total trade value in thousand US dollars.

• tonnes: Total trade quantity in tonnes.

• price: Price in KDollars per tonne.

Examples

build_trade_prices(example = TRUE)

Description

Sums the three BNF components: symbiotic crop legumes, symbiotic weeds/cover crops, and non-symbiotic free-living fixation, by running calculate_crop_bnf(), calculate_weed_bnf() and calculate_nonsymbiotic_bnf(). When a climate_type column is present, the climate-specific parameters from bnf_climate_params override the relevant defaults per climate type.

Usage

calculate_bnf(
  x,
  symbiotic_params = list(),
  nonsymbiotic_params = list(),
  soil_params = list()
)

Arguments

Details

The weed component uses the weed_npp_n_t already present in x. In the standard crop-NPP chain this is non-zero only when calculate_crop_npp_components() has been run, or when callers supply weed NPP directly; calculate_npp_carbon_nitrogen() treats missing weed biomass as zero.

Value

The input tibble with all component columns plus fert_type ("BNF") and bnf_t (total BNF).

Examples

calculate_bnf(
  tibble::tibble(
    item_prod_code = "176", crop_npp_n_t = 10, product_n_t = 5,
    weed_npp_n_t = 4, land_use = "Cropland", legumes_seeded = 0,
    seeded_cover_crop_share = 0, area_ha = 40
  )
)

Description

Distributes national herd totals across GLEAM-defined cohorts and production systems using gleam_livestock_categories and regional weight data.

Usage

calculate_cohorts_systems(data, system_shares = NULL)

Arguments

Value

Dataframe expanded to cohort level with cohort, system, cohort_heads, and cohort_fraction columns.

Examples

tibble::tibble(
  species = "Cattle", heads = 10000,
  iso3 = "DEU"
) |>
  calculate_cohorts_systems()

Description

Estimates symbiotic BNF from leguminous crops via two methods (an NPP-based estimate and the Anglade product-based estimate). Environmental modifiers (nitrogen inhibition, temperature, water) are applied only when their driver columns are present in x; an absent driver leaves that modifier at 1.

Usage

calculate_crop_bnf(x, symbiotic_params = list())

Arguments

Value

The input tibble with the environmental factors, ndfa_adj, crop_bnf_t (NPP method), crop_bnf_anglade_t (Anglade method) and the per-product ratios bnf_product_ratio_npp / bnf_product_ratio_anglade.

Examples

calculate_crop_bnf(
  tibble::tibble(item_prod_code = "176", crop_npp_n_t = 10, product_n_t = 5)
)

Description

Assembles total crop net primary production (product plus residue plus root dry matter) by running calculate_crop_residues() then calculate_crop_roots().

Usage

calculate_crop_npp(
  x,
  residue_method = "ensemble",
  root_method = "ensemble",
  weights = list(w_ipcc = 0.5, w_ref = 0.5)
)

Arguments

Value

The input tibble with product_dm_t, yield_dm_t_ha, residue_dm_t, root_dm_t, crop_npp_dm_t, method_residue and method_root.

Examples

calculate_crop_npp(
  tibble::tibble(item_prod_code = "15", production_t = 100, area_ha = 40)
)

Description

Assembles full cropland net primary production: scales weed biomass from potential NPP and the weed_npp_scaling factors, then partitions crop and weed biomass into dry matter, carbon and nitrogen via calculate_npp_carbon_nitrogen().

Usage

calculate_crop_npp_components(
  x,
  .by = NULL,
  potential = list(method = "lpjml")
)

Arguments

Details

The weed_npp_scaling table is taken from Spain_Hist and is flagged to_be_revised: it is Spain-specific and not validated for WHEP's global scope. A weed_scaling_to_be_revised column records this on the output and a one-time warning is emitted.

Value

The input tibble with weed dry matter, the dry-matter / nitrogen / carbon partition for crop, weeds and total, and weed_scaling_to_be_revised.

Examples

tibble::tibble(
  item_prod_code = "15", production_t = 100, area_ha = 40,
  year = 2000, npp_potential_dm_t_ha = 5
) |>
  calculate_crop_npp() |>
  calculate_crop_npp_components()

Description

Estimates crop residue dry matter from production and area using an ensemble of an IPCC 2019 linear model and a bio_coefs residue:product ratio. The irrigation and modern-variety adjustments activate only when their driver columns are present in x.

Usage

calculate_crop_residues(
  x,
  method = c("ensemble", "ipcc", "ratio"),
  weights = list(w_ipcc = 0.5)
)

Arguments

Value

The input tibble with product_dm_t, yield_dm_t_ha, residue_dm_t and method_residue.

Examples

calculate_crop_residues(
  tibble::tibble(item_prod_code = "15", production_t = 100, area_ha = 40)
)

Description

Estimates root dry matter from above-ground biomass using an ensemble of an IPCC root:shoot ratio and a reference below-ground biomass per hectare. The nitrogen-input and irrigation adjustments activate only when their driver columns are present in x.

Usage

calculate_crop_roots(
  x,
  method = c("ensemble", "root_shoot", "reference"),
  weights = list(w_ref = 0.5)
)

Arguments

Value

The input tibble with root_dm_t and method_root.

Examples

calculate_crop_roots(
  tibble::tibble(
    item_prod_code = "15",
    product_dm_t = 87.9,
    residue_dm_t = 135.75,
    area_ha = 40
  )
)

Description

Wrapper that selects Tier 1 or 2 for enteric CH4 based on data availability.

Usage

calculate_enteric_ch4(data, tier = NULL)

Arguments

Value

Dataframe with all input columns preserved, plus:

• method_enteric: tracking label ("IPCC_2019_Tier1" or "IPCC_2019_Tier2").

• Tier 1: enteric_ef_kgch4 (emission factor), enteric_ch4_tier1 (total kg CH4).

• Tier 2: gross_energy, ym_factor, enteric_ch4_per_head (kg CH4/head/yr), enteric_ch4_tier2 (total kg CH4).

Examples

tibble::tibble(
  species = "Cattle", heads = 1000, iso3 = "DEU"
) |>
  calculate_enteric_ch4(tier = 1)

Description

Main dispatcher that runs the full IPCC 2019 livestock emissions pipeline: energy demand (Tier 2), enteric CH4, manure CH4, and manure N2O.

Selects tier automatically: Tier 2 when cohort-level data (weight, diet) are available; Tier 1 otherwise.

Usage

calculate_livestock_emissions(data, tier = NULL)

Arguments