Skip to contents

Introduction

The gleam R package implements the core computational engine of the Global Livestock Environmental Assessment Model (GLEAM), developed by the Food and Agriculture Organization of the United Nations (FAO). It provides a modular, transparent, and reproducible framework for quantifying greenhouse gas (GHG) emissions from livestock supply chains using a Life Cycle Assessment (LCA) approach based on the IPCC Tier 2 methodology.

The package covers seven livestock species: cattle (CTL), buffalo (BFL), camels (CML), sheep (SHP), goats (GTS), pigs (PGS), and chickens (CHK). It estimates emissions from enteric fermentation, manure management, and feed production, and allocates them to livestock commodities (meat, milk, fibre, and work) using a biophysical energy-based allocation framework consistent with ISO 14044, LEAP guidelines and the IDF Global Carbon Footprint Standard.

The package is part of the broader GLEAM ecosystem, which includes interactive web applications, dashboards, data infrastructure, and capacity-building tools. This vignette provides an overview of the R package specifically; a brief description of the wider ecosystem is given in The GLEAM Ecosystem.

Species currently covered in GLEAM

Species currently covered in GLEAM

Installation

Install the package from the FAO GitHub repository:

# Install devtools if not already available
install.packages("devtools")

# Install the gleam package from GitHub
devtools::install_git("https://github.com/un-fao/GLEAM.git")

The package depends on data.table for all data manipulation. All input and output datasets are data.table objects throughout the pipeline.

Key Concepts

Species codes

Every function in the package identifies livestock species using standardized short codes that appear as species_short in the data:

Code Species
CTL Cattle
BFL Buffalo
SHP Sheep
GTS Goats
CML Camels
PGS Pigs
CHK Chickens

Sex–age cohort codes

Animals within each herd are classified into demographic or non-demographic cohorts, depending on how their life cycle and production process are represented.

Demographic Cohorts

Demographic cohorts classify animals according to their sex, age class, and reproductive development. Animals progress through successive life stages, from juvenile to sub-adult and adult, with transitions determined by biological milestones such as weaning, first parturition, or first breeding.

This classification allows the model to represent herd population dynamics, including growth, maturation, reproduction, and changes in herd composition over time.

Six demographic cohorts are defined:

Code Sex Age class Life stage definition
FJ Female Juvenile From birth to weaning
FS Female Sub-adult From weaning to first parturition
FA Female Adult From first parturition onwards
MJ Male Juvenile From birth to weaning
MS Male Sub-adult From weaning to first breeding
MA Male Adult From first breeding onwards

These cohort codes appear in the cohort_short column of all cohort-level data tables and are required by nearly every function in the package.

Non-Demographic Cohorts

Non-demographic cohorts represent animals managed through defined production cycles without explicitly tracking their age or reproductive development.

Animals are classified by sex and production phase.

Two non-demographic cohort codes are defined:

Code Sex Age class Definition
FN Female Non-demographic Females assigned to a defined production cycle
MN Male Non-demographic Males assigned to a defined production cycle

Each non-demographic cohort must include production phase 1 and may include an optional phase 2, as specified by nondemo_productive_phase_id.

Explore the practical use here.

Herd structure

Herd structure describes the distribution of the total herd population across demographic and non-demographic cohorts.

If the herd structure is not provided by the user, the GLEAM herd module estimates the population of each cohort based on herd-level parameters and the total herd population.

Assessment period

The assessment period (simulation_duration) defines the time window over which emissions and production are computed. It is specified in days (typically 365 for a standard annual assessment). Per-head, per-day intermediate values are scaled to cohort totals over the assessment period in the aggregation step. The assessment period can also be used to represent different seasons with distinct variations in input data (e.g., feed basket composition or nutritional quality).

Quick Start

The following example runs the full pipeline using the shipped mixed-herd inputs. Both herd modules are enabled: the demographic module simulates the breeding population and calculates juvenile diversion into the FN/MN production phases. The non-demographic module then simulates those phases. The combined average stock and offtake are rescaled to the supplied herd_size_total.

