# About gleam modules

# 1 Introduction

This vignette provides a high-level overview of all GLEAM modules, the sequence of their functions, and their input and output datasets. An overview of the full pipeline is provided in the GLEAM Overview. Full documentation for each module is available via the module reference pages linked in each section below.

# 2 Herd Simulation Module

See `run_demographic_herd_module()` for full documentation.

This module takes herd- and cohort-level demographic inputs and estimates a steady-state sex–age herd structure compatible with downstream calculations in GLEAM. In addition to cohort population sizes, it derives population growth rates and offtake numbers. The steady state is defined as a constant sex–age cohort structure over time, with population size potentially growing or declining at a constant rate.

The module operates under a steady-state assumption: demographic parameters are constant over time, so the population converges to a stable cohort composition and a constant annual growth rate. Once this regime is reached, the model computes cohort population sizes (start/end/average), cohort shares, and offtake totals.

A key feature of this implementation is that it applies demography at a daily resolution. Annual mortality and offtake inputs are converted into daily hazards and daily transition probabilities under competing risks (death vs. offtake vs. survival). Conceptually, this corresponds to the steady-state demographic approach implemented in Dynmod STEADY1 (Lesnoff, 2013), adapted here to a daily time-step formulation.

The population is divided by sex (female/male) and age class (juvenile/subadult/adult), represented by six cohorts: `FJ`, `FS`, `FA` (female juvenile, subadult, adult) and `MJ`, `MS`, `MA` (male juvenile, subadult, adult).

Overview of the GLEAM demographic herd module with functions, input and output:

# 3 Weights Module

See `run_weights_module()` for full documentation.

Computes cohort-level live weight metrics by combining cohort-level inputs with herd-level biological parameters. The module appends cohort weights (initial, potential final, slaughter), then derives average and final live weights accounting for offtake, and finally computes average daily live weight gain over each cohort stage.

Overview of the GLEAM weights module with functions, input and output:

The calculation pipeline consists of the following steps:

1. Cohort-stage weight assignment — herd-level biological parameters are matched to each cohort row by `herd_id` and weights are assigned per life stage using `calc_cohort_weights()`.
2. Average and final live weights (accounting for offtake) — computed using `calc_avg_weights()`.
3. Average daily live weight gain — computed using `calc_daily_weight_gain()`.

# 4 Ration Nutritional Content Module

See `run_ration_quality_module()` for full documentation.

Computes cohort-level diet nutritional metrics — gross and metabolizable energy content, digestibility, nitrogen content, urinary energy losses, and ash content — from cohort-level feed ration composition shares and feed component nutrient parameters.

Overview of the GLEAM herd module with functions, input and output:

The module joins ration shares with feed parameters by `feed_id`, uses `species_short` for species-specific lookups, and computes ration-weighted nutritional metrics by cohort through the following steps:

1. Species-specific digestibility fractions are computed from energy parameters using `calc_feed_digestibility_fraction()`.
2. Contributions of each feed component are computed as ration-weighted values for:
   - gross energy — `calc_ration_gross_energy()`
   - nitrogen — `calc_ration_nitrogen_content()`
   - digestibility — `calc_ration_digestibility()`
   - metabolizable energy — `calc_ration_metabolizable_energy()`
   - urinary energy fraction — `calc_ration_urinary_energy_fraction()`
   - ash — `calc_ration_ash()`
3. Component contributions are summed to produce cohort-level diet metrics, including `calc_ration_intake()`.

# 5 Metabolic Energy Requirements and Ration Intake Module

See `run_metabolic_energy_req_module()` for full documentation.

Computes cohort-level daily energy requirements (MJ/head/day) and feed dry matter intake (kg DM/head/day) by applying the IPCC Tier 2 energy partitioning functions.

Energy requirements are expressed as net energy (NE) for CTL, BFL, SHP, and GTS, and as metabolizable energy (ME) for CML, PGS, and CHK. The module computes the following energy partitions:

- Maintenance — `calc_metabolic_energy_req_maintenance()`
- Activity — `calc_metabolic_energy_req_activity()`
- Growth — `calc_metabolic_energy_req_growth()`
- Lactation — `calc_metabolic_energy_req_lactation()`
- Pregnancy — `calc_metabolic_energy_req_pregnancy()`
- Work (draught power; CTL, BFL, CML only) — `calc_metabolic_energy_req_work()`
- Fibre production (SHP, GTS, CML only) — `calc_metabolic_energy_req_fibre()`

