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

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

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: Carbon content of roots 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,
  .fixed_data = NULL
)

Arguments

Value

A tibble in long format with columns: year, area_code, item_cbs_code, element (e.g. "production", "import", "food"), value, source, fao_flag.

Examples

build_commodity_balances(example = TRUE)

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

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.

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

• 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

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
)

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

• fd_labels: Tibble mapping each Y column to its area_code (consuming country) and fd_col (demand category, e.g. "food") . 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

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: Numeric production item code.

• 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 three pipeline steps:

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

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

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

Usage

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

Arguments

Value

A tibble with the same columns as get_primary_production(): year, area_code (numeric FAOSTAT), item_prod_code, item_cbs_code, live_anim_code, unit, value. Names can be recovered via add_area_name(), add_item_prod_name(), etc. 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

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.

  • 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 (see get_wide_cbs() for more). For example, the rice code for a rice production process or the cottonseed code for the cotton production one.

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

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

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

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

Value

Dataframe with all emission columns, method tracking, and original data columns preserved.

Examples

tibble::tibble(
  species = "Dairy Cattle",
  cohort = "Adult Female",
  heads = 1000,
  weight = 600,
  diet_quality = "High",
  milk_yield_kg_day = 20
) |>
  calculate_livestock_emissions() |>
  dplyr::select(species, cohort, heads,
    enteric_ch4_tier2, manure_ch4_tier2,
    manure_n2o_total)

Description

Performs LMDI (Log Mean Divisia Index) decomposition analysis with flexible identity parsing, automatic factor detection, and support for multiple periods and groupings. Supports sectoral decomposition using bracket notation for both summing and grouping operations.

Usage

calculate_lmdi(
  data,
  identity,
  identity_labels = NULL,
  time_var = year,
  periods = NULL,
  periods_2 = NULL,
  .by = NULL,
  rolling_mean = 1,
  output_format = "clean",
  verbose = TRUE
)

Arguments

Details

The LMDI method decomposes changes in a target variable into contributions from multiple factors using logarithmic mean weights. This implementation supports:

Flexible identity specification:

• Automatic factor detection from identity string.

• Support for ratio calculations (implicit division).

• Sectoral aggregation with ⁠[]⁠ notation.

• Sectoral grouping with {} notation.

Period analysis: The function can decompose changes over single or multiple periods. Periods are defined by consecutive pairs in the periods vector.

Grouping capabilities: Use .by to perform separate decompositions for different groups (e.g., countries, regions) while maintaining consistent factor structure.

Value

A tibble with LMDI decomposition results containing:

• Time variables and grouping variables (if specified).

• additive: Additive contributions (sum equals total change in target).

• multiplicative: Multiplicative indices (product equals target ratio).

• multiplicative_log: Log of multiplicative indices.

• Period identifiers and metadata.

Identity Syntax

The identity parameter uses a special syntax to define decomposition:

Basic format: "target:factor1*factor2*factor3"

Simple decomposition (no sectors):

• Basic: "emissions:gdp*(emissions/gdp)"

• Complete: "emissions:(emissions/gdp)*(gdp/population)*population"

Understanding bracket notation:

Square brackets ⁠[]⁠ specify variables to sum across categories, enabling structural decomposition. The bracket aggregates values BEFORE calculating ratios.

Single-level structural decomposition:

• "emissions:activity*(activity[sector]/activity)*(emissions[sector]/activity[sector])"

• Creates 3 factors: Activity level, Sectoral structure, Sectoral intensity.

Multi-level structural decomposition:

• Two levels: "emissions:activity*(activity[sector]/activity)*(activity[sector+fuel]/activity[sector])*(emissions[sector+fuel]/activity[sector+fuel])"

• Creates 4 factors: Activity level, Sector structure, Fuel structure, Sectoral-fuel intensity.

Data Requirements

The input data frame must contain:

• All variables mentioned in the identity.

• The time variable (default: "year").

• Grouping variables if using .by.

• No missing values in key variables for decomposition periods.

Examples

# In these examples, 'activity' is a measure of scale
# (e.g., GDP in million USD) and 'intensity' is the target
# variable per unit activity (e.g., emissions per million USD).
# The units are illustrative; adapt to your context.
# --- Shared sample data ---
data_simple <- tibble::tribble(
  ~year, ~activity, ~intensity, ~emissions,
  2010,  1000,      0.10,       100,
  2011,  1100,      0.12,       132,
  2012,  1200,      0.09,       108,
  2013,  1300,      0.10,       130
)

# --- 1. Year-over-year decomposition (default) ---
# Decompose annual emission changes into activity and intensity effects.
# The additive column sums to the total change in emissions each period.
calculate_lmdi(
  data_simple,
  identity = "emissions:activity*intensity",
  time_var = year,
  verbose = FALSE
) |>
  dplyr::select(
    period,
    component_type,
    factor_label,
    additive,
    multiplicative
  )

# --- 2. Single baseline-to-end period ---
# Pass a two-element periods vector to get a single cumulative period
# instead of year-over-year results.
calculate_lmdi(
  data_simple,
  identity = "emissions:activity*intensity",
  time_var = year,
  periods = c(2010, 2013),
  verbose = FALSE
) |>
  dplyr::select(
    period,
    component_type,
    factor_label,
    additive,
    multiplicative
  )

# --- 3. Year-over-year AND one cumulative summary period ---
# Use periods_2 to append an extra comparison period alongside the
# year-over-year results.
calculate_lmdi(
  data_simple,
  identity = "emissions:activity*intensity",
  time_var = year,
  periods = c(2010, 2011, 2012, 2013),
  periods_2 = c(2010, 2013),
  verbose = FALSE
) |>
  dplyr::select(
    period,
    component_type,
    factor_label,
    additive,
    multiplicative
  )

# --- 4. Per-country decomposition with .by ---
# Separate LMDI runs per country; results are stacked with a country column.
data_countries <- tibble::tribble(
  ~year, ~country, ~activity, ~intensity, ~emissions,
  2010, "ESP", 1000, 0.10, 100,
  2011, "ESP", 1100, 0.11, 121,
  2012, "ESP", 1200, 0.10, 120,
  2010, "FRA", 2000, 0.05, 100,
  2011, "FRA", 2200, 0.05, 110,
  2012, "FRA", 2400, 0.05, 120
)

calculate_lmdi(
  data_countries,
  identity = "emissions:activity*intensity",
  time_var = year,
  .by = "country",
  verbose = FALSE
) |>
  dplyr::select(
    country,
    period,
    component_type,
    factor_label,
    additive,
    multiplicative
  )

# --- 5. Ratio notation ---
# Express factors as explicit ratios (e.g. intensity = emissions/activity).
# Factor labels in the output preserve the ratio form for clarity.
calculate_lmdi(
  data_simple,
  identity = "emissions:(emissions/activity)*activity",
  time_var = year,
  verbose = FALSE
) |>
  dplyr::select(
    period,
    component_type,
    factor_label,
    additive,
    multiplicative
  )