This example includes all 15 herds. Herd 14 has FN laying hens alongside a demographic component; herd 15 has FN/MN meat chickens alongside a demographic component. The non-demographic-only example below represents these same herd IDs as separate production operations without a breeding population.

library(gleam)
library(data.table)

# ---- Load sample data from inst/extdata ----
path <- system.file("extdata/run_gleam_examples", package = "gleam")

cohort_dt      <- fread(file.path(path, "master_chrt_lvl_no_structure_mixed_data.csv"))
herd_dt        <- fread(file.path(path, "master_hrd_lvl_mixed_data.csv"))
rations_dt     <- fread(file.path(path, "feed_rations_share_chrt.csv"))
feed_params_dt <- fread(file.path(path, "feed_quality.csv"))
feed_emis_dt   <- fread(file.path(path, "feed_emission_factors.csv"))
mms_frac_dt    <- fread(file.path(path, "manure_management_system_fraction.csv"))
mms_fact_dt    <- fread(file.path(path, "manure_management_system_factors.csv"))

# ---- Run the full GLEAM pipeline ----
results <- run_gleam(
  has_herd_structure                = FALSE,
  run_demographic                   = TRUE,
  run_nondemographic                = TRUE,
  cohort_level_data                 = cohort_dt,
  herd_level_data                   = herd_dt,
  feed_rations                      = rations_dt,
  feed_params                       = feed_params_dt,
  feed_emissions                    = feed_emis_dt,
  manure_management_system_fraction = mms_frac_dt,
  manure_management_system_factors  = mms_fact_dt,
  simulation_duration               = 365,
  global_warming_potential_set      = "AR6"
)

# ---- Inspect results ----
print(results$cohort_level_results)
print(results$herd_level_results)
print(results$allocation_long)
print(results$aggregation_results$results_emissions)

Choosing a workflow

Choose one matching cohort and herd file pair. These are alternative workflows; do not append the non-demographic-only files to the mixed files.

Workflow Cohort file Herd file
Mixed simulation master_chrt_lvl_no_structure_mixed_data.csv master_hrd_lvl_mixed_data.csv
Non-demographic-only simulation master_chrt_lvl_no_structure_nondemo_data.csv master_hrd_lvl_nondemo_data.csv
Supplied herd structure master_chrt_lvl_structure_data.csv master_hrd_lvl_structure_data.csv

Use run_gleam_examples/ for the full pipeline. The separate run_modules_examples/ folder contains subsets of the mixed example with only the inputs needed by each module. Downstream inputs include values calculated by the preceding pipeline stages. Use each module’s matching input files when running it separately.

Non-demographic-only simulation

This example contains only FN/MN phases for herds 14 and 15. Annual entrants are supplied directly in the herd file; the demographic module is disabled. The herd file omits demographic, reproductive, milk, fibre and draught-work inputs that are unused by these chicken production phases. The dedicated ration-share and manure-fraction files contain only the FN/MN phases in this example. The manure-system factors file contains only herds 14 and 15. Load these files directly; feed quality and feed emission factors are shared with the other workflows:

cohort_nd <- fread(file.path(
  path, "master_chrt_lvl_no_structure_nondemo_data.csv"
))
herd_nd <- fread(file.path(path, "master_hrd_lvl_nondemo_data.csv"))
rations_nd <- fread(file.path(path, "feed_rations_share_chrt_nondemo.csv"))
mms_frac_nd <- fread(file.path(path, "manure_management_system_fraction_nondemo.csv"))
mms_fact_nd <- fread(file.path(path, "manure_management_system_factors_nondemo.csv"))

results_nd <- run_gleam(
  has_herd_structure = FALSE,
  run_demographic = FALSE,
  run_nondemographic = TRUE,
  cohort_level_data = cohort_nd,
  herd_level_data = herd_nd,
  feed_rations = rations_nd,
  feed_params = feed_params_dt,
  feed_emissions = feed_emis_dt,
  manure_management_system_fraction = mms_frac_nd,
  manure_management_system_factors = mms_fact_nd,
  simulation_duration = 365,
  global_warming_potential_set = "AR6"
)

The supplied non-demographic-only herd file has no herd_size_total column, so average stock and offtake remain unscaled. Annual entrants are a flow in heads/year, not average animals present. Add herd_size_total to rescale both stock and offtake to a herd-size target.

