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_historical_land_areas(): Build a pre-1962 land series measured on each year's own borders
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
read_glw_density(): Read GLW3 gridded livestock counts on WHEP's 0.5-degree grid
admin_shares_prototype(): The admin-shares zero-row prototype
admin_shares_schema(): The admin-shares table contract
ensure_admin_shares(): Complete a table to the admin-shares contract
read_admin_stats_nass(): Read United States state or county agricultural statistics from NASS
read_admin_stats_eurostat(): Read Eurostat regional crop and livestock statistics
read_admin_stats_sidra(): Read Brazilian state agricultural statistics from IBGE SIDRA
read_admin_family(): Read the per-family subnational admin-statistics pins
read_admin_shares(): Read the assembled subnational admin-shares pin
resolve_admin_units(): Resolve source-native admin identifiers to polity codes
resolve_admin_shares(): Resolve one source per container from the admin-shares table
read_level_country_grid(): Read the cell-to-polity country grid at a containment depth
build_allocation_layer(): Choose an allocation depth per country and assert no cell is claimed twice
admin_coverage_prototype(): Zero-row prototype of the run's admin-coverage report
build_level_crop_targets(): Split a national crop total across the units of its container
allocate_level_crops(): Allocate national crop areas at a granted containment depth
reconcile_admin_allocation(): Reconcile a level allocation against the national totals that bind
unit_cropland_extent(): The cropland each unit holds, on the basis the capacity ceiling uses
aggregate_unit_extent(): Aggregate a gridded land quantity onto administrative units
check_extent_jumps(): Flag implausible year-on-year jumps in a per-unit extent
backcast_admin_shares(): Back-cast admin shares across the seam
seam_gate_tolerances(): Tolerances of the admin-shares seam gate
seam_gate(): Gate an admin-shares back-cast at its seams

Polycell spatial support

Build the canonical spatial support unit, the polycell: a 0.5-degree grid cell intersected with a polity over its validity interval, carrying the territory decomposed into land, inland water and ice so that polycells re-aggregate to a polity without value change or cross-border leakage.

build_polycell_land_uses(): Partition each polycell into mutually exclusive land uses.
build_polycell_support(): Build the polycell spatial support table
expand_polycell_years(): Expand the interval-keyed polycell support to one row per year
polycell_example_geometries(): A minimal polity geometry table for examples and smoke tests
read_polycell_support(): Read the polycell support table from its registered pin
read_glwd_water(): Read the GLWD inland-water fraction on the 0.5-degree grid
glwd_water_fraction(): Derive the lake-and-river fraction of each 0.5-degree cell from GLWD
read_glaciated_areas(): Read the Natural Earth glaciated-areas ice layer
read_luh2_terrestrial(): Read the LUH2 terrestrial-area validation layer

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.

Soil balances - water

Read LPJmL hydrology outputs (drainage, evapotranspiration components, precipitation, irrigation, runoff, discharge, soil water content and the per-crop net irrigation requirement) into tidy long form, close the gridded soil water balance exposing the footprint-relevant terms (precipitation, applied irrigation, blue and green consumptive water, net irrigation requirement), and assemble the monthly climate drivers (with the HWSD soil hydraulic properties) for the soil-organic-carbon dynamics.

read_lpjml_hydrology(): Read an LPJmL hydrology variable into a tidy tibble.
read_lpjml_litterfall(): Read litterfall by land-use class from an LPJmL run.
read_lpjml_natural_cover(): Read natural-land soil cover from an LPJmL run.
read_lpjml_npp(): Read a per-PFT annual LPJmL carbon variable into a tidy tibble.
read_lpjml_regime_yield(): Read LPJmL irrigated and rainfed crop yields per cell.
read_spam_yields(): Read SPAM harvested area, production and yield by crop and technology.
build_regime_yield_ratio(): Build the irrigated:rainfed yield ratio per cell, crop and year.
split_regime_yield(): Split a cell-crop's production between its rainfed and irrigated regimes.
read_cru_climate(): Read a CRU TS 4.09 monthly climate variable into a tidy tibble.
read_soil_hydraulic(): Read gridded soil hydraulic properties from HWSD onto WHEP's grid.
build_water_balance(): Build a gridded soil water balance from LPJmL hydrology.
build_crop_water_consumption(): Build per-crop consumptive water from an LPJmL run, one row per band.
build_crop_water_use(): Build per-crop monthly applied irrigation from an LPJmL run.
get_soc_climate_drivers(): Assemble monthly SOC climate drivers from CRU climate and LPJmL hydrology.

