demographics
Define pregnancy, deaths, migration, etc.
Classes
| Name | Description |
|---|---|
| Births | Create births based on rates, rather than based on pregnancy. |
| Deaths | Configure disease-independent “background” deaths. |
| Demographics | A demographic module typically handles births/deaths/migration and takes |
| Pregnancy | Create births via pregnancies for each agent. |
| PregnancyPars | Pregnancy parameters and default values |
Births
demographics.Births(
pars=None,
birth_rate=_,
rel_birth=_,
rate_units=_,
metadata=None,
**kwargs,
)Create births based on rates, rather than based on pregnancy.
Births are generated using population-level birth rates that can vary by year. The number of births per timestep is determined by applying the birth rate to the current population size.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| birth_rate | float / rate / dataframe |
value for birth rate, or birth rate data | _ |
| rel_birth | float | constant used to scale all birth rates | _ |
| rate_units | float | units for birth rates (default assumes per 1000) | _ |
| metadata | dict | dict with data column mappings for birth rate data (if birth_rate is a dataframe) | None |
Methods
| Name | Description |
|---|---|
| add_births | Add n_new births to each state in the sim |
| get_births | Extract the right birth rates to use and translate it into a number of people to add. |
| init_pre | Initialize with sim information |
| standardize_birth_data | Standardize/validate birth rates - handled in an external file due to shared functionality |
| update_results | Calculate new births and crude birth rate |
add_births
demographics.Births.add_births()Add n_new births to each state in the sim
get_births
demographics.Births.get_births()Extract the right birth rates to use and translate it into a number of people to add.
init_pre
demographics.Births.init_pre(sim)Initialize with sim information
standardize_birth_data
demographics.Births.standardize_birth_data()Standardize/validate birth rates - handled in an external file due to shared functionality
update_results
demographics.Births.update_results()Calculate new births and crude birth rate
Deaths
demographics.Deaths(
pars=None,
rel_death=_,
death_rate=_,
rate_units=_,
metadata=None,
**kwargs,
)Configure disease-independent “background” deaths.
The probability of death for each agent on each timestep is determined by the death_rate parameter and the time step. The default value of this parameter is 0.01, indicating that all agents will face a 1% chance of death per year.
However, this function can be made more realistic by using a dataframe for the death_rate parameter, to allow it to vary by year, sex, and age. The separate ‘metadata’ argument can be used to configure the details of the input datafile.
Alternatively, it is possible to override the death_rate parameter with a bernoulli distribution containing a constant value of function of your own design.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| pars | dict with arguments including: rel_death: constant used to scale all death rates death_rate: float, dict, or pandas dataframe/series containing mortality data rate_units: units for death rates (see in-line comment on par dict below) | None |
|
| metadata | data about the data contained within the data input. “data_cols” is is a dictionary mapping standard keys, like “year” to the corresponding column name in data. Similar for “sex_keys”. | None |
Methods
| Name | Description |
|---|---|
| make_p_death | Take in the module, sim, and uids, and return the probability of death for each UID on this timestep |
| standardize_death_data | Standardize/validate death rates - handled in an external file due to shared functionality |
| step | Select people to die |
make_p_death
demographics.Deaths.make_p_death()Take in the module, sim, and uids, and return the probability of death for each UID on this timestep
standardize_death_data
demographics.Deaths.standardize_death_data()Standardize/validate death rates - handled in an external file due to shared functionality
step
demographics.Deaths.step()Select people to die
Demographics
demographics.Demographics(name=None, label=None, **kwargs)A demographic module typically handles births/deaths/migration and takes place at the start of the timestep, before networks are updated and before any disease modules are executed.
Pregnancy
demographics.Pregnancy(
pars=None,
fertility_rate=_,
rel_fertility=_,
p_infertile=_,
min_age=_,
max_age=_,
rate_units=_,
dur_pregnancy=_,
dur_breastfeed=_,
p_breastfeed=_,
rr_ptb=_,
rr_ptb_age=_,
p_maternal_death=_,
p_survive_maternal_death=_,
sex_ratio=_,
burnin=_,
slot_scale=_,
min_slots=_,
trimesters=_,
metadata=None,
**kwargs,
)Create births via pregnancies for each agent.
This module models conception, pregnancy, and birth at the individual level using age-specific fertility rates. Supports prenatal and postnatal transmission networks, maternal and neonatal mortality, and burn-in of existing pregnancies at simulation start.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| fertility_rate | float / dataframe |
value or dataframe with age-specific fertility rates | _ |
| rel_fertility | float | constant used to scale all fertility rates | _ |
| p_infertile | bernoulli |
probability of primary infertility (default 0) | _ |
| min_age | float | minimum age for pregnancy (default 15) | _ |
| max_age | float | maximum age for pregnancy (default 50) | _ |
| rate_units | float | units for fertility rates (default assumes per 1000) | _ |
| dur_pregnancy | float / dur | duration of pregnancy (default: drawn from choice distribution, 32-42 weeks) | _ |
| dur_breastfeed | float / dur | duration of breastfeeding (default: drawn from lognormal distribution, 9±6 months) | _ |
| rr_ptb | float | base relative risk of pre-term birth (default normal with mean 1, std 0.1) | _ |
| rr_ptb_age | array | relative risk of pre-term birth by maternal age (default [[18,35,100],[1.2,1,1.2]]) | _ |
| p_maternal_death | float | probability of maternal death during pregnancy (default 0.0) | _ |
| p_survive_maternal_death | float | probability that an unborn agent will survive death of the mother (default 0) | _ |
| sex_ratio | float | probability of female births (default 0.5) | _ |
| burnin | bool | whether to seed pregnancies from before simulation start (default true) | _ |
| slot_scale | float | scale factor for assigning slots to newborn agents (default 5) | _ |
| min_slots | int | minimum number of slots for newborn agents (default 100) | _ |
| trimesters | list | list of durations defining the end of each trimester | _ |
| metadata | dict | data column mappings for fertility rate data if a dataframe is supplied | None |
Attributes
| Name | Description |
|---|---|
| dur_gestation | Return duration of gestation for currently-pregnant women in years |
| dur_gestation_at_birth | Return duration of gestation at birth for agents born during the simulation |
| fecund | Defined as women of childbearing age |
| fertile | Defined as women of childbearing age who are not infertile. Includes women who may be pregnant |
| nulliparous | Women of childbearing age who have never been pregnant |
| susceptible | Defined as fertile women of childbearing age who are not pregnant, and so are susceptible to conception |
| tri1_uids | Return UIDs of those in their first trimester |
| tri2_uids | Return UIDs of those in their second trimester |
| tri3_uids | Return UIDs of those in their third trimester |
Methods
| Name | Description |
|---|---|
| compute_asfr | Computes age-specific fertility rates (ASFR). Since this is calculated each timestep, |
| init_results | Initialize results. By default, this includes: |
| make_embryos | Make newly-conceived agents. This method calls two helper methods, which grow the population |
| make_p_conceive | Take in the module, sim, and uids, and return the conception probability for each UID on this timestep |
| make_pregnancies | Make pregnancies, assign durations, and determine multiples |
| process_delivery | Handle delivery by updating all states for the mother. This method also transfers |
| process_maternal_deaths | If any pregnant mothers die, we also process the death of the unborn agent. |
| process_newborns | Set states for newborn agents |
| process_prenatal_deaths | If any deaths occur in unborn agents, we handle changes to pregnancy and record as a miscarriage |
| progress_pregnancies | Update pregnant women. The method can be enhanced by derived classes that add logic |
| select_conceivers | Select people to make pregnant |
| set_breastfeeding | Set breastfeeding durations for new mothers. This method could be extended to |
| set_ptb | Update relative risk of pre-term birth |
| set_rel_sus | Set relative susceptibility to pregnancy. Note that rel_sus isn’t used in this module, |
| standardize_fertility_data | Standardize/validate fertility rates |
| step | Perform all updates except for deaths, which are handled in finish_step |
| step_die | Wipe dates and states following death |
| update_maternal_deaths | Check for maternal deaths |
| updates_pre | This runs prior at the beginning of each timestep, prior to calculating pregnancy exposure, |
compute_asfr
demographics.Pregnancy.compute_asfr()Computes age-specific fertility rates (ASFR). Since this is calculated each timestep, the annualized results should compute the sum.
init_results
demographics.Pregnancy.init_results()Initialize results. By default, this includes: - pregnancies: number of new pregnancies on each timestep - births: number of new births on each timestep - cbr: crude birth rate on each timestep - tfr: total fertility rate on each timestep - The number of people who are fecund, (in)fertile, susceptible, postpartum, pregnant, infertile, breastfeeding
make_embryos
demographics.Pregnancy.make_embryos(conceive_uids, embryo_counts=None)Make newly-conceived agents. This method calls two helper methods, which grow the population and set the states for the newborn agents.
make_p_conceive
demographics.Pregnancy.make_p_conceive(filter_uids=None)Take in the module, sim, and uids, and return the conception probability for each UID on this timestep
make_pregnancies
demographics.Pregnancy.make_pregnancies(uids)Make pregnancies, assign durations, and determine multiples
process_delivery
demographics.Pregnancy.process_delivery(mother_uids, newborn_uids)Handle delivery by updating all states for the mother. This method also transfers recorded information stored with the mother to the newborn. During pregnancy, gestational age is tracked with the mother; at birth, this value is transferred to the newborn agent before being reset for the mother. Likewise, during pregnancy, the child UID is stored with the mother; at birth, this value is removed from the mother, although newborn agents can still be linked to the mother via the parent state.
process_maternal_deaths
demographics.Pregnancy.process_maternal_deaths(death_uids)If any pregnant mothers die, we also process the death of the unborn agent. Default probability is set to 1 meaning we assume that unborn children do not survive.
process_newborns
demographics.Pregnancy.process_newborns(uids)Set states for newborn agents
process_prenatal_deaths
demographics.Pregnancy.process_prenatal_deaths(death_uids)If any deaths occur in unborn agents, we handle changes to pregnancy and record as a miscarriage
progress_pregnancies
demographics.Pregnancy.progress_pregnancies()Update pregnant women. The method can be enhanced by derived classes that add logic for miscarriage, termination, maternal death, etc.
select_conceivers
demographics.Pregnancy.select_conceivers(uids=None)Select people to make pregnant
set_breastfeeding
demographics.Pregnancy.set_breastfeeding(mother_uids, newborn_uids)Set breastfeeding durations for new mothers. This method could be extended to store duration of exclusive breastfeeding, partial breastfeeding, etc, and these properties could be stored with the infant for tracking other health outcomes.
set_ptb
demographics.Pregnancy.set_ptb()Update relative risk of pre-term birth
set_rel_sus
demographics.Pregnancy.set_rel_sus()Set relative susceptibility to pregnancy. Note that rel_sus isn’t used in this module, but it’s a key ingredient for derived modules that compute pregnancies based on exposure.
standardize_fertility_data
demographics.Pregnancy.standardize_fertility_data()Standardize/validate fertility rates
step
demographics.Pregnancy.step()Perform all updates except for deaths, which are handled in finish_step
step_die
demographics.Pregnancy.step_die(uids)Wipe dates and states following death
update_maternal_deaths
demographics.Pregnancy.update_maternal_deaths()Check for maternal deaths
updates_pre
demographics.Pregnancy.updates_pre(uids=None, upper_age=None)This runs prior at the beginning of each timestep, prior to calculating pregnancy exposure, advancing pregnancies, adding new pregnancies, or determing delivery outcomes. Here we make any updates that affect the risk of pregnancy or pre-term birth on this timestep. We also set the baseline values for newborn agents.
PregnancyPars
demographics.PregnancyPars(**kwargs)Pregnancy parameters and default values