Supplied herd structure

For this workflow, load the supplied-structure file pair and set has_herd_structure = TRUE. The cohort table already contains cohort_stock_size and offtake_heads_assessment. The pipeline skips both herd simulations and starts with weights. The run_demographic and run_nondemographic switches have no effect in this mode; set both to FALSE to make the example’s intent explicit. See ?run_gleam for the complete call.

Pipeline Overview

The run_gleam() function orchestrates the full modelling pipeline by calling individual modules in sequence. Each module can also be run independently for custom workflows. The pipeline consists of the following steps:

# Module Function Key outputs
1 Herd simulation (optional) run_all_herd_module() Demographic/Non demographic cohort sizes, offtake numbers, herd growth rate
2 Cohort weights run_weights_module() Initial, average, and final live weights; daily weight gain
3 Ration nutritional content run_ration_quality_module() Diet gross energy, digestibility, nitrogen, ash
4 Metabolic energy requirements and ration intake run_metabolic_energy_req_module() Energy partitions (maintenance, growth, lactation, etc.); dry matter intake
5 Enteric emissions run_emissions_enteric_module() Enteric CH₄ emissions
6 Nitrogen balance run_nitrogen_balance_module() Nitrogen intake, retention, and excretion
7 Manure emissions run_emissions_manure_module() CH₄ and N₂O from manure management
8 Feed production emissions run_emissions_ration_module() GHG from feed production
9 Production outputs run_production_module() Production of milk, meat, and fibre
10 Emission allocation run_allocation_module() Biophysical allocation shares and allocated emissions per commodity
11 Aggregation and reporting run_aggregation_module() Herd-level aggregation of emissions and conversion to CO₂eq

Each module validates its inputs before execution, checking for required columns, valid value ranges, and consistency across data tables. This ensures that errors are caught early and do not propagate silently through the pipeline. A three-tier structure is implemented consistently throughout. Every public function calls its validator before any computation. Constants are centralized in gleam_constants.R.

run_*_module()          # orchestrator: validates, calls core functions, assembles output
    └─ core_model_*.R     # scientific functions: one exported function per quantity
         └─ validate_*.R  # input guards: called first in every function
Overview of the GLEAM pipeline wih the different modules:
Overview of the GLEAM pipeline with the different modules

Running individual modules

For custom workflows, research applications, or step-by-step debugging, each module can be called independently.

For example, to compute only metabolic energy requirements:

# Load metabolic energy requirements inputs (cohort and herd-level)
metabolic_energy_req_chrt_dt <- data.table::fread(system.file(
  "extdata/run_modules_examples/metabolic_energy_req_input_chrt_data.csv",
  package = "gleam"
))
metabolic_energy_req_hrd_dt <- data.table::fread(system.file(
  "extdata/run_modules_examples/metabolic_energy_req_input_hrd_data.csv",
  package = "gleam"
))

# Run metabolic energy requirement and rations calculations
results <- run_metabolic_energy_req_module(
  cohort_level_data = metabolic_energy_req_chrt_dt,
  herd_level_data = metabolic_energy_req_hrd_dt
)

An overview of all modules, their inputs and outputs is provided in the Module Overview vignette.

Running individual scientific functions

At the lowest level, all core computations are exposed as individual scientific functions. These can be called directly for research or testing purposes. For example, to compute maintenance energy requirements for a single cohort:

e_maint <- calc_metabolic_energy_req_maintenance(
  species_short              = "CTL",
  cohort_short               = "FA",
  live_weight_cohort_average = 450,
  lactating_females_fraction = 0.7,
  offtake_rate               = 0.15,
  age_first_parturition      = 1095
)

Input Data

The run_gleam() pipeline requires several input data tables. Sample files for all tables are provided in inst/extdata/run_gleam_examples/ and can be loaded with data.table::fread() as shown in the Quick Start example.

cohort_level_data

A data.table with one row per herd and demographic cohort, or per herd, non-demographic cohort and productive phase.

