This function orchestrates the demographic herd module
run_demographic_herd_module() and the non-demographic herd module
run_nondemographic_herd_module() within a single wrapper. Depending on the
selected logical switches, it runs the demographic module, the
non-demographic module, or both, and returns a harmonized herd-module output
structure for downstream use in run_gleam().
Usage
run_all_herd_module(
cohort_level_data = NULL,
herd_level_data = NULL,
simulation_duration = 365,
show_indicator = TRUE,
run_demographic = TRUE,
run_nondemographic = TRUE
)Arguments
- cohort_level_data
A
data.tablewith one row perherd_idand cohort. Required rows and columns depend on the selected execution mode:Case 1 - when
run_demographic = TRUEandrun_nondemographic = FALSE:cohort_level_datamust contain rows for the demographic cohorts only (FA,FJ,FS,MA,MJ,MS). In this case the table must contain the columns required byrun_demographic_herd_module():herd_idCharacter. Unique identifier for the herd, repeated for each cohort belonging to the same herd.
cohort_shortCharacter. 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 femalesMN: non-demographic males
cohort_duration_daysNumeric. Amount of time that each animal spends in a specific cohort and production phase (days). For
CHK, suggested value forFJandMJcohorts: 3 days. Not required forFNandMNwhen phase durations are supplied in the herd table; the code fills it from the herd values, which override any cohort values.offtake_rateNumeric. Annual proportion of animals removed from the herd for each demographic cohort (fraction).
death_rateNumeric. Fraction of animals dying in the assessed cohort over one year for demographic cohorts (fraction).
Case 2 - when
run_demographic = FALSEandrun_nondemographic = TRUE:cohort_level_datamust contain rows for the non-demographic cohorts only (FN,MN). In this case the table must contain the columns required byrun_nondemographic_herd_module():herd_idCharacter. Unique identifier for the herd, repeated for each cohort belonging to the same herd.
cohort_shortCharacter. 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 femalesMN: non-demographic males
nondemo_productive_phase_idNumeric. Productive phase identifier for non-demographic cohorts (
FN,MN). Takes value1for phase 1 and optionally2for phase 2. Demographic cohorts useNA.death_rateNumeric. Fraction of animals dying in the assessed cohort over the productive phase for non-demographic cohorts (fraction).
Case 3 - when
run_demographic = TRUEandrun_nondemographic = TRUE:cohort_level_datamust contain both demographic and non-demographic rows. In this case the table must satisfy both sets of requirements described above. Internally,run_all_herd_module()splits the combined input into demographic and non-demographic subsets usingcohort_short.
- herd_level_data
A
data.tablewith one row perherd_id. This table is required in all execution modes. Required columns depend on the selected execution mode:Case 1 - when
run_demographic = TRUEandrun_nondemographic = FALSE:herd_level_datamust contain the herd-level inputs required byrun_demographic_herd_module():herd_idCharacter. Unique identifier for the herd.
reproductive_rateNumeric. Average annual number of parturitions per reproductive female (# parturitions/reproductive female/year). For chickens, annual number of eggs laid for reproduction per breeding hen (# eggs/hen/year).
offspring_per_reproductive_eventNumeric. Average number of offspring born per parturition (# offspring/parturition). For chickens, hatchability of eggs laid for reproduction, calculated as the number of chicks hatched divided by the number of eggs laid for reproduction (fraction).
birth_fraction_femaleNumeric. Female birth fraction, defined as the probability that a newborn offspring is female (fraction).
herd_size_totalNumeric. Total demographic population size at the start of the year, including all cohorts (# heads)
prop_nondemo_mal_juvNumeric. Fraction of male juveniles diverted into the non-demographic stream at the moment they transition to the next age class (fraction).
prop_nondemo_fem_juvNumeric. Fraction of female juveniles diverted into the non-demographic stream at the moment they transition to the next age class (fraction).
Case 2 - when
run_demographic = FALSEandrun_nondemographic = TRUE:herd_level_datamust contain the herd-level inputs required byrun_nondemographic_herd_module():herd_idCharacter. Unique identifier for the herd.
cohort_stock_fem_annual_nondemoNumeric. Annual number of female animals entering the non-demographic pathway (
FN) over the 365-time horizon (# heads). When both demographic and non-demographic modules are run, this is derived internally from the demographic calculations.cohort_stock_mal_annual_nondemoNumeric. Annual number of male animals entering the non-demographic pathway (
MN) over the 365-time horizon (# heads). When both demographic and non-demographic modules are run, this is derived internally from the demographic calculations.rest_between_nondemo_cycles_durationNumeric. Duration of the resting or empty phase between non-demographic cycles (days). Use
0when there is no rest between cycles.phase1_nondemo_fem_duration_daysNumeric. Duration of productive phase 1 for the female non-demographic cohort (
FN) (days).phase2_nondemo_fem_duration_daysNumeric. Duration of productive phase 2 for the female non-demographic cohort (
FN) (days).phase1_nondemo_mal_duration_daysNumeric. Duration of productive phase 1 for the male nondemographic cohort (
MN) (days).phase2_nondemo_mal_duration_daysNumeric. Duration of productive phase 2 for the male non-demographic cohort (
MN) (days).
Case 3 - when
run_demographic = TRUEandrun_nondemographic = TRUE:herd_level_datamust contain the demographic herd inputs required byrun_demographic_herd_module(), plus the non-demographic cycle-duration inputs required to runrun_nondemographic_herd_module()after annual non-demographic entrants are derived internally from the demographic output:herd_idCharacter. Unique identifier for the herd.
reproductive_rateNumeric. Average annual number of parturitions per reproductive female (# parturitions/reproductive female/year). For chickens, annual number of eggs laid for reproduction per breeding hen (# eggs/hen/year).
offspring_per_reproductive_eventNumeric. Average number of offspring born per parturition (# offspring/parturition). For chickens, hatchability of eggs laid for reproduction, calculated as the number of chicks hatched divided by the number of eggs laid for reproduction (fraction).
birth_fraction_femaleNumeric. Female birth fraction, defined as the probability that a newborn offspring is female (fraction).
herd_size_totalNumeric. Total demographic population size at the start of the year, including all cohorts (# heads)
prop_nondemo_mal_juvNumeric. Fraction of male juveniles diverted into the non-demographic stream at the moment they transition to the next age class (fraction).
prop_nondemo_fem_juvNumeric. Fraction of female juveniles diverted into the non-demographic stream at the moment they transition to the next age class (fraction).
rest_between_nondemo_cycles_durationNumeric. Duration of the resting or empty phase between non-demographic cycles (days). Use
0when there is no rest between cycles.phase1_nondemo_fem_duration_daysNumeric. Duration of productive phase 1 for the female non-demographic cohort (
FN) (days).phase2_nondemo_fem_duration_daysNumeric. Duration of productive phase 2 for the female non-demographic cohort (
FN) (days).phase1_nondemo_mal_duration_daysNumeric. Duration of productive phase 1 for the male nondemographic cohort (
MN) (days).phase2_nondemo_mal_duration_daysNumeric. Duration of productive phase 2 for the male non-demographic cohort (
MN) (days).
In this combined mode,
cohort_stock_fem_annual_nondemoandcohort_stock_mal_annual_nondemoare omitted because derived internally from the demographic output and therefore do not need to be supplied as primary herd-level inputs.
- simulation_duration
Numeric. Length of the assessment period (days).
- show_indicator
Logical. Whether to display progress indicators during calculations. Defaults to
TRUE.- run_demographic
Logical. If
TRUE, runrun_demographic_herd_module().- run_nondemographic
Logical. If
TRUE, runrun_nondemographic_herd_module().
Value
A named list with two elements:
cohort_level_resultsA
data.tablewith one row per retained cohort. Depending on the selected execution mode, this table contains demographic rows only, non-demographic rows only, or both in a harmonized schema. Intermediate scaling variables are removed before return. It includes the original cohort-level input columns plus the following result variables when available:cohort_stock_sizeNumeric. Average population size of the assessed cohort (# heads).
offtake_headsNumeric. Total number of animals removed from each cohort over the full 365-day simulation horizon (# heads/year).
offtake_heads_assessmentNumeric. Total number of animals removed from each cohort over the assessment period (# heads/assessment period).
cohort_stock_annual_nondemographicNumeric. Annual number of animals diverted from the demographic pathway into the non-demographic pathway (# heads).
nondemo_productive_phase_idNumeric. Productive phase identifier for non-demographic cohorts (
FN,MN). Takes value1for phase 1 and optionally2for phase 2. Demographic cohorts useNA.partial_nondemo_phase_durationNumeric. Duration of the terminal partial productive phase falling within the fixed 365-day non-demographic simulation horizon (days).
number_full_nondemo_cyclesInteger. Number of complete cycles fully contained within the fixed 365-day time horizon for the assessed non-demographic cohort (
FNorMN) (# cycles).total_nondemo_cycle_starts_to_distributeInteger. Total number of cycle starts within the fixed 365-day time horizon for the assessed non-demographic cohort (
FNorMN) (# cycle starts).
herd_level_resultsA
data.tablewith one row perherd_id. Depending on the selected execution mode, this is the herd-level output of the demographic module, the non-demographic module, or the merged herd-level output of both modules. It includes the original herd-level input columns plus the following result variables when available:growth_rate_herdNumeric. Annualized growth rate at which the herd reaches steady state (fraction).
cohort_stock_fem_annual_nondemoNumeric. Annual number of female animals entering the non-demographic pathway (
FN) over the 365-time horizon (# heads). When both demographic and non-demographic modules are run, this is derived internally from the demographic calculations.cohort_stock_mal_annual_nondemoNumeric. Annual number of male animals entering the non-demographic pathway (
MN) over the 365-time horizon (# heads). When both demographic and non-demographic modules are run, this is derived internally from the demographic calculations.rest_between_nondemo_cycles_durationNumeric. Duration of the resting or empty phase between non-demographic cycles (days). Use
0when there is no rest between cycles.total_nondemo_fem_duration_daysNumeric. Total duration of the productive non-demographic phases assigned to the female non-demographic cohort block (
FN) (days).total_nondemo_mal_duration_daysNumeric. Total duration of the productive non-demographic phases assigned to the male non-demographic cohort block (
MN) (days).
Details
The function supports three execution modes:
Demographic only: see
run_demographic_herd_module()for additional details.Non-demographic only: see
run_nondemographic_herd_module()for additional details.Demographic and non-demographic together: When
run_demographic = TRUEandrun_nondemographic = TRUE, the function:runs
run_demographic_herd_module()on the demographic subsetderives annual non-demographic entrants from the demographic output
runs
run_nondemographic_herd_module()on the non-demographic subsetrow-binds the two cohort-level result tables
harmonizes shared output columns
rescales average stock and offtake to the herd total
When both modules are run, annual entrants into the non-demographic blocks are derived from the demographic output:
female entrants to
FNare taken from demographic cohortFJascohort_stock_fem_annual_nondemo = cohort_stock_annual_nondemographicmale entrants to
MNare taken from demographic cohortMJascohort_stock_mal_annual_nondemo = cohort_stock_annual_nondemographic
These entrant counts are merged with herd-level non-demographic timing inputs such as:
rest_between_nondemo_cycles_durationphase1_nondemo_fem_duration_daysphase2_nondemo_fem_duration_daysphase1_nondemo_mal_duration_daysphase2_nondemo_mal_duration_days
After the selected modules run, the function combines their cohort-level
outputs using data.table::rbindlist(..., use.names = TRUE, fill = TRUE).
This allows demographic and non-demographic rows to share a common schema.
The combined cohort output harmonizes, when needed:
offtake_headsofftake_heads_assessmentcohort_duration_daysdeath_ratecohort_stock_size
When both modules are run, intermediate unscaled cohort stock and offtake
outputs are combined and rescaled so that the summed cohort average stock
matches herd_size_total from herd_level_data. The same rescaling applies
to non-demographic-only runs when herd_size_total is supplied.
The rescaling is performed in two steps:
cohort_stock_size_unscaledis rescaled internally tocohort_stock_sizewithin eachherd_idofftake_heads_unscaledandofftake_heads_assessment_unscaledare rescaled proportionally to the finalcohort_stock_size
When only the demographic module is run, its scaled outputs are renamed to
the harmonized final output names. Non-demographic-only runs without
herd_size_total return unscaled stock and offtake under those names.
The function then rescales the combined cohort
stock and offtake outputs so that the summed cohort average stock matches
herd_size_total from herd_level_data.
The rescaling is performed in two steps:
cohort_stock_size_unscaledis rescaled tocohort_stock_sizewithin eachherd_idofftake_headsandofftake_heads_assessmentare rescaled proportionally from the unscaled cohort stock to the scaled cohort stock
Without a herd-size target in non-demographic-only mode,
cohort_stock_size_unscaled is simply renamed to cohort_stock_size.
Use cases
Use case 1: Run both demographic and non-demographic modules
# Load herd simulation inputs (cohort and herd-level)
herd_all_chrt_dt <- data.table::fread(system.file(
"extdata/run_modules_examples/herd_all_input_chrt_data.csv",
package = "gleam"
))
herd_all_hrd_dt <- data.table::fread(system.file(
"extdata/run_modules_examples/herd_all_input_hrd_data.csv",
package = "gleam"
))
# Run mixed demographic and non-demographic herd simulation
results <- run_all_herd_module(
cohort_level_data = herd_all_chrt_dt,
herd_level_data = herd_all_hrd_dt,
run_demographic = TRUE,
run_nondemographic = TRUE,
simulation_duration = 365,
show_indicator = TRUE
)Use case 2: Run the non-demographic module only
# Load non-demographic-only herd inputs (CHK layers and broilers)
herd_all_chrt_dt <- data.table::fread(system.file(
"extdata/run_modules_examples/herd_all_nondemo_input_chrt_data.csv",
package = "gleam"
))
herd_all_hrd_dt <- data.table::fread(system.file(
"extdata/run_modules_examples/herd_all_nondemo_input_hrd_data.csv",
package = "gleam"
))
# Run non-demographic-only herd simulation
results <- run_all_herd_module(
cohort_level_data = herd_all_chrt_dt,
herd_level_data = herd_all_hrd_dt,
run_demographic = FALSE,
run_nondemographic = TRUE,
simulation_duration = 365,
show_indicator = TRUE
)Use case 3: Run the demographic module only
# Load demographic-only herd inputs (cohort and herd-level)
herd_all_chrt_dt <- data.table::fread(system.file(
"extdata/run_modules_examples/herd_all_demo_input_chrt_data.csv",
package = "gleam"
))
herd_all_hrd_dt <- data.table::fread(system.file(
"extdata/run_modules_examples/herd_all_demo_input_hrd_data.csv",
package = "gleam"
))
# Run demographic-only herd simulation
results <- run_all_herd_module(
cohort_level_data = herd_all_chrt_dt,
herd_level_data = herd_all_hrd_dt,
run_demographic = TRUE,
run_nondemographic = FALSE,
simulation_duration = 365,
show_indicator = TRUE
)