fpsim.parameters module

Handle sim parameters

class Pars(pars=None, *args, **kwargs)[source]

Bases: dict

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

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


pars (dict) – dictionary of parameters


Shortcut for deep copying


Return parameters as a new dictionary

to_json(filename, **kwargs)[source]

Export parameters to a JSON file.

  • filename (str) – filename to save to

  • kwargs (dict) – passed to sc.savejson



from_json(filename, **kwargs)[source]

Import parameters from a JSON file.

  • filename (str) – filename to load from

  • kwargs (dict) – passed to sc.loadjson



validate(die=True, update=True)[source]

Perform validation on the 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)[source]

Update efficacy of one or more contraceptive methods.

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


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)[source]

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

  • 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


Refresh the methods map to be self-consistent

add_method(name, eff, modern=True)[source]

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.

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


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


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.


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


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


Reorder the contraceptive method matrices.

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

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

  • sim (Sim) – if supplied, also reorder


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)[source]

Function for getting default 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


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