tlo.methods.contraception module

class Contraception(name=None, resourcefilepath=None, use_healthsystem=True)[source]

Contraception module covering baseline contraception methods use, failure (i.e., pregnancy), Switching contraceptive methods, and discontinuation rates by age. Calibration is done in two stages: (i) A scaling factor on the risk of pregnancy (scaling_factor_on_monthly_risk_of_pregnancy) is used to induce the

correct number of age-specific births initially, given the initial pattern of contraceptive use;

(ii) Trends over time in the risk of starting (time_age_trend_in_initiation) and stopping (time_age_trend_in_stopping) of contraceptives are used to induce the correct trend in the number of births.

Bases: tlo.core.Module

PARAMETERS:

Item

Type

Description

Method_Use_In_2010

DATA_FRAME

Proportion of women using each method in 2010, by age.

Pregnancy_NotUsing_In_2010

DATA_FRAME

Probability per year of a women not on contraceptive becoming pregnant, by age.

Pregnancy_NotUsing_HIVeffect

DATA_FRAME

Relative probability of becoming pregnant whilst not using a a contraceptive for HIV-positive women compared to HIV-negative women.

Failure_ByMethod

DATA_FRAME

Probability per month of a women on a contraceptive becoming pregnant, by method

rr_fail_under25

REAL

The relative risk of becoming pregnant whilst using a contraceptive for woman younger than 25 years compared to older women.

Initiation_ByMethod

DATA_FRAME

Probability per month of a women who is not using any contraceptive method of starting use of a method, by method.

Initiation_ByAge

DATA_FRAME

The effect of age on the probability of starting use of contraceptive (add one for multiplicative effect).

Initiation_AfterBirth

DATA_FRAME

The probability of a woman starting a contraceptive immidiately after birth, by method.

Discontinuation_ByMethod

DATA_FRAME

The probability per month of discontinuing use of a method, by method.

Discontinuation_ByAge

DATA_FRAME

The effect of age on the probability of discontinuing use of contraceptive (add one for multiplicative effect).

Prob_Switch_From

DATA_FRAME

The probability per month that a women switches from one form of contraceptive to another, conditional that she will not discontinue use of the method.

Prob_Switch_From_And_To

DATA_FRAME

The probability of switching to a new method, by method, conditional that the woman will switch to a new method.

days_between_appts_for_maintenance

INT

The number of days between successive family planning appointments for women that are maintaining the use of a method.

age_specific_fertility_rates

DATA_FRAME

Data table from official source (WPP) for age-specific fertility rates and calendar period

scaling_factor_on_monthly_risk_of_pregnancy

LIST

Scaling factor (by age-group: 15-19, 20-24, …, 45-49) on the monthly risk of pregnancy and contraceptive failure rate. This value is found through calibration so that, at the beginning of the simulation, the age-specific monthly probability of a woman having a live birth matches the WPP age-specific fertility rate value for the same year.

max_number_of_runs_of_hsi_if_consumable_not_available

INT

