tlo.methods.contraception module

class Contraception(name=None, resourcefilepath=None, use_healthsystem=True, run_update_contraceptive=True)

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.

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.

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.
Interventions_Pop	DATA_FRAME	Pop (population scale contraception intervention) intervention multiplier.
Interventions_PPFP	DATA_FRAME	PPFP (post-partum family planning) intervention multiplier.
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	LIST	The number of days between successive family planning appointments for women that are maintaining the use of a method (for each method insorted(self.states_that_may_require_HSI_to_maintain_on), i.e.[IUD, implant, injections, other_modern, pill]).
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).
use_interventions	BOOL	if True: FP interventions (pop & ppfp) are simulated from the date ‘interventions_start_date’, if False: FP interventions (pop & ppfp) are not simulated.
interventions_start_date	DATE	The date since which the FP interventions (pop & ppfp) are implemented, if at all (ie, if use_interventions==True

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 method-specific parameter days_between_appts_for_maintenance.

Class attributes:

ADDITIONAL_DEPENDENCIES : {‘Labour’, ‘Hiv’}

INIT_DEPENDENCIES : {‘Demography’}

METADATA : {}

OPTIONAL_INIT_DEPENDENCIES : {‘HealthSystem’}

__annotations__ : {}

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

contraceptives_initiated_with_additional_items : {‘injections’, ‘IUD’, ‘female_sterilization’, ‘implant’, ‘pill’}

Functions (defined or overridden in class Contraception):

__init__(name=None, resourcefilepath=None, use_healthsystem=True, run_update_contraceptive=True)

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)

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

pre_initialise_population()

Process parameters before initialising population and simulation

initialise_population(population)

Set initial values for properties

initialise_simulation(sim)

• 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)

• 1. Formally end the pregnancy

• 2. Initialise properties for the newborn

end_pregnancy(person_id)

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()

Process parameters that have been read-in.

update_params_for_interventions()

Updates process parameters to enable FP interventions.

select_contraceptive_following_birth(mother_id, mother_age)

Initiation of mother’s contraception after birth.

get_item_code_for_each_contraceptive()

Get the item_code for each contraceptive and for contraceptive initiation.

schedule_batch_of_contraceptive_changes(ids, old, new)

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)

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

schedule_births_for_first_9_months()

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. When initialising population ensured person_id=0 is a man, so can safely exclude person_id=0 from choice of direct birth mothers without loss of generality.

on_simulation_end()

Do tasks at the end of the simulation: Raise warning and enter to log about women_ids who are sterilized when under 30 years old.

class DirectBirth(module, person_id)

Do birth, with the mother_id set to person_id*(-1) to reflect that this was a DirectBirth.

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.

• priority – a keyword-argument to set the priority (see Priority enum)

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

Functions (defined or overridden in class DirectBirth):

__init__(module, person_id)

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.

• priority – a keyword-argument to set the priority (see Priority enum)

apply(person_id)

Apply this event to the given target.

Must be implemented by subclasses.

Parameters:

target – the target of the event

class ContraceptionPoll(module, run_do_pregnancy=True, run_update_contraceptive=True)

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

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)

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

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class ContraceptionPoll):

__init__(module, run_do_pregnancy=True, run_update_contraceptive=True)

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)

Determine who will become pregnant and update contraceptive method.

update_contraceptive()

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

initiate(individuals_not_using: Index)

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

discontinue_switch_or_continue(individuals_using: Index)

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()

Determine who will become pregnant

pregnancy_for_those_on_contraceptive()

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()

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

set_new_pregnancy(women_id: list)

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

class ContraceptionLoggingEvent(module)

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

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

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class ContraceptionLoggingEvent):

__init__(module)

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

apply(population)

Apply this event to the given target.

This is a no-op; subclasses should override this method.

Parameters:

target – the target of the event

class HSI_Contraception_FamilyPlanningAppt(module, person_id, new_contraceptive)

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

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.

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

Class attributes:

EXPECTED_APPT_FOOTPRINT : <property object at 0x129030c20>

__annotations__ : {}

Functions (defined or overridden in class HSI_Contraception_FamilyPlanningAppt):

__init__(module, person_id, new_contraceptive)

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)

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

post_apply_hook()

Do any required processing after apply() completes.

reschedule()

Schedule for this same HSI_Event to occur tomorrow.

never_ran()

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

class StartInterventions(module)

This event is run by Contraception module exactly once when interventions are introduced, or never if interventions are not used. If run, it updates parameters changed to reflect the FP interventions to be used from now on.

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.

• priority – a keyword-argument to set the priority (see Priority enum)

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

Class attributes:

__annotations__ : {}

Functions (defined or overridden in class StartInterventions):

__init__(module)

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.

• priority – a keyword-argument to set the priority (see Priority enum)

apply(population)

Apply this event to the given target.

Must be implemented by subclasses.

Parameters:

target – the target of the event

class SimplifiedPregnancyAndLabour(*args)

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.

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.

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 : {}

__annotations__ : {}

Functions (defined or overridden in class SimplifiedPregnancyAndLabour):

__init__(*args)

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)

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)

Set our property values for the initial population.

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.

By default, all Property``s in ``self.PROPERTIES will have their columns in the population dataframe set to the default value.

Modules that wish to implement this behaviour do not need to implement this method, it will be inherited automatically. Modules that wish to perform additional steps during the initialise_population stage should reimplement this method and call

`python super().initialise_population(population=population) `

at the beginning of the method, then proceed with their additional steps. Modules that do not wish to inherit this default behaviour should re-implement initialise_population without the call to super() above.

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 in the simulation.

initialise_simulation(*args)

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)

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_id – the person id for the mother of this child (can be -1 if the mother is not identified).

• child_id – the person id of new child

set_date_of_labour(person_id)

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)

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

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.

• priority – a keyword-argument to set the priority (see Priority enum)

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

Functions (defined or overridden in class EndOfPregnancyEvent):

__init__(module, person_id, live_birth)

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.

• priority – a keyword-argument to set the priority (see Priority enum)

apply(person_id)

End pregnancy and do live birth if needed