Soil-balance coefficient tables

Structural parameter tables for the soil-organic-carbon turnover models (HSOC, RothC, ICBM, AMG, Century), the AMG humification coefficient by carbon input type, the soil carbon-to-nitrogen ratios used to convert soil-carbon change into net nitrogen mineralization or sequestration, the per-input-type humification fractions for the HSOC model, and the USDA texture-class soil hydraulic properties (with the HWSD texture-code crosswalk) feeding the ICBM moisture modifier.

soc_turnover_params: Soil organic carbon turnover parameters by model.
amg_h_by_input_type: AMG humification coefficient by carbon input type.
soil_cn_ratios: Soil carbon-to-nitrogen ratios for organic-matter balances.
residue_humification: Humification fraction by carbon input type.
soc_soil_cover_curve: Generic land-use soil-cover curve for the RothC/HSOC cover factor.
soil_hydraulic_by_texture: Soil hydraulic properties by USDA texture class.
hwsd_texture_usda: HWSD topsoil USDA texture code to texture-class crosswalk.

Nitrogen-loss coefficient tables

Coefficient datasets for the nitrogen-loss cascade (Module C): the disaggregated direct N2O emission factors by climate and irrigation, the fertiliser-type N2O modifying factors, the Meisinger and Randall topsoil denitrification matrix with its drainage-class bins, the subsoil nitrate reduction shares, the MANNER ammonia-volatilisation factor tables (plus the synthetic-fertiliser rate/rainfall factors, the organic-manure incorporation-delay factor, the inorganic nitrogen fraction by species and the gross-default technique/incorporation-delay blend), the IPCC 2006 Tier 1 direct soil N2O factors, the soil organic matter content bins, and the C:N leaching-attenuation and indirect-N2O constants.

n2o_efs_disaggregated: Disaggregated direct soil N2O emission factors by climate and irrigation.
fertiliser_n2o_modifiers: Fertiliser-type modifying factors for direct soil N2O.
meisinger_denitrification: Meisinger and Randall topsoil denitrification share matrix.
drainage_ranges: Drainage-class bins keyed on annual soil drainage.
subsoil_no3_reduction: Subsoil nitrate reduction shares by source, climate and irrigation.
manner_params: MANNER process-based ammonia-volatilisation factors.
manner_rate_factor: MANNER synthetic-fertiliser application-rate factor.
manner_rain_factor: MANNER synthetic-fertiliser rainfall factor.
manner_incorporation_factor: MANNER organic-manure incorporation-delay factor.
manure_inorganic_n: Inorganic (mineral) nitrogen fraction of excreted manure by species.
manner_default_technique_mix: Gross-default technique/incorporation-delay blend for MANNER.
n2o_efs_ipcc2006: IPCC 2006 Tier 1 direct soil N2O emission factors by climate and irrigation.
som_ranges: Soil organic matter content bins.
n_attenuation_constants: Nitrogen leaching-attenuation and indirect-N2O constants.
ipcc_2019_soil_n_ef: IPCC 2019 Tier 1 soil nitrogen emission and leaching factors.

Human-population nitrogen coefficient tables

Historical calibration series (Module C, Task C3) behind build_human_n()’s global default per-capita rate for the nitrogen a population returns to farmland (municipal solid waste, sewage sludge, human excreta): the raw national-total series and its derived per-capita rates, per inhabitant and per urban inhabitant.

human_n_reference urban_n_reference: Historical human-population nitrogen applied to agriculture.
human_kgn_cap_total_reference: Human-population nitrogen rate per inhabitant.
human_kgn_cap_reference urban_kgn_cap_reference: Human-population nitrogen rate per urban inhabitant.

Soil balances - carbon (SOC climate)

Per-model native climate rate-modifying functions for the soil-organic-carbon turnover models. Each model carries its own published temperature and moisture response (RothC/HSOC abc, ICBM re_clim, AMGv2 f(T)*f(H), Century DEFAC), not a shared scalar.

