Dist#

class Dist(dist=None, distname=None, name=None, seed=None, offset=None, strict=True, auto=True, sim=None, module=None, debug=False, **kwargs)[source]#

Bases: object

Base class for tracking one random number generator associated with one distribution, i.e. one decision per timestep.

See ss.dist_list for a full list of supported distributions.

Although it’s possible in theory to define a custom distribution (i.e., not one from NumPy or SciPy), in practice this is difficult. The distribution needs to have both a way to return random variates (easy), as well as the probability point function (inverse CDF). In addition, the distribution must be able to take a NumPy RNG as its bit generator. It’s easier to just use a default Dist (e.g., ss.random()), and then take its output as input (i.e., quantiles) for whatever custom distribution you want to create.

Parameters:

dist (rv_generic) – optional; a scipy.stats distribution (frozen or not) to get the ppf from
distname (str) – the name for this class of distribution (e.g. “uniform”)
name (str) – the name for this particular distribution (e.g. “age_at_death”)
seed (int) – the user-chosen random seed (e.g. 3)
offset (int) – the seed offset; will be automatically assigned (based on hashing the name) if None
strict (bool) – if True, require initialization and invalidate after each call to rvs()
auto (bool) – whether to auto-reset the state after each draw
sim (Sim) – usually determined on initialization; the sim to use as input to callable parameters
module (Module) – usually determined on initialization; the module to use as input to callable parameters
kwargs (dict) – parameters of the distribution

Examples:

dist = ss.Dist(sps.norm, loc=3)
dist.rvs(10) # Return 10 normally distributed random numbers

Attributes

`bitgen`
`state`	Get the current state
`state_int`	Get the integer corresponding to the current state

Methods

disp()[source]#: Return full display of object

show_state(output=False)[source]#: Show the state of the object

__call__(n=1)[source]#: Alias to self.rvs()

set(*args, dist=None, **kwargs)[source]#: Set (change) the distribution type, or one or more parameters of the distribution

property state#: Get the current state

property state_int#: Get the integer corresponding to the current state

get_state()[source]#: Return a copy of the state

make_history(reset=False)[source]#: Store the current state in history

reset(state=0)[source]#

Restore state, allowing the same numbers to be resampled

Use 0 for original state, -1 for most recent state.

Example:

dist = ss.random(seed=5).init()
r1 = dist(5)
r2 = dist(5)
dist.reset(-1)
r3 = dist(5)
dist.reset(0)
r4 = dist(5)
assert all(r1 != r2)
assert all(r2 == r3)
assert all(r4 == r1)

jump(to=None, delta=1, force=False)[source]#: Advance the RNG, e.g. to timestep “to”, by jumping

jump_dt(ti=None, force=False)[source]#

Automatically jump on the next value of dt

Parameters:: ti (int) – if specified, jump to this timestep (default: current module timestep plus one)

init(trace=None, seed=None, module=None, sim=None, slots=None, force=False)[source]#: Calculate the starting seed and create the RNG

link_sim(sim=None, overwrite=False)[source]#: Shortcut for linking the sim, only overwriting an existing one if overwrite=True; not for the user

link_module(module=None, overwrite=False)[source]#: Shortcut for linking the module

process_seed(trace=None, seed=None)[source]#: Obtain the seed offset by hashing the path to this distribution; not for the user

process_dist()[source]#: Ensure the distribution works; not for the user

process_size(n=1)[source]#: Handle an input of either size or UIDs and calculate size, UIDs, and slots; not for the user

process_pars(call=True)[source]#: Ensure the supplied dist and parameters are valid, and initialize them; not for the user

preprocess_timepar(key, timepar)[source]#: Method to handle how timepars are processed; not for the user. By default, scales the output of the distribution.

convert_callable(key, val, size, uids)[source]#: Method to handle how callable parameters are processed; not for the user

call_par(key, val, size, uids)[source]#: Check if this parameter needs to be called to be turned into an array; not for the user

call_pars()[source]#: Check if any parameters need to be called to be turned into arrays; not for the user

sync_pars()[source]#: Perform any necessary synchronizations or transformations on distribution parameters; not for the user

update_dist_pars(pars=None)[source]#: Update SciPy distribution parameters; not for the user

rand(size)[source]#: Simple way to get simple random numbers

make_rvs()[source]#: Return default random numbers for scalar parameters; not for the user

ppf(rands)[source]#: Return default random numbers for array parameters; not for the user

postprocess_timepar(rvs)[source]#: Scale random variates after generation; not for the user

rvs(n=1, reset=False)[source]#

Get random variates – use this!

Parameters:

n (int/tuple/arr) – if an int or tuple, return this many random variates; if an array, treat as UIDs
reset (bool) – whether to automatically reset the random number distribution state after being called

to_json()[source]#: Return a dictionary representation of the Dist

plot_hist(n=1000, bins=None, fig_kw=None, hist_kw=None)[source]#: Plot the current state of the RNG as a histogram