# --- 6. Structural (sectoral) decomposition with [] notation ---
# Decomposes emissions into:
#   total_activity * sector_structure * sector_intensity
# [] sums the bracketed variable across sector before forming ratios,
# enabling proper structural decomposition.
data_sectors <- tibble::tribble(
  ~year, ~sector, ~activity, ~emissions,
  2010, "industry", 600, 60,
  2010, "transport", 400, 40,
  2011, "industry", 700, 63,
  2011, "transport", 500, 55
) |>
  dplyr::group_by(year) |>
  dplyr::mutate(total_activity = sum(activity)) |>
  dplyr::ungroup()

calculate_lmdi(
  data_sectors,
  identity = paste0(
    "emissions:",
    "total_activity*",
    "(activity[sector]/total_activity)*",
    "(emissions[sector]/activity[sector])"
  ),
  time_var = year,
  verbose = FALSE
) |>
  dplyr::select(
    period,
    component_type,
    factor_label,
    additive,
    multiplicative
  )

# --- 7. Custom factor labels ---
# Replace raw variable names with readable labels for reporting.
# Supply one label per term (target first, then each factor in order).
calculate_lmdi(
  data_simple,
  identity = "emissions:activity*intensity",
  identity_labels = c(
    "Total Emissions",
    "Activity Effect",
    "Intensity Effect"
  ),
  time_var = year,
  verbose = FALSE
) |>
  dplyr::select(
    period,
    component_type,
    factor_label,
    additive,
    multiplicative
  )

# --- 8. Rolling mean smoothing before decomposition ---
# A 3-year rolling mean reduces noise in volatile series before
# computing LMDI weights. Edge years use partial windows (fewer
# than k observations) so no periods are lost.
data_smooth <- tibble::tibble(
  year      = 2010:2020,
  activity  = seq(1000, 2000, length.out = 11),
  intensity = rep(0.1, 11),
  emissions = seq(1000, 2000, length.out = 11) * 0.1
)

calculate_lmdi(
  data_smooth,
  identity = "emissions:activity*intensity",
  time_var = year,
  rolling_mean = 3,
  verbose = FALSE
) |>
  dplyr::select(
    period,
    component_type,
    factor_label,
    additive,
    multiplicative
  )

Description

Wrapper that selects Tier 1 or 2 for manure CH4 and computes N2O (Tier 2 only; skipped for Tier 1).

Usage

calculate_manure_emissions(data, tier = NULL)

Arguments

Value

Dataframe with all input columns preserved, plus:

• method_manure_ch4: tracking label.

• Tier 1: manure_ef_kgch4, manure_ch4_tier1.

• Tier 2: volatile_solids, methane_potential, weighted_mcf, manure_ch4_per_head, manure_ch4_tier2.

• N2O (Tier 2 only): method_manure_n2o, n_excretion, manure_n2o_direct, manure_n2o_indirect, manure_n2o_total.

Examples

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

Description

N inputs (deposition, fixation, synthetic fertilizers, urban sources, manure) and N production in Spain from 1860 to the present for the GRAFS model at the provincial level. The crop NUE is defined as the percentage of produced nitrogen relative to the total nitrogen inputs to the soil. Total soil inputs are calculated as: inputs = deposition + fixation + synthetic + manure + urban

Usage

calculate_nue_crops(example = FALSE)

Arguments

Value

A tibble containing nitrogen use efficiency (NUE) for crops. It includes the following columns:

• year: Year.

• province_name: The Spanish province.

• item: The item which was produced, defined in names_biomass_cb.

• box: One of the two systems of the GRAFS model: cropland or semi-natural agroecosystems.

• nue: Nitrogen Use Efficiency as a percentage (%).

Examples

calculate_nue_crops(example = TRUE)

Description

Calculates Nitrogen Use Efficiency (NUE) for livestock categories (excluding pets).

The livestock NUE is defined as the percentage of nitrogen in livestock products relative to the nitrogen in feed intake: nue = prod_n / feed_n * 100

Additionally, a mass balance is calculated to check the recovery of N in products and excretion relative to feed intake: mass_balance = (prod_n + excretion_n) / feed_n

Usage

calculate_nue_livestock(example = FALSE)

Arguments

Value

A tibble containing:

• year: Year

• province_name: Spanish province

• livestock_cat: Livestock category

• item: Produced item

• prod_n: Nitrogen in livestock products (Mg)

• feed_n: Nitrogen in feed intake (Mg)

• excretion_n: Nitrogen excreted (Mg)

• nue: Nitrogen Use Efficiency (%)

• mass_balance: Mass balance ratio (%)

Examples

calculate_nue_livestock(example = TRUE)

Description

Calculates the NUE for Spain at the provincial level. The system NUE is defined as the percentage of total nitrogen production (total_prod) relative to the sum of all nitrogen inputs (inputs) into the soil system.

Usage

calculate_system_nue(n_soil_inputs = create_n_soil_inputs(), example = FALSE)

Arguments

Value

A tibble with the following columns:

• year: Year

• province_name: Spanish province

• total_prod: Total nitrogen production (Mg)

• inputs: Total nitrogen inputs (Mg)

• nue_system: System-level Nitrogen Use Efficiency (%)

Examples

calculate_system_nue(example = TRUE)

Description

Applies IPCC uncertainty ranges to emission estimates. Multipliers sourced from uncertainty_ranges table (no hardcoded values).

Usage

calculate_uncertainty_bounds(data)

Arguments

Value

Dataframe with added ⁠_lower⁠ and ⁠_upper⁠ columns for each emission estimate.

Examples

tibble::tibble(
  species = "Dairy Cattle",
  cohort = "Adult Female",
  heads = 1000,
  weight = 600,
  diet_quality = "High",
  milk_yield_kg_day = 20
) |>
  calculate_livestock_emissions() |>
  calculate_uncertainty_bounds() |>
  dplyr::select(species, cohort, heads,
    enteric_ch4_tier2, enteric_ch4_tier2_lower,
    enteric_ch4_tier2_upper, manure_ch4_tier2,
    manure_ch4_tier2_lower, manure_ch4_tier2_upper)

Description

Specifies the product fractions obtained when CBS items are processed, linking processed items to their output CBS categories.

Usage

cb_processing

Format

A tibble where each row corresponds to one processed-item / output-category combination. It contains the following columns:

• ProcessedItem: Name of the CBS item being processed (e.g., "Apples and products", "Barley and products").

• item_cbs: Name of the output CBS category produced by processing (e.g., "Alcohol, Non-Food").

• Product_fraction: Conversion factor from processed input quantity to output product quantity. This can exceed 1 when the output includes added mass, such as water in beverages.

• Value_fraction: Economic value fraction associated with the output product (numeric; largely NA in current data).

• Required: Marks required co-product links in selected processing chains.

Source

Derived from FAOSTAT commodity balance sheet processing assumptions.

Examples

head(cb_processing)

Description

Maps detailed FAOSTAT trade item codes to their corresponding CBS item categories, enabling aggregation of bilateral trade data into the CBS framework.

Usage

cbs_trade_codes

Format

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

• item_code_trade: Numeric FAOSTAT trade item code (e.g., 15 for wheat).

• item_trade: Name of the trade item (e.g., "Wheat", "Flour, wheat", "Bran, wheat").

• item_cbs: Name of the CBS category this trade item belongs to (e.g., "Wheat and products").

