Package index

Build datasets

Build full datasets from raw FAOSTAT inputs. These functions orchestrate reading, gap-filling, historical extension, and balance validation.

build_primary_production(): Build primary production dataset
build_commodity_balances(): Build commodity balance sheets
build_processing_coefs(): Build processing coefficients
build_detailed_trade(): Build detailed bilateral trade matrix
build_trade_prices(): Build global trade prices
build_primary_prices(): Build primary item prices
build_cbs_prices(): Build CBS item prices

Spatialization

Disaggregate country-level agricultural data to a 0.5-degree grid. run_spatialize() wraps build_gridded_landuse() with named presets (LPJmL-faithful vs full WHEP) for direct cross-model comparison.

run_spatialize(): Run the gridded land-use spatialization pipeline
build_gridded_landuse(): Build gridded landuse dataset
build_gridded_livestock(): Build gridded livestock dataset

Constant-territory back-casting

Rebuild historical series onto a fixed reference-year’s boundaries by dasymetric spatial reallocation, optionally weighted by LPJmL/WHEP gridded covariates.

build_constant_territory_series(): Build a constant-territory time series for a reference year's boundaries
make_lpjml_covariate(): Build an LPJmL/WHEP spatial covariate function

LPJmL grass availability

Read managed-grassland net primary production from a finished LPJmL run into grazable above-ground dry-matter availability, the forage supply ceiling for feed allocation.

build_grass_availability(): Build grazable grass availability.
build_grass_availability_lpjml(): Build grazable grass availability from an LPJmL run.
grass_access_shares(): Accessibility and conversion parameters for grazable grass availability.
aggregate_grass_to_polity(): Aggregate gridded grass availability to polity totals.
read_lpjml_grass_productivity(): Read natural-grass productivity from an LPJmL run.

Crop NPP, BNF and coefficient tables

Crop net primary production (products, residues, roots, weeds), biological nitrogen fixation, residue destinies, and the coefficient tables that drive them. Ported from afsetools, item-keyed and multi-method.

whep_coef_table(): Read a WHEP coefficient table.
calculate_potential_npp(): Estimate potential net primary production.
calculate_crop_residues(): Estimate crop above-ground residue biomass.
calculate_crop_roots(): Estimate crop below-ground (root) biomass.
calculate_crop_npp(): Estimate total crop net primary production.
calculate_npp_carbon_nitrogen(): Partition crop and weed NPP into dry matter, carbon and nitrogen.
calculate_crop_npp_components(): Estimate cropland NPP components including weeds.
calculate_crop_bnf(): Estimate symbiotic biological nitrogen fixation by crop legumes.
calculate_weed_bnf(): Estimate symbiotic biological nitrogen fixation by weeds and cover crops.
calculate_nonsymbiotic_bnf(): Estimate non-symbiotic biological nitrogen fixation.
calculate_bnf(): Estimate total biological nitrogen fixation.
summarize_bnf(): Summarise biological nitrogen fixation results.
calculate_residue_destinies(): Estimate the destinies of crop residues.
build_residue_feed_avail(): Build residue feed availability for feed allocation.

Tidy datasets

Get cleaned dataframes with project related data.

Production

Production, supply/use, and processing datasets.

build_supply_use(): Supply and use tables
get_feed_intake(): Livestock feed intake
build_feed_demand(): Build livestock feed demand.
build_feed_intake_local(): Build local (per-cell) feed intake, chunked by year.
get_primary_production(): Primary items production
get_primary_residues(): Crop residue items
get_processing_coefs(): Processed products share factors
get_wide_cbs(): Commodity balance sheet data.
get_livestock_cbs(): Livestock commodity balance sheet entries

Trade

Bilateral trade datasets.

get_bilateral_trade(): Bilateral trade data

Nitrogen cycles

Nitrogen inputs, outputs, production, and destinies for Spain.

create_n_prov_destiny(): GRAFS Nitrogen (N) flows
create_n_soil_inputs(): Nitrogen (N) soil inputs for Spain
create_n_production(): N production for Spain
calculate_nue_crops(): N soil inputs and Nitrogen Use Efficiency (NUE) for crop
calculate_nue_livestock(): NUE for Livestock
calculate_system_nue(): System NUE
create_n_nat_destiny(): GRAFS Nitrogen (N) flows at Spain national level

