fpsim.utils module

File for storing utilities and probability calculators needed to run FP model

fpsim.utils.set_seed(seed=None)

Reset the random seed – complicated because of Numba

fpsim.utils.bt(prob)

A simple Bernoulli (binomial) trial

fpsim.utils.bc(prob, repeats)

A binomial count

fpsim.utils.rbt(prob, repeats)

A repeated Bernoulli (binomial) trial

fpsim.utils.mt(probs)

A multinomial trial

fpsim.utils.fixaxis(useSI=True, set_lim=True, legend=True)

Fix the plotting

fpsim.utils.dict2obj(d)

Convert a dictionary to an object – REFACTOR to use sc.dictobj()

fpsim.utils.sample(dist='uniform', par1=0, par2=1, size=1, **kwargs)

Draw a sample from the distribution specified by the input. The available distributions are:

  • ‘uniform’ : uniform distribution from low=par1 to high=par2; mean is equal to (par1+par2)/2

  • ‘normal’ : normal distribution with mean=par1 and std=par2

  • ‘lognormal’ : lognormal distribution with mean=par1 and std=par2 (parameters are for the lognormal distribution, not the underlying normal distribution)

  • ‘normal_pos’ : right-sided normal distribution (i.e. only positive values), with mean=par1 and std=par2 of the underlying normal distribution

  • ‘normal_int’ : normal distribution with mean=par1 and std=par2, returns only integer values

  • ‘lognormal_int’ : lognormal distribution with mean=par1 and std=par2, returns only integer values

  • ‘poisson’ : Poisson distribution with rate=par1 (par2 is not used); mean and variance are equal to par1

  • ‘neg_binomial’ : negative binomial distribution with mean=par1 and k=par2; converges to Poisson with k=∞

Parameters
  • dist (str) – the distribution to sample from

  • par1 (float) – the “main” distribution parameter (e.g. mean)

  • par2 (float) – the “secondary” distribution parameter (e.g. std)

  • size (int) – the number of samples (default=1)

  • kwargs (dict) – passed to individual sampling functions

Returns

A length N array of samples

Examples:

fp.sample() # returns Unif(0,1)
fp.sample(dist='normal', par1=3, par2=0.5) # returns Normal(μ=3, σ=0.5)
fp.sample(dist='lognormal_int', par1=5, par2=3) # returns a lognormally distributed set of values with mean 5 and std 3

Notes

Lognormal distributions are parameterized with reference to the underlying normal distribution (see: https://docs.scipy.org/doc/numpy-1.14.0/reference/generated/numpy.random.lognormal.html), but this function assumes the user wants to specify the mean and std of the lognormal distribution.

Negative binomial distributions are parameterized with reference to the mean and dispersion parameter k (see: https://en.wikipedia.org/wiki/Negative_binomial_distribution). The r parameter of the underlying distribution is then calculated from the desired mean and k. For a small mean (~1), a dispersion parameter of ∞ corresponds to the variance and standard deviation being equal to the mean (i.e., Poisson). For a large mean (e.g. >100), a dispersion parameter of 1 corresponds to the standard deviation being equal to the mean.