Fertility
Fertility components introduce new simulants into the simulation during runtime, e.g. to model the arrival of newborns or perhaps immigration. Three fertility implementations that span a range of complexity and data requirements currently exist.
Note that fertility components are optional — a model that does not need births simply omits them.
Component |
Stochasticity |
Typical Use |
|---|---|---|
Deterministic |
Adds a fixed, known number of new simulants per year. Useful for controlled experiments or simple projections. |
|
Stochastic (Poisson) |
Uses population-level live-birth covariate data and the scaling relationship between the modeled and true population to determine births each time step. |
|
Stochastic (per-simulant hazard) |
Applies age-specific fertility hazards to individual living females,
creates newborn simulants with parent links, and enforces a gestational
spacing assumption via |
Deterministic Fertility Model
FertilityDeterministic
is the simplest fertility model. It adds a fixed number of new simulants per
year, controlled by the fertility.number_of_new_simulants_each_year
configuration key. On each time step the component scales that
annual count by the step size and accumulates any fractional remainder across
steps so that no births are lost to rounding.
All newborns enter the simulation at age zero.
Crude Birth Rate Model
FertilityCrudeBirthRate
computes the expected number of births from live-birth covariate data and the
ratio of the simulation’s population.population_size to the true population
count in the artifact. On each time step it draws from a Poisson distribution
to decide how many new simulants to create.
The component respects two time-dependence toggles (fertility.time_dependent_live_births
and fertility.time_dependent_population_fraction) that control whether birth
rates and population fractions are held constant at the simulation start year
or allowed to vary.
Age-Specific Fertility Rate Model
FertilityAgeSpecificRates
operates at the individual simulant level. It registers a fertility rate
attribute pipeline and, on each time step, evaluates whether each
eligible female simulant gives birth based on a hazard draw. Eligibility
includes an age window and a gestational spacing assumption tied to the
last_birth_time column.
Newborn simulants are created through the framework’s simulant creator and
receive a parent_id linking them back to their mother.