Skip to contents

Calculates 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.

Usage

run_ration_quality_module(rations_share, feed_params, show_indicator = TRUE)

Arguments

rations_share

data.table. Cohort-level feed ration composition shares with the following minimum data requirement:

herd_id

Character. Unique identifier for the herd, repeated for each cohort belonging to the same herd.

species_short

Character. Code identifying the livestock species. Supported values include:

  • PGS: pigs

  • CML: camels

  • CTL: cattle

  • BFL: buffalo

  • SHP: sheep

  • GTS: goats

  • CHK: chickens

cohort_short

Character. Sex-specific cohort code describing the age and/or the production stage of the animals. Supported values include:

  • FA: adult females (from age at first parturition)

  • FS: sub-adult females (from weaning to age at first parturition)

  • FJ: juvenile females (from birth to weaning)

  • MA: adult males (from age at first breeding)

  • MS: sub-adult males (from weaning to age at first breeding)

  • MJ: juvenile males (from birth to weaning)

  • FN: non-demographic females

  • MN: non-demographic males

nondemo_productive_phase_id

Numeric. Optional productive phase identifier for non-demographic cohorts (FN, MN). Takes value 1 for phase 1 and optionally 2 for phase 2.

feed_id

Character. Unique identifier for the feed component, used to join feed ration data with feed parameter tables.

feed_name

Character. Feed component name (optional, for readability and reporting). If provided, it should uniquely identify the same feed component as feed_id.

feed_ration_fraction

Numeric. Proportion of a specific feed component in the total ration, expressed as its fraction of diet dry matter intake (fraction). Within each herd_id and cohort, proportions should sum to 1.

feed_params

data.table. Feed nutritional parameters with the following minimum data requirement:

feed_id

Character. Unique identifier for the feed component, used to join feed ration data with feed parameter tables.

feed_gross_energy

Numeric. Gross energy content of a feed component, representing the total chemical energy released upon complete combustion of the feed (MJ/kg DM).

feed_digestible_energy_ruminant

Numeric. Digestible energy content of a feed component for ruminants, representing the energy absorbed by the animal after fecal losses (MJ/kg DM).

feed_digestible_energy_pigs

Numeric. Digestible energy content of a feed component for pigs, representing the energy absorbed by the animal after fecal losses (MJ/kg DM).

feed_metabolizable_energy_ruminant

Numeric. Metabolizable energy content of a feed component for ruminants, representing digestible energy minus energy losses in urine and gaseous products of digestion (MJ/kg DM).

feed_metabolizable_energy_pigs

Numeric. Metabolizable energy content of a feed component for pigs, representing digestible energy minus energy losses in urine and gaseous products of digestion (MJ/kg DM).

feed_metabolizable_energy_chicken

Numeric. Metabolizable energy content of a feed component for chickens (MJ/kg DM).

feed_nitrogen_content

Numeric. Nitrogen content of a feed component (kg N/kg DM).

feed_urinary_energy_ruminant

Numeric. Fraction of feed's gross energy that is excreted in urine for ruminants (fraction).

feed_urinary_energy_pigs

Numeric. Fraction of feed's gross energy that is excreted in urine for pigs (fraction).

feed_ash

Numeric. Average ash content by feed component, expressed as a fraction of the dry matter intake (g ash/100g DM).

category

Character. Feed category (optional). If provided, it should be used consistently with feed_id, for a coherent result.

feed_name

Character. Feed component name (optional, for readability and reporting). If provided, it should uniquely identify the same feed component as feed_id.

show_indicator

Logical. Whether to display progress indicators during calculations. Defaults to TRUE.

Value

data.table. Cohort-level nutritional metrics summarized by herd_id, species_short, cohort_short, and nondemo_productive_phase_id when present, with the following columns:

ration_gross_energy

Numeric. Average gross energy content of the diet (MJ/kg DM).

ration_metabolizable_energy

Numeric. Average metabolizable energy content of the diet (MJ/kg DM).

ration_nitrogen

Numeric. Average nitrogen content of diet (kg N/kg DM).

ration_digestibility_fraction

Numeric. Average digestibility of the feed ration, expressed as ratio of digestible (or metabolizable, for chickens) to gross energy content (fraction).

ration_urinary_energy_fraction

Numeric. Fraction of feed's gross energy that is excreted in urine (fraction).

ration_ash

Numeric. Average ash content of feed, calculated as a fraction of the dry matter intake (kg ash/kg DM).

Details

This function represents the intermediate module of the Global Livestock Environmental Assessment Model (GLEAM) computational pipeline run_gleam() to estimate the nutritional quality of the feed ration. This function joins rations_share with feed_params by feed_id, uses species_short directly, and computes ration-weighted nutritional metrics by cohort. For chickens, digestibility is calculated using chicken metabolizable energy divided by gross energy. Urinary energy is set to zero because these losses are already included in metabolizable energy.

The following calculation sequence is applied:

  1. Species-specific digestibility ratios are computed from energy parameters and feed_gross_energy using calc_feed_digestibility_fraction.

  2. Contributions of each feed component are computed as ration-weighted values:

  3. Cohort-level nutritional metrics are obtained for the whole feed ration by summing contributions across feed components within each herd_id, species_short, and cohort_short group, and within nondemo_productive_phase_id when that column is provided.

Examples

# \donttest{
# Load feed ration inputs (cohort-level shares and feed parameters)
feed_rations_chrt_dt <- data.table::fread(system.file(
  "extdata/run_modules_examples/feed_rations_share_chrt.csv",
  package = "gleam"
))
feed_params_dt <- data.table::fread(system.file(
  "extdata/run_modules_examples/feed_quality.csv",
  package = "gleam"
))

# Run ration quality calculations
results <- run_ration_quality_module(
  rations_share = feed_rations_chrt_dt,
  feed_params = feed_params_dt
)
#> πŸ•’ Aggregating ration quality, please wait…
#> βœ” Ration quality aggregation complete.
# }