Column Type Description
herd_id Character Unique herd identifier, repeated for each cohort
species_short Character Livestock species code (see species codes)
cohort_short Character Sex–age cohort code (see cohort codes)
cohort_duration_days Numeric Amount of time that each animal spends in a specific cohort and production phase (days). For CHK, suggested value for FJ and MJ cohorts: 3 days. Not required for FN and MN when phase durations are supplied in the herd table; the code fills it from the herd values, which override any cohort values.
offtake_rate Numeric Annual proportion of animals removed from the herd per cohort (fraction)
death_rate Numeric Death fraction: annual for demographic cohorts, per productive phase for FN/MN; required when has_herd_structure = FALSE
nondemo_productive_phase_id Numeric Phase 1 or 2 for FN/MN; NA for demographic cohorts
is_egg_producing Logical Food-egg production flag for CHK FA or FN phase 2
low_activity_fraction Numeric Proportion of the assessment period with low-intensity movement (fraction)
high_activity_fraction Numeric Proportion of the assessment period with sustained locomotion (fraction)

Additional columns are required when has_herd_structure = TRUE (cohort_stock_size, offtake_heads_assessment). See ?run_gleam for the complete column specification.

herd_level_data

A data.table with one row per herd.

Key columns include live weights (adult female/male, birth, weaning, slaughter), reproductive parameters (parturition rate, litter size, pregnancy duration), production parameters (milk yield, milk composition, fibre yield), draught work parameters, and slaughter/dressing parameters. See ?run_gleam for the full list.

feed_rations

A data.table with one row per herd × cohort × feed component.

Column Type Description
herd_id Character Unique herd identifier
cohort_short Character Cohort code
feed_id Character Unique feed component identifier
feed_ration_fraction Numeric Share of this feed in the total ration dry matter (fraction); must sum to 1 per herd × cohort

feed_params

A data.table with one row per feed component, providing nutritional parameters: gross energy, digestible energy (ruminants and pigs), metabolizable energy (ruminants, pigs, chickens), nitrogen content, urinary energy fraction, and ash content. Joined to feed_rations by feed_id.

feed_emissions

A data.table with one row per feed component, providing emission factors (g gas/kg DM) for CO₂ from fertilizer manufacture, pesticide manufacture, on-field crop activities, and land-use change (peat and non-peat); N₂O from fertilizer use, manure applied to soil, and crop residues; and CH₄ from rice cultivation.

manure_management_system_fraction

A data.table with one row per herd × cohort × manure management system (MMS), specifying the fraction of total manure handled by each system. The names mms_pasture and mms_burned are reserved for manure deposited on pasture and burned for fuel, respectively. Fractions must sum to 1 per herd × cohort.

manure_management_system_factors

A data.table with one row per MMS, providing emission factors and parameters: methane conversion factor (MCF), maximum CH₄ producing capacity (B₀), direct and indirect N₂O emission factors (EF3, EF4, EF5), and nitrogen volatilisation and leaching fractions.

Output Structure

run_gleam() returns a named list with four elements:

  • cohort_level_results: A cohort-level data.table containing all original input columns plus every variable computed across the pipeline, expressed as per-head, per-day quantities. Calculated variables include cohort stock sizes and offtake numbers, live weights, ration quality metrics, energy requirements, dry matter intake, enteric CH₄, nitrogen balance, volatile solids, manure CH₄ and N₂O (by MMS group), feed production emission factors, production outputs (milk, meat, fibre), and allocation energies.

  • herd_level_results: A herd-level data.table containing the herd-level input parameters plus, when has_herd_structure = FALSE, the annualized herd growth rate (growth_rate_herd).

  • allocation_long: A herd-level data.table in long format with one row per herd × commodity × emission source, containing the biophysical allocation shares used to distribute herd-level emissions to commodities (Milk, Meat, Fibre, Work, Eggs, None).

  • aggregation_results: A named list with four data.table elements:

    • results_emissions: herd-level GHG emissions scaled to the assessment period and expressed in kg gas and kg CO₂eq;
    • results_feed: herd-level feed intake;
    • results_production: herd-level production of milk, meat, and fibre;
    • results_nitrogen: herd-level nitrogen balance.

Key output units