soc_rate_modifier_rothc(): Compute the RothC and HSOC annual climate rate modifier.
soc_rate_modifier_icbm(): Compute the ICBM annual climate rate modifier.
soc_rate_modifier_lpjml(): Compute the LPJmL annual decomposition response.
soc_rate_modifier_amg(): Compute the AMG (AMGv2) annual climate rate modifier.
soc_rate_modifier_century(): Compute the Century DEFAC annual climate rate modifier.

Soil balances - carbon (SOC models)

Soil-organic-carbon turnover models sharing a common annual call contract. HSOC (two pools plus inert organic matter) and RothC (five pools) step forward in time; ICBM (two pools) and AMG (active plus stable) are analytical; Century (five pools) integrates an ODE. Each pulls its rate constants from soc_turnover_params and takes an annual climate modifier. calculate_soc_dynamics is the selector that dispatches to any of them and builds the per-model native climate modifier from supplied climate drivers. Each model function returns its own wide pool columns; the selector normalises all five to one long schema (year, pool, stock_mgc_ha, soc_total, method_soc) so callers never branch on the model.

calculate_soc_dynamics(): Simulate soil organic carbon dynamics with a selectable model.
calculate_soc_hsoc(): Simulate soil organic carbon with the HSOC two-pool model.
calculate_soc_rothc(): Simulate soil organic carbon with the RothC five-pool model.
calculate_soc_icbm(): Simulate soil organic carbon with the ICBM two-pool model.
calculate_soc_lpjml(): Simulate soil organic carbon with the LPJmL two-pool soil model.
calculate_soc_amg(): Simulate soil organic carbon with the AMG model.
calculate_soc_century(): Simulate soil organic carbon with the Century five-pool model.

Soil balances - carbon (inputs)

Assemble the soil carbon-input layer the turnover models consume: crop residue, root and applied-manure carbon per cell, crop and year in megagrams of carbon per hectare, plus the carbon-weighted humification fraction from residue_humification. The grassland and natural-land carbon inputs come from the LPJmL net primary production minus harvested carbon (grassland additionally carrying grazing-excreta carbon), read per plant functional type and as litterfall by land-use class.

read_lpjml_npp(): Read a per-PFT annual LPJmL carbon variable into a tidy tibble.
read_lpjml_litterfall(): Read litterfall by land-use class from an LPJmL run.
soc_crop_group(): Assign each crop to its soil-carbon crop group.
build_soil_carbon_inputs(): Assemble soil carbon inputs per cell, crop and year.
build_grass_natural_carbon_inputs(): Build grassland and natural-land soil carbon inputs from LPJmL.
build_carbon_inputs(): Assemble the per-land-use-class soil carbon inputs.

Soil balances - nitrogen

Gridded nitrogen-balance inputs (Module C). Atmospheric nitrogen deposition from HaNi NHx and NOy, aggregated to WHEP’s 0.5-degree grid and converted to a per-hectare rate using the true latitude-dependent cell area, with an opt-in year-resolved correction of its European trend toward the EMEP MSC-W model. Urban/human-excreta nitrogen from gridded HYDE population and a per-capita rate, with neighbour-cell transport buffering for cells with no local cropland room. Ammonia-N volatilisation from the MANNER process-based model, for synthetic fertiliser and organic manure, plus a gross-default organic-manure variant that fills in the application technique and incorporation delay from a documented placeholder blend instead of requiring per-cell/per-era survey data. Gridded windspeed and soil pH drivers, the cell-polity assembly, and the polity-to-crop-to-grid spatialization of a country-level nitrogen total (Task C6 infrastructure). The gridded nitrogen INPUT assembly combines every source (BNF, residue/root recycling, manure, deposition, urban, soil organic-matter mineralization, synthetic fertiliser) into one long-format table (Task C6 final phase). The gridded soil-surface nitrogen surplus (net inputs minus harvested-nitrogen exports) is a balance term computed from that balance.

