fpmod
Defines the FPmod class. This class inherits from the Starsim Pregnancy module, but has its own logic for how pregnancies are conceived.
Classes
| Name | Description |
|---|---|
| FPmod | Class for storing and updating FP-related events. Inherits from Starsim’s Pregnancy module. |
FPmod
fpmod.FPmod(pars=None, location=None, data=None, name='fp', **kwargs)Class for storing and updating FP-related events. Inherits from Starsim’s Pregnancy module.
Methods are organized in the order they are called during the simulation lifecycle: initialization → pre-step updates → pregnancy progression → delivery → conception → results.
Attributes
| Name | Description |
|---|---|
| end_tri1_uids | Return UIDs of those in the final timestep of their first trimester |
| end_tri2_uids | Return UIDs of those in the final timestep of their second trimester |
| postpartum | Boolean mask of women within the postpartum window (defined by dur_postpartum par). |
| susceptible | Sexually-active fertile women of childbearing age who are not pregnant. |
Methods
| Name | Description |
|---|---|
| bfilter | Shortcut for probability-based filtering: set dist probability and return matching UIDs. |
| bsplit | Shortcut for probability-based splitting: set dist probability and split UIDs into two groups. |
| check_infant_mortality | Check for probability of neonatal death (< 1 year of age). |
| check_sexually_active | Determine sexual activity status for all women each timestep. |
| compute_method_usage | Store the proportion of women using each contraceptive method. |
| finalize_results | Compute cumulative event counts after the simulation completes. |
| get_contra_eff | Build an efficacy array from each agent’s current contraceptive method. |
| get_lam_eff | Compute lactational amenorrhea (LAM) efficacy adjustment. |
| handle_abortion | Process abortion outcomes. |
| handle_loss | Shared handler for pregnancy losses (miscarriage, stillbirth, abortion, neonatal death). |
| init_intent_states | Initialize intent_to_use and fertility_intent states for women aged 15-49. |
| init_post | Initialize population states, then set fertility/contraception intent for all fecund women |
| init_results | Initialize result storage. |
| make_p_conceive | Calculate per-agent conception probability with FP-specific factors. |
| make_pregnancies | Create new pregnancies and disable contraception during pregnancy. |
| process_delivery | Save twin status before the parent resets it, then proceed with delivery. |
| process_prenatal_deaths | Extend parent’s prenatal death classification with FPsim-specific tracking. |
| progress_pregnancies | Advance ongoing pregnancies with gestational-age-dependent loss via p_loss. |
| record_ages | Record maternal ages at birth/stillbirth events and compute short birth intervals. |
| select_conceivers | Select women who conceive, then apply abortion logic. |
| set_rel_sus | Set relative susceptibility to pregnancy. |
| update_breastfeeding | Extend parent breastfeeding update to track cumulative duration. |
| update_mortality | Update infant, maternal, and stillbirth mortality rates for the current year. |
| update_results | Per-step result recording. |
| update_time_to_choose | Initialize the counter for when women will first choose a contraceptive method. |
| updates_pre | Pre-step state updates, run at the beginning of each timestep. |
bfilter
fpmod.FPmod.bfilter(dist, uids, probs)Shortcut for probability-based filtering: set dist probability and return matching UIDs.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| dist | a Bernoulli distribution object | required | |
| uids | UIDs to filter | required | |
| probs | probability values to set on the distribution | required |
Returns
| Name | Type | Description |
|---|---|---|
| ss.uids: UIDs that passed the filter |
bsplit
fpmod.FPmod.bsplit(dist, uids, probs)Shortcut for probability-based splitting: set dist probability and split UIDs into two groups.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| dist | a Bernoulli distribution object | required | |
| uids | UIDs to split | required | |
| probs | probability values to set on the distribution | required |
Returns
| Name | Type | Description |
|---|---|---|
| tuple | (true_uids, false_uids) — UIDs that matched and those that didn’t |
check_infant_mortality
fpmod.FPmod.check_infant_mortality(uids)Check for probability of neonatal death (< 1 year of age).
Uses age-adjusted mortality rates to determine which newborns die.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| uids | UIDs of mothers with live births | required |
Returns
| Name | Type | Description |
|---|---|---|
| tuple | (mothers_of_nnd, nnds) — mother UIDs and newborn UIDs that died |
check_sexually_active
fpmod.FPmod.check_sexually_active(uids=None)Determine sexual activity status for all women each timestep.
Categorizes women into parous (have had a birth) and non-parous groups. Parous women with a recorded live birth get birth spacing preferences applied to their sexual activity rate. Non-parous women past debut age get age-based rates. Pre-debut women are not touched (stay inactive).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| uids | UIDs to check (should be non-pregnant fecund women) | None |
compute_method_usage
fpmod.FPmod.compute_method_usage()Store the proportion of women using each contraceptive method.
Filters to women of method-eligible age, then computes the distribution across method indices and stores in self.method_mix[:, ti].
finalize_results
fpmod.FPmod.finalize_results()Compute cumulative event counts after the simulation completes.
Adds cum_{key} results for each event type in fpd.event_counts, and for the parent Pregnancy results in fpd.inherited_counts (cum_births, cum_stillbirths, cum_miscarriages, cum_pregnancies, cum_maternal_deaths), which the parent does not accumulate itself.
get_contra_eff
fpmod.FPmod.get_contra_eff()Build an efficacy array from each agent’s current contraceptive method.
Returns
| Name | Type | Description |
|---|---|---|
| np.ndarray: per-agent contraceptive efficacy (0 to 1) |
get_lam_eff
fpmod.FPmod.get_lam_eff()Compute lactational amenorrhea (LAM) efficacy adjustment.
LAM candidates are breastfeeding, susceptible women within the data-defined postpartum window. LAM is switched off for anyone not breastfeeding or over the maximum LAM duration.
Returns
| Name | Type | Description |
|---|---|---|
| np.ndarray: per-agent LAM efficacy (0 or LAM_efficacy parameter) |
handle_abortion
fpmod.FPmod.handle_abortion(uids)Process abortion outcomes.
Called prior to make_embryos/make_pregnancies, so no pregnancy state reset is needed. Increments abortion and pregnancy counters, records the age at abortion, and updates results.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| uids | UIDs of women who aborted | required |
handle_loss
fpmod.FPmod.handle_loss(uids)Shared handler for pregnancy losses (miscarriage, stillbirth, abortion, neonatal death).
Triggers three actions
- Schedule contraceptive method update for the next timestep
- Schedule breastfeeding to stop next timestep
- Request death for unborn/newborn children
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| uids | UIDs of mothers who experienced a loss | required |
init_intent_states
fpmod.FPmod.init_intent_states(uids)Initialize intent_to_use and fertility_intent states for women aged 15-49.
Uses age-specific probability distributions from the contraception connector’s intent_pars data. If no data is available, sets defaults (False for both states).
Fertility intent categories: 0=cannot-get-pregnant, 1=no, 2=yes.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| uids | UIDs of agents to initialize (filtered to eligible 15-49 females) | required |
init_post
fpmod.FPmod.init_post()Initialize population states, then set fertility/contraception intent for all fecund women
init_results
fpmod.FPmod.init_results()Initialize result storage.
Adds FP-specific results on top of the parent Pregnancy results: - Event counts (pregnancies, births, stillbirths, etc.) with cumulative versions - People counts (n_fecund, n_on_contra, etc.) - Rates (IMR, proportion of short-interval births) - Method mix array (stored separately as a 2D array, not a Result)
make_p_conceive
fpmod.FPmod.make_p_conceive(filter_uids=None)Calculate per-agent conception probability with FP-specific factors.
Steps
- Get individual exposure risk via rel_sus (contraception and LAM applied)
- Apply individual fecundity variation and age-specific fecundity
- Adjust for nulliparity
- Apply exposure factors from calibration (overall, by parity, by age)
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| filter_uids | optional UIDs to restrict to (intersected with susceptible) | None |
Returns
| Name | Type | Description |
|---|---|---|
| np.ndarray: per-agent conception probability for this timestep |
make_pregnancies
fpmod.FPmod.make_pregnancies(uids)Create new pregnancies and disable contraception during pregnancy.
Calls the parent to set pregnancy states, then resets contraception (on_contra = False, method = 0) for the newly pregnant women.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| uids | UIDs of women who conceived | required |
Returns
| Name | Type | Description |
|---|---|---|
| np.ndarray: embryo counts per mother (from parent) |
process_delivery
fpmod.FPmod.process_delivery(mother_uids, newborn_uids)Save twin status before the parent resets it, then proceed with delivery.
The parent’s process_delivery sets carrying_multiple to False before calling _post_delivery, so we capture the twin status here for use in _do_stillbirths.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| mother_uids | UIDs of mothers delivering | required | |
| newborn_uids | UIDs of newborn agents | required |
process_prenatal_deaths
fpmod.FPmod.process_prenatal_deaths(death_uids)Extend parent’s prenatal death classification with FPsim-specific tracking.
The parent classifies deaths by gestational age (miscarriage vs stillbirth) and updates results. We additionally record ages, update timing states, and trigger handle_loss for contraception/breastfeeding updates.
progress_pregnancies
fpmod.FPmod.progress_pregnancies()Advance ongoing pregnancies with gestational-age-dependent loss via p_loss.
Sets p_loss dynamically before calling the parent: - First trimester: per-timestep probability derived from age-specific miscarriage rates - Second/third trimester: per-timestep probability derived from year- and age-adjusted stillbirth rates
The parent applies p_loss to all ongoing (non-delivering) pregnancies and request_death’s unborn children. Classification (miscarriage vs stillbirth) happens later in process_prenatal_deaths based on gestational age.
record_ages
fpmod.FPmod.record_ages(stillborn, single, twin)Record maternal ages at birth/stillbirth events and compute short birth intervals.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| stillborn | UIDs of mothers with stillbirths | required | |
| single | UIDs of mothers with singleton live births | required | |
| twin | UIDs of mothers with twin live births | required |
select_conceivers
fpmod.FPmod.select_conceivers(uids=None)Select women who conceive, then apply abortion logic.
Calls the parent to determine initial conceivers based on conception probability, then splits them into abortions and continuing pregnancies. Tracks method failures (women who conceived while on contraception).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| uids | UIDs to consider (default: susceptible women) | None |
Returns
| Name | Type | Description |
|---|---|---|
| ss.uids: UIDs of women with continuing pregnancies (after abortions removed) |
set_rel_sus
fpmod.FPmod.set_rel_sus()Set relative susceptibility to pregnancy.
Formula: rel_sus = (1 - method_eff) * (1 - lam_eff) for susceptible women, 0 otherwise. This combines contraceptive efficacy and lactational amenorrhea effects.
update_breastfeeding
fpmod.FPmod.update_breastfeeding(uids)Extend parent breastfeeding update to track cumulative duration.
When women stop breastfeeding, adds their current breastfeeding duration to dur_breastfeed_total (lifetime cumulative).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| uids | UIDs of breastfeeding women to check | required |
update_mortality
fpmod.FPmod.update_mortality()Update infant, maternal, and stillbirth mortality rates for the current year.
Reads year-specific rates from the parameter data and stores them in self.mortality_probs (for infant and stillbirth) and updates the maternal death distribution directly.
update_results
fpmod.FPmod.update_results()Per-step result recording.
Extends the parent to add: - Total births (live births plus stillbirths) - Infant mortality rate (IMR) = infant_deaths / births * 1000 - Method mix via compute_method_usage
update_time_to_choose
fpmod.FPmod.update_time_to_choose(uids=None)Initialize the counter for when women will first choose a contraceptive method.
Computes the number of timesteps until each woman’s fated sexual debut age, then sets ti_contra accordingly. Women past their debut age get ti_contra = 0 (choose immediately).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| uids | UIDs to initialize (default: all alive agents) | None |
updates_pre
fpmod.FPmod.updates_pre(uids=None, upper_age=None)Pre-step state updates, run at the beginning of each timestep.
This runs prior to calculating pregnancy exposure, advancing pregnancies, adding new pregnancies, or determining delivery outcomes. Steps performed: 1. Update fecundity and mortality rates for the current year 2. Set sexual activity status (postpartum and non-postpartum) 3. Initialize contraception timing for new agents 4. Initialize fertility intent for women entering the 15-49 age range 5. Update contraceptive intent and method choices
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| uids | UIDs to update (default: all female agents up to upper_age) | None |
|
| upper_age | float | maximum age for filtering UIDs | None |