Download large input datasets

Fetch large files from external sources and cache them.

whep_read_file(): Download, cache and read files
whep_inputs: External inputs
whep_list_file_versions(): Input file versions
whep_clear_cache(): Clear the build pipeline cache

Code namings

Add name columns in dataframes from their codes or viceversa.

Polities

polities: Polities
polity_area_crosswalk: FAOSTAT/FABIO area-to-polity crosswalk
polities_cats: Polity categories and regional classifications
regions_full: Full polity and region reference table
add_polity_code(): Add WHEP polity codes to a table
add_area_code(): Get area codes from area names
add_area_name(): Get area names from area codes
get_polity_geometries(): Get WHEP polity geometries

Commodity balance sheet items

items_cbs: Commodity balance sheet items
items_full: Full CBS item table
cbs_trade_codes: CBS to trade item code mapping
add_item_cbs_code(): Get commodity balance sheet item codes from item names
add_item_cbs_name(): Get commodity balance sheet item names from item codes

Primary production items

items_prod: Primary production items
items_prim: Primary production items linked to CBS
items_prod_full: Full production item table
add_item_prod_code(): Get production item codes from item names
add_item_prod_name(): Get production item names from item codes

Reference tables

Lookup and coefficient tables used internally across the pipeline.

animals_codes: Animal codes and classifications
biomass_coefs: Biomass coefficients for crops and livestock products
cb_processing: Commodity balance sheet processing fractions
cft_mapping: FAOSTAT crop to LPJmL crop functional type (CFT) mapping
crops_eurostat: Eurostat crop classification codes
crops_manure_n: Manure nitrogen application by crop and country
lassaletta_grassland_share: Grassland share of synthetic nitrogen by country and year
liv_lu_coefs: Livestock unit coefficients
mueller_synthetic_n: Synthetic nitrogen application rates by crop and country
primary_double: Items with double-counting in production statistics
smil_2001_synthetic_n_global: Smil (2001) global synthetic nitrogen production, 1913-2000

FAOSTAT raw data

Download FAOSTAT data as is.

get_faostat_data(): Scrapes activity_data from FAOSTAT and slightly post-processes it

Data sources

Get a tidy dataframe with the found sources for different data.

expand_trade_sources(): Trade data sources

Gap filling functions

Functions to fill gaps (NA values) in time-dependent variables using different methods.

fill_linear(): Fill gaps by linear interpolation, or carrying forward or backward.
fill_sum(): Fill gaps summing the previous value of a variable to the value of another variable.
fill_proxy_growth(): Fill gaps using growth rates from proxy variables

Multi-source consolidation

Reduce a multi-source panel to one winning row per cell by source priority, with measure-aware demotion, coverage and quality tie-breaks, and an isolated-flip continuity override.

consolidate_sources(): Consolidate a multi-source panel to one winning row per cell.

Decomposition analysis

Functions for index decomposition analysis.

calculate_lmdi(): Calculate LMDI decomposition.
decompose_weighted_ratio(): Decompose a weighted aggregate ratio.

Multi-regional input-output model

Build and analyze multi-regional input-output (MRIO) models following the FABIO framework.

