covasim.utils module¶
Numerical utilities for running Covasim.
These include the viral load, transmissibility, and infection calculations at the heart of the integration loop.
-
sample
(dist=None, par1=None, par2=None, size=None, **kwargs)[source]¶ 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:
cv.sample() # returns Unif(0,1) cv.sample(dist='normal', par1=3, par2=0.5) # returns Normal(μ=3, σ=0.5) cv.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.
-
get_pdf
(dist=None, par1=None, par2=None)[source]¶ 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.
-
set_seed
(seed=None)[source]¶ 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
-
n_binomial
(prob, n)[source]¶ 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
-
binomial_filter
(prob, arr)[source]¶ 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
-
binomial_arr
(prob_arr)[source]¶ 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
-
n_multinomial
(probs, n)[source]¶ 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
-
poisson
[source]¶ A Poisson trial.
Parameters: rate (float) – the rate of the Poisson process Example:
outcome = cv.poisson(100) # Single Poisson trial with mean 100
-
n_poisson
[source]¶ 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
-
n_neg_binomial
(rate, dispersion, n, step=1)[source]¶ An array of negative binomial trials. See cv.sample() for more explanation.
Parameters: - rate (float) – the rate of the process (mean, same as Poisson)
- dispersion (float) – dispersion parameter; lower is more dispersion, i.e. 0 = infinite, ∞ = 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, 50) # 50 negative binomial trials with mean 100 and dispersion roughly equal to mean (large-mean limit) outcomes = cv.n_neg_binomial(1, 100, 20) # 20 negative binomial trials with mean 1 and dispersion still roughly equal to mean (approximately Poisson)
-
choose
[source]¶ 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)
-
choose_r
[source]¶ 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)
-
choose_w
(probs, n, unique=True)[source]¶ 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.
-
true
(arr)[source]¶ 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])) # Returns array([0, 3, 4, 6])
-
false
(arr)[source]¶ 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]))
-
defined
(arr)[source]¶ 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]))
-
undefined
(arr)[source]¶ 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]))
-
itrue
(arr, inds)[source]¶ 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]))
-
ifalse
(arr, inds)[source]¶ 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]))
-
idefined
(arr, inds)[source]¶ Returns the indices that are defined 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]))
-
iundefined
(arr, inds)[source]¶ Returns the indices that are undefined in the array – name is short for indices[undefined]
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.iundefined(np.array([3,np.nan,np.nan,4]), inds=np.array([5,22,47,93]))
-
itruei
(arr, inds)[source]¶ 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]))
-
ifalsei
(arr, inds)[source]¶ 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]))
-
idefinedi
(arr, inds)[source]¶ 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]))
-
iundefinedi
(arr, inds)[source]¶ Returns the indices that are undefined 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.iundefinedi(np.array([4,np.nan,0,np.nan,np.nan,4,7,4,np.nan]), inds=np.array([0,1,3,5]))