Fertility Models

Provide several different models of fertility.

class vivarium_public_health.population.add_new_birth_cohorts.FertilityDeterministic[source]

Deterministic model of births based on a fixed yearly simulant count.

At each time step this component adds a fixed number of newborn simulants proportional to fertility.number_of_new_simulants_each_year and the current step size. Sub-integer remainders are accumulated across steps and applied when they reach a whole number.

CONFIGURATION_DEFAULTS: dict[str, Any] = {'fertility': {'number_of_new_simulants_each_year': 1000}}: A dictionary containing the defaults for any configurations managed by this component. An empty dictionary indicates no managed configurations. Components will look for a data_sources block in this dictionary to build lookup tables automatically.

setup(builder)[source]

Set up the component by reading configuration and obtaining the simulant creator.

Parameters:: builder (Builder) – Access point for utilizing framework interfaces during setup.
Return type:: None

on_time_step(event)[source]

Add a set number of simulants to the population each time step.

Parameters:: event (Event) – The event that triggered this method call.
Return type:: None

class vivarium_public_health.population.add_new_birth_cohorts.FertilityCrudeBirthRate[source]

Population-level model of births using crude birth rate.

The number of births added each time step is calculated as:

new_births = sim_pop_size_t0 * live_births / true_pop_size * step_size

Where:

sim_pop_size_t0 — the initial simulation population size
live_births — annual number of live births in the true population
true_pop_size — the true population size

This component has configuration flags that determine whether the live births and the true population size should vary with time.

Notes

The OECD definition of crude birth rate can be found on their website, while a more thorough discussion of fertility and birth rate models can be found on Wikipedia or in demography textbooks.

CONFIGURATION_DEFAULTS: dict[str, Any] = {'fertility': {'time_dependent_live_births': True, 'time_dependent_population_fraction': False}}: A dictionary containing the defaults for any configurations managed by this component. An empty dictionary indicates no managed configurations. Components will look for a data_sources block in this dictionary to build lookup tables automatically.

setup(builder)[source]

Set up the component by loading birth rate data and obtaining the simulant creator.

Parameters:: builder (Builder) – Access point for utilizing framework interfaces during setup.
Raises:: ValueError – If population.initialization_age_min is not zero.
Return type:: None

on_time_step(event)[source]

Add new simulants based on crude birth rate and a Poisson distribution.

Parameters:: event (Event) – The event that triggered this method call.
Return type:: None

class vivarium_public_health.population.add_new_birth_cohorts.FertilityAgeSpecificRates[source]

Simulant-specific model of fertility based on age-specific fertility rates.

At each time step, this component determines which living female simulants give birth. Eligibility requires at least nine months to have elapsed since the simulant’s last birth. Newborns are added to the state table with a reference to their parent simulant.

property configuration_defaults: dict[str, dict]: The default configuration values for this component.

setup(builder)[source]

Set up the common randomness stream and age-specific fertility lookup tables.

Parameters:: builder (Builder) – Access point for utilizing framework interfaces during setup.
Return type:: None

load_age_specific_fertility_rate_data(builder)[source]

Load and filter age-specific fertility rate data from the artifact.

Reads the covariate.age_specific_fertility_rate.estimate dataset, retains only female mean-value estimates, and returns the relevant columns.

Parameters:: builder (Builder) – Access point for utilizing framework interfaces during setup.
Return type:: DataFrame
Returns:: A pandas.DataFrame with columns year_start, year_end, age_start, age_end, and value.

initialize_birth_time_and_parent_id(pop_data)[source]

Add ‘last_birth_time’ and ‘parent’ columns to the state table.

Parameters:: pop_data (SimulantData) – Metadata about the simulants being initialized.
Return type:: None

on_time_step(event)[source]

Produce new children and update parent status on time steps.

Parameters:: event (Event) – The event that triggered this method call.
Return type:: None