build_io_model(): Build multi-regional input-output model.
compute_leontief_inverse(): Compute Leontief inverse.
balance_ras(): Balance a matrix to target margins by RAS.
balance_io_flows(): Balance input-output flows so the footprint conserves.
compute_footprint(): Compute environmental footprints.
build_footprint(): Compute a footprint end-to-end from an extension table.
align_extension(): Align an extension table to input-output sector labels.
compute_footprint_paths(): Compute first-use footprint paths.
compute_fp_product_paths(): Compute final-product footprint paths.
add_footprint_product_stage(): Add a final-demand product-area stage to footprints.
build_crop_land_extension(): Build per-crop physical cropland extension.
get_crop_land_extension(): Get the per-crop physical cropland extension from spatialization inputs.
build_cropgrids_land_extension(): Build a per-crop physical land extension from CROPGRIDS.
build_hayr_land_extension(): Build a hectare-year (land-occupation) crop land extension.
build_grassland_land_extension(): Build the native grassland land extension.
build_livestock_ghg_extension(): Build the livestock greenhouse-gas emissions extension.
build_energy_co2_extension(): Build the livestock energy-use CO2 footprint extension (meat only).
build_crop_soil_n2o_extension(): Build the crop/soil N2O extension.
gridded_fallow_weights(): Build agro-climatic, rainfed-gated fallow allocation weights.
attribute_fallow_to_crops(): Attribute reported fallow land to crops.
plot_footprint_sankey(): Interactive footprint Sankey viewer
compute_footprint_balance(): Compute land footprints by physical trade balance.
build_land_balance_footprint(): Build a consumption land footprint by physical trade balance.
melt_bilateral_trade(): Melt a bilateral trade matrix to long format.
compare_footprint_methods(): Compare two footprint estimates.
allocate_grazing_to_products(): Allocate grazing land forward to livestock products.
build_grazing_feed_footprint(): Build a grazing-land footprint by forward feed-allocation.

Trustworthiness and quality control

Checks that make footprint, balance and time-series results trustworthy: conservation invariants, accounting identities, within-series jump detection (the level-2 detector of the AFE data-validation framework), and other data-quality diagnostics.

check_footprint_conservation(): Check footprint conservation against direct extensions.
summarise_conservation(): Summarise a footprint conservation report.
assert_footprint_invariants(): Assert that footprint conservation invariants hold.
check_supply_use_balance(): Check the commodity balance sheet supply-use identity.
check_series_jumps(): Flag implausible year-on-year jumps in a time series.

Uncertainty and sensitivity

Propagate input uncertainty through a footprint, combine data-quality coefficients of variation, and rank sectors by local sensitivity.

propagate_fp_uncertainty(): Propagate input uncertainty through a footprint.
combine_cov(): Combine independent coefficient-of-variation components.
footprint_sensitivity(): Local sensitivity of a footprint to each extension.

Provenance and reproducibility

Record and carry the code and input versions behind a result so any number can be traced back to what produced it.

record_provenance(): Record provenance for a reproducible result.
attach_provenance(): Attach a provenance record to a result.
get_provenance(): Retrieve a result's provenance record.

Scope and transparency

Attach a machine-readable goal-and-scope record (method, boundary, allocation, vintage, limitations) to a footprint result.

footprint_scope(): Describe the scope of a footprint result.
attach_scope(): Attach a scope record to a result.
get_scope(): Retrieve a result's scope record.

Livestock emissions

Calculate livestock GHG emissions using IPCC 2019 Tier 1 and Tier 2 methods for enteric methane, manure methane, and manure nitrous oxide.

prepare_livestock_emissions(): Prepare production data for livestock emission calculations.
calculate_livestock_emissions(): Calculate all livestock emissions.
calculate_enteric_ch4(): Calculate enteric methane emissions.
calculate_manure_emissions(): Calculate manure emissions (CH4 + N2O).
estimate_n_excretion(): Estimate livestock nitrogen, carbon and volatile-solids excretion.
split_manure_management(): Split livestock excretion across manure-management systems.
apply_management_losses(): Apply IPCC manure-management losses to the collected manure streams.
build_livestock_nutrient_flows(): Build livestock nutrient flows from realised feed intake.
allocate_manure_to_land(): Allocate field-available manure to cropland and grassland by crop.
allocate_manure_transport(): Spill surplus manure to neighbouring cells with spare capacity.
estimate_energy_demand(): Estimate energy demand (Gross Energy) - Tier 2
calculate_cohorts_systems(): Calculate cohort and production system distribution.
calculate_uncertainty_bounds(): Calculate uncertainty bounds for livestock emissions.

Feed intake

Estimate livestock feed demand and allocate it against feed availability.

redistribute_feed(): Redistribute available feed supply among livestock demand.

Feed coefficient tables

Bouwman and Krausmann feed coefficients, feed taxonomy and diet share caps.

