demographics
Births, deaths, migration, and pregnancy
These exist so that the population can change during a run. ss.Births and ss.Deaths are written as code, ss.birth() and the like declare the same flows for the whole population, and ss.Pregnancy is declared, so that conception and delivery are transitions that other modules can modify or respond to.
Used with: agents and compartments; declared and coded modules
Classes
| Name | Description |
|---|---|
| Births | Births at a crude birth rate, without modeling pregnancy: for when the number of births matters but not the pregnancies behind them (for those, use ss.Pregnancy) |
| Deaths | Background deaths: deaths from causes other than the diseases modeled |
| Demographics | Base class for demographic modules. |
| Flows | Births, deaths, and migration declared for the whole population, as ss.Sim(demographics=[ss.birth(...), ss.death(...)]) gives them |
| Pregnancy | Pregnancy, as declared states and transitions |
| preterm | The risk of preterm birth in ss.Pregnancy (preterm=ss.preterm(...)), for the options that are rarely changed |
Births
demographics.Births(
pars=None,
birth_rate=_,
rel_birth=_,
min_age=_,
max_age=_,
rate_per=_,
columns=None,
**kwargs,
)Births at a crude birth rate, without modeling pregnancy: for when the number of births matters but not the pregnancies behind them (for those, use ss.Pregnancy)
The birth rate can vary by year. The number of births in each step is the birth rate times the number of people alive; each newborn’s parent (people.parent) is a woman of reproductive age (min_age to max_age).
Note: CRN safe.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| birth_rate | float / rate / dataframe / str |
the crude birth rate: a bare number (per year) or a typed rate, per 1,000 people if above 1 per year (e.g. 20, or ss.peryear(20)) and else per person (e.g. ss.peryear(0.02), the default); birth rate data (per 1,000 or per person, read in the same way); or a place by name, for its UN rates (e.g. ‘Kenya’) |
_ |
| rel_birth | float |
constant used to scale all birth rates | _ |
| min_age | float |
the youngest age of a mother (default 15) | _ |
| max_age | float |
the age that mothers are younger than (default 50) | _ |
| rate_per | float |
how many people the rates are per: 1000 or 1 (per person); by default, read from their size (see ss.demographics.rate_per_of()). The crude birth rate result (cbr) is per 1,000 people per year. |
_ |
| columns | dict |
if birth_rate is a table, its column for each standard key, where they differ from the defaults (year='Year', which may also be Time, and value='CBR'), e.g. columns=dict(value='rate') |
None |
| pars | dict |
the same parameters, as a dict | None |
Examples
ss.Births(birth_rate=35) # 35 per 1,000 people per year
ss.Births(birth_rate=ss.peryear(0.035)) # The same, per person
ss.Births(birth_rate=ss.peryear(35)) # The same: above 1 per year, so per 1,000Methods
| Name | Description |
|---|---|
| add_births | Add the step’s newborns to the population, each with their mother as parent |
| agent_reasons | It adds agents, unless it says it works on groups |
| finalize | The crude birth rate, per 1,000 people per year: the births of each step, over the people alive at its start |
| get_births | The mothers of the step’s births: the birth rate of this year, as a chance over the step, drawn among women of reproductive age so that there are as many births as at that rate for everyone |
| init_pre | Note if the birth rates are far apart in time |
| record_events | The births of the step (already counted) |
| standardize_birth_data | Standardize/validate birth rates; see ss.utils.standardize_data() |
add_births
demographics.Births.add_births()Add the step’s newborns to the population, each with their mother as parent
agent_reasons
demographics.Births.agent_reasons(sim)It adds agents, unless it says it works on groups
finalize
demographics.Births.finalize()The crude birth rate, per 1,000 people per year: the births of each step, over the people alive at its start
get_births
demographics.Births.get_births()The mothers of the step’s births: the birth rate of this year, as a chance over the step, drawn among women of reproductive age so that there are as many births as at that rate for everyone
init_pre
demographics.Births.init_pre(sim)Note if the birth rates are far apart in time
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| sim | Sim | the sim being initialized | required |
record_events
demographics.Births.record_events()The births of the step (already counted)
standardize_birth_data
demographics.Births.standardize_birth_data()Standardize/validate birth rates; see ss.utils.standardize_data()
Deaths
demographics.Deaths(
pars=None,
rel_death=_,
death_rate=_,
rate_per=_,
columns=None,
lifetable=None,
**kwargs,
)Background deaths: deaths from causes other than the diseases modeled
Each agent’s chance of dying in each step comes from death_rate and the length of the step. By default, this is ss.peryear(0.01) (10 per 1,000 people per year), so everyone faces about a 1% chance of death per year. For more realism, give rates that vary by year, sex, and age (a table, a life table, or a place by name, for its UN rates); columns= says which columns of a table are which.
Note: CRN safe.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| rel_death | float |
constant used to scale all death rates | _ |
| death_rate | float / rate / dict / dataframe / series / str |
the death rate: a bare number (per year) or a typed rate, per 1,000 people if above 1 per year (e.g. 10, or ss.peryear(10)) and else per person (e.g. ss.peryear(0.01), the default); mortality data by year, sex, and age (per 1,000 or per person, as the UN’s mx are, read in the same way, from the median rate); or a place by name, for its UN rates (e.g. ‘Kenya’) |
_ |
| lifetable | ss.lifetable/dict |
instead of death_rate, life tables (ss.lifetable): one, one for each sex (dict(female=..., male=...)), or one (or one for each sex) for each year from which it holds ({2000: ..., 2010: ...}); each is the death rate of each of its age bands, per person, so deaths follow the table of the year and each person’s sex and age as time goes on (ss.death(lifetable=) instead draws each person’s age at death once, from one table) |
None |
| rate_per | float |
how many people the rates are per: 1000 or 1 (per person); by default, read from their size (see ss.demographics.rate_per_of()). The crude mortality rate result (cmr) is per 1,000 people per year. |
_ |
| columns | dict |
if death_rate is a table, its column for each standard key, where they differ from the defaults, those of UN data (year='Time', sex='Sex', age='AgeGrpStart', value='mx'), e.g. columns=dict(value='rate'); and sex_keys, the data’s label for each sex, if not Female and Male (e.g. sex_keys=dict(F='f', M='m')) |
None |
| pars | dict |
the same parameters, as a dict | None |
Methods
| Name | Description |
|---|---|
| init_pre | Note if the death rates are far apart in time |
| make_p_death | The chance that each agent alive dies in this step: one number if it is the same for everyone, else one for each, by age, sex, and year |
| standardize_death_data | Standardize/validate death rates; see ss.utils.standardize_data() |
| step | Select people to die |
init_pre
demographics.Deaths.init_pre(sim)Note if the death rates are far apart in time
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| sim | Sim | the sim being initialized | required |
make_p_death
demographics.Deaths.make_p_death()The chance that each agent alive dies in this step: one number if it is the same for everyone, else one for each, by age, sex, and year
standardize_death_data
demographics.Deaths.standardize_death_data()Standardize/validate death rates; see ss.utils.standardize_data()
step
demographics.Deaths.step()Select people to die
Demographics
demographics.Demographics(name=None, label=None, **kwargs)Base class for demographic modules.
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. See ss.Births, ss.Deaths, and ss.Pregnancy for built-in implementations. Demographic modules modify the ss.People population and can interact with ss.Network objects (e.g. to add newborns to contact networks).
Flows
demographics.Flows(transitions, **kwargs)Births, deaths, and migration declared for the whole population, as ss.Sim(demographics=[ss.birth(...), ss.death(...)]) gives them
Every declared disease’s people are born and die by them, once, under every solver: they become transitions of the first declared disease (or the first with the state that births name), whose people are everyone’s, since as agents the diseases share the people, and in a compartmental run with several declared diseases, their states are tracked jointly (see ss.solvers.choose.init_flows()). With no declared disease, the sim adds one of everyone alive to hold them (ss.SimPars.population()), so they are a declared model like any other. This class is not usually used directly.
Note: CRN safe as agents.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| transitions | list |
births (ss.birth()), deaths of everyone (ss.death() with no state), and migration (ss.immigration(), ss.emigration() with no state) |
required |
Methods
| Name | Description |
|---|---|
| init_pre | Note any rates given as bare numbers |
init_pre
demographics.Flows.init_pre(sim)Note any rates given as bare numbers
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| sim | Sim | the sim being initialized | required |
Pregnancy
demographics.Pregnancy(pars=None, fetal_agents='auto', columns=None, **kwargs)Pregnancy, as declared states and transitions
Everyone is in NP (not pregnant: men and children too) or P (pregnant). Gestational age is P.time_in. Conception is one transition, so contraception, HIV, or LAM are modifiers of it (ss.modify(preg.conception, multiply=...)). A pregnancy ends in an abortion (at once, with p_abortion), a miscarriage or stillbirth (a hazard before or after loss_threshold), a maternal death (antepartum, with maternal_death_rate), or a delivery at the end of a dwell of dur_pregnancy. Each delivery gives children children (birth): as agents, new agents whose parent is the mother, placed in each declared module’s state given by its own ss.birth(when=preg.delivery) (or else its first state). Children die before the age of 1 at infant_death_rate (infant_mortality; 0 by default). It runs as agents under solver='auto'; a compartmental solver named explicitly runs a small approximate form (see compartmental_form()).
For other modules, preg.delivery happens to the mother, and to her fetuses (if they are agents: see _init_fetus()) before they are born, so a death of a fetus when=preg.delivery is a stillbirth; preg.birth happens to the newborns, so a neonatal death is when=preg.birth. Code reads a step’s newborns and their mothers in that step, before the diseases’ step, with on_birth(parents, children) in any module (see ss.Module.on_birth()), which is called at the delivery; the mothers delivered in the step are also preg.ti_delivered == sim.ti.
As agents, a live birth starts breastfeeding (lactating, with p_breastfeed), or restarts it for a woman breastfeeding already; it ends after dur_breastfeed, or at once if a child of hers dies before the age of 1. It is a state of each woman rather than one of the module’s exclusive states (NP, P), since it overlaps the next pregnancy. A BreastfeedingNet pairs each newborn with a mother who breastfeeds, and ends the pair when she stops.
As agents, a woman who leaves P (a delivery, a loss, or an abortion) faces conception again in the same step, for what is left of it (half a step); the children and records of a delivery (ti_delivered, since_birth, lactating) are made first, so a rate or a modifier that reads them sees this delivery. A rate given as a function (e.g. an override of conception_rate()) can be called more than once a step, for those who arrive in NP within it, so it should not draw random numbers.
Its parameters are listed in __init__(); code reacts to its events with add_callback(), e.g. preg.add_callback(preg.birth, fn). Its states and results are P (pregnant), ti_P, the scheduled delivery ti_exit_P (set_delivery() reschedules it), and the flows conception, birth, miscarriage, stillbirth, and abortion; as agents, lactating (breastfeeding).
Note: CRN safe as agents.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| fertility_rate | rate / dataframe / str / func |
one rate, a bare number (per year) or typed, per 1,000 women if above 1 per year (e.g. 100, or ss.peryear(100)) and else per woman (e.g. ss.peryear(0.1), the default); age-specific fertility rates (a table, per 1,000 women as the UN’s are, or per woman, read in the same way); or a country by name, for its UN rates (e.g. ‘Nigeria’), turned into the hazard of conception by conception_rate(); or a function of (sim) or (sim, uids) giving the hazard of conception itself (as conception_rate() does) |
|
| rate_per | float |
how many women the rates of fertility_rate are per: 1000 or 1 (per woman); by default, read from their size (see ss.demographics.rate_per_of()) |
|
| rel_fertility | float |
multiplier on the fertility rate | |
| p_infertile | bernoulli | primary infertility | |
| min_age | float |
minimum age of conception | |
| max_age | float |
maximum age of conception | |
| dur_pregnancy | dur / Dist |
duration of pregnancy; a number is in weeks | |
| loss_rate | rate / func |
hazard of a spontaneous loss, or a function of (sim, uids) |
|
| loss_threshold | dur |
gestational age that separates a miscarriage from a stillbirth | |
| maternal_death_rate | rate / func |
hazard of a maternal death while pregnant (antepartum), e.g. ss.peryear(0.002) |
|
| p_maternal_death | float / bernoulli |
chance of a maternal death at delivery, e.g. 0.001 (agents only); can be given with maternal_death_rate, and set later, e.g. preg.pars.p_maternal_death.set(p=0.002) |
|
| infant_death_rate | rate / func |
hazard of death before the age of 1, for the children (a function of the sim and the agents is called only for the children aged 0 to 1); ss.mother(x) in it reads each child’s mother (so fetuses need not be agents) |
|
| p_breastfeed | bernoulli | chance a mother breastfeeds a newborn | |
| dur_breastfeed | dur / Dist |
duration of breastfeeding | |
| p_abortion | float |
chance a pregnancy ends in an abortion, at conception | |
| burnin | bool |
whether women are pregnant at the start, at the gestational ages they would have reached (default True; see burnin_plan()); agents only |
|
| fetal_agents | bool / str |
whether fetuses are agents from conception: ‘auto’ (the default), if something reads them (a prenatal network, or ss.mother() in a module); agents only |
'auto' |
| p_female | float / bernoulli |
the fraction of babies born female (default 0.5) | |
| children | int / Dist |
the number of children of each delivery: a number, or a distribution (e.g. ss.choice(a=[1, 2], p=[0.98, 0.02]) for twins) |
|
| preterm | ss.preterm |
the risk of preterm birth (see ss.preterm()): the thresholds, each woman’s relative risk, and the relative risk by her age |
|
| columns | dict |
if fertility_rate is a table, its column for each standard key, where they differ from the defaults (year='Time', age='AgeGrp', value='ASFR') |
None |
| pars | dict |
the same parameters, as a dict | None |
Examples
preg = ss.Pregnancy(fertility_rate=ss.peryear(0.08)) # 80 conceptions per 1,000 women a year
sim = ss.Sim(demographics=preg, n_agents=5000, start=2000, stop=2010, dt=ss.months(1)).run()
sim.results.pregnancy.conception.sum()
# Nigeria's age-specific fertility rates, from the UN
preg = ss.Pregnancy(fertility_rate='Nigeria')
# Lactational amenorrhea: fewer conceptions while breastfeeding, in the first 6 months
lam = ss.modify(preg.conception, multiply=0.1, who=preg.lactating & (preg.since_birth < ss.months(6)))Attributes
| Name | Description |
|---|---|
| infant_death | On the mother: a child of hers died before the age of 1 |
| live_birth | On the mother: at least one child born alive |
| loss | On the mother: an abortion, miscarriage, stillbirth, or infant death |
| since_birth | Time since the last live birth (inf if never); survives later losses |
Methods
| Name | Description |
|---|---|
| also_happened | A delivery happens to the fetuses as well as the mother, before they are born, so ss.on(preg.delivery) can remove a fetus as a stillbirth |
| attr | A value drawn for each woman each time a transition of the pregnancy happens to her, e.g. the gestational age of |
| burnin_plan | burnin=True (the default): women pregnant at the start. Each woman who could conceive has the chance of |
| compartmental_form | The small compartmental form, used only when a compartmental solver is named (solver='auto' runs a pregnancy as |
| compute_asfr | The age-specific fertility rates of the step (per 1000 women: deliveries by the mother’s age, over the women of |
| conception_rate | The hazard of conception, per year, for each agent (by UID) or each group: the fertility rate (in the year a |
| init_pre | Prepare the fertility rates, then initialize as a disease |
| lactate | At a live birth (agents): each mother breastfeeds, or breastfeeds again, with p_breastfeed, for dur_breastfeed from step ti |
| make_children | As agents, at a delivery: the children of the mothers (see ss.solvers.Agents.step_per()), and the events on the mothers |
| on_death | As agents: take the dead out of the states. The death of the last fetus of a pregnancy is a miscarriage or a |
| preterm_risk | At conception: each woman’s relative risk of preterm birth (rel_preterm), her baseline (rel_preterm) times the risk at her |
| run_callbacks | The callbacks (see add_callback()) see the step’s new pregnancies once their fetuses and preterm risk are set, so a callback’s set_delivery() is kept |
| set_delivery | Reschedule the deliveries of some pregnant women to a step (its index, as ti_exit_P reads; each scheduled exit of P is the delivery: losses are |
| step | The pregnancy’s transitions, at the start of the step, before the diseases’ |
also_happened
demographics.Pregnancy.also_happened(name, uids)A delivery happens to the fetuses as well as the mother, before they are born, so ss.on(preg.delivery) can remove a fetus as a stillbirth
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| name | str |
the name of the transition | required |
| uids | array |
the agents it happened to | required |
attr
demographics.Pregnancy.attr(name, dist, when='conception')A value drawn for each woman each time a transition of the pregnancy happens to her, e.g. the gestational age of her first antenatal visit, for conditions such as preg.P & (preg.P.time_in >= anc_ga): an ss.attr(dist, when=) of the pregnancy
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| name | str |
the name of the value, an array of the module | required |
| dist | Dist | what it is drawn from (durations are in the sim’s unit when read) | required |
| when | str / Transition |
the transition, by name (e.g. ‘conception’ or ‘delivery’) or as itself (preg.delivery) |
'conception' |
burnin_plan
demographics.Pregnancy.burnin_plan(engine)burnin=True (the default): women pregnant at the start. Each woman who could conceive has the chance of having conceived in the mean duration of a pregnancy before the start, at her conception hazard then (1 - exp(-h*dur)), at a step uniform over it, and is run forward by the pregnancy’s own transitions (abortion, losses, and delivery, with no births), so the start has the gestational ages and the first steps their deliveries. In the compartmental form, the same fraction of each group, less the abortions and the losses on the way, is spread evenly over gestation (see ss.solvers.Compartmental.backfill_burnin()).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| engine | Engine |
the engine running this module | required |
compartmental_form
demographics.Pregnancy.compartmental_form(sim)The small compartmental form, used only when a compartmental solver is named (solver='auto' runs a pregnancy as agents): the states NP and P, conception, abortion, maternal deaths, and the delivery at the end of dur_pregnancy (a fixed delay, or Erlang stages for a distribution), with n children per delivery (ss.birth(when=preg.delivery)). The losses do not read the gestational age (P.time_in): the loss rate is split between miscarriage and stillbirth by the fraction of the mean gestation below loss_threshold. It has no fetuses, no links between mothers and children, no breastfeeding, no preterm risk, and no deaths at delivery (p_maternal_death). Returns the note that says so
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| sim | Sim | the sim being initialized | required |
compute_asfr
demographics.Pregnancy.compute_asfr()The age-specific fertility rates of the step (per 1000 women: deliveries by the mother’s age, over the women of that age), and the TFR from them. As compartments, by the age of each group, so it needs an age stratification (otherwise NaN)
conception_rate
demographics.Pregnancy.conception_rate(sim)The hazard of conception, per year, for each agent (by UID) or each group: the fertility rate (in the year a pregnancy starting now would end, if given by year), rescaled from all fecund women to those not pregnant; 0 for anyone not fecund
An override can instead take (sim, uids) and return a rate for each of those agents (as agents only), e.g. ss.peryear(table[self.method[uids]]), rather than one for every slot of the raw arrays.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| sim | Sim | the sim | required |
init_pre
demographics.Pregnancy.init_pre(sim)Prepare the fertility rates, then initialize as a disease
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| sim | Sim | the sim being initialized | required |
lactate
demographics.Pregnancy.lactate(moms, ti)At a live birth (agents): each mother breastfeeds, or breastfeeds again, with p_breastfeed, for dur_breastfeed from step ti
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| moms | array |
the mothers who gave birth | required |
| ti | int |
the step of the birth | required |
make_children
demographics.Pregnancy.make_children(tr, parents, ti)As agents, at a delivery: the children of the mothers (see ss.solvers.Agents.step_per()), and the events on the mothers
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| tr | Transition | the transition that makes the children | required |
| parents | array |
the mothers | required |
| ti | int |
the step of the delivery | required |
on_death
demographics.Pregnancy.on_death(uids)As agents: take the dead out of the states. The death of the last fetus of a pregnancy is a miscarriage or a stillbirth for the mother, by gestational age; a mother who dies while pregnant loses her fetuses, counted the same way; and a death before the age of 1 is an infant death for the mother.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| uids | array |
the agents who died | required |
preterm_risk
demographics.Pregnancy.preterm_risk(uids, rel=None)At conception: each woman’s relative risk of preterm birth (rel_preterm), her baseline (rel_preterm) times the risk at her age (preterm.by_age), multiplies her probability of a preterm duration (below preterm.threshold), capped at 1; the durations within the preterm and the term ones keep their fractions. For dur_pregnancy as an ss.choice (the default), each duration is drawn so (one uniform number, by inverse transform), kept in weeks (dur_gestation, the gestational age at birth), and the delivery scheduled by it, as the engine schedules a dwell time (agents only)
Called again during a pregnancy, it draws the duration again: with rel, a relative risk for this draw on top of hers (e.g. an infection acquired while pregnant), which her baseline for later pregnancies does not keep. A delivery it would schedule in a step already past is taken in the next step (see set_delivery()).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| uids | uids | the women | required |
| rel | float / array |
a relative risk for this draw only, one number or one per woman | None |
Example
preg.preterm_risk(uids, rel=2.0) # Twice the risk of preterm birth, for the pregnancies these women have nowrun_callbacks
demographics.Pregnancy.run_callbacks()The callbacks (see add_callback()) see the step’s new pregnancies once their fetuses and preterm risk are set, so a callback’s set_delivery() is kept
set_delivery
demographics.Pregnancy.set_delivery(uids, ti, weeks=None)Reschedule the deliveries of some pregnant women to a step (its index, as ti_exit_P reads; each scheduled exit of P is the delivery: losses are rates, which compete with it), with the gestational age they will have then (dur_gestation): weeks if given, otherwise the weeks from conception to that step. A step already past is the next step, the first a delivery can be taken in.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| uids | array |
the women to reschedule | required |
| ti | int / array |
the step of the delivery, for all of them or for each | required |
| weeks | float / array |
the gestational age at delivery, in weeks | None |
step
demographics.Pregnancy.step()The pregnancy’s transitions, at the start of the step, before the diseases’
preterm
demographics.preterm(threshold=None, very_threshold=None, rel=None, by_age=None)The risk of preterm birth in ss.Pregnancy (preterm=ss.preterm(...)), for the options that are rarely changed
At conception, each woman’s relative risk of preterm birth (rel, drawn for her once, times the risk at her age, by_age) multiplies the probability of a duration of pregnancy below threshold (see ss.Pregnancy.preterm_risk()). Newborns below threshold are preterm (preg.preterm), and below very_threshold very preterm.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| threshold | dur |
the gestational age below which a birth is preterm (default 37 weeks) | None |
| very_threshold | dur |
the gestational age below which a birth is very preterm (default 32 weeks) | None |
| rel | float / Dist |
each woman’s baseline relative risk, from factors other than her age (default ss.normal(mean=1, std=0.1)) |
None |
| by_age | array |
the relative risk by the mother’s age: the upper edge of each age group, and the risk in it (default [[18, 35, 1000], [1.2, 1, 1.2]]: 1.2 below 18 and from 35) |
None |
Example
preg = ss.Pregnancy(preterm=ss.preterm(rel=ss.constant(1), by_age=[[18, 35, 1000], [1.5, 1, 1.3]]))Functions
| Name | Description |
|---|---|
| bare_rate | A crude rate of births or deaths of everyone (ss.birth(), ss.death()), read as ss.Births and ss.Deaths read theirs: a rate |
| data_columns | Which columns of a table of rates are which, for ss.utils.standardize_data(): the defaults, updated by columns= |
| lifetable_rates | Life tables (ss.lifetable), by year and sex (see ss.Deaths(lifetable=)), as a death rate per person for each age band of each: a table, and its columns |
| note_sparse | A note when rates by year that apply during the run are further apart than 5 years: each holds until the next label (see period_year()), which is right for data by period (the UN’s 5-year labels) but not for estimates for single years |
| period_year | The year of the data that applies at year: the latest at or before it, as ss.timeseries holds each value until the next |
| rate_per_of | How many people the rates of ss.Births, ss.Deaths, or ss.Pregnancy are per: rate_per as given, or else read |
| rate_rows | Rates by year (or year and sex), and by age, as NumPy, so that no step reads a dataframe |
| rate_size | The typical size of rates of births, deaths, or fertility, per year: the value of one rate (a typed rate per year, e.g. 30 |
| say_bare | Say the note from bare_rate(), if any: kept in sim.notes, and printed at verbose=2 |
| standardize_fertility_data | The fertility rates of a pregnancy module (fertility_rate= as given, with columns= for a table): a rate, or by year and age, with 1-year steps and a 0 past the last age group |
| yearly_rows | Rates from rate_rows() that are estimates for single years some years apart (a named place’s UN rates, every ten years), as a row for each year between, linearly interpolated, so none is held for a decade |
bare_rate
demographics.bare_rate(rate, name)A crude rate of births or deaths of everyone (ss.birth(), ss.death()), read as ss.Births and ss.Deaths read theirs: a rate above 1 per year, given as a bare number or typed, is per 1,000 people (e.g. 30, or ss.peryear(30)), and one of 1 or below is per person (e.g. 0.03, or ss.peryear(0.03); see rate_per_of()). A bare number is a rate per year. Anything else (e.g. a function) is returned as it is.
Returns the rate, per person, and a note saying how it was read (None for a typed rate per person), which is said with say_bare() once the module is in a sim: these are the usual ways to give these rates, so it is not a warning
A time series is read the same way, from the median of its values.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| rate | any |
the rate as given | required |
| name | str |
what it is, for the note (e.g. “rate”) | required |
Examples
rate, note = ss.demographics.bare_rate(30, 'rate') # ss.peryear(0.03): 30 per 1,000 people per year
rate, note = ss.demographics.bare_rate(ss.peryear(30), 'rate') # The same
rate, note = ss.demographics.bare_rate(ss.timeseries({2000: 40, 2030: 20}), 'rate') # ss.peryear(0.04) falling to ss.peryear(0.02)data_columns
demographics.data_columns(defaults, columns=None, sex_keys=None)Which columns of a table of rates are which, for ss.utils.standardize_data(): the defaults, updated by columns= of ss.Births, ss.Deaths, or ss.Pregnancy
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| defaults | dict |
the column of each standard key (year, age, sex, value) |
required |
| columns | dict |
the columns given, which replace the defaults of the same keys; sex_keys in it is the data’s label of each sex |
None |
| sex_keys | dict |
the default labels of the sexes, if the table has a sex column | None |
lifetable_rates
demographics.lifetable_rates(tables)Life tables (ss.lifetable), by year and sex (see ss.Deaths(lifetable=)), as a death rate per person for each age band of each: a table, and its columns
note_sparse
demographics.note_sparse(rows, years, sim, name)A note when rates by year that apply during the run are further apart than 5 years: each holds until the next label (see period_year()), which is right for data by period (the UN’s 5-year labels) but not for estimates for single years
period_year
demographics.period_year(years, year)The year of the data that applies at year: the latest at or before it, as ss.timeseries holds each value until the next
Rates labeled by the start of their period (e.g. the UN’s “2010” for 2010 to 2014) apply from that year until the next label. Before the first label, the first applies.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| years | array |
the years of the data (may repeat, e.g. once per sex) | required |
| year | float |
the year now | required |
rate_per_of
demographics.rate_per_of(per, rates, name)How many people the rates of ss.Births, ss.Deaths, or ss.Pregnancy are per: rate_per as given, or else read from their size. Rates of births, deaths, and conceptions are well below 1 per person per year, and well above 1 per 1,000, so rates above 1 per year (the median, for a table) are per 1,000 people, as data usually are (e.g. ss.Births(birth_rate=20), or ss.peryear(20)), and rates of 1 or below are per person (e.g. ss.peryear(0.02), or the UN’s death rates by age, mx). This is the same for a bare number, a typed rate, and a table. rate_per=1000 or rate_per=1 says which.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| per | float |
rate_per as given: None to read it from the rates, 1000 for per 1,000, 1 for per person |
required |
| rates | number / rate / timeseries / dataframe |
the rates, or rate data | required |
| name | str |
what the rates are, for the error (e.g. “birth_rate”) | required |
rate_rows
demographics.rate_rows(data)Rates by year (or year and sex), and by age, as NumPy, so that no step reads a dataframe
Returns a dict of the rows (a number, or an array by age) by the index of each row, e.g. (2010, ‘f’), the years, and the ages (the columns, if any); None if the rates are not a dataframe or series
rate_size
demographics.rate_size(rates)The typical size of rates of births, deaths, or fertility, per year: the value of one rate (a typed rate per year, e.g. 30 for ss.peryear(30)), or the median of several (a time series or a table), which a few large rates (e.g. deaths at the oldest ages) don’t sway; None if there are none to read (e.g. a function)
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| rates | number / rate / timeseries / series / dataframe |
the rates | required |
say_bare
demographics.say_bare(note, sim)Say the note from bare_rate(), if any: kept in sim.notes, and printed at verbose=2
standardize_fertility_data
demographics.standardize_fertility_data(mod)The fertility rates of a pregnancy module (fertility_rate= as given, with columns= for a table): a rate, or by year and age, with 1-year steps and a 0 past the last age group
yearly_rows
demographics.yearly_rows(found)Rates from rate_rows() that are estimates for single years some years apart (a named place’s UN rates, every ten years), as a row for each year between, linearly interpolated, so none is held for a decade