Randomness Streams

This module provides a wrapper around numpy’s randomness system with the intent of coupling it to vivarium’s tools for Common Random Number genereration.

vivarium.framework.randomness.stream.RESIDUAL_CHOICE

A probability placeholder to be used in an un-normalized array of weights to absorb leftover weight so that the array sums to unity. For example:

[0.2, 0.2, RESIDUAL_CHOICE] => [0.2, 0.2, 0.6]

Note

Currently this object is only used in the choice function of this module.

Type:: object

vivarium.framework.randomness.stream.get_hash(key)[source]

Gets a hash of the provided key.

Parameters:: key (str) – A string used to create a seed for the random number generator.
Returns:: A hash of the provided key.
Return type:: int

class vivarium.framework.randomness.stream.RandomnessStream(key, clock, seed, index_map, initializes_crn_attributes=False)[source]

A stream for producing common random numbers.

RandomnessStream objects provide an interface to Vivarium’s common random number generation. They provide a number of methods for doing common simulation tasks that require random numbers like making decisions among a number of choices.

Parameters:

key (str) –
clock (Callable) –
seed (Any) –
index_map (IndexMap) –
initializes_crn_attributes (bool) –

key: The name of the randomness stream.

clock: A way to get the current simulation time.

seed: An extra number used to seed the random number generation.

Notes

Should not be constructed by client code.

Simulation components get RandomnessStream objects by requesting them from the builder provided to them during the setup phase. I.E.:

class VivariumComponent:
    def setup(self, builder):
        self.randomness_stream = builder.randomness.get_stream('stream_name')

property name

get_draw(index, additional_key=None)[source]

Get an indexed set of numbers uniformly drawn from the unit interval.

Parameters:

index (Index) – An index whose length is the number of random draws made and which indexes the returned pandas.Series.
additional_key (Any | None) – Any additional information used to seed random number generation.

Returns:

A series of random numbers indexed by the provided pandas.Index.

Return type:

pandas.Series

Note

This is the core of the CRN implementation, allowing for consistent use of random numbers across simulations with multiple scenarios.

See also

https://en.wikipedia.org/wiki/Variance_reduction and “Untangling Uncertainty with Common Random Numbers: A Simulation Study; A.Flaxman, et. al., Summersim 2017”

filter_for_rate(population, rate, additional_key=None)[source]

Decide an event outcome for each individual from rates.

Given a population or its index and an array of associated rates for some event to happen, we create and return the subpopulation for whom the event occurred.

Parameters:

population (DataFrame | Series | Index) – A view on the simulants for which we are determining the outcome of an event.
rate (float | List | Tuple | ndarray | Series) – A scalar float value or a 1d list of rates of the event under consideration occurring which corresponds (i.e. len(population) == len(probability)) to the population view passed in. The rates must be scaled to the simulation time-step size either manually or as a post-processing step in a rate pipeline. If a scalar is provided, it is applied to every row in the population.
additional_key (Any | None) – Any additional information used to create the seed.

Returns:

The subpopulation of the simulants for whom the event occurred. The return type will be the same as type(population)

Return type:

pandas.core.generic.PandasObject

filter_for_probability(population, probability, additional_key=None)[source]

Decide an outcome for each individual from probabilities.

Given a population or its index and an array of associated probabilities for some event to happen, we create and return the subpopulation for whom the event occurred.

Parameters:

population (DataFrame | Series | Index) – A view on the simulants for which we are determining the outcome of an event.
probability (float | List | Tuple | ndarray | Series) – A scalar float value or a 1d list of probabilities of the event under consideration occurring which corresponds (i.e. len(population) == len(probability) to the population view passed in. If a scalar is provided, it is applied to every row in the population.
additional_key (Any | None) – Any additional information used to create the seed.

Returns:

The subpopulation of the simulants for whom the event occurred. The return type will be the same as type(population)

Return type:

pandas.core.generic.PandasObject

choice(index, choices, p=None, additional_key=None)[source]

Decides between a weighted or unweighted set of choices.

Given a set of choices with or without corresponding weights, returns an indexed set of decisions from those choices. This is simply a vectorized way to make decisions with some book-keeping.

Parameters:

index (Index) – An index whose length is the number of random draws made and which indexes the returned pandas.Series.
choices (List | Tuple | ndarray | Series) – A set of options to choose from.
p (List | Tuple | ndarray | Series | None) – The relative weights of the choices. Can be either a 1-d array of the same length as choices or a 2-d array with len(index) rows and len(choices) columns. In the 1-d case, the same set of weights are used to decide among the choices for every item in the index. In the 2-d case, each row in p contains a separate set of weights for every item in the index.
additional_key (Any | None) – Any additional information used to seed random number generation.

Returns:

An indexed set of decisions from among the available choices.

Return type:

pandas.Series

Raises:

RandomnessError – If any row in p contains RESIDUAL_CHOICE and the remaining weights in the row are not normalized or any row of p contains more than one reference to `RESIDUAL_CHOICE.