conv_bouwman: Bouwman feed conversion ratios.
conv_krausmann: Krausmann per head feed intake.
feed_taxonomy: Feed taxonomy.
max_intake_share: Maximum intake shares.

Livestock coefficient tables

IPCC and GLEAM coefficient tables for livestock emission calculations.

GLEAM supplement tables

Data from MacLeod et al. (2018) GLEAM 3.0 Supplement S1.

gleam_animal_weights: GLEAM animal weights.
gleam_crop_residue_params: GLEAM crop residue parameters.
gleam_dressing_percentages: GLEAM dressing percentages.
gleam_enteric_params: GLEAM enteric fermentation parameters.
gleam_feed_categories: GLEAM feed categories.
gleam_feed_composition: GLEAM feed use efficiency.
gleam_feed_conversion_ratios: GLEAM feed conversion ratios for monogastrics.
gleam_feed_digestibility: GLEAM feed digestibility for ruminants.
gleam_geographic_hierarchy: GLEAM geographic hierarchy.
gleam_livestock_categories: GLEAM livestock categories.
gleam_milk_production: GLEAM milk production.
gleam_mms_shares: GLEAM manure management system shares.
gleam_field_operation_ef: Emission factors for field operations on feed materials.
gleam_mechanization_levels: Country-level mechanization levels for feed materials.
gleam_processing_transport_ef: Processing and transport emission factors for feeds.
gleam_crop_residue_nitrogen: Nitrogen parameters for crop residues of feed materials.
gleam_fracremove: Country-level fraction of crop residues removed.
gleam_energy_use_ef: Energy use emission factors for livestock production.

Emission factors and parameters from IPCC 2019, Vol 4, Ch 10.

ipcc_2019_enteric_ef_cattle: IPCC 2019 enteric EF for cattle.
ipcc_2019_enteric_ef_other: IPCC 2019 enteric EF for non-cattle.
ipcc_2019_manure_ch4_ef_cattle: IPCC 2019 manure CH4 EF for cattle.
ipcc_2019_manure_ch4_ef_other: IPCC 2019 manure CH4 EF for non-cattle.
ipcc_2019_mcf_manure: IPCC 2019 MCF for manure management.
ipcc_2019_n_excretion: IPCC 2019 nitrogen excretion rates.
ipcc_2019_n2o_ef_direct: IPCC 2019 direct N2O emission factors.
ipcc_2019_ym: IPCC 2019 Ym values (Table 10.12).
ipcc_2019_bo: IPCC 2019 Bo values (Table 10.16).
ipcc_2019_cfi: IPCC 2019 Cfi values (Table 10.4).

IPCC 2006 tables

Emission factors from IPCC 2006 Guidelines, Vol 4, Ch 10.

ipcc_2006_enteric_ef: IPCC 2006 Tier 1 enteric emission factors.
ipcc_2006_manure_ef: IPCC 2006 Tier 1 manure emission factors.
ipcc_2006_mcf_temp: IPCC 2006 MCF by temperature.

Tier 2 parameters

Detailed parameters for IPCC Tier 2 calculations.

ipcc_tier2_energy_coefs: Tier 2 energy coefficients.
ipcc_tier2_ym_values: Tier 2 Ym values.
ipcc_tier2_bo_values: Tier 2 Bo values.
ipcc_tier2_manure_ash: Tier 2 manure ash content.
ipcc_tier2_n_retention: Tier 2 nitrogen retention fractions.
livestock_production_defaults: Default production parameters.
feed_characteristics: Feed characteristics by diet quality.
livestock_constants: Livestock physical constants.

Other livestock tables

Climate, manure management, and uncertainty tables.

climate_mcf: Climate-zone MCF values.
regional_mms_distribution: Regional MMS distribution.
temperature_adjustment: Temperature adjustment factors for NEm.
grazing_energy_coefs: Grazing energy coefficients.
indirect_n2o_ef: Indirect N2O emission factors.
uncertainty_ranges: Uncertainty ranges for emission parameters.

Harmonization

Functions to harmonize time series items according to specified mapping.

harmonize_simple(): Harmonize rows labeled "simple" by summing values
harmonize_interpolate(): Harmonize advanced cases with interpolation for 1:N groups