Total energy requirements are then aggregated using `calc_total_metabolic_energy_req()`, and dry matter intake is derived using `calc_ration_intake()` by dividing the total energy requirement by the diet energy density.

Overview of the GLEAM metabolic energy requirements module with functions, input and output:

# 6 Enteric Emissions Module

# 7 Enteric Emissions Module

See `run_emissions_enteric_module()` for full documentation.

Computes daily enteric methane emissions by cohort (kg CH₄/head/day) using the IPCC Tier 2 approach, by applying species-, cohort-, and diet-specific methane conversion factors (ym).
Overview of the GLEAM enteric emissions module with functions, input and output:

The calculation pipeline consists of the following steps:

1. If `ch4_mitigation_factor` is not provided in the input data, it is set to `1` (no mitigation).
2. The methane conversion factor (ym) is computed using `calc_conversion_factor_ym()`.
3. Daily enteric methane emissions are computed using `calc_ch4_enteric()`.

# 8 Nitrogen Balance Module

See `run_nitrogen_balance_module()` for full documentation.

Computes cohort-level daily nitrogen intake, retention, and excretion (kg N/head/day) following the IPCC Tier 2 approach.

Overview of the GLEAM nitrogen balance module with functions, input and output:

The following calculation sequence is applied:

1. Daily nitrogen intake is computed from `ration_intake` and `ration_nitrogen` using `calc_nitrogen_intake()`.
2. Daily nitrogen retention (in body tissues and products such as growth, pregnancy, and milk) is computed using `calc_nitrogen_retention()`.
3. Daily nitrogen excretion is computed as intake minus retention using `calc_nitrogen_excretion()`.

# 9 Manure Emissions Module

See `run_emissions_manure_module()` for full documentation.

Computes cohort-level greenhouse gas emissions from manure management systems (MMS) following the IPCC Tier 2 methodology, using volatile solids (VS), MMS allocation fractions, and MMS-specific emission factors.

For each `herd_id`, the set of MMS identifiers must be consistent between the `manure_management_system_fraction` and `manure_management_system_factors` tables. The following calculation sequence is applied:

1. Volatile solids (VS) excretion is computed from feed ration nutritional parameters (digestibility, urinary energy, ash) using
   Overview of the GLEAM manure emissions module with functions, input and output:

    [`calc_volatile_solids()`](../reference/calc_volatile_solids.html)
    (IPCC 2006/2019, Eq. 10.24).

2. Methane (CH₄) emissions from manure management are computed from VS and MMS-specific factors (MCF and B₀), reported by MMS group (pasture, burned, other) using `calc_ch4_manure()` (IPCC 2006/2019, Eq. 10.23).
3. Direct N₂O emissions are computed from nitrogen excretion and MMS-specific EF3 values, reported by MMS group using `calc_n2o_manure_direct()` (IPCC 2006/2019, Eq. 10.25).
4. Indirect N₂O emissions are the sum of:

- Volatilisation-driven N₂O from MMS-specific nitrogen losses (FracGas) and EF4 using `calc_n2o_manure_volatilization()` (IPCC 2006/2019, Eq. 10.26–10.28).
- Leaching/runoff-driven N₂O from MMS-specific nitrogen losses (FracLeach) and EF5 using `calc_n2o_manure_leaching()` (IPCC 2006/2019, Eq. 10.27–10.29).

5. Total N₂O (direct + indirect) is summed by MMS group using `calc_n2o_manure_total()`.

# 10 Feed Production Emissions Module

See `run_emissions_ration_module()` for full documentation.

Computes cohort-level average greenhouse gas emission factors from feed production by weighting the emission factors of individual feed components by diet composition. Returns diet-level average GHG emission factors by gas and emission source for each cohort.

The module joins ration shares with feed emission factors by `feed_id` and applies the following calculation sequence:

