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, 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
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 fectorized hash and vectorized lookups.
- initializes_crn_attributes
A boolean indicating whether the stram is used to initialize CRN attributes.
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.
- Return type:
- Parameters:
- Returns:
A series of random numbers indexed by the provided pandas.Index.
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.
- Return type:
- 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) – 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).
- 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.
- Return type:
- 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) – 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).
- 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.
- Return type:
- 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.
- 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.
- 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.
- Return type:
- Parameters:
index (Index) – An index whose length is the number of random draws made and which indexes the returned pandas.Series.
distribution (rv_continuous | None) – A scipy.stats distribution object.
ppf (Callable[[Series, dict[str, Any]], Series] | 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 (dict[str, Any]) – Additional keyword arguments to pass to the distribution’s ppf function.
- Returns:
An indexed set of samples from the provided distribution.