fpsim.parameters module

Handle sim parameters

class Pars(pars=None, *args, **kwargs)

Bases: dict

Class to hold a dictionary of parameters, and associated methods.

Usually not called by the user directly – use fp.pars() instead.

Parameters:

pars (dict) – dictionary of parameters

copy()

Shortcut for deep copying

to_dict()

Return parameters as a new dictionary

to_json(filename, **kwargs)

Export parameters to a JSON file.

Parameters:

• filename (str) – filename to save to

• kwargs (dict) – passed to sc.savejson

Example::

sim.pars.to_json(‘my_pars.json’)

from_json(filename, **kwargs)

Import parameters from a JSON file.

Parameters:

• filename (str) – filename to load from

• kwargs (dict) – passed to sc.loadjson

Example::

sim.pars.from_json(‘my_pars.json’)

validate(die=True, update=True)

Perform validation on the parameters

Parameters:

• die (bool) – whether to raise an exception if an error is encountered

• update (bool) – whether to update the method and age maps

update_method_eff(method, eff=None, verbose=False)

Update efficacy of one or more contraceptive methods.

Parameters:

• method (str/dict) – method to update, or dict of method:value pairs

• eff (float) – new value of contraceptive efficacy (not required if method is a dict)

Examples::

pars.update_method_eff(‘Injectables’, 0.99) pars.update_method_eff({‘Injectables’:0.99, ‘Condoms’:0.50})

update_method_prob(source=None, dest=None, factor=None, value=None, ages=None, matrix=None, copy_from=None, verbose=False)

Updates the probability matrices with a new value. Usually used via the intervention fp.update_methods().

Parameters:

• source (str/int) – the method to switch from

• dest (str/int) – the method to switch to

• factor (float) – if supplied, multiply the probability by this factor

• value (float) – if supplied, change the probability to this value

• ages (str/list) – the ages to modify (default: all)

• matrix (str) – which switching matrix to modify (default: annual)

• copy_from (str) – the existing method to copy the probability vectors from (optional)

• verbose (bool) – how much detail to print

reset_methods_map()

Refresh the methods map to be self-consistent

add_method(name, eff, modern=True)

Add a new contraceptive method to the switching matrices.

A new method should only be added before the sim is run, not during.

Note: the matrices are stored in pars['methods']['raw']; this method is a helper function for modifying those. For more flexibility, modify them directly. The fp.update_methods() intervention can be used to modify the switching probabilities later.

Parameters:

• name (str) – the name of the new method

• eff (float) – the efficacy of the new method

• modern (bool) – whether it’s a modern method (default: yes)

Examples::

pars = fp.pars() pars.add_method(‘New method’, 0.90) pars.add_method(name=’Male pill’, eff=0.98, modern=True)

rm_method(name)

Removes a contraceptive method from the switching matrices.

A method should only be removed before the sim is run, not during, since the method associated with each person in the sim will point to the wrong index.

Parameters:

name (str/ind) – the name or index of the method to remove

Example::

pars = fp.pars() pars.rm_method(‘Other modern’)

reorder_methods(order)

Reorder the contraceptive method matrices.

Method reordering should be done before the sim is created (or at least before it’s run).

Parameters:

• order (arr) – the new order of methods, either ints or strings

• sim (Sim) – if supplied, also reorder

Exampls::

pars = fp.pars() pars.reorder_methods([2, 6, 4, 7, 0, 8, 5, 1, 3])

pars(location=None, validate=True, die=True, update=True, **kwargs)

Function for getting default parameters.

Parameters:

• location (str) – the location to use for the parameters; use ‘test’ for a simple test set of parameters

• validate (bool) – whether to perform validation on the parameters

• die (bool) – whether to raise an exception if validation fails

• update (bool) – whether to update values during validation

• kwargs (dict) – custom parameter values

Example::

pars = fp.pars(location=’senegal’)