Category Units
Energy requirements MJ/head/day
Dry matter intake kg DM/head/day
Nitrogen balance kg N/head/day
Enteric CH₄ kg CH₄/head/day
Manure emissions kg gas/head/day
Feed emission factors g gas/kg DM
Production kg/cohort/assessment period
Aggregated emissions kg gas/herd/assessment period and kg CO₂eq

Methodological Background

LCA approach and system boundary

Livestock agrifood systems and the GLEAM system boundary

Livestock agrifood systems and the GLEAM system boundary

GLEAM applies a cradle-to-processing-point Life Cycle Assessment (LCA) framework. The system boundary encompasses:

  • Upstream processes: feed crop and pasture production, fertilizer and input production, and feed processing.
  • On-farm processes: animal husbandry, enteric fermentation, manure management, and on-farm energy use.
  • Downstream processes: primary processing, storage, and transport of livestock products.

Note: The current R package implements the on-farm emission modules (metabolic energy requirements, enteric emissions, manure management emissions, production outputs, and biophysical allocation). Feed production emissions are computed using emission factors per feed component. Downstream processing modules are under development.

IPCC Tier 2 energy partitioning

The package implements the IPCC Tier 2 methodology for estimating GHG emissions from livestock. Energy requirements are partitioned into maintenance, activity, growth, lactation, pregnancy, work, and fibre production components using species-specific equations from the IPCC 2006 Guidelines and the 2019 Refinement. Total daily energy requirements are then used to estimate dry matter intake, volatile solids excretion, and enteric methane emissions.

Energy requirements for CTL, BFL, SHP, and GTS are expressed as net energy (NE); for CML, PGS, and CHK they are expressed as metabolizable energy (ME).

Biophysical allocation

Environmental burdens are allocated to livestock co-products (meat, milk, fibre, and work) using a biophysical approach based on the energy required to produce each commodity. This follows the IDF Global Carbon Footprint Standard (IDF, 2022) and is consistent with ISO 14044:2006 (Section 4.3.4.2, Step 2).

Emissions from manure deposited on pasture and manure burned as fuel are assigned to the residual category “Other” (not allocated to any commodity), in line with LCA cut-off rules and to avoid double-counting with upstream feed production.

Global warming potentials

CO₂-equivalent emissions are computed using GWP-100 factors from the selected IPCC Assessment Report. The global_warming_potential_set argument accepts:

Value Report CH₄ N₂O
"AR6" IPCC 6th Assessment (2021) 27 273
"AR5_excluding_carbon_feedback" IPCC 5th Assessment, excl. feedbacks (2013) 28 265
"AR5_including_carbon_feedback" IPCC 5th Assessment, incl. feedbacks (2013) 34 298
"AR4" IPCC 4th Assessment (2007) 25 298

Further Resources

Package documentation

  • Function reference: Full documentation for all exported functions is available via ?function_name (e.g., ?run_gleam) or the online reference manual.
  • Sample data: Example datasets for all input tables are in inst/extdata/run_gleam_examples/.

Methodological references

GLEAM publications

  • Gerber, P.J., Steinfeld, H., Henderson, B., Mottet, A., Opio, C., Dijkman, J., Falcucci, A., & Tempio, G. (2013).
    Tackling climate change through livestock: A global assessment of emissions and mitigation opportunities.
    FAO, Rome.
    https://www.fao.org/4/i3437e/i3437e04.pdf

  • FAO. (2023).
    Pathways towards lower emissions — A global assessment of the greenhouse gas emissions and mitigation options from livestock agrifood systems.
    FAO, Rome.
    DOI: https://doi.org/10.4060/cc9029en

  • Wisser, D., Grogan, D.S., Lanzoni, L., Tempio, G., Cinardi, G., Prusevich, A., & Glidden, S. (2024).
    Water Use in Livestock Agri-Food Systems and Its Contribution to Local Water Scarcity: A Spatially Distributed Global Analysis. Water, 16(12), 1681.
    https://doi.org/10.3390/w16121681

Resource partner

The development of the GLEAM ecosystem was supported by the German Federal Ministry of Food, Agriculture, and Regional Identity BMELH

bmleh logo

bmleh logo