read_n_deposition(): Read a HaNi atmospheric nitrogen deposition species onto WHEP's grid.
build_n_deposition(): Build gridded atmospheric nitrogen deposition inputs.
read_emep_deposition(): Read EMEP MSC-W atmospheric nitrogen deposition onto WHEP's grid.
correct_n_deposition(): Correct HaNi's European deposition trend toward EMEP.
read_hyde_population(): Read gridded HYDE population onto WHEP's grid.
build_total_population_grid(): Build gridded total population from UN WPP and HYDE.
read_population(): Read national population on WHEP area codes.
read_wpp_population(): Read UN World Population Prospects population.
read_fbs_population(): Read FAOSTAT Food Balance Sheet population on WHEP area codes.
population_source_reach(): Report which areas a present-day-ISO3 population source can reach.
build_human_n() build_urban_n(): Build gridded human-population nitrogen inputs to agriculture.
calculate_manner_nh3(): Estimate ammonia-N volatilisation with the MANNER process-based model.
calculate_manner_nh3_default(): Estimate ammonia-N volatilisation with MANNER's gross-default technique and incorporation-delay blend.
calculate_nh3(): Estimate ammonia-N volatilisation from applied nitrogen.
calculate_soil_n2o(): Estimate direct soil N2O emissions from applied nitrogen.
calculate_n_leaching(): Estimate nitrate leaching, topsoil denitrification and indirect N2O.
calculate_indirect_n2o_nh3(): Estimate indirect N2O from volatilised ammonia.
read_lpjml_wind(): Read gridded LPJmL-forcing windspeed onto WHEP's grid.
read_soil_ph(): Read gridded soil pH onto WHEP's grid.
build_cell_polity(): Assemble WHEP's cell-polity crosswalk with true grid-cell area.
spatialize_country_n_to_crops(): Spatialize a polity-level nitrogen total to crops and grid cells.
build_ag_land_support(): Build the gridded agricultural land support.
build_n_inputs(): Assemble gridded nitrogen inputs from every WHEP N-input source.
build_n_loss_drivers(): Build the IPCC 2019 wet/dry drivers of the nitrogen loss cascade.
build_nitrogen_balance(): Build the full nitrogen balance: inputs, outputs, losses and NUE.
calculate_n_surplus(): Calculate the gridded soil-surface nitrogen surplus.

SJOS - nitrogen

Safe and Just Operating Space for nitrogen. Reader for the Schulte-Uebbing et al. (2022) gridded critical-nitrogen layers (critical surplus, critical input, exceedance, the medium-specific critical losses and the binding-threshold map) that the boundary-exceedance modules compare the WHEP nitrogen surplus and process-based losses against. The surplus-mode critical-boundary exceedance of the nitrogen surplus (see calculate_n_surplus() under the nitrogen balance), decomposed per crop into the parts within and above the boundary. The pathway-mode boundary instead routes each process-based nitrogen loss to its medium-specific critical load (ammonia to air, nitrate to the tighter of groundwater and surface water), decomposing each medium and naming the binding boundary per crop. The nourishment (“just”) axis supplies per-capita protein and dietary energy, from the commodity-balance food element times the biomass nutrition coefficients divided by population, or from FAOSTAT Food Balance Sheet per-capita supply, and normalizes that supply onto a piecewise adequacy score classified Under, Adequate or Over. The boundary and nourishment sides are then crossed per crop into the 2-way safe-and-just classification, and each crop’s exceedance, within-boundary or total surplus nitrogen becomes the intensity of an embodied-nitrogen trade footprint extension.

read_critical_n(): Read a Schulte-Uebbing gridded critical-nitrogen layer.
calculate_critical_n(): Calculate critical-nitrogen allowances with the Schulte-Uebbing method.
build_grassland_intensity_classes(): Classify grassland cells as intensive or extensive through time
build_critical_n_binding(): Derive the binding critical-nitrogen threshold per cell.
build_n_boundary_exceedance(): Build source-exact gridded critical-nitrogen exceedance.
build_n_boundary_country(): Summarise gridded nitrogen exceedance to a country-year table.
build_n_pathway_exceedance(): Build the pathway-mode critical-nitrogen boundary exceedance.
build_food_supply(): Build per-capita food supply for the nourishment axis.
build_protein_requirement(): Build the population protein requirement.
read_habitual_cv(): Read FAOSTAT's coefficient of variation of habitual caloric consumption.
build_intake_dispersion(): Build the within-country intake dispersion.
build_loss_wedge(): Build the supply-to-intake loss wedge.
build_protein_quality(): Build the protein-quality correction for the nourishment band.
build_protein_score(): Score a diet's protein against the age-weighted requirement pattern.
build_nourishment_band(): Build the SJOS-N nourishment band.
normalize_nourishment(): Normalize and classify per-capita nourishment.
calculate_food_gini(): Between-country population-weighted Gini of per-capita food supply.
disaggregate_ussr(): Split the pre-1992 aggregate USSR supply into successor states.
build_n_boundary_percapita(): Build the per-capita nitrogen-boundary versus nourishment scatter.
build_n_percapita(): Build country per-capita anthropogenic reactive nitrogen.
classify_sjos_n(): Classify crops into the 2-way SJOS-N safe-and-just space.
build_n_exceedance_extension(): Build the embodied-nitrogen footprint extension.
build_sjos_n_footprint(): Build the embodied-nitrogen trade footprint.
build_sjos_nitrogen(): Assemble the end-to-end SJOS-N output tables.