The maximum number of time an HSI can run (repeats occur if the consumables are not available

max_days_delay_between_decision_to_change_method_and_hsi_scheduled

INT

The maximum delay (in days) between the decision for a contraceptive to change and the `topen`date of the HSI that is scheduled to effect the change (when using the healthsystem),

PROPERTIES:

Item

Type

Description

co_contraception

CATEGORICAL

Current contraceptive method. Possible values are: [IUD, female_sterilization, implant, injections, male_condom, not_using, other_modern, other_traditional, periodic_abstinence, pill, withdrawal, ]

is_pregnant

BOOL

Whether this individual is currently pregnant

date_of_last_pregnancy

DATE

Date that the most recent or current pregnancy began.

co_unintended_preg

BOOL

Whether the most recent or current pregnancy was unintended.

co_date_of_last_fp_appt

DATE

The date of the most recent Family Planning appointment. This is used to determine if a Family Planning appointment is needed to maintain the person on their current contraceptive. If the person is to maintain use of the current contraceptive, they will have an HSI only if the days elapsed since this value exceeds the parameter days_between_appts_for_maintenance.

Class attributes:

ADDITIONAL_DEPENDENCIES : {‘Labour’, ‘Hiv’}

INIT_DEPENDENCIES : {‘Demography’}

METADATA : {}

OPTIONAL_INIT_DEPENDENCIES : {‘HealthSystem’}

all_contraception_states : {‘IUD’, ‘male_condom’, ‘female_sterilization’, ‘other_traditional’, ‘withdrawal’, ‘implant’, ‘injections’, ‘pill’, ‘other_modern’, ‘not_using’, ‘periodic_abstinence’}

Functions (defined or overridden in class Contraception):

__init__(name=None, resourcefilepath=None, use_healthsystem=True)[source]

Construct a new disease module ready to be included in a simulation.

Initialises an empty parameters dictionary and module-specific random number generator.

Parameters

name – the name to use for this module. Defaults to the concrete subclass’ name.

read_parameters(data_folder)[source]

Import the relevant sheets from the ResourceFile (excel workbook) and declare values for other parameters.

pre_initialise_population()[source]

Process parameters before initialising population and simulation

initialise_population(population)[source]

Set initial values for properties

initialise_simulation(sim)[source]
  • Schedule the ContraceptionPoll and ContraceptionLoggingEvent

  • Retrieve the consumables codes for the consumables used

  • Create second random number generator

  • Schedule births to occur during the first 9 months of the simulation

on_birth(mother_id, child_id)[source]
    1. Formally end the pregnancy

    1. Initialise properties for the newborn

end_pregnancy(person_id)[source]

End the pregnancy. Reset pregnancy status and may initiate a contraceptive method. This is called by on_birth in this module and by Labour/Pregnancy modules for births that do result in live birth.

process_params()[source]

Process parameters that have been read-in.

select_contraceptive_following_birth(mother_id)[source]

Initiation of mother’s contraception after birth.

get_item_code_for_each_contraceptive()[source]

Get the item_code for each contraceptive

schedule_batch_of_contraceptive_changes(ids, old, new)[source]

Enact the change in contraception, either through editing properties instantaneously or by scheduling HSI. ids: pd.Index of the woman for whom the contraceptive state is changing old: iterable giving the corresponding contraceptive state being switched from new: iterable giving the corresponding contraceptive state being switched to

It is assumed that even with the option self.use_healthsystem=True that switches to certain methods do not require the use of HSI (these are not in states_that_may_require_HSI_to_switch_to).

do_and_log_individual_contraception_change(woman_id: int, old, new)[source]

Implement and then log a start / stop / switch of contraception.

schedule_births_for_first_9_months()[source]

Schedule births to occur during the first 9 months of the simulation. This is necessary because at initiation no women are pregnant, so the first births generated endogenously (through pregnancy -> gestation -> labour) occur after 9 months of simulation time. This method examines age-specific fertility rate data and causes there to be the appropriate number of births, scattered uniformly over the first 9 months of the simulation. These are

“direct live births” that are not subjected to any of the processes (e.g. risk of loss of pregnancy, or risk of death to mother) represented in the PregnancySupervisor, CareOfWomenDuringPregnancy or Labour.

class DirectBirth(module, person_id)[source]

Do birth, with the mother_id set to -1 (we do not associate the child with a particular mother).

Bases: tlo.events.Event, tlo.events.IndividualScopeEventMixin

Functions (defined or overridden in class DirectBirth):

__init__(module, person_id)[source]

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.

apply(person_id)[source]

Apply this event to the given person.

Must be implemented by subclasses.

Parameters

person_id – the person the event happens to

class ContraceptionPoll(module, run_do_pregnancy=True, run_update_contraceptive=True)[source]

The regular poll (monthly) for the Contraceptive Module: * Determines contraceptive start / stops / switches * Determines the onset of pregnancy

Bases: tlo.events.RegularEvent, tlo.events.Event, tlo.events.PopulationScopeEventMixin

Functions (defined or overridden in class ContraceptionPoll):

__init__(module, run_do_pregnancy=True, run_update_contraceptive=True)[source]

Create a new regular event.

Parameters
  • module – the module that created this event

  • frequency (pandas.tseries.offsets.DateOffset) – the interval from one occurrence to the next (must be supplied as a keyword argument)

apply(population)[source]

Determine who will become pregnant and update contraceptive method.

update_contraceptive()[source]

Determine women that will start, stop or switch contraceptive method.

initiate(individuals_not_using: pandas.core.indexes.base.Index)[source]

Check all females not using contraception to determine if contraception starts (i.e. category should change from ‘not_using’ to something else) with reference to initiation_rate1 (irate_1).

discontinue_switch_or_continue(individuals_using: pandas.core.indexes.base.Index)[source]

Check all females currently using contraception to determine if they discontinue it, switch to a different one, or keep using the same one.

update_pregnancy()[source]

Determine who will become pregnant

pregnancy_for_those_on_contraceptive()[source]

Look across all women who are using a contraception method to determine if they become pregnant (i.e., the method fails).

pregnancy_for_those_not_on_contraceptive()[source]

Look across all woman who are not using a contraceptive to determine who will become pregnant.

set_new_pregnancy(women_id: list)[source]

Effect that these women are now pregnancy and enter to the log

class ContraceptionLoggingEvent(module)[source]

Bases: tlo.events.RegularEvent, tlo.events.Event, tlo.events.PopulationScopeEventMixin

Functions (defined or overridden in class ContraceptionLoggingEvent):

__init__(module)[source]

Logs state of contraceptive usage in the population at a point in time.

apply(population)[source]

Apply this event to the population.

Must be implemented by subclasses.

Parameters

population – the current population

class HSI_Contraception_FamilyPlanningAppt(module, person_id, new_contraceptive)[source]

HSI event for the starting a contraceptive method, maintaining use of a method of a contraceptive, or switching between contraceptives.

Bases: tlo.methods.healthsystem.HSI_Event, tlo.events.IndividualScopeEventMixin

Functions (defined or overridden in class HSI_Contraception_FamilyPlanningAppt):

__init__(module, person_id, new_contraceptive)[source]

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.

apply(person_id, squeeze_factor)[source]

If the relevant consumable is available, do change in contraception and log it

reschedule()[source]

Schedule for this same HSI_Event to occur tomorrow.

never_ran()[source]

If this HSI never ran, the person defaults to “not_using” a contraceptive.

class SimplifiedPregnancyAndLabour(*args)[source]

Simplified module to replace Labour, ‘PregnancySupervisor` and other associated module, for use in testing/calibrating the Contraception Module. The module calls itself Labour and provides the method set_date_of_labour, which is called by the Contraception Module at the onset of pregnancy. It schedules an event for the end of the pregnancy (approximately 9 months later) which may or may not result in a live birth.

Bases: tlo.core.Module

PARAMETERS:

Item

Type

Description

prob_live_birth

REAL

Probability that a pregnancy results in a live birth.

PROPERTIES:

Item

Type

Description

la_currently_in_labour

BOOL

whether this woman is currently in labour

la_has_had_hysterectomy

BOOL

whether this woman has had a hysterectomy as treatment for a complication of labour, and therefore is unable to conceive

la_is_postpartum

BOOL

Whether a woman is in the postpartum period, from delivery until day +42 (6 weeks)

ps_ectopic_pregnancy

CATEGORICAL

Whether a woman is experiencing ectopic pregnancy and its current state. Possible values are: [none, not_ruptured, ruptured, ]

Class attributes:

ALTERNATIVE_TO : {‘Labour’}

INIT_DEPENDENCIES : {‘Contraception’}

METADATA : {}

Functions (defined or overridden in class SimplifiedPregnancyAndLabour):

__init__(*args)[source]

Construct a new disease module ready to be included in a simulation.

Initialises an empty parameters dictionary and module-specific random number generator.

Parameters

name – the name to use for this module. Defaults to the concrete subclass’ name.

read_parameters(*args)[source]

Read parameter values from file, if required.

Must be implemented by subclasses.

Parameters

data_folder – path of a folder supplied to the Simulation containing data files. Typically modules would read a particular file within here.

initialise_population(population)[source]

Set our property values for the initial population.

Must be implemented by subclasses.

This method is called by the simulation when creating the initial population, and is responsible for assigning initial values, for every individual, of those properties ‘owned’ by this module, i.e. those declared in its PROPERTIES dictionary.

TODO: We probably need to declare somehow which properties we ‘read’ here, so the simulation knows what order to initialise modules in!

Parameters

population – the population of individuals

initialise_simulation(*args)[source]

Get ready for simulation start.

Must be implemented by subclasses.

This method is called just before the main simulation loop begins, and after all modules have read their parameters and the initial population has been created. It is a good place to add initial events to the event queue.

on_birth(mother_id, child_id)[source]

Initialise our properties for a newborn individual.

Must be implemented by subclasses.

This is called by the simulation whenever a new person is born.

Parameters
  • mother – the mother for this child (can be -1 if the mother is not identified).

  • child – the new child

set_date_of_labour(person_id)[source]

This is a drop-in replacement for the method in Labour that triggers the processes that determine the outcome of a pregnancy.

class EndOfPregnancyEvent(module, person_id, live_birth)[source]

This event signals the end of the pregnancy, which may or may not result in a live-birth

Bases: tlo.events.Event, tlo.events.IndividualScopeEventMixin

Functions (defined or overridden in class EndOfPregnancyEvent):

__init__(module, person_id, live_birth)[source]

Create a new event.

Note that just creating an event does not schedule it to happen; that must be done by calling Simulation.schedule_event.

Parameters

module – the module that created this event. All subclasses of Event take this as the first argument in their constructor, but may also take further keyword arguments.

apply(person_id)[source]

End pregnancy and do live birth if needed