utils
utils
Numerical utilities for Covasim: sampling, random numbers, and array indexing helpers.
Functions
| Name | Description |
|---|---|
| binomial_arr | Binomial (Bernoulli) trials each with different probabilities. |
| binomial_filter | Binomial “filter” – the same as n_binomial, except return |
| choose | Choose a subset of items (e.g., people) without replacement. |
| choose_r | Choose a subset of items (e.g., people), with replacement. |
| choose_w | Choose n items (e.g. people), each with a probability from the distribution probs. |
| defined | Returns the indices of the values of the array that are not-nan. For a Starsim |
| false | Returns the indices of the values of the array that are false. For a Starsim |
| get_pdf | Return a probability density function for the specified distribution. This |
| idefined | Returns the indices that are defined in the array – name is short for indicesdefined |
| idefinedi | Returns the indices that are defined in the array – name is short for indices[defined[indices]] |
| ifalse | Returns the indices that are false in the array – name is short for indicesfalse |
| ifalsei | Returns the indices that are false in the array – name is short for indices[false[indices]] |
| itrue | Returns the indices that are true in the array – name is short for indicestrue |
| itruei | Returns the indices that are true in the array – name is short for indices[true[indices]] |
| iundefined | Returns the indices that are undefined in the array – name is short for indicesundefined |
| iundefinedi | Returns the indices that are undefined in the array – name is short for indices[undefined[indices]] |
| n_binomial | Perform multiple binomial (Bernoulli) trials |
| n_multinomial | An array of multinomial trials. |
| n_neg_binomial | An array of negative binomial trials. See cv.sample() for more explanation. |
| n_poisson | An array of Poisson trials. |
| poisson | A Poisson trial. |
| sample | Draw a sample from the distribution specified by the input. The available |
| set_seed | Reset the random seed – complicated because of Numba, which requires special |
| true | Returns the indices of the values of the array that are true: for a NumPy |
| undefined | Returns the indices of the values of the array that are nan. For a Starsim |
binomial_arr
utils.binomial_arr(prob_arr)Binomial (Bernoulli) trials each with different probabilities.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| prob_arr | array | array of probabilities | required |
Returns
| Name | Type | Description |
|---|---|---|
| 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 probabilitiesbinomial_filter
utils.binomial_filter(prob, arr)Binomial “filter” – the same as n_binomial, except return the elements of arr that succeeded.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| prob | float | probability of each trial succeeding | required |
| arr | array | the array to be filtered | required |
Returns
| Name | Type | Description |
|---|---|---|
| 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 flipchoose
utils.choose(max_n, n)Choose a subset of items (e.g., people) without replacement.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| max_n | int | the total number of items | required |
| n | int | the number of items to choose | required |
Example::
choices = cv.choose(5, 2) # choose 2 out of 5 people with equal probability (without repeats)choose_r
utils.choose_r(max_n, n)Choose a subset of items (e.g., people), with replacement.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| max_n | int | the total number of items | required |
| n | int | the number of items to choose | required |
Example::
choices = cv.choose_r(5, 10) # choose 10 out of 5 people with equal probability (with repeats)choose_w
utils.choose_w(probs, n, unique=True)Choose n items (e.g. people), each with a probability from the distribution probs.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| probs | array | list of probabilities, should sum to 1 | required |
| n | int | number of samples to choose | required |
| unique | bool | whether or not to ensure unique indices | True |
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.defined
utils.defined(arr)Returns the indices of the values of the array that are not-nan. For a Starsim array (e.g. sim.people.date_symptomatic), returns the UIDs of the matching agents.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| arr | array | any array | required |
Example::
inds = cv.defined(np.array([1,np.nan,0,np.nan,1,0,1]))false
utils.false(arr)Returns the indices of the values of the array that are false. For a Starsim array (e.g. sim.people.susceptible), returns the UIDs of the matching agents.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| arr | array | any array | required |
Example::
inds = cv.false(np.array([1,0,0,1,1,0,1]))get_pdf
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.
Note that the parameters differ from those of cv.sample() for the same distribution names:
- ‘uniform’ : from par1 to par1+par2 (i.e. par2 is the width, not the upper limit)
- ‘lognormal’ : mean=par1 and variance=par2 (not std) of the lognormal distribution, shifted 0.5 days earlier
idefined
utils.idefined(arr, inds)Returns the indices that are defined in the array – name is short for indicesdefined
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| arr | array | any array, used as a filter | required |
| inds | array | any other array (usually, an array of indices) of the same size | required |
Note: for a Starsim array, inds must have one entry per living agent (see cv.itrue()).
Example::
inds = cv.idefined(np.array([3,np.nan,np.nan,4]), inds=np.array([5,22,47,93]))
uids = cv.idefined(sim.people.date_symptomatic, sim.people.uid)idefinedi
utils.idefinedi(arr, inds)Returns the indices that are defined in the array – name is short for indices[defined[indices]]
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| arr | array | any array, used as a filter | required |
| inds | array | an array of indices for the original array | required |
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]))ifalse
utils.ifalse(arr, inds)Returns the indices that are false in the array – name is short for indicesfalse
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| arr | array | a Boolean array, used as a filter | required |
| inds | array | any other array (usually, an array of indices) of the same size | required |
Note: for a Starsim array, inds must have one entry per living agent (see cv.itrue()).
Example::
inds = cv.ifalse(np.array([True,False,True,True]), inds=np.array([5,22,47,93]))
uids = cv.ifalse(sim.people.susceptible, sim.people.uid)ifalsei
utils.ifalsei(arr, inds)Returns the indices that are false in the array – name is short for indices[false[indices]]
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| arr | array | a Boolean array, used as a filter | required |
| inds | array | an array of indices for the original array | required |
Example::
inds = cv.ifalsei(np.array([True,False,True,True,False,False,True,False]), inds=np.array([0,1,3,5]))itrue
utils.itrue(arr, inds)Returns the indices that are true in the array – name is short for indicestrue
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| arr | array | a Boolean array, used as a filter | required |
| inds | array | any other array (usually, an array of indices) of the same size | required |
Note: a Starsim array (e.g. sim.people.susceptible) only has entries for living agents, so inds must have one entry per living agent, e.g. sim.people.uid; np.arange(pop_size) gives positions, not UIDs, once agents have died.
Example::
inds = cv.itrue(np.array([True,False,True,True]), inds=np.array([5,22,47,93]))
uids = cv.itrue(sim.people.susceptible, sim.people.uid)itruei
utils.itruei(arr, inds)Returns the indices that are true in the array – name is short for indices[true[indices]]
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| arr | array | a Boolean array, used as a filter | required |
| inds | array | an array of indices for the original array | required |
Example::
inds = cv.itruei(np.array([True,False,True,True,False,False,True,False]), inds=np.array([0,1,3,5]))iundefined
utils.iundefined(arr, inds)Returns the indices that are undefined in the array – name is short for indicesundefined
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| arr | array | any array, used as a filter | required |
| inds | array | any other array (usually, an array of indices) of the same size | required |
Note: for a Starsim array, inds must have one entry per living agent (see cv.itrue()).
Example::
inds = cv.iundefined(np.array([3,np.nan,np.nan,4]), inds=np.array([5,22,47,93]))
uids = cv.iundefined(sim.people.date_symptomatic, sim.people.uid)iundefinedi
utils.iundefinedi(arr, inds)Returns the indices that are undefined in the array – name is short for indices[undefined[indices]]
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| arr | array | any array, used as a filter | required |
| inds | array | an array of indices for the original array | required |
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]))n_binomial
utils.n_binomial(prob, n)Perform multiple binomial (Bernoulli) trials
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| prob | float | probability of each trial succeeding | required |
| n | int | number of trials (size of array) | required |
Returns
| Name | Type | Description |
|---|---|---|
| Boolean array of which trials succeeded |
Example::
outcomes = cv.n_binomial(0.5, 100) # Perform 100 coin-flipsn_multinomial
utils.n_multinomial(probs, n)An array of multinomial trials.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| probs | array | probability of each outcome, which usually should sum to 1 | required |
| n | int | number of trials | required |
Returns
| Name | Type | Description |
|---|---|---|
| Array of integer outcomes |
Example::
outcomes = cv.n_multinomial(np.ones(6)/6.0, 50)+1 # Return 50 die-rollsn_neg_binomial
utils.n_neg_binomial(rate, dispersion, n, step=1)An array of negative binomial trials. See cv.sample() for more explanation.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| rate | float | the rate of the process (mean, same as Poisson) | required |
| dispersion | float | dispersion parameter; lower is more dispersion, i.e. 0 = infinite, ∞ = Poisson | required |
| n | int | number of trials | required |
| step | float | the step size to use if non-integer outputs are desired | 1 |
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)n_poisson
utils.n_poisson(rate, n)An array of Poisson trials.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| rate | float | the rate of the Poisson process (mean) | required |
| n | int | number of trials | required |
Example::
outcomes = cv.n_poisson(100, 20) # 20 Poisson trials with mean 100poisson
utils.poisson(rate)A Poisson trial.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| rate | float | the rate of the Poisson process | required |
Example::
outcome = cv.poisson(100) # Single Poisson trial with mean 100sample
utils.sample(dist=None, par1=None, par2=None, size=None, **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’ : as ‘normal_pos’ (i.e. mean=par1 and std=par2 of the underlying normal distribution), but 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
| Name | Type | Description | Default |
|---|---|---|---|
| dist | str | the distribution to sample from (default ‘uniform’) | None |
| par1 | float | the “main” distribution parameter (e.g. mean; default 0) | None |
| par2 | float | the “secondary” distribution parameter (e.g. std; default 1) | None |
| size | int | the number of samples (default: a single sample, returned as a scalar) | None |
| kwargs | dict | passed to individual sampling functions | {} |
Returns
| Name | Type | Description |
|---|---|---|
| A length N array of samples, or a single sample if size is None |
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 3Notes
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.
set_seed
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 generator.
Note: this resets the global NumPy, Numba, and Python random number generators used by the functions in this module, not Starsim’s per-distribution random number streams (which are set by the sim’s rand_seed).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| seed | int | the random seed | None |
true
utils.true(arr)Returns the indices of the values of the array that are true: for a NumPy array, just an alias for arr.nonzero()[0]. For a Starsim array (e.g. sim.people.susceptible), returns the UIDs of the matching agents.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| arr | array | any array | required |
Example::
inds = cv.true(np.array([1,0,0,1,1,0,1])) # Returns array([0, 3, 4, 6])
inds = cv.true(sim.people.age > 65) # Returns the UIDs of people over 65undefined
utils.undefined(arr)Returns the indices of the values of the array that are nan. For a Starsim array (e.g. sim.people.date_symptomatic), returns the UIDs of the matching agents.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| arr | array | any array | required |
Example::
inds = cv.undefined(np.array([1,np.nan,0,np.nan,1,0,1]))