SJOS - nitrogen coefficient tables

Planetary reactive-nitrogen boundary parameters, the nourishment protein/energy thresholds (with the waste-inequality factor and class cutoffs), and the boundary/nourishment classification levels with their plotting colours, feeding the SJOS-N per-capita boundary axis and the 2-way safe-and-just classification.

n_boundary_params: Planetary reactive-nitrogen boundary parameters.
nourishment_thresholds: Nourishment protein and energy thresholds.
sjos_levels: Safe-and-just nitrogen classification levels and colours.
nourish_levels: Nourishment classification levels and colours.

Soil balances - carbon (historical balance)

Reconstruct per-cell soil-organic-carbon stock trajectories: equilibrium initialisation under the earliest land-use carbon inputs, a forward march on yearly per-cell per-class land-use areas with a carbon-conserving land-use-change transfer, and the derived soil-organic-nitrogen change via the asymmetric soil carbon-to-nitrogen ratios. The LPJmL soil-cover readers supply its optional cropland and natural-land cover inputs, and the HWSD topsoil organic-carbon reader is its observational benchmark.

build_carbon_balance(): Build the historical gridded soil-organic-carbon balance.
read_luh2_landuse(): Read gridded yearly LUH2 land-use-class fractions and areas.
read_lpjml_crop_cover(): Read monthly cropland soil cover from an LPJmL run's crop calendar.
read_lpjml_natural_cover(): Read natural-land soil cover from an LPJmL run.
read_hwsd_topsoil_soc(): Read observed topsoil organic carbon from HWSD onto WHEP's grid.

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_bedding_supply(): Build the bedding straw supply reaching the managed manure chain.

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 – National Spain
create_grafs_plot_df(): Create GRAFS plot dataset.
plot_input_output(): Plot national nitrogen inputs, production, and surplus for a land system.
plot_input_output_livestock(): Plot national nitrogen inputs, production, and surplus for livestock.
plot_input_output_system(): Plot national nitrogen inputs and uses for the full agro-food system.

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_registry(): Read a registry of pinned input files
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
polity_label_aliases: Source label to polity aliases
polity_containment: Polity containment edges
polity_label_item_corrections: Source label corrections scoped to one item
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
polity_anchor_drift(): Find back-cast rows whose polity label and growth proxy describe different territories
polity_bucket_coverage(): Report reporting buckets that sum more than one territory
polity_coverage_gaps(): Find rows attributed to a polity not live in the row's year
polity_mapping_provenance(): Report which authority a row's territorial identity rests on
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
folded_reporting_areas(): List the reporting areas whose data is folded into another area code
row_promotion_status(): Report which Rest-of-World members report under their own territory
whep_polity_columns: Polity columns on WHEP outputs
resolve_polity_label(): Resolve a source's country label to a polity
resolve_polity_lineage(): Resolve a national row onto the polity its grid support carries that year
polity_identity_conventions(): Which territorial identity WHEP's year-less objects carry

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

Administrative-statistics vocabularies

Source crop classes and livestock classes of the subnational statistics readers mapped onto WHEP items and species groups, with the mapping kind and, for livestock aggregates, the group set whose sum they constrain.

admin_source_vocabularies: Source-item vocabularies for the subnational admin statistics
admin_items_nass: USDA NASS crop series and their WHEP items
admin_items_eurostat: Eurostat crop classes and their WHEP items
admin_items_sidra: IBGE SIDRA crop classes and their WHEP items
admin_items_jrc: JRC subnational crop classes and their WHEP items
admin_species_nass: USDA NASS livestock series and their WHEP species groups
admin_species_eurostat: Eurostat livestock classes and their WHEP species groups
admin_species_sidra: IBGE SIDRA herd types and their WHEP species groups

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
coello_synthetic_n: Coello (2025) crop-specific synthetic nitrogen application rates
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
regime_yield_crop_mapping: Crop sources for the irrigated:rainfed regime yield ratio
smil_2001_synthetic_n_global: Smil (2001) global synthetic nitrogen production, 1913-2000