• item_check: Cross-validation column repeating the mapped CBS name; used to flag mapping inconsistencies during data processing.

Source

Derived from FAOSTAT Detailed Trade Matrix and commodity balance sheet correspondence tables.

Examples

head(cbs_trade_codes)

Description

Maps FAOSTAT primary-production item codes to WHEP's granular 33-class crop functional type taxonomy and the coarser LPJmL-compatible parent class. Used by build_gridded_landuse() and run_spatialize() to aggregate spatialized crop-level output into named crop functional types.

Usage

cft_mapping

Format

A tibble with one row per mapped FAOSTAT item. Columns:

• item_prod_code: Integer FAOSTAT item code.

• item_prod_name: Human-readable FAOSTAT item name.

• cft_name: Granular WHEP CFT name (33 classes, e.g. "temperate_cereals", "coffee", "oil_crops_oilpalm").

• cft_lpjml: LPJmL-compatible parent class; one of the 12 LPJmL v6 named crop CFTs or "others".

• luh2_type: LUH2 crop functional type (c3ann, c4ann, c3per, or c3nfx).

Source

Adapted from LandInG's crop_types_FAOSTAT_LPJmL_default.csv (Ostberg et al. 2023) with WHEP granular extensions.

Examples

head(cft_mapping)

Description

Methane Conversion Factors by MMS type and climate zone (Cool/Temperate/Warm).

Usage

climate_mcf

Format

A tibble with mms_type, climate_zone, mcf_percent.

Source

IPCC 2019 Refinement, Vol 4, Ch 10, Table 10.17.

Examples

climate_mcf

Description

Trace environmental extensions through the supply chain using the Leontief inverse, following the FABIO methodology (Bruckner et al., 2019). The footprint shows how much of an environmental pressure (e.g. land use, water, emissions) is embodied in the final consumption of each product in each country.

The multiplier matrix is computed as $MP_{ij} = (e_i / X_i) \cdot L_{ij}$, where $e_i$ is the extension for sector $i$. For each demand category, the footprint is decomposed per target item using the FABIO diagonal approach: $FP = MP \cdot \text{diag}(y)$, aggregated by item.

For large systems, pass z_mat and x_vec instead of l_inv. This solves $(I - A) x = Y$ directly using a sparse LU factorisation, avoiding the dense Leontief inverse entirely and reducing memory from $O(n^2)$ to $O(nnz)$.

Usage

compute_footprint(
  l_inv = NULL,
  x_vec,
  y_mat,
  extensions,
  labels,
  z_mat = NULL,
  fd_labels = NULL,
  output_tol = 1e-08,
  value_added_floor = 0.001,
  conserve_extensions = TRUE
)

Arguments

Value

A tibble with footprint results containing:

• origin_area: Country where the pressure occurs.

• origin_item: Item causing the pressure.

• target_area: Country consuming the product.

• target_item: Item consumed.

• target_fd: Demand category (e.g. "food"). Only present when fd_labels is provided.

• value: Footprint value in extension units.

Examples

z_mat <- matrix(c(0, 5, 10, 0), nrow = 2)
x_vec <- c(100, 200)
l_inv <- compute_leontief_inverse(z_mat, x_vec)
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)
)

# Small system: pass pre-computed L
compute_footprint(l_inv, x_vec, y_mat, extensions, labels)

# Using Z directly (computes L internally)
compute_footprint(
  x_vec = x_vec, y_mat = y_mat,
  extensions = extensions, labels = labels,
  z_mat = z_mat
)

Description

Decompose an origin footprint into the first sector that directly uses the origin product before the footprint reaches final demand. This is useful for Sankey views that show paths such as origin product -> first-use area -> first-use product -> final-demand area.

The decomposition uses the IO identity $x = d + A x$. For each selected origin sector $i$ and final-demand target, the origin requirement $x_i$ is split into direct final demand $d_i$ and direct intermediate use $A_{ij} x_j$. Values are multiplied by the origin extension intensity $e_i / X_i$.

Usage

compute_footprint_paths(
  z_mat,
  x_vec,
  y_mat,
  extensions,
  labels,
  fd_labels,
  origin_area = NULL,
  origin_item = NULL,
  output_tol = 1e-08,
  value_added_floor = 0.001,
  conserve_extensions = TRUE,
  min_value = 0
)

Arguments

Value

A tibble with origin_area, origin_item, use_area, use_item, target_area, target_item, target_fd, path_type, and value.

Description

Decompose an origin footprint by the area and item of the product supplied to final demand. This adds the missing FABIO-viewer style phase between origin product and final-demand area: origin product -> supplied product area -> supplied product -> final-demand area.

Unlike compute_footprint_paths(), this does not show the first direct intermediate input. It shows the downstream product row in Y whose final demand carries the origin footprint.

Usage

compute_fp_product_paths(
  z_mat,
  x_vec,
  y_mat,
  extensions,
  labels,
  fd_labels,
  origin_area = NULL,
  origin_item = NULL,
  output_tol = 1e-08,
  value_added_floor = 0.001,
  conserve_extensions = TRUE,
  min_value = 0
)

Arguments

Value

A tibble with origin_area, origin_item, product_area, product_item, target_area, target_fd, and value.

Description

Compute the Leontief inverse matrix from intermediate flows and total output. The Leontief inverse captures both direct and indirect requirements across the entire supply chain, enabling footprint tracing.

The technical coefficients matrix is computed as $A_{ij} = Z_{ij} / X_j$, representing the input of sector $i$ needed per unit of output from sector $j$. Column sums of A are capped below 1 using value_added_floor (FABIO convention plus an explicit leakage floor) to ensure $(I - A)$ is invertible even when supply-use data are inconsistent. The Leontief inverse is then $L = (I - A)^{-1}$.

For large systems (thousands of sectors) this function is not usable: the dense L matrix requires $n^2 \times 8$ bytes of memory (e.g. ~4.8 GiB for n = 25 000). Use compute_footprint() directly with z_mat and x_vec instead, which solves $(I - A) x = Y$ without ever materialising L.

Accepts both dense and sparse (Matrix package) inputs.

Usage

compute_leontief_inverse(z_mat, x_vec, max_n = 5000, value_added_floor = 0.001)

Arguments

Value

The Leontief inverse matrix $L$. Negative values are set to zero. Returns a dense matrix.

Examples

z_mat <- matrix(c(0, 5, 10, 0), nrow = 2)
x_vec <- c(100, 200)
compute_leontief_inverse(z_mat, x_vec)

Description

Provides N flows of the Spanish agro-food system on a national level between 1860 and 2020. This dataset is the national equivalent of the provincial GRAFS model and represents Spain as a single system without internal trade between provinces. All production, consumption and soil inputs are aggregated nationally before calculating trade with the outside.

Usage

create_n_nat_destiny(example = FALSE)

Arguments

Value

A final tibble containing national N flow data by origin and destiny. It includes the following columns:

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

• item: The item which was produced, defined in names_biomass_cb.

• irrig_cat: Irrigation form (irrigated or rainfed)

• box: One of the GRAFS model systems: cropland, Semi-natural agroecosystems, Livestock, Fish, or Agro-industry.

