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]
Type:

object

Notes

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

class vivarium.framework.randomness.stream.PPFCallable(*args, **kwargs)[source]
vivarium.framework.randomness.stream.get_hash(key)[source]

Gets a hash of the provided key.

Return type:

int

Parameters:

key (str) – A string used to create a seed for the random number generator.

Returns:

A hash of the provided key.

class vivarium.framework.randomness.stream.RandomnessStream(key, clock, seed, index_map, component=None, 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.

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')
Parameters:

  • key (str)

  • clock (Callable[[], ClockTime])

  • seed (Any)

  • index_map (IndexMap)

  • component (Component | None)

  • 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.

index_map

A key-index mapping with a vectorized hash and vectorized lookups.

initializes_crn_attributes

A boolean indicating whether the stream is used to initialize CRN attributes.

get_draw(index, additional_key=None)[source]

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

Parameters:

  • index (pd.Index[int]) – An index whose length is the number of random draws made and which indexes the returned pandas.Series.

  • additional_key (Any) – Any additional information used to seed random number generation.

Returns:

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

Return type:

pd.Series[float]

Notes

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 (PandasObject) – A view on the simulants for which we are determining the outcome of an event.

  • rate (float | list[float] | tuple[float] | NumericArray | pd.Series[float]) – 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) – 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:

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 (PandasObject) – A view on the simulants for which we are determining the outcome of an event.

  • probability (float | list[float] | tuple[float] | NumericArray | pd.Series[float]) – 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) – 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:

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 (pd.Index[int]) – An index whose length is the number of random draws made and which indexes the returned pandas.Series.

  • choices (list[Any] | tuple[Any] | npt.NDArray[Any] | pd.Series[Any]) – A set of options to choose from.

  • p (list[float | object] | tuple[float | object] | npt.NDArray[np.number[npt.NBitBase] | np.object_] | pd.Series[Any] | 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) – Any additional information used to seed random number generation.

Returns:

An indexed set of decisions from among the available choices.

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.

Return type:

pd.Series[Any]

sample_from_distribution(index, distribution=None, ppf=None, additional_key=None, **distribution_kwargs)[source]

Given a distribution, returns an indexed set of samples from that distribution.

Parameters:

  • index (pd.Index[int]) – An index whose length is the number of random draws made and which indexes the returned pandas.Series.

  • distribution (stats.rv_continuous | None) – A scipy.stats distribution object.

  • ppf (PPFCallable | None) – A function that takes a series of draws and returns a series of samples.

  • additional_key (Any) – Any additional information used to seed random number generation.

  • distribution_kwargs (Any) – Additional keyword arguments to pass to the distribution’s ppf function.

Returns:

An indexed set of samples from the provided distribution.

Return type:

pd.Series[Any]