interventions
Specify the core interventions available in FPsim. Other interventions can be defined by the user by inheriting from these classes.
Classes
| Name | Description |
|---|---|
| add_method | Intervention to add a new contraceptive method to the simulation at a specified time. |
| change_initiation | Intervention that modifies the outcomes of whether women are on contraception or not |
| change_initiation_prob | Intervention to change the probabilty of contraception use trend parameter in |
| change_par | Change a parameter at a specified point in time. |
| change_people_state | Intervention to modify values of a People’s boolean state at one specific |
| method_switching | Intervention that causes women to switch from specific contraceptive methods to a target method. |
| update_methods | Intervention to modify method efficacy and/or switching matrix. |
add_method
interventions.add_method(
year=None,
method=None,
method_pars=None,
copy_from=None,
split_shares=None,
verbose=True,
**kwargs,
)Intervention to add a new contraceptive method to the simulation at a specified time.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| year | float | The year at which to activate the new method | None |
| method | Method |
A Method object defining the new contraceptive method. If None, the method will be copied from the source method (specified by copy_from). |
None |
| method_pars | dict | Dictionary of parameters to update the method attributes. If provided, these values will override corresponding attributes in the method object (whether it was provided directly or copied from source). If None, defaults to empty dict. | None |
| copy_from | str | Name of the existing method to copy switching probabilities from. Also used as the source method when method=None. |
None |
| split_shares | float | If provided, % who would have chosen the ‘copy_from’ method and now choose the new method | None |
| verbose | bool | Whether to print messages when method is activated (default True) | True |
Examples::
# Using a Method object directly
new_method = fp.Method(name='new_impl', label='New Implant', efficacy=0.999,
dur_use=ss.lognorm_ex(ss.years(3), ss.years(0.5)), modern=True)
intv = fp.add_method(year=2010, method=new_method, copy_from='impl')
# Copying from source method (method=None, method_pars=None)
# Creates a copy of 'impl' with name 'impl_copy'
intv = fp.add_method(year=2010, copy_from='impl')
# Copying from source and overriding properties
intv = fp.add_method(year=2010, method_pars={'name': 'new_inj', 'efficacy': 0.995},
copy_from='inj')
# Using method object and overriding properties with method_pars
base_method = fp.Method(name='new_method', efficacy=0.90)
intv = fp.add_method(year=2010, method=base_method,
method_pars={'efficacy': 0.998}, copy_from='impl')Methods
| Name | Description |
|---|---|
| finalize | Report summary statistics about the new method usage. |
| init_pre | Initialize the intervention before the simulation starts. |
| step | At the specified year, copy switching probabilities to make the method available. |
finalize
interventions.add_method.finalize()Report summary statistics about the new method usage.
init_pre
interventions.add_method.init_pre(sim)Initialize the intervention before the simulation starts. This registers the new method but does not activate it yet.
step
interventions.add_method.step()At the specified year, copy switching probabilities to make the method available.
change_initiation
interventions.change_initiation(
years=None,
eligibility=None,
perc=0.0,
annual=True,
force_theoretical=False,
age_range=None,
perc_of_eligible=False,
target_method=None,
final_perc=None,
verbose=False,
**kwargs,
)Intervention that modifies the outcomes of whether women are on contraception or not Select a proportion of women and sets them on a contraception method.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| years | (list, float) | The year we want to start the intervention. if years is None, uses start and end years of sim as defaults if years is a number or a list with a single element, eg, 2000.5, or [2000.5], this is interpreted as the start year of the intervention, and the end year of intervention will be the end of the simulation | None |
| eligibility | callable | callable that returns a filtered version of people eligible to receive the intervention | None |
| perc | float | a value between 0 and 1 indicating the x% extra of women who will be made to select a contraception method. The proportion or % is with respect to the number of women who were on contraception: - the previous year (12 months earlier)? - at the beginning of the intervention. | 0.0 |
| annual | bool | whether the increase, perc, represents a “per year” increase. | True |
| age_range | tuple | (min_age, max_age) to restrict eligibility. If provided, only women in this age range are eligible. Use with perc_of_eligible=True. | None |
| perc_of_eligible | bool | If True, perc is percentage of eligible women (not of current users). Use this with age_range for age-targeted scale-up scenarios. | False |
| target_method | str / int | Method name or index for new users. If None, uses natural method distribution. | None |
| final_perc | float | If provided, perc will scale linearly from initial perc to final_perc over the intervention period. Enables scale-up scenarios. | None |
Methods
| Name | Description |
|---|---|
| check_eligibility | Select eligible who is eligible |
check_eligibility
interventions.change_initiation.check_eligibility()Select eligible who is eligible
change_initiation_prob
interventions.change_initiation_prob(
year=None,
prob_use_intercept=0.0,
verbose=False,
**kwargs,
)Intervention to change the probabilty of contraception use trend parameter in contraceptive choice modules that have a logistic regression model.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| year | float | The year in which this intervention will be applied | None |
| prob_use_intercept | float | A number that changes the intercept in the logistic regression model | 0.0 |
Methods
| Name | Description |
|---|---|
| step | Applies the changes to efficacy or contraceptive uptake changes if it is the specified year |
step
interventions.change_initiation_prob.step()Applies the changes to efficacy or contraceptive uptake changes if it is the specified year based on scenario specifications.
change_par
interventions.change_par(par, years=None, vals=None, verbose=False, **kwargs)Change a parameter at a specified point in time.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| par | str | the parameter to change | required |
| years | float / arr |
the year(s) at which to apply the change | None |
| vals | any | a value or list of values to change to (if a list, must have the same length as years); or a dict of year:value entries | None |
If any value is 'reset', reset to the original value.
Example::
ec0 = fp.change_par(par='exposure_factor', years=[2000, 2010], vals=[0.0, 2.0]) # Reduce exposure factor
ec0 = fp.change_par(par='exposure_factor', vals={2000:0.0, 2010:2.0}) # Equivalent way of writing
sim = fp.Sim(interventions=ec0).run()change_people_state
interventions.change_people_state(
state_name,
new_val,
years=None,
eligibility=None,
prop=1.0,
annual=False,
**kwargs,
)Intervention to modify values of a People’s boolean state at one specific point in time.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| state_name | string | name of the People’s state that will be modified | required |
| new_val | (bool, float) | the new state value eligible people will have | required |
| years | (list, float) | The year we want to start the intervention. if years is None, uses start and end years of sim as defaults if years is a number or a list with a single element, eg, 2000.5, or [2000.5], this is interpreted as the start year of the intervention, and the end year of intervention will be the end of the simulation | None |
| eligibility | inds / callable |
indices OR callable that returns inds | None |
| prop | float | a value between 0 and 1 indicating the x% of eligible people who will have the new state value | 1.0 |
| annual | bool | whether the increase, prop, represents a “per year” increase, or per time step | False |
Methods
| Name | Description |
|---|---|
| check_eligibility | Return an array of uids of agents eligible |
check_eligibility
interventions.change_people_state.check_eligibility()Return an array of uids of agents eligible
method_switching
interventions.method_switching(
year=None,
from_methods=None,
to_method=None,
switch_prob=None,
age_groups=None,
postpartum=None,
annual=False,
verbose=False,
**kwargs,
)Intervention that causes women to switch from specific contraceptive methods to a target method.
This intervention modifies the switching probabilities in the contraception module’s switching matrix to induce transitions from one or more source methods to a destination method.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| year | float | Year when switching intervention begins | None |
| from_methods | str / list | Method name(s) or index(es) to switch from | None |
| to_method | str / int | Method name or index to switch to | None |
| switch_prob | float / dict | Probability of switching. Can be: - float: Same probability for all source methods - dict: {method_name: probability} for different rates per source | None |
| age_groups | list | Age group names to apply switching. If None, applies to all age groups. Use None for all, or list like [‘<18’, ‘18-20’, ‘20-25’, ‘25-35’, ‘>35’] | None |
| postpartum | int / list | Postpartum states to modify (0, 1, 6). If None, modifies all states. | None |
| annual | bool | If True, switch_prob is annual and converted to per-timestep | False |
| verbose | bool | Print detailed information | False |
Example::
# 10% of injectable users switch to DMPA-SC starting in 2025
intv1 = fp.method_switching(
year=2025,
from_methods='inj',
to_method='dmpasc',
switch_prob=0.10,
annual=False
)
# Different rates for different methods
intv2 = fp.method_switching(
year=2030,
from_methods=['dmpasc3', 'withdrawal', 'other_trad'],
to_method='dmpasc6',
switch_prob={'dmpasc3': 0.26, 'withdrawal': 0.20, 'other_trad': 0.20},
annual=False
)update_methods
interventions.update_methods(
year,
eff=None,
dur_use=None,
p_use=None,
method_mix=None,
method_choice_pars=None,
verbose=False,
**kwargs,
)Intervention to modify method efficacy and/or switching matrix.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| year | float | The year we want to change the method. | required |
| eff | dict | An optional key for changing efficacy; its value is a dictionary with the following schema: {method: efficacy} Where method is the name of the contraceptive method to be changed, and efficacy is a number with the efficacy | None |
| dur_use | dict | Optional key for changing the duration of use; its value is a dictionary with the following schema: {method: dur_use} Where method is the method to be changed, and dur_use is a dict representing a distribution, e.g. dur_use = {‘Injectables: dict(dist=’lognormal’, par1=a, par2=b)} | None |
| p_use | float | probability of using any form of contraception | None |
| method_mix | list / arr |
probabilities of selecting each form of contraception | None |
Methods
| Name | Description |
|---|---|
| step | Applies the efficacy or contraceptive uptake changes if it is the specified year |
step
interventions.update_methods.step()Applies the efficacy or contraceptive uptake changes if it is the specified year based on scenario specifications.