ContraceptiveChoice

class ContraceptiveChoice(pars=None, **kwargs)

Bases: Connector

Attributes

auto_state_list	List of "automatic" states with boolean type (ss.BoolState) that were added via define_states()
average_dur_use
dt	Get the current module timestep
n_methods
n_options	Number of contraceptive methods defined
now	Shortcut to self.t.now()
state_dict	Return a flat dictionary (objdict) of all states
state_list	Return a flat list of all states (ss.Arr objects)
ti	Get the current module timestep
timevec	Shortcut to self.t.timevec

Methods

property n_options

Number of contraceptive methods defined

set_init_dist()

If no initial distribution has been provided, use the method_choice_pars to set one. The initial distribution will be the probabilities of switching from no method

get_method_by_label(method_label)

Extract method according to its label / long name

get_method(identifier)

Get a method by name (first) or label (second). :type identifier: :param identifier: Method name (e.g., ‘impl’) or label (e.g., ‘Implants’) :type identifier: str

Returns:

The matching method object

Return type:

Method

add_method(method, copy_from=None)

Add a new contraceptive method to the simulation.

Parameters:

• method – Method object to add (must have name, label, csv_name, efficacy, modern, dur_use)

• copy_from – Optional method name/label to copy switching probabilities from

make_empty_method_choice_pars()

Create an empty method_choice_pars structure with zero entries. Useful for creating new simulations without location data.

extend_method_choice_pars(new_method_name, copy_from_method=None)

Extend method_choice_pars to include a new method.

Parameters:

• new_method_name (str) – Name of the new method being added

• copy_from_method (str or None) – Name of existing method to copy probabilities from. If None, initialize with zeros.

renormalize_method_choice_pars()

Renormalize all probability arrays in method_choice_pars to sum to 1. Replaces Switching.renormalize_all()

set_switching_prob(from_method, to_method, value, postpartum=None, age_grp=None, renormalize=False)

Set switching probability from one method to another. :type from_method: :param from_method: Method name to switch from :type from_method: str :type to_method: :param to_method: Method name to switch to :type to_method: str :type value: :param value: Probability value :type value: float :type postpartum: :param postpartum: Postpartum state(s) (0, 1, or 6). None = all. :type postpartum: int or list or None :type age_grp: :param age_grp: Age group(s). None = all. :type age_grp: str or list or None :type renormalize: :param renormalize: Whether to renormalize after setting :type renormalize: bool

get_switching_prob(from_method, to_method, postpartum, age_grp)

Get switching probability from one method to another. :type from_method: :param from_method: Method name to switch from :type from_method: str :type to_method: :param to_method: Method name to switch to :type to_method: str :type postpartum: :param postpartum: Postpartum state (0, 1, or 6) :type postpartum: int :type age_grp: :param age_grp: Age group :type age_grp: str

Returns:

Probability value

Return type:

float

copy_switching_probs(from_method_source, to_method_source, from_method_dest, to_method_dest, postpartum=None, age_grp=None, renormalize=False)

Copy switching probability from one method pair to another. Example: Copy the probability of switching from pill->iud

to the probability of switching from condom->implant

copy_switching_to_method(source_to_method, dest_to_method, split_shares=None, postpartum=None, age_grp=None, renormalize=False)

Copy all switching probabilities TO a method (entire column). Example: Copy all probabilities of switching to IUD

to be the probabilities of switching to implant.

copy_switching_from_method(source_from_method, dest_from_method, postpartum=None, age_grp=None, renormalize=False)

Copy all switching probabilities FROM a method (entire row block). Example: Copy all probabilities of switching from pill to other methods

to be the probabilities of switching from implant to other methods. This makes implant users switch like pill users.

get_switching_matrix(postpartum, from_method=None)

Get switching matrix for a particular postpartum status across all age groups. :type postpartum: :param postpartum: Postpartum state (0, 1, or 6) :type postpartum: int :type from_method: :param from_method: Method name for pp=0 or 6 :type from_method: str or None

Returns:

Dictionary keyed by age group with probability arrays

Return type:

dict

init_results()

Initialize results for this module

init_post()

Decide who will start using contraception, when, which contraception method and the duration on that method. This method is called by the simulation to initialise the people object at the beginning of the simulation and new people born during the simulation.

init_contraception(uids)

Used for all agents at the start of a sim and for newly active agents throughout

start_contra(uids)

Wrapper method to start contraception for a set of users

get_contra_users(uids, event=None)

Select contraception users, return boolean array

update_contra(uids)

Update contraceptive choices for a set of users.

set_method(uids)

Wrapper for choosing method and assigning duration of use

update_results()

Note that we are not including LAM users in mCPR as this model counts all women passively using LAM but DHS data records only women who self-report LAM which is much lower. Follows the DHS definition of mCPR.

update_intent_to_use(uids)

Intent is optional, so pass if not implemented for a given ContraceptiveChoice