• origin: The origin category of N: Cropland, Semi-natural agroecosystems, Livestock, Fish, Agro-industry, Deposition, Fixation, Synthetic, People (waste water), Livestock (manure).

• destiny: The destiny category of N: population_food, population_other_uses, livestock_mono, livestock_rum (feed), export, Cropland (for N soil inputs).

• mg_n: Nitrogen amount in megagrams (Mg).

• province_name: Set to "Spain" for all national-level rows.

Examples

create_n_nat_destiny(example = TRUE)

Description

Calculates N production at the provincial level in Spain. Production is derived from consumption, export, import, and other uses.

Usage

create_n_production(example = FALSE)

Arguments

Value

A tibble containing:

• year: Year

• province_name: Spanish province

• item: Product item

• box: Ecosystem box

• prod: Produced N (Mg)

Examples

create_n_production(example = TRUE)

Description

Provides N flows of the spanish agro-food system on a provincial level between 1860 and 2020. This dataset is the the base of the GRAFS model and contains data in megagrams of N (MgN) for each year, province, item, origin and destiny. Thereby, the origin column represents where N comes from, which includes N soil inputs, imports and production. The destiny column shows where N goes to, which includes export, population food, population other uses and feed or cropland (in case of N soil inputs). Processed items, residues, woody crops, grazed weeds are taken into account.

Usage

create_n_prov_destiny(example = FALSE)

Arguments

Value

A final tibble containing N flow data by origin and destiny. It includes the following columns:

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

• province_name: The Spanish province where the data is from.

• item: The item which was produced, defined in names_biomass_cb.

• irrig_cat: Irrigation form (irrigated or rainfed)

• box: One of the GRAFS model systems: cropland, Semi-natural agroecosystems, Livestock, Fish, or Agro-industry.

• origin: The origin category of N: Cropland, Semi-natural agroecosystems, Livestock, Fish, Agro-industry, Deposition, Fixation, Synthetic, People (waste water), Livestock (manure).

• destiny: The destiny category of N: population_food, population_other_uses, livestock_mono, livestock_rum (feed), export, Cropland (for N soil inputs).

• mg_n: Nitrogen amount in megagrams (Mg).

Examples

create_n_prov_destiny(example = TRUE)

Description

Calculates total nitrogen inputs to soils in Spain at the provincial level. This includes contributions from:

• Atmospheric deposition (deposition)

• Biological nitrogen fixation (fixation)

• Synthetic fertilizers (synthetic)

• Manure (excreta, solid, liquid) (manure)

• Urban sources (urban)

Special land use categories and items are aggregated:

• Semi-natural agroecosystems (e.g., Dehesa, Pasture_Shrubland)

• Firewood biomass (e.g., Conifers, Holm oak)

Usage

create_n_soil_inputs(example = FALSE)

Arguments

Value

A tibble containing:

• year: Year

• province_name: Spanish province

• item: Crop, land use, or biomass item

• irrig_cat: Irrigation form (irrigated or rainfed)

• box: Land use or ecosystem box for aggregation

• deposition: N input from atmospheric deposition (Mg)

• fixation: N input from biological N fixation (Mg)

• synthetic: N input from synthetic fertilizers (Mg)

• manure: N input from livestock manure (Mg)

• urban: N input from urban sources (Mg)

Examples

create_n_soil_inputs(example = TRUE)

Description

Maps Eurostat crop codes to their full crop category names, used when integrating Eurostat agricultural statistics.

Usage

crops_eurostat

Format

A tibble where each row corresponds to one Eurostat crop category. It contains the following columns:

• Crop: Eurostat crop code (e.g., "G0000", "G1000").

• Name_Eurostat: Full name of the crop category as used in Eurostat (e.g., "Plants harvested green from arable land", "Temporary grasses and grazings").

Source

Eurostat Agricultural Statistics.

Examples

head(crops_eurostat)

Description

Country- and crop-level estimates of manure nitrogen applied to cropland, from West et al. (2014). Used as a reference for spatializing manure N inputs in the WHEP pipeline.

Usage

crops_manure_n

Format

A tibble with one row per crop-country combination containing:

• Crop_name: Crop name (character).

• ISO: ISO 3166-1 alpha-3 country code.

• Continent: Three-letter continent code (e.g. "AFR", "ASI").

• Manure_N_Mg: Manure nitrogen applied in megagrams (Mg).

Source

West, P. C. et al. (2014). Leverage points for improving global food security and the environment. Science, 345(6194), 325–328. doi:10.1126/science.1246067

Examples

head(crops_manure_n)

Description

Calculate gross energy (GE) intake per IPCC 2019 Tier 2 equations (Vol 4, Ch 10). Estimates net energy components for maintenance, activity, lactation, work, pregnancy, growth, and wool, then derives total gross energy using the REM/REG ratio approach from IPCC Eq 10.16.

All coefficients come from internal package data.

Usage

estimate_energy_demand(data, method = "ipcc2019")

Arguments

Value

Dataframe with added gross_energy (MJ/day), intermediate net energy components, and method_energy tracking column.

Examples

tibble::tibble(
  species = "Dairy Cattle", cohort = "Adult Female",
  heads = 100, weight = 600, diet_quality = "High",
  milk_yield_kg_day = 20
) |>
  estimate_energy_demand() |>
  dplyr::select(species, cohort, heads, ne_maintenance,
    ne_activity, ne_lactation, ne_growth, gross_energy)

Description

Create a new dataframe where each row has a year range into one where each row is a single year, effectively 'expanding' the whole year range.

Usage

expand_trade_sources(trade_sources)

Arguments

Value

A tibble dataframe where each row corresponds to a single year for a given source.

Examples

trade_sources <- tibble::tibble(
  Name = c("a", "b", "c"),
  Trade = c("t1", "t2", "t3"),
  Info_Format = c("year", "partial_series", "year"),
  Timeline_Start = c(1, 1, 2),
  Timeline_End = c(3, 4, 5),
  Timeline_Freq = c(1, 1, 2),
  `Imp/Exp` = "Imp",
  SACO_link = NA,
)
expand_trade_sources(trade_sources)

Description

DE%, NDF%, GE content, and crude protein percentage for High/Medium/Low diet quality levels.

Usage

feed_characteristics

Format

A tibble with diet_quality, de_percent, ndf_percent, ge_content_mj_kg_dm, cp_percent.

Source

IPCC 2019, Vol 4, Ch 10.

Examples

feed_characteristics

Description

Fills gaps (NA values) in a time-dependent variable by linear interpolation between two points, or carrying forward or backwards the last or initial values, respectively. It also creates a new variable indicating the source of the filled values.

Usage

fill_linear(
  data,
  value_col,
  time_col = year,
  interpolate = TRUE,
  fill_forward = TRUE,
  fill_backward = TRUE,
  value_smooth_window = NULL,
  .by = NULL,
  .copy = TRUE
)

Arguments

Value

A tibble data frame (ungrouped) where gaps in value_col have been filled, and a new "source" variable has been created indicating if the value is original or, in case it has been estimated, the gapfilling method that has been used.

Examples