1. Merge ration shares with emission factors at the feed-component level.
2. Compute feed-component contributions (row-wise) for each emission source by multiplying the ration share of each feed component (`feed_ration_fraction`) by the corresponding emission factor:
   - CO₂ from fertilizer manufacture — `calc_co2_ration_fertilizer()`
   - CO₂ from pesticide manufacture — `calc_co2_ration_pesticides()`
   - CO₂ from on-field crop activities — `calc_co2_ration_crop_activities()`
   - CO₂ from land-use change (no peat) — `calc_co2_ration_luc_nopeat()`
   - CO₂ from land-use change (peat) — `calc_co2_ration_luc_peat()`
   - N₂O from fertilizer use — `calc_n2o_ration_fertilizer()`
   - N₂O from manure applied to soil — `calc_n2o_ration_manure()`
   - N₂O from crop residues — `calc_n2o_ration_crop_residues()`
   - CH₄ from rice cultivation — `calc_ch4_ration_rice()`
3. Sum component contributions within each cohort to obtain diet-level average emission factors (g gas/kg DM).

Overview of the GLEAM feed production emissions module with functions, input and output:

# 11 Production Module

See `run_production_module()` for full documentation.

Computes cohort-level production outputs over the assessment period by combining cohort-level herd structure inputs with herd-level production parameters. The module returns milk, fibre, and meat outputs for each cohort.

Overview of the GLEAM production module with functions, input and output:

The following calculation sequence is applied:

1. Milk outputs (raw mass, protein, and fat-protein-corrected milk — FPCM) are computed using `calc_milk_production()`.
2. Fibre outputs (wool, cashmere, mohair) are computed using `calc_fibre_production()`.
3. Meat outputs (live weight, carcass weight, bone-free meat, and protein) are computed using `calc_meat_production()`.

# 12 Emission Allocation Module

See `run_allocation_module()` for full documentation.

Computes biophysical allocation shares for livestock commodities by calculating cohort-level energy requirements for meat, milk, fibre, work, and eggs, aggregating these terms to herd level, and assigning allocation shares to emission sources. The approach follows the IDF Global Carbon Footprint Standard for the dairy sector, adapted for livestock systems in which emissions are apportioned among multiple products according to their physiological energy requirements. This is consistent with ISO 14044:2006 (Section 4.3.4.2, Step 2).
Overview of the GLEAM emissions allocation module with functions, input and output:

The pipeline consists of the following steps:

1. Cohort-level energy allocation terms are computed for each commodity:
   - Meat — `calc_meat_allocation_energy()`
   - Milk — `calc_milk_allocation_energy()`
   - Fibre — `calc_fibre_allocation_energy()`
   - Work (draught power) — `calc_work_allocation_energy()`
   - Eggs — set to 0 (not yet implemented)
2. Cohort-level energy terms are aggregated to herd level using `calc_cohort_to_herd_aggregation()`.
3. Herd-level allocation shares are computed using `calc_allocation_shares()`.
4. Allocation shares are reshaped to long format and assigned to emission sources using `assign_allocation_shares()`.

# 13 Aggregation and Reporting Module

See `run_aggregation_module()` for full documentation.

This is the final step of the GLEAM pipeline. It generates final herd-level results by aggregating key cohort-level outputs, scaling variables over the assessment duration, allocating emissions to commodities, and converting CH₄ and N₂O emissions to CO₂-equivalents (CO₂eq) using selected 100-year Global Warming Potential (GWP-100) factors.

Overview of the GLEAM aggregation module with functions, input and output:

The following calculation sequence is applied:

1. Cohort-level variables are reshaped from wide to long format.
2. Variables are classified into `"Feed"`, `"NitrogenBalance"`, `"Production"`, and `"Emissions"`.
3. Cohort totals are calculated using `calc_cohort_totals()`. Production variables are retained as provided; emissions, feed, and nitrogen balance variables are scaled using cohort stock size and simulation duration.
4. Cohort totals are aggregated to herd level using `calc_cohort_to_herd_aggregation()`.
5. Herd-level emissions are merged with commodity allocation shares.
6. Emissions are allocated to commodities using `calc_allocated_emissions()`.
7. Gas type (CH₄, N₂O, CO₂) is identified from the emission variable name.
8. Allocated emissions are converted to CO₂eq using `calc_co2eq()` and the selected GWP-100 option (AR4, AR5, or AR6).
9. Final output tables are produced summarising herd-level results for emissions, feed, production, and nitrogen balance.