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:
Notes
Currently this object is only used in the choice function of this module.
- 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
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]