Data sources

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

expand_trade_sources(): Trade data sources

Nitrogen typologies Spain

Functions to generate data for N inputs, outputs, production, destinies, typologies, etc.

create_typologies_of_josette(): Typologies of Josette
create_typologies_grafs_spain(): Typologies of Julia
create_alfredos_typologies(): Alfredo's typology classification
create_typologies_whep(): Create WHEP typologies for Spain
create_grafs_plot_df(): Create GRAFS plot dataset.
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 – National Spain
run_typology_sensitivity(): Run one-at-a-time sensitivity analysis on typology thresholds.
plot_typology_indicators_panel(): Plot four N indicators as time series per typology
plot_typology_periods_panel(): Plot four N indicators as period comparisons per typology

Data-frame utilities

Declare a table’s schema once, as serializable data, then build it, reach it or prove it. empty_table_from_schema() turns the schema into the typed zero-row table it describes; ensure_columns() coerces a table onto such a prototype; check_table_schema() reports every violation of a declarative schema without touching the table, and assert_table_schema() is the build-time gate over the same schema.

empty_table_from_schema(): Build a typed zero-row table from a declarative schema.
ensure_columns(): Complete columns from a typed prototype.
check_table_schema(): Check a table against a declarative schema.
assert_table_schema(): Assert that a table conforms to a declarative schema.

Absent-input guards

Assert that an input arrived, never that the totals it feeds reconcile. Zero satisfies a sum, so a consistency identity, a conservation check and a row count are all passed by an absence. check_inputs_supplied() refuses a column that is missing, or present and identically zero or missing; check_labels_supplied() refuses a value vocabulary that no longer carries the labels a filter selects on, and names what it carries instead; stamp_inputs_supplied() writes the provenance label the first one reads, which no arithmetic downstream can forge.

check_inputs_supplied(): Refuse an input that was never supplied
check_labels_supplied(): Refuse a value vocabulary that no longer contains the labels a filter needs
stamp_inputs_supplied(): Record which optional inputs a build consumed

Gap filling functions

Functions to fill gaps (NA values) in time-dependent variables using different methods. interp_vec() is the vector-level interpolation primitive behind fill_linear(log_space = TRUE), for callers working with plain vectors.

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
interp_vec(): Interpolate anchor points at arbitrary output positions.

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, and LMDI decomposition of territorial nitrogen surplus and losses (cropland, semi-natural, livestock manure, urban), specialization and crop-livestock connectivity covariance, and destiny-mix shifts.

calculate_lmdi(): Calculate LMDI decomposition.
decompose_weighted_ratio(): Decompose a weighted aggregate ratio.
decompose_cropland_surplus(): Decompose cropland N surplus into size, intensity, and inefficiency drivers
decompose_semi_natural_surplus(): Decompose semi-natural agroecosystem N surplus into size, intensity, and inefficiency drivers
decompose_manure_losses(): Decompose livestock manure management losses into herd, feed, excretion, and management-loss drivers
decompose_urban_losses(): Decompose urban nitrogen losses into population, per-capita, and recycling drivers
decompose_terr_losses(): Decompose total territorial N losses into compartments and mechanisms
decompose_terr_losses_periods(): Decompose territorial N losses by reference period (chained)
decompose_specialization_cov(): Decompose specialization from diversification via the Olley-Pakes allocation covariance
decompose_crop_livestock_conn(): Compute the crop-livestock connectivity index per province
decompose_destiny_mix(): Compute the national cropland destiny mix over time
plot_loss_decomp(): Plot cumulative drivers of the change in territorial N losses
plot_loss_decomp_periods(): Plot period-based drivers of the change in territorial N losses
plot_loss_decomp_periods_panel(): Plot period-based drivers of territorial N losses, as one combined panel plot
plot_loss_decomp_rolling(): Plot rolling-mean year-on-year drivers of the change in territorial N losses
plot_loss_decomp_rolling_panel(): Plot rolling-mean year-on-year drivers of territorial N losses, as one combined panel plot
plot_loss_decomp_yearly(): Plot year-on-year (non-cumulative) drivers of the change in territorial N losses
plot_compart_factor(): Plot each compartment's own factor breakdown
plot_compart_factor_periods(): Plot each compartment's own factor breakdown by period, as one combined panel plot
plot_compart_factor_roll(): Plot each compartment's own factor breakdown, rolling mean
plot_compart_factor_roll_panel(): Plot each compartment's own factor breakdown, rolling mean, as one combined panel plot
plot_compart_factor_yearly(): Plot each compartment's own factor breakdown, year-on-year (non-cumulative)
plot_specialization_cov(): Plot the specialization-vs-diversification allocation covariance
plot_crop_livestock_conn(): Plot the crop-livestock connectivity index
plot_destiny_mix(): Plot the cropland destiny mix over time

