covasim.utils module¶

Numerical utilities for running Covasim

covasim.utils.sample(dist=None, par1=None, par2=None, size=None, **kwargs)¶

Draw a sample from the distribution specified by the input.

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:

sample() # returns Unif(0,1)
sample(dist='normal', par1=3, par2=0.5) # returns Normal(μ=3, σ=0.5)

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 variance of the lognormal distribution.

covasim.utils.get_pdf(dist=None, par1=None, par2=None)¶: Return a probability density function for the specified distribution. This is used for example by test_num to retrieve the distribution of times from symptom-to-swab for testing. For example, for Washington State, these values are dist=’lognormal’, par1=10, par2=170.

covasim.utils.set_seed(seed=None)¶

Reset the random seed – complicated because of Numba, which requires special syntax to reset the seed. This function also resets Python’s built-in random number generated.

Parameters: seed (int) – the random seed

covasim.utils.n_binomial(prob, n)¶

Perform multiple binomial (Bernolli) trials

Parameters

prob (float) – probability of each trial succeeding
n (int) – number of trials (size of array)

Returns

Boolean array of which trials succeeded

Example:

outcomes = cv.n_binomial(0.5, 100) # Perform 100 coin-flips

covasim.utils.binomial_filter(prob, arr)¶

Binomial “filter” – the same as n_binomial, except return the elements of arr that succeeded.

Parameters

prob (float) – probability of each trial succeeding
arr (array) – the array to be filtered

Returns

Subset of array for which trials succeeded

Example:

inds = cv.binomial_filter(0.5, np.arange(20)**2) # Return which values out of the (arbitrary) array passed the coin flip

covasim.utils.binomial_arr(prob_arr)¶

Binomial (Bernoulli) trials each with different probabilities.

Parameters: prob_arr (array) – array of probabilities
Returns: Boolean array of which trials on the input array succeeded

Example:

outcomes = cv.binomial_arr([0.1, 0.1, 0.2, 0.2, 0.8, 0.8]) # Perform 6 trials with different probabilities

covasim.utils.n_multinomial(probs, n)¶

An array of multinomial trials.

Parameters

probs (array) – probability of each outcome, which usually should sum to 1
n (int) – number of trials

Returns

Array of integer outcomes

Example:

outcomes = cv.multinomial(np.ones(6)/6.0, 50)+1 # Return 50 die-rolls

covasim.utils.poisson(rate)¶

A Poisson trial.

Parameters: rate (float) – the rate of the Poisson process

Example:

outcome = cv.poisson(100) # Single Poisson trial with mean 100

covasim.utils.n_poisson(rate, n)¶

An array of Poisson trials.

Parameters

rate (float) – the rate of the Poisson process (mean)
n (int) – number of trials

Example:

outcomes = cv.n_poisson(100, 20) # 20 poisson trials with mean 100

covasim.utils.n_neg_binomial(rate, dispersion, n, step=1)¶

An array of negative binomial trials; with dispersion = ∞, converges to Poisson.

Parameters

rate (float) – the rate of the process (mean, same as Poisson)
dispersion (float) – amount of dispersion: 0 = infinite, 1 = std is equal to mean, ∞ = Poisson
n (int) – number of trials
step (float) – the step size to use if non-integer outputs are desired

Example:

outcomes = cv.n_neg_binomial(100, 1, 20) # 20 negative binomial trials with mean 100 and dispersion equal to mean

covasim.utils.choose(max_n, n)¶

Choose a subset of items (e.g., people) without replacement.

Parameters

max_n (int) – the total number of items
n (int) – the number of items to choose

Example:

choices = cv.choose(5, 2) # choose 2 out of 5 people with equal probability (without repeats)

covasim.utils.choose_r(max_n, n)¶

Choose a subset of items (e.g., people), with replacement.

Parameters

max_n (int) – the total number of items
n (int) – the number of items to choose

Example:

choices = cv.choose_r(5, 10) # choose 10 out of 5 people with equal probability (with repeats)

covasim.utils.choose_w(probs, n, unique=True)¶

Choose n items (e.g. people), each with a probability from the distribution probs.

Parameters

probs (array) – list of probabilities, should sum to 1
n (int) – number of samples to choose
unique (bool) – whether or not to ensure unique indices

Example:

choices = cv.choose_w([0.2, 0.5, 0.1, 0.1, 0.1], 2) # choose 2 out of 5 people with nonequal probability.

covasim.utils.true(arr)¶

Returns the indices of the values of the array that are true: just an alias for arr.nonzero()[0].

Parameters: arr (array) – any array

Example:

inds = cv.true(np.array([1,0,0,1,1,0,1]))

covasim.utils.false(arr)¶

Returns the indices of the values of the array that are false.

Parameters: arr (array) – any array

Example:

inds = cv.false(np.array([1,0,0,1,1,0,1]))

covasim.utils.defined(arr)¶

Returns the indices of the values of the array that are not-nan.

Parameters: arr (array) – any array

Example:

inds = cv.defined(np.array([1,np.nan,0,np.nan,1,0,1]))

covasim.utils.undefined(arr)¶

Returns the indices of the values of the array that are not-nan.

Parameters: arr (array) – any array

Example:

inds = cv.defined(np.array([1,np.nan,0,np.nan,1,0,1]))

covasim.utils.itrue(arr, inds)¶

Returns the indices that are true in the array – name is short for indices[true]

Parameters

arr (array) – a Boolean array, used as a filter
inds (array) – any other array (usually, an array of indices) of the same size

Example:

inds = cv.itrue(np.array([True,False,True,True]), inds=np.array([5,22,47,93]))

covasim.utils.ifalse(arr, inds)¶

Returns the indices that are true in the array – name is short for indices[false]

Parameters

arr (array) – a Boolean array, used as a filter
inds (array) – any other array (usually, an array of indices) of the same size

Example:

inds = cv.ifalse(np.array([True,False,True,True]), inds=np.array([5,22,47,93]))

covasim.utils.idefined(arr, inds)¶

Returns the indices that are true in the array – name is short for indices[defined]

Parameters

arr (array) – any array, used as a filter
inds (array) – any other array (usually, an array of indices) of the same size

Example:

inds = cv.idefined(np.array([3,np.nan,np.nan,4]), inds=np.array([5,22,47,93]))

covasim.utils.itruei(arr, inds)¶

Returns the indices that are true in the array – name is short for indices[true[indices]]

Parameters

arr (array) – a Boolean array, used as a filter
inds (array) – an array of indices for the original array

Example:

inds = cv.itruei(np.array([True,False,True,True,False,False,True,False]), inds=np.array([0,1,3,5]))

covasim.utils.ifalsei(arr, inds)¶

Returns the indices that are false in the array – name is short for indices[false[indices]]

Parameters

arr (array) – a Boolean array, used as a filter
inds (array) – an array of indices for the original array

Example:

inds = cv.ifalsei(np.array([True,False,True,True,False,False,True,False]), inds=np.array([0,1,3,5]))

covasim.utils.idefinedi(arr, inds)¶

Returns the indices that are defined in the array – name is short for indices[defined[indices]]

Parameters

arr (array) – any array, used as a filter
inds (array) – an array of indices for the original array

Example:

inds = cv.idefinedi(np.array([4,np.nan,0,np.nan,np.nan,4,7,4,np.nan]), inds=np.array([0,1,3,5]))