sample_tibble <- tibble::tibble(
  category = c("a", "a", "a", "a", "a", "a", "b", "b", "b", "b", "b", "b"),
  year = c(
    "2015", "2016", "2017", "2018", "2019", "2020",
    "2015", "2016", "2017", "2018", "2019", "2020"
  ),
  value = c(NA, 3, NA, NA, 0, NA, 1, NA, NA, NA, 5, NA),
)
fill_linear(sample_tibble, value, .by = c("category"))
fill_linear(
  sample_tibble,
  value,
  interpolate = FALSE,
  .by = c("category"),
)

Description

Fills missing values using growth rates from a proxy variable (reference series). Supports regional aggregations, weighting, and linear interpolation for small gaps.

Usage

fill_proxy_growth(
  data,
  value_col,
  proxy_col,
  time_col = year,
  .by = NULL,
  max_gap = Inf,
  max_gap_linear = 3,
  fill_scope = NULL,
  value_smooth_window = NULL,
  proxy_smooth_window = 1,
  output_format = "clean",
  verbose = TRUE
)

Arguments

Details

Combined Growth Sequence (Hierarchical Interpolation):

When using multiple proxies with hierarchical fallback, the function implements an intelligent combined growth sequence strategy:

1. Better proxies (earlier in hierarchy) are tried first for each gap.

2. If a better proxy has partial coverage within a gap, those growth rates are used for the covered positions.

3. Fallback proxies fill only the remaining positions where better proxies are not available.

4. Values filled by better proxies are protected from being overwritten.

Value

A data frame with filled values. If output_format = "clean", returns original columns with updated value_col and added source column. If "detailed", includes all intermediate columns.

See Also

fill_linear(), fill_sum()

Examples

# Fill GDP using population as proxy
data <- tibble::tibble(
  country = rep("ESP", 4),
  year = 2010:2013,
  gdp = c(1000, NA, NA, 1200),
  population = c(46, 46.5, 47, 47.5)
)

fill_proxy_growth(
  data,
  value_col = gdp,
  proxy_col = "population",
  .by = "country"
)

Description

Fills gaps in a variable with the sum of its previous value and the value of another variable. When a gap has multiple observations, the values are accumulated along the series. When there is a gap at the start of the series, it can either remain unfilled or assume an invisible 0 value before the first observation and start filling with cumulative sum.

Usage

fill_sum(
  data,
  value_col,
  change_col,
  time_col = year,
  start_with_zero = TRUE,
  .by = NULL
)

Arguments

Value

A tibble dataframe (ungrouped) where gaps in value_col have been filled, and a new "source" variable has been created indicating if the value is original or, in case it has been estimated, the gapfilling method that has been used.

Examples

sample_tibble <- tibble::tibble(
  category = c("a", "a", "a", "a", "a", "a", "b", "b", "b", "b", "b", "b"),
  year = c(
    "2015", "2016", "2017", "2018", "2019", "2020",
    "2015", "2016", "2017", "2018", "2019", "2020"
  ),
  value = c(NA, 3, NA, NA, 0, NA, 1, NA, NA, NA, 5, NA),
  change_variable = c(1, 2, 3, 4, 1, 1, 0, 0, 0, 0, 0, 1)
)
fill_sum(
  sample_tibble,
  value,
  change_variable,
  start_with_zero = FALSE,
  .by = c("category")
)
fill_sum(
  sample_tibble,
  value,
  change_variable,
  start_with_zero = TRUE,
  .by = c("category")
)

Description

Reports trade between pairs of countries in given years.

Usage

get_bilateral_trade(example = FALSE, cbs = NULL)

Arguments

Value

A tibble with the reported trade between countries. For efficient memory usage, the tibble is not exactly in tidy format. It contains the following columns:

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

• item_cbs_code: FAOSTAT internal code for the item that is being traded. For code details see e.g. add_item_cbs_name().

• bilateral_trade: Square matrix of NxN dimensions where N is the total number of countries being considered. The matrix row and column names are exactly equal and they represent country codes.

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

  • Column name: FAOSTAT internal code for the country that is importing the item. See row name explanation above.

  If m is the matrix, the value at m["A", "B"] is the trade in tonnes from country "A" to country "B", for the corresponding year and item. The matrix can be considered balanced. This means:

  • The sum of all values from row "A", where "A" is any country, should match the total exports from country "A" reported in the commodity balance sheet (which is considered more accurate for totals).

  • The sum of all values from column "A", where "A" is any country, should match the total imports into country "A" reported in the commodity balance sheet (which is considered more accurate for totals).

  The sums may not be exactly the expected values because of precision issues and/or the iterative proportional fitting algorithm not converging fast enough, but should be relatively very close to the desired totals.

The step by step approach to obtain this data tries to follow the FABIO model and is explained below. All the steps are performed separately for each group of year and item.

• From the FAOSTAT reported bilateral trade, there are sometimes two values for one trade flow: the exported amount claimed by the reporter country and the import amount claimed by the partner country. Here, the export data was preferred, i.e., if country "A" says it exported X tonnes to country "B" but country "B" claims they got Y tonnes from country "A", we trust the export data X. This choice is only needed if there exists a reported amount from both sides. Otherwise, the single existing report is chosen.

• Complete the country data, that is, add any missing combinations of country trade with NAs, which will be estimated later. In the matrix form, this doesn't increase the memory usage since we had to build a matrix anyway (for the balancing algorithm), and the empty parts also take up memory. This is also done for total imports/exports from the commodity balance sheet, but these are directly filled with 0s instead.

• The total imports and exports from the commodity balance sheet are balanced by downscaling the largest of the two to match the lowest. This is done in the following way:

  • If total_imports > total_exports: Set import as total_exports * import / total_import.

  • If total_exports > total_exports: Set export as total_exports * export / total_export.

• The missing data in the matrix must be estimated. It's done like this:

  • For each pair of exporter i and importer j, we estimate a bilateral trade m[i, j] using the export shares of i and import shares of j from the commodity balance sheet:

    • est_1 <- exports[i] * imports[j] / sum(imports), i.e., total exports of country i spread among other countries' import shares.

    • est_2 <- imports[j] * exports[i] / sum(exports), i.e. total imports of country j spread among other countries' export shares.

    • est <- (est_1 + est_2) / 2, i.e., the mean of both estimates.

    In the above computations, exports and imports are the original values before they were balanced.

  • The estimates for data that already existed (i.e. non-NA) are discarded. For the ones left, for each row (i.e. exporter country), we get the difference between its balanced total export and the sum of original non-estimated data. The result is the gap we can actually fill with estimates, so as to not get past the reported total export. If the sum of non-discarded estimates is larger, it must be downscaled and spread by computing gap * non_discarded_estimate / sum(non_discarded_estimates).

  • The estimates are divided by a trust factor, in the sense that we don't rely on the whole value, thinking that a non-present value might actually be because that specific trade was 0, so we don't overestimate too much. The chosen factor is 10%, so only 10% of the estimate's value is actually used to fill the NA from the original bilateral trade matrix.

• The matrix is balanced, as mentioned before, using the iterative proportional fitting algorithm. The target sums for rows and columns are respectively the balanced exports and imports computed from the commodity balance sheet.

Examples

get_bilateral_trade(example = TRUE)

Description

Important: Dynamically allows for the introduction of subsets as "...".