Circularity index

Finn’s cycling index for the nitrogen flow network.

create_finn_indicator(): Calculate Finn Cycling Index for each province and year
plot_finn_circularity(): Plot Finn Cycling Index evolution and period comparison

National trade validation

Compare provincial-model trade flows against raw FAOSTAT bilateral trade totals.

compute_trade_flows_raw(): Compute national trade flows: model vs. raw historical FAO series
validate_national_trade(): Validate national net trade balance
validate_national_trade_raw(): Validate national net trade against raw historical FAO series
plot_national_trade_flows_raw(): Plot national trade flows: model vs. raw historical FAO series
plot_national_trade_validation(): Plot national net trade validation
europe_fao_spain_trade: Spain's historical export and import series, 1849-1960

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.
get_arable_permanent_land(): Physical arable and permanent-crop land base (fallow-inclusive).
build_fao_arable_fallow_extension(): Build a per-crop physical land extension with FAO fallow-inclusive arable land.
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), completeness against an expected key lattice, 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.
check_keys_complete(): Refuse an aggregate built over an incomplete key lattice
key_lattice_gaps(): Report the expected keys that no row supplies
check_fodder_land_share(): Check how much arable land the fallow split attributes to fodder crops.
check_arable_composition(): Check where the arable-land extension changes composition mid-panel.
check_parquet_integrity(): Check the structural integrity of a Parquet file.
assert_parquet_integrity(): Assert that a Parquet file is structurally sound.
write_parquet_checked(): Write a Parquet file and verify it before returning.
write_table_checked(): Write a table to disk safely and verifiably.

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.

Row-level evidence

Record what each row of a result rests on — the producer, its source version and the row’s documented evidence fields — as a keyed sidecar table that survives the joins an attribute would not. row_evidence() produces it, row_evidence_schema() is its contract, combine_row_evidence() merges producers without letting one overwrite another, evidence_conflicts() reports where they disagree, and evidence_for() carries evidence through a join.

row_evidence(): Produce row-level evidence for a table.
row_evidence_schema(): The declarative schema of a row-evidence table.
combine_row_evidence(): Combine row evidence from several producers.
evidence_conflicts(): Report where row evidence disagrees.
evidence_for(): Carry row evidence through a join or a filter.

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.
build_gridded_livestock_emissions(): Build per-cell livestock greenhouse-gas emissions.
build_cell_climate_zone(): Build the per-cell IPCC climate zone from CRU mean annual temperature.
build_cell_moisture_regime(): Build the IPCC 2019 wet/dry moisture regime of WHEP's crop land.
livestock_emissions_to_kt(): Convert IPCC per-animal livestock emissions from kilograms to kilotonnes.
calculate_enteric_ch4(): Calculate enteric methane emissions.
calculate_manure_emissions(): Calculate manure emissions (CH4 + N2O).
manure_engine_options: Manure engine options
estimate_n_excretion(): Estimate livestock nitrogen, carbon and volatile-solids excretion.
split_manure_management(): Split livestock excretion across manure-management systems.
add_manure_bedding(): Add bedding carbon and nitrogen to the housed manure streams.
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: Enteric methane conversion factors (IPCC defaults, not GLEAM).
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_enteric_ef_tier1: IPCC Tier 1 enteric emission factors, as published.
ipcc_manure_ef3: IPCC direct manure N2O emission factors (EF3), by edition.
ipcc_2019_ym: IPCC Ym values.
ipcc_2019_bo: IPCC 2019 Bo values (Table 10.16A).
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.
climate_mcf_ipcc: As-published MCF alternatives to climate_mcf.
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