Note: overhead by individually scraping FAOSTAT code QCL for crop data; it's fine.

Usage

get_faostat_data(activity_data, ...)

Arguments

Value

data.frame of FAOSTAT for activity_data; default is for all years and countries.

Examples

## Not run: 
get_faostat_data("livestock", year = 2010, area = "Portugal")

## End(Not run)

Description

Get amount of items used for feeding livestock.

Usage

get_feed_intake(example = FALSE)

Arguments

Value

A tibble with the feed intake data. 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().

• live_anim_code: Commodity balance sheet code for the type of livestock that is fed. For code details see e.g. add_item_cbs_name().

• item_cbs_code: The code of the item that is used for feeding the animal. For code details see e.g. add_item_cbs_name().

• feed_type: The type of item that is being fed. It can be one of:

  • animals: Livestock product, e.g. ⁠Bovine Meat⁠, ⁠Butter, Ghee⁠, etc.

  • crops: Crop product, e.g. ⁠Vegetables, Other⁠, Oats, etc.

  • residues: Crop residue, e.g. Straw, ⁠Fodder legumes⁠, etc.

  • grass: Grass, e.g. Grassland, ⁠Temporary grassland⁠, etc.

  • scavenging: Other residues. Single Scavenging item.

• supply: The computed amount in tonnes of this item that should be fed to this animal, when sharing the total item feed use from the Commodity Balance Sheet among all livestock.

• intake: The actual amount in tonnes that the animal needs, which can be less than the theoretical used amount from supply.

• intake_dry_matter: The amount specified by intake but only considering dry matter, so it should be less than intake.

• loss: The amount that is not used for feed. This is supply - intake.

• loss_share: The percent that is lost. This is loss / supply.

Examples

get_feed_intake(example = TRUE)

Description

Read and clean the land_fp input file, returning only land-use entries from local production (Impact == "Land" and Origin == "Production").

Usage

get_land_fp_production(example = FALSE)

Arguments

Value

A tibble with columns:

• year: Year.

• area_code: Numeric area code.

• item_cbs_code: Commodity balance sheet item code.

• impact: Impact category.

• element: Source element.

• origin: Origin type.

• group: Group category.

• impact_u: Land footprint value (TODO: find which unit).

Examples

get_land_fp_production(example = TRUE)

Description

Get amount of crops, livestock and livestock products.

Usage

get_primary_production(example = FALSE)

Arguments

Value

A tibble with the item production data. 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().

• item_prod_code: FAOSTAT internal code for each produced item.

• item_cbs_code: FAOSTAT internal code for each commodity balance sheet item. The commodity balance sheet contains an aggregated version of production items. This field is the code for the corresponding aggregated item.

• live_anim_code: Commodity balance sheet code for the type of livestock that produces the livestock product. It can be:

  • NA: The entry is not a livestock product.

  • Non-NA: The code for the livestock type. The name can also be retrieved by using add_item_cbs_name().

• unit: Measurement unit for the data. Here, keep in mind three groups of items: crops (e.g. ⁠Apples and products⁠, Beans...), livestock (e.g. ⁠Cattle, dairy⁠, Goats...) and livestock products (e.g. ⁠Poultry Meat⁠, ⁠Offals, Edible⁠...). Then the unit can be one of:

  • tonnes: Available for crops and livestock products.

  • ha: Hectares, available for crops.

  • t_ha: Tonnes per hectare, available for crops.

  • heads: Number of animals (stocks), available for livestock.

  • slaughtered_heads: Number of animals slaughtered, available for livestock.

  • LU: Standard Livestock Unit measure, available for livestock.

  • t_head: tonnes per head, available for livestock products.

  • t_LU: tonnes per Livestock Unit, available for livestock products.

• value: The amount of item produced, measured in unit.

Examples

get_primary_production(example = TRUE)

Description

Get type and amount of residue produced for each crop production item.

Usage

get_primary_residues(example = FALSE)

Arguments

Value

A tibble with the crop residue data. 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().

• item_cbs_code_crop: FAOSTAT internal code for each commodity balance sheet item. This is the crop that is generating the residue.

• item_cbs_code_residue: FAOSTAT internal code for each commodity balance sheet item. This is the obtained residue. In the commodity balance sheet, this can be three different items right now:

  • 2105: Straw

  • 2106: ⁠Other crop residues⁠

  • 2107: Firewood

  These are actually not FAOSTAT defined items, but custom defined by us. When necessary, FAOSTAT codes are extended for our needs.

• value: The amount of residue produced, measured in tonnes.

Examples

get_primary_residues(example = TRUE)

Description

Reports quantities of commodity balance sheet items used for processing and quantities of their corresponding processed output items.

Usage

get_processing_coefs(example = FALSE)

Arguments

Value

A tibble with the quantities for each processed product. 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().

• item_cbs_code_to_process: FAOSTAT internal code for each one of the items that are being processed and will give other subproduct items. For code details see e.g. add_item_cbs_name().

• value_to_process: tonnes of this item that are being processed. It matches the amount found in the processing column from the data obtained by get_wide_cbs().

• item_cbs_code_processed: FAOSTAT internal code for each one of the subproduct items that are obtained when processing. For code details see e.g. add_item_cbs_name().

• initial_conversion_factor: estimate for the number of tonnes of item_cbs_code_processed obtained for each tonne of item_cbs_code_to_process. It will be used to compute the final_conversion_factor, which leaves everything balanced. TODO: explain how it's computed.

• initial_value_processed: first estimate for the number of tonnes of item_cbs_code_processed obtained from item_cbs_code_to_process. It is computed as value_to_process * initial_conversion_factor.

• conversion_factor_scaling: computed scaling needed to adapt initial_conversion_factor so as to get a final balanced total of subproduct quantities. TODO: explain how it's computed.

• final_conversion_factor: final used estimate for the number of tonnes of item_cbs_code_processed obtained for each tonne of item_cbs_code_to_process. It is computed as initial_conversion_factor * conversion_factor_scaling.

• final_value_processed: final estimate for the number of tonnes of item_cbs_code_processed obtained from item_cbs_code_to_process. It is computed as initial_value_processed * final_conversion_factor.

For the final data obtained, the quantities final_value_processed are balanced in the following sense: the total sum of final_value_processed for each unique tuple of ⁠(year, area_code, item_cbs_code_processed)⁠ should be exactly the quantity reported for that year, country and item_cbs_code_processed item in the production column obtained from get_wide_cbs(). This is because they are not primary products, so the amount from 'production' is actually the amount of subproduct obtained. TODO: Fix few data where this doesn't hold.

Examples

get_processing_coefs(example = TRUE)

Description

Retrieve supply and use parts for each commodity balance sheet (CBS) item. Stock variations are split into two non-negative columns following the FABIO methodology.

Usage

get_wide_cbs(example = FALSE)

Arguments

Value

A tibble with the commodity balance sheet data in wide format. 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().

• item_cbs_code: FAOSTAT internal code for each item. For code details see e.g. add_item_cbs_name().

The other columns are quantities where total supply and total use should be balanced. Units are tonnes for most items, and heads for live animals (see items_cbs item_type).

For supply:

• production: Produced locally.

• import: Obtained from importing from other countries.

• stock_withdrawal: Biomass taken out of storage (non-negative). Positive when stocks decrease.

For use:

• food: Food for humans.

• feed: Food for animals.

• export: Released as export for other countries.

• seed: Intended for new production.

• processing: Used to obtain other subproducts.

• other_uses: Any other use not included above.

• stock_addition: Biomass placed into storage (non-negative). Positive when stocks increase.

There is an additional column domestic_supply which is computed as total use excluding export.

Examples

get_wide_cbs(example = TRUE)

Description

Typical live weights by region, species, system, and cohort.

Usage

gleam_animal_weights

Format

A tibble with region, species, system, cohort, weight_kg.

Source

MacLeod et al. (2018) GLEAM 3.0.

Examples

gleam_animal_weights

Description

Nitrogen content of above- and below-ground residues and root-to-shoot ratios for feed materials.

Usage

gleam_crop_residue_nitrogen

Format

A tibble with columns:

material_number

Sequential material identifier.

material

Feed material code.

n_ag

Nitrogen content of above-ground residues.

rbg_bio

Ratio of below-ground residues to above-ground biomass.

n_bg

Nitrogen content of below-ground residues.

species_group

"ruminant" or "monogastric".

Source

MacLeod et al. (2018) GLEAM 3.0 Supplement S1, Tables S.6.7 and S.6.8.

Examples

gleam_crop_residue_nitrogen

Description

Dry matter content and parameters for calculating crop residue yield by crop type.

Usage

gleam_crop_residue_params

Format

A tibble with columns:

crop

Crop name.

dry_matter_pct

Dry matter content (percent).

slope

Slope for residue yield calculation.

intercept

Intercept for residue yield calculation.

Source

MacLeod et al. (2018) GLEAM 3.0 Supplement S1, Table S.3.1. doi:10.1088/1748-9326/aad4d8

Examples

gleam_crop_residue_params

Description

Carcass weight as percentage of live weight by species, production system, cohort, and GLEAM region. Includes country-specific overrides for industrial pig systems in Western Europe.

Usage

gleam_dressing_percentages

Format

A tibble with columns:

species

Animal species (Cattle, Buffaloes, Sheep, Goats, Pigs, Chicken).

production_system

Production system (Dairy, Beef, Backyard, Intermediate, Industrial, Layers, Broilers). NA for species without system breakdown.

cohort

Cohort (e.g. Adult and replacement female). NA for species without cohort breakdown.

country

Country name for country-specific values. NA for regional values.

gleam_region

GLEAM region abbreviation (NA, RUS, WE, EE, NENA, ESEA, OCE, SA, LAC, SSA).

dressing_percent

Dressing percentage.

Source

MacLeod et al. (2018) GLEAM 3.0 Supplement S1, Table S.9.1. doi:10.1088/1748-9326/aad4d8

Examples

gleam_dressing_percentages

Description

Emission factors for embedded and direct energy use in livestock production, by species, production system, and climate zone.

Usage

gleam_energy_use_ef

Format

A tibble in long format with columns:

grouping

Country or country group (e.g. "OECD", "EU 27").

species

Animal species or group (e.g. "dairy_cattle", "pigs").

system

Production system (e.g. "Grassland based", "industrial"). NA when not applicable.

climate

Climate zone ("arid", "humid", "temperate"). NA when not applicable.

energy_type

"embedded" or "direct".

emission_factor

Emission factor in kg CO2-eq per unit product.

Source

MacLeod et al. (2018) GLEAM 3.0 Supplement S1, Tables S.7.1 through S.7.7.

Examples

gleam_energy_use_ef

Description

Ym (% GE) values by species and production system. Feedlot cattle use 3.0% per IPCC 2019 Table 10.12.

Usage

gleam_enteric_params

Format

A tibble with species, system, ym_percent, notes.

Source

IPCC 2019 Refinement, Vol 4, Ch 10, Table 10.12.

Examples

gleam_enteric_params

Description

Feed classification used in GLEAM 3.0.

Usage

gleam_feed_categories

Format

A tibble with feed_category, feed_type, description.

Source

MacLeod et al. (2018) GLEAM 3.0.

Examples

gleam_feed_categories

Description

Regional feed use efficiency (FUE) values for forages and crop residues of ruminant species.

Usage

gleam_feed_composition

Format

A tibble with columns:

feed_group

Feed material group (1-6 or 9-15).

feed_type

Feed type (mixed, grassland, or all).

gleam_region

GLEAM geographic region.

feed_use_efficiency

FUE value (0-1 fraction).

Source

MacLeod et al. (2018) GLEAM 3.0 Supplement S1, Table S.3.2.

Examples

gleam_feed_composition

Description

Nutritional values for feed materials of monogastric species (chicken and pigs).

Usage

gleam_feed_conversion_ratios

Format

A tibble with columns:

number

Feed material number.

material

Feed material code.

gross_energy_j_kg

Gross energy (J per kg).

n_content_g_kg

Nitrogen content (g per kg DM).

me_chicken_j_kg

Metabolisable energy for chicken (J per kg).

me_pigs_j_kg

Metabolisable energy for pigs (J per kg).

digestibility_pct

Digestibility (percent).

Source

MacLeod et al. (2018) GLEAM 3.0 Supplement S1, Table S.3.4.

Examples

gleam_feed_conversion_ratios

Description

Nutritional values for feed materials of ruminant species, including gross energy, nitrogen content, and digestibility.

Usage

gleam_feed_digestibility

Format

A tibble with columns:

number

Feed material number.

material

Feed material code.

gross_energy_mj_kg

Gross energy (MJ per kg DM).

n_content_g_kg

Nitrogen content (g per kg DM).

digestibility_pct

Digestibility (percent).

Source

MacLeod et al. (2018) GLEAM 3.0 Supplement S1, Table S.3.3.

Examples

gleam_feed_digestibility

Description

CO2-equivalent emissions per hectare from field operations for ruminant and monogastric feed materials.

Usage

gleam_field_operation_ef

Format

A tibble with columns:

material_number

Sequential material identifier.

material

Feed material code (e.g. "GRASSF", "WHEAT").

emission_factor_kg_co2eq_ha

Emission factor in kg CO2-eq per hectare.

species_group

"ruminant" or "monogastric".

Source

MacLeod et al. (2018) GLEAM 3.0 Supplement S1, Tables S.6.1 and S.6.2.

Examples

gleam_field_operation_ef

Description

Countries whose FracReMove value differs from the GLEAM default.

Usage

gleam_fracremove

Format

A tibble with columns:

country

Country name.

continent

Continent.

region

GLEAM region.

fracremove

Fraction of crop residues removed (0 to 1).

Source

MacLeod et al. (2018) GLEAM 3.0 Supplement S1, Table S.6.9.

Examples

gleam_fracremove

Description

Maps countries (ISO3) to GLEAM regions, FAOSTAT regions, and classification indicators.

Usage

gleam_geographic_hierarchy

Format

A tibble with columns:

iso3

ISO3 country code.

country

Country name.

continent

Continent.

faostat_region

FAOSTAT regional grouping.

gleam_region

GLEAM regional grouping.

Source

MacLeod et al. (2018) GLEAM 3.0 Supplement S1, Tables S.A1-S.A2. doi:10.1088/1748-9326/aad4d8

Examples

gleam_geographic_hierarchy

Description

Species, production systems, and cohort definitions from GLEAM 3.0.

Usage

gleam_livestock_categories

Format

A tibble with columns:

species

Animal species.

production_system

Dairy, Beef, Meat, etc.

cohort

Age/sex cohort.

description

Cohort description.

Source

MacLeod et al. (2018) GLEAM 3.0 Model Description.

Examples

gleam_livestock_categories

Description

Mechanization level by country for each feed material, for ruminant and monogastric species.

Usage

gleam_mechanization_levels

Format

A tibble in long format with columns:

country

Country name.

continent

Continent.

region

GLEAM region.

feed_material

Feed material code in lowercase.

mechanization_level

Numeric mechanization level.

species_group

"ruminant" or "monogastric".

Source

MacLeod et al. (2018) GLEAM 3.0 Supplement S1, Tables S.6.3 and S.6.4.

Examples

gleam_mechanization_levels

Description

Average annual milk yields and lactation lengths by region.

Usage

gleam_milk_production

Format

A tibble with region, species, system, milk_kg_head_yr, lactation_days.

Source

MacLeod et al. (2018) GLEAM 3.0.

Examples

gleam_milk_production

Description

Regional MMS allocation by species and system.

Usage

gleam_mms_shares

Format

A tibble with region, species, system, mms, share_percent.

Source

MacLeod et al. (2018) GLEAM 3.0.

Examples

gleam_mms_shares

Description

Emission factors for processing and transport of feed materials, for ruminant and monogastric species.

Usage

gleam_processing_transport_ef

Format

A tibble with columns:

material_number

Sequential material identifier.

material

Feed material code.

processing_g_co2eq_kg_dm

Processing emission factor in g CO2-eq per kg dry matter.

transport_g_co2eq_kg_dm

Transport emission factor in g CO2-eq per kg dry matter.

species_group

"ruminant" or "monogastric".

Source

MacLeod et al. (2018) GLEAM 3.0 Supplement S1, Tables S.6.5 and S.6.6.

Examples

gleam_processing_transport_ef

Description

Walking energy cost for grazing animals (MJ/kg body weight/km).

Usage

grazing_energy_coefs

Format

A tibble with parameter, value_mj_kg_km, source.

Source

NRC 2001 (0.00045 Mcal/kg/km converted to MJ).

Examples

grazing_energy_coefs

Description

Harmonize data containing "simple" and "1:n" mappings. "simple" covers both 1:1 and N:1 relationships (values are summed). For "1:n" groups (one original item splits into several harmonized items) this function computes value shares across the full year range, interpolates missing shares, and applies them to split values.

Important for 1:n mappings: For each original item that splits into multiple harmonized items (e.g., "wheatrice" into "wheat" and "rice"), provide one row per target item_code_harm. Each row should have the same item, year, and value, differing only in item_code_harm. For example, to disaggregate "wheatrice":

• Row 1: item = "wheatrice", item_code_harm = 1

• Row 2: item = "wheatrice", item_code_harm = 2

Do not provide a single row; the function will not create duplicates automatically.

Usage

harmonize_interpolate(data, ...)

Arguments

Value

A tibble with columns:

• item_code: Numeric, code for harmonized item.

• year: Numeric, year of observation.

• value: Numeric, summed value of observation.

• and any additional grouping columns.

Examples

# Simple-only data (no 1:n rows)
df_simple <- tibble::tribble(
  ~item, ~item_code_harm, ~year, ~value, ~type,
  "wheat", 1, 2000, 5, "simple",
  "barley", 2, 2000, 3, "simple",
  "oats", 2, 2000, 2, "simple"
)
harmonize_interpolate(df_simple)

# Mixed simple + 1:n data
df_mixed <- tibble::tribble(
  ~item, ~item_code_harm, ~year, ~value, ~type,
  "wheatrice", 1, 2000, 20, "1:n",
  "wheatrice", 2, 2000, 20, "1:n",
  "wheat", 1, 2000, 8, "simple",
  "rice", 2, 2000, 12, "simple"
)
harmonize_interpolate(df_mixed)

# Multiple years with share interpolation
# Shares are known in 2000 and 2002; 2001 is interpolated.
df_years <- tibble::tribble(
  ~item, ~item_code_harm, ~year, ~value, ~type,
  "wheat", 1, 2000, 6, "simple",
  "rice", 2, 2000, 4, "simple",
  "wheatrice", 1, 2001, 10, "1:n",
  "wheatrice", 2, 2001, 10, "1:n",
  "wheat", 1, 2002, 8, "simple",
  "rice", 2, 2002, 2, "simple"
)
harmonize_interpolate(df_years)

# With extra grouping columns
df_grouped <- tibble::tribble(
  ~item, ~item_code_harm, ~year, ~value, ~type, ~country,
  "wheat", 1, 2000, 6, "simple", "usa",
  "rice", 2, 2000, 4, "simple", "usa",
  "wheatrice", 1, 2001, 10, "1:n", "usa",
  "wheatrice", 2, 2001, 10, "1:n", "usa",
  "wheat", 1, 2002, 8, "simple", "usa",
  "rice", 2, 2002, 2, "simple", "usa",
  "wheat", 1, 2002, 8, "simple", "germany"
)
harmonize_interpolate(df_grouped, country)

Description

Sum value for rows where type == "simple". This covers both 1:1 and N:1 item mappings, since in both cases the values are simply summed. The results are grouped by item_code_harm, year and any additional grouping columns supplied via ....

Usage

harmonize_simple(data, ...)

Arguments

Value

A tibble with columns:

• item_code_harm: Numeric, code for harmonized item.

• year: Numeric, year of observation.

• value: Numeric, summed value of observation.

• and any additional grouping columns.

Examples

# 1:1 mapping: one original item -> one harmonized code
df_one_to_one <- tibble::tribble(
  ~item_code_harm, ~year, ~value, ~type,
  1, 2000, 10, "simple",
  2, 2000, 3, "simple",
  1, 2001, 12, "simple",
  2, 2001, 5, "simple"
)
harmonize_simple(df_one_to_one)

# N:1 mapping: multiple items map to the same code
df_many_to_one <- tibble::tribble(
  ~item_code_harm, ~year, ~value, ~type,
  1, 2000, 4, "simple",
  1, 2000, 6, "simple",
  2, 2000, 3, "simple"
)
harmonize_simple(df_many_to_one)

# With an extra grouping column (e.g. country)
df_grouped <- tibble::tribble(
  ~item_code_harm, ~year, ~value, ~type, ~country,
  1, 2000, 4, "simple", "usa",
  1, 2000, 6, "simple", "usa",
  1, 2000, 9, "simple", "germany",
  2, 2000, 3, "simple", "usa"
)
harmonize_simple(df_grouped, country)

# Rows with type != "simple" are ignored
df_mixed <- tibble::tribble(
  ~item_code_harm, ~year, ~value, ~type,
  1, 2000, 10, "simple",
  1, 2000, 99, "1:n",
  2, 2000, 3, "simple"
)
harmonize_simple(df_mixed)