distributions
Define random-number-safe distributions.
Classes
| Name | Description |
|---|---|
| Dist | Base class for tracking one random number generator associated with one distribution, |
| DistNotInitializedError | Raised when Dist object is called when not initialized. |
| DistNotReadyError | Raised when a Dist object is called without being ready. |
| DistSeedRepeatError | Raised when a Dist object shares a seed with another |
| Dists | Class for managing a collection of Dist objects |
| bernoulli | Bernoulli distribution: return True or False with the specified probability (which can be an array) |
| beta_dist | Beta distribution |
| beta_mean | Beta distribution paramterized by the mean |
| choice | Random choice between discrete options (note: dynamic parameters not supported) |
| constant | Constant (delta) distribution: equivalent to np.full() |
| expon | Exponential distribution |
| gamma | Gamma distribution (specifically, scipy.stats.gamma) |
| histogram | Sample from a histogram with defined bins |
| lognorm_ex | Lognormal distribution, parameterized in terms of the “explicit” (lognormal) |
| lognorm_im | Lognormal distribution, parameterized in terms of the “implicit” (normal) |
| multi_random | A class for holding two or more ss.random() distributions, and generating |
| nbinom | Negative binomial distribution |
| normal | Normal distribution |
| poisson | Poisson distribution |
| rand_raw | Directly sample raw integers (uint64) from the random number generator. |
| randint | Random integer distribution, on the interval [low, high) |
| random | Random distribution, with values on the interval (0, 1) |
| scale_types | Define how distributions scale |
| uniform | Uniform distribution, values on interval (low, high) |
| weibull | Weibull distribution (specifically, scipy.stats.weibull_min) |
Dist
distributions.Dist(
dist=None,
distname=None,
name=None,
unit=None,
seed=None,
offset=None,
strict=True,
auto=True,
sim=None,
module=None,
mock=False,
debug=False,
**kwargs,
)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. Parameter inputs tend to follow SciPy’s, rather than NumPy’s, definitions (although in most cases they’re the same). See also ss.distributions.scale_types for more information on how different distributions scale by time.
Note: by default, ss.Dist is initialized with an ss.Sim object to ensure random number reproducibility. You can override this with either ss.Dist(strict=False) on creation, or dist.init(force=True) after creation.
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
| Name | Type | Description | Default |
|---|---|---|---|
| dist | rv_generic |
optional; a scipy.stats distribution (frozen or not) to get the ppf from |
None |
| distname | str | the name for this class of distribution (e.g. “uniform”) | None |
| name | str | the name for this particular distribution (e.g. “age_at_death”) | None |
| unit | str/ss.TimePar |
if provided, convert the output of the distribution to a timepar (e.g. rate or duration); can also be inferred from distribution parameters (see examples below) | None |
| seed | int | the user-chosen random seed (e.g. 3) | None |
| offset | int | the seed offset; will be automatically assigned (based on hashing the name) if None | None |
| strict | bool | if True, require initialization and invalidate after each call to rvs() | True |
| auto | bool | whether to auto-reset the state after each draw | True |
| sim | Sim | usually determined on initialization; the sim to use as input to callable parameters | None |
| module | Module | usually determined on initialization; the module to use as input to callable parameters | None |
| mock | int | if provided, then initialize with a mock Sim object (of size mock) for debugging purposes |
False |
| debug | bool | print out additional detail | False |
| kwargs | dict | parameters of the distribution | {} |
Examples:
# Create a Bernoulli distribution
p_death = ss.bernoulli(p=0.1).init(force=True)
p_death.rvs(50) # Create 50 draws
# Create a normal distribution that's also a timepar
dur_infection = ss.normal(loc=12, scale=2, unit='years')
dur_infection = ss.years(ss.normal(loc=12, scale=2)) # Same as above
dur_infection = ss.normal(loc=ss.years(12), scale=2)) # Same as above
dur_infection = ss.normal(loc=ss.years(12), scale=ss.months(24)) # Same as above, perform time unit conversion internally
dur_infection.init(force=True).plot_hist() # Show results
# Create a distribution manually
dist = ss.Dist(dist=sps.norm, loc=3).init(force=True)
dist.rvs(10) # Return 10 normally distributed random numbersAttributes
| Name | Description |
|---|---|
| state | Get the current state |
| state_int | Get the integer corresponding to the current state |
Methods
| Name | Description |
|---|---|
| call_par | Check if this parameter needs to be called to be turned into an array; not for the user |
| call_pars | Check if any parameters need to be called to be turned into arrays; not for the user |
| convert_callable | Method to handle how callable parameters are processed; not for the user |
| convert_timepars | Convert time parameters (durations and rates) to scalars |
| disp | Return full display of object |
| get_state | Return a copy of the state |
| init | Calculate the starting seed and create the RNG |
| jump | Advance the RNG, e.g. to timestep “to”, by jumping |
| jump_dt | Automatically jump on the next value of dt |
| link_module | Shortcut for linking the module |
| link_sim | Shortcut for linking the sim, only overwriting an existing one if overwrite=True; not for the user |
| make_history | Store the current state in history |
| make_rvs | Return default random numbers for scalar parameters; not for the user |
| mock | Create a distribution using a mock sim for testing purposes |
| plot_hist | Plot the current state of the RNG as a histogram |
| ppf | Return default random numbers for array parameters; not for the user |
| process_dist | Ensure the distribution works; not for the user |
| process_pars | Ensure the supplied dist and parameters are valid, and initialize them; not for the user |
| process_seed | Obtain the seed offset by hashing the path to this distribution; not for the user |
| process_size | Handle an input of either size or UIDs and calculate size, UIDs, and slots; not for the user |
| rand | Simple way to get simple random numbers |
| randround | Round the values up or down to an integer stochastically; usually called via dist.rvs(round=True) |
| reset | Restore state, allowing the same numbers to be resampled |
| rvs | Get random variates – use this! |
| set | Set (change) the distribution type, or one or more parameters of the distribution |
| show_state | Show the state of the object |
| shrink | Shrink the size of the module for saving to disk |
| sync_pars | Perform any necessary synchronizations or transformations on distribution parameters; not for the user |
| to_json | Return a dictionary representation of the Dist |
| update_dist_pars | Update SciPy distribution parameters; not for the user |
| validate_pars | Check if parameters are valid; only used for non-SciPy distributions |
call_par
distributions.Dist.call_par(key, val, size, uids)Check if this parameter needs to be called to be turned into an array; not for the user
call_pars
distributions.Dist.call_pars()Check if any parameters need to be called to be turned into arrays; not for the user
convert_callable
distributions.Dist.convert_callable(parkey, func, size, uids)Method to handle how callable parameters are processed; not for the user
convert_timepars
distributions.Dist.convert_timepars()Convert time parameters (durations and rates) to scalars
This function converts time parameters into bare numbers that will be returned by rvs() depending on the timestep of the parent module for this Dist. The conversion for these types is
- Durations are divided by
dt(so the result will be a number of timesteps) - Rates are multiplied by
dt(so the result will be a number of events, or else the equivalent multiplicate value for the timestep)
disp
distributions.Dist.disp()Return full display of object
get_state
distributions.Dist.get_state()Return a copy of the state
init
distributions.Dist.init(
trace=None,
seed=None,
module=None,
sim=None,
slots=None,
force=False,
)Calculate the starting seed and create the RNG
Typically this is not invoked by the user, although the user can call it with force=True to initialize a distribution manually independently of a ss.Sim object (which is equivalent to setting strict=False when creating the dist).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| trace | str | the distribution’s location within the sim | None |
| seed | int | the base random number seed that other random number seeds will be generated from | None |
| module | ss.Module |
the parent module | None |
| sim | ss.Sim |
the parent sim | None |
| slots | array | the agent slots of the parent sim | None |
| force | bool | whether to skip validation (if the dist has already been initialized, and if any inputs are None) | False |
jump
distributions.Dist.jump(to=None, delta=1, force=False)Advance the RNG, e.g. to timestep “to”, by jumping
jump_dt
distributions.Dist.jump_dt(ti=None, force=False)Automatically jump on the next value of dt
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| ti | int | if specified, jump to this timestep (default: current module timestep plus one) | None |
link_module
distributions.Dist.link_module(module=None, overwrite=False)Shortcut for linking the module
link_sim
distributions.Dist.link_sim(sim=None, overwrite=False)Shortcut for linking the sim, only overwriting an existing one if overwrite=True; not for the user
make_history
distributions.Dist.make_history(reset=False)Store the current state in history
make_rvs
distributions.Dist.make_rvs()Return default random numbers for scalar parameters; not for the user
mock
distributions.Dist.mock(trace='mock', **kwargs)Create a distribution using a mock sim for testing purposes
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| trace | str | the “trace” of the distribution (normally, where it would be located in the sim) | 'mock' |
| **kwargs | dict | passed to ss.mock_sim() as well as ss.mock_module() (typically time args, e.g. dt) |
{} |
Example:
dist = ss.normal(3, 2, unit='years').mock(dt=ss.days(1))
dist.rvs(10)plot_hist
distributions.Dist.plot_hist(n=1000, bins=None, fig_kw=None, hist_kw=None)Plot the current state of the RNG as a histogram
ppf
distributions.Dist.ppf(rands)Return default random numbers for array parameters; not for the user
process_dist
distributions.Dist.process_dist()Ensure the distribution works; not for the user
process_pars
distributions.Dist.process_pars(call=True)Ensure the supplied dist and parameters are valid, and initialize them; not for the user
process_seed
distributions.Dist.process_seed(trace=None, seed=None)Obtain the seed offset by hashing the path to this distribution; not for the user
process_size
distributions.Dist.process_size(n=1)Handle an input of either size or UIDs and calculate size, UIDs, and slots; not for the user
rand
distributions.Dist.rand(size)Simple way to get simple random numbers
randround
distributions.Dist.randround(rvs)Round the values up or down to an integer stochastically; usually called via dist.rvs(round=True)
reset
distributions.Dist.reset(state=0)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)rvs
distributions.Dist.rvs(n=1, round=False, reset=False)Get random variates – use this!
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| n | int / tuple / arr |
if an int or tuple, return this many random variates; if an array, treat as UIDs | 1 |
| round | bool | if True, randomly round up or down based on how close the value is | False |
| reset | bool | whether to automatically reset the random number distribution state after being called | False |
set
distributions.Dist.set(*args, dist=None, **kwargs)Set (change) the distribution type, or one or more parameters of the distribution
show_state
distributions.Dist.show_state(output=False)Show the state of the object
shrink
distributions.Dist.shrink()Shrink the size of the module for saving to disk
sync_pars
distributions.Dist.sync_pars()Perform any necessary synchronizations or transformations on distribution parameters; not for the user
to_json
distributions.Dist.to_json()Return a dictionary representation of the Dist
update_dist_pars
distributions.Dist.update_dist_pars(pars=None)Update SciPy distribution parameters; not for the user
validate_pars
distributions.Dist.validate_pars()Check if parameters are valid; only used for non-SciPy distributions
DistNotInitializedError
distributions.DistNotInitializedError(dist=None, msg=None)Raised when Dist object is called when not initialized.
DistNotReadyError
distributions.DistNotReadyError(dist=None, msg=None)Raised when a Dist object is called without being ready.
DistSeedRepeatError
distributions.DistSeedRepeatError(dist1=None, dist2=None, msg=None)Raised when a Dist object shares a seed with another
Dists
distributions.Dists(obj=None, *args, base_seed=None, sim=None)Class for managing a collection of Dist objects
Methods
| Name | Description |
|---|---|
| check_seeds | Check that no two distributions share the same seed |
| copy_to_module | Copy the Sim’s Dists object to the specified module |
| init | Set the base seed, find and initialize all distributions in an object |
| jump | Advance all RNGs, e.g. to call “to”, by jumping |
| jump_dt | Advance all RNGs to the next timestep |
| keys | Return the keys of the Dist objects |
| reset | Reset each RNG |
check_seeds
distributions.Dists.check_seeds()Check that no two distributions share the same seed
copy_to_module
distributions.Dists.copy_to_module(module)Copy the Sim’s Dists object to the specified module
init
distributions.Dists.init(obj=None, base_seed=None, sim=None, force=False)Set the base seed, find and initialize all distributions in an object
In practice, the object is usually a Sim, but can be anything.
jump
distributions.Dists.jump(to=None, delta=1, force=False)Advance all RNGs, e.g. to call “to”, by jumping
jump_dt
distributions.Dists.jump_dt(ti=None, force=False)Advance all RNGs to the next timestep
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| ti | int | if specified, jump to this timestep (default: current sim timestep) | None |
keys
distributions.Dists.keys()Return the keys of the Dist objects
reset
distributions.Dists.reset()Reset each RNG
bernoulli
distributions.bernoulli(p=0.5, **kwargs)Bernoulli distribution: return True or False with the specified probability (which can be an array)
Unlike other distributions, Bernoulli distributions have a filter() method, which returns elements of the array that return True.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| p | float | the probability of returning True (default 0.5) | 0.5 |
Methods
| Name | Description |
|---|---|
| filter | Return UIDs that correspond to True, or optionally return both True and False |
| split | Alias to filter(uids, both=True) |
filter
distributions.bernoulli.filter(uids=None, both=False)Return UIDs that correspond to True, or optionally return both True and False
split
distributions.bernoulli.split(uids=None)Alias to filter(uids, both=True)
beta_dist
distributions.beta_dist(a=1.0, b=1.0, **kwargs)Beta distribution
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| a | float | shape parameter, must be > 0 (default 1.0) | 1.0 |
| b | float | shape parameter, must be > 0 (default 1.0) | 1.0 |
beta_mean
distributions.beta_mean(mean=0.5, var=0.05, force=False, **kwargs)Beta distribution paramterized by the mean
Note: the variance of a beta distribution must be 0 < var < mean*(1-mean)
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| mean | float | mean of distribution, must be 0 < a < 1 (default 0.5) | 0.5 |
| var | float | variance of distribution, must be > 0 (default 0.05) | 0.05 |
| force | bool | if True, scale the parameters to the valid range | False |
choice
distributions.choice(a=2, p=None, replace=True, **kwargs)Random choice between discrete options (note: dynamic parameters not supported)
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| a | int or array | the number of choices, or the choices themselves (default 2) | 2 |
| p | array | if supplied, the probability of each choice (default, 1/a for a choices) | None |
Examples:
# Simulate 10 die rolls
ss.choice(6, strict=False)(10) + 1
# Choose between specified options each with a specified probability (must sum to 1)
ss.choice(a=[30, 70], p=[0.3, 0.7], strict=False)(10)Note: although Bernoulli trials can be generated using a=2, it is much faster to use ss.bernoulli() instead.
Methods
| Name | Description |
|---|---|
| ppf | Shouldn’t actually be needed since dynamic pars not supported |
ppf
distributions.choice.ppf(rands)Shouldn’t actually be needed since dynamic pars not supported
constant
distributions.constant(v=0.0, **kwargs)Constant (delta) distribution: equivalent to np.full()
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| v | float | the value to return | 0.0 |
expon
distributions.expon(scale=1.0, **kwargs)Exponential distribution
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| scale | float | the scale of the distribution (default 1.0) | 1.0 |
gamma
distributions.gamma(a=1.0, loc=0.0, scale=1.0, **kwargs)Gamma distribution (specifically, scipy.stats.gamma)
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| a | float | the shape parameter, sometimes called k (default 1.0) | 1.0 |
| loc | float | the location parameter, which shifts the position of the distribution (default 0.0) | 0.0 |
| scale | float | the scale parameter, sometimes called θ (default 1.0) | 1.0 |
Methods
| Name | Description |
|---|---|
| make_rvs | Use SciPy rather than NumPy to include the scale parameter |
make_rvs
distributions.gamma.make_rvs()Use SciPy rather than NumPy to include the scale parameter
histogram
distributions.histogram(
values=None,
bins=None,
density=False,
data=None,
**kwargs,
)Sample from a histogram with defined bins
Note: unlike other distributions, the parameters of this distribution can’t be modified after creation.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| values | array | the probability (or count) of each bin | None |
| bins | array | the edges of each bin | None |
| density | bool | treat the histogram as a density instead of counts; only matters with unequal bin widths, see numpy.histogram and scipy.stats.rv_histogram for more information | False |
| data | array | if supplied, compute the values and bin edges using this data and np.histogram() instead | None |
Note: if the length of bins is equal to the length of values, they will be interpreted as left bin edges, and one additional right-bin edge will be added based on the difference between the last two bins (e.g. if the last two bins are 40 and 50, the final right edge will be added at 60). If no bins are supplied, then they will be created as integers matching the length of the values.
The values can be supplied in either normalized (sum to 1) or un-normalized format.
Examples:
# Sample from an age distribution
age_bins = [0, 10, 20, 40, 65, 100]
age_vals = [0.1, 0.1, 0.3, 0.3, 0.2]
h1 = ss.histogram(values=age_vals, bins=age_bins, strict=False)
h1.plot_hist()
# Create a histogram from data
data = np.random.randn(10_000)*2+5
h2 = ss.histogram(data=data, strict=False)
h2.plot_hist(bins=100)lognorm_ex
distributions.lognorm_ex(mean=1.0, std=1.0, **kwargs)Lognormal distribution, parameterized in terms of the “explicit” (lognormal) distribution, with mean=mean and std=std for this distribution (see lognorm_im for comparison). Note that a mean ≤ 0.0 is impossible, since this is the parameter of the distribution after the log transform.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| mean | float | the mean of this distribution (not the underlying distribution) (default 1.0) | 1.0 |
| std | float | the standard deviation of this distribution (not the underlying distribution) (default 1.0) | 1.0 |
Example:
ss.lognorm_ex(mean=2, std=1, strict=False).rvs(1000).mean() # Should be close to 2Methods
| Name | Description |
|---|---|
| convert_ex_to_im | Lognormal distributions can be specified in terms of the mean and standard |
| sync_pars | Convert from overlying to underlying parameters, then translate to SciPy |
convert_ex_to_im
distributions.lognorm_ex.convert_ex_to_im()Lognormal distributions can be specified in terms of the mean and standard deviation of the “explicit” lognormal distribution, or the “implicit” normal distribution. This function converts the parameters from the lognormal distribution to the parameters of the underlying (implicit) distribution, which are the form expected by NumPy’s and SciPy’s lognorm() distributions.
sync_pars
distributions.lognorm_ex.sync_pars()Convert from overlying to underlying parameters, then translate to SciPy
lognorm_im
distributions.lognorm_im(mean=0.0, sigma=1.0, **kwargs)Lognormal distribution, parameterized in terms of the “implicit” (normal) distribution, with mean=loc and std=scale (see lognorm_ex for comparison).
Note: the “loc” parameter here does not correspond to the mean of the resulting random variates!
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| mean | float | the mean of the underlying normal distribution (not this distribution) (default 0.0) | 0.0 |
| sigma | float | the standard deviation of the underlying normal distribution (not this distribution) (default 1.0) | 1.0 |
Example:
ss.lognorm_im(mean=2, sigma=1, strict=False).rvs(1000).mean() # Should be roughly 10Methods
| Name | Description |
|---|---|
| sync_pars | Translate between NumPy and SciPy parameters |
sync_pars
distributions.lognorm_im.sync_pars(call=True)Translate between NumPy and SciPy parameters
multi_random
distributions.multi_random(names, *args, **kwargs)A class for holding two or more ss.random() distributions, and generating random numbers linked to each of them. Useful for e.g. pairwise transmission probabilities.
See ss.combine_rands() for the manual version; in almost all cases this class should be used instead.
Usage
multi = ss.multi_random(‘source’, ‘target’) rvs = multi.rvs(source_uids, target_uids)
Methods
| Name | Description |
|---|---|
| combine_rvs | Combine inputs into one number |
| init | Not usually needed since each dist will handle this automatically; for completeness only |
| jump | Not usually needed since each dist will handle this automatically; for completeness only |
| reset | Not usually needed since each dist will handle this automatically; for completeness only |
| rvs | Get random variates from each of the underlying distributions and combine them efficiently |
combine_rvs
distributions.multi_random.combine_rvs(rvs_list, int_type, int_max)Combine inputs into one number
init
distributions.multi_random.init(*args, **kwargs)Not usually needed since each dist will handle this automatically; for completeness only
jump
distributions.multi_random.jump(*args, **kwargs)Not usually needed since each dist will handle this automatically; for completeness only
reset
distributions.multi_random.reset(*args, **kwargs)Not usually needed since each dist will handle this automatically; for completeness only
rvs
distributions.multi_random.rvs(*args)Get random variates from each of the underlying distributions and combine them efficiently
nbinom
distributions.nbinom(n=1, p=0.5, **kwargs)Negative binomial distribution
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| n | float | the number of successes, > 1 (default 1.0) | 1 |
| p | float | the probability of success in [0,1], (default 0.5) | 0.5 |
normal
distributions.normal(loc=0.0, scale=1.0, **kwargs)Normal distribution
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| loc | float | the mean of the distribution (default 0.0) | 0.0 |
poisson
distributions.poisson(lam=1.0, **kwargs)Poisson distribution
Note: unlike rate-based distributions, the Poisson lambda parameter is not automatically scaled by dt. If using this distribution in a context where dt != 1, you may need to scale lambda manually (e.g., lam*dt).
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| lam | float | the scale of the distribution (default 1.0) | 1.0 |
Methods
| Name | Description |
|---|---|
| sync_pars | Translate between NumPy and SciPy parameters |
sync_pars
distributions.poisson.sync_pars()Translate between NumPy and SciPy parameters
rand_raw
distributions.rand_raw(
dist=None,
distname=None,
name=None,
unit=None,
seed=None,
offset=None,
strict=True,
auto=True,
sim=None,
module=None,
mock=False,
debug=False,
**kwargs,
)Directly sample raw integers (uint64) from the random number generator. Typicaly only used with ss.combine_rands().
randint
distributions.randint(
*args,
low=None,
high=None,
dtype=ss.dtypes.rand_int,
allow_time=False,
**kwargs,
)Random integer distribution, on the interval [low, high)
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| low | int | the lower bound of the distribution (default 0) | None |
| high | int | the upper bound of the distribution (default of maximum integer size: 9,223,372,036,854,775,807) | None |
| allow_time | bool | allow time parameters to be specified as high/low values (disabled by default since introduces rounding error) | False |
random
distributions.random(**kwargs)Random distribution, with values on the interval (0, 1)
scale_types
distributions.scale_types()Define how distributions scale
Distributions scale in different ways, such as converting between time units. Some distributions can’t be scaled at all (e.g. ss.beta_dist() or ss.choice()). For distributions that can be scaled, some distributions can only be (linearly) scaled before the random numbers are generated (called “predraw”), some can only be scaled after (called “postdraw”), and some can be scaled in either way (“both”).
For example, a normal distribution is “both” since 2Normal(a, b) = Normal(2a, 2b). A Poisson distribution is “predraw” since 2Poisson(λ) ≠ Poisson(2λ), and there is no way to get the correct shape of a different Poisson distribution once the numbers have been drawn. Finally, distributions with unitless shape parameters as well as parameter that can have units (e.g. a gamma distribution with shape and scale parameters) are referred to as “postdraw” since scaling all input parameters is invalid (i.e. 2Gamma(shape, scale) ≠ Gamma(2shape, 2scale)), but they can still be scaled (i.e. 2Gamma(shape, scale) = Gamma(1shape, 2*scale)).
To summarize, options for dist.scaling are:
- 'postdraw' (after the random numbers are drawn, e.g. `ss.weibull()`)
- 'predraw' (before the draw, e.g. `ss.poisson()`)
- 'both' (either pre or post draw, e.g. `ss.normal()`)
- False (not at all, e.g. `ss.beta_dist()`)Use ss.distributions.scale_types.show() to show how each distribution scales with time.
Methods
| Name | Description |
|---|---|
| check_postdraw | Check if the supplied distribution supports post-draw (results) scaling |
| check_predraw | Check if the supplied distribution supports pre-draw (parameter) scaling |
| show | Show which distributions have which scale types |
check_postdraw
distributions.scale_types.check_postdraw(dist)Check if the supplied distribution supports post-draw (results) scaling
check_predraw
distributions.scale_types.check_predraw(dist)Check if the supplied distribution supports pre-draw (parameter) scaling
show
distributions.scale_types.show(to_df=False)Show which distributions have which scale types
uniform
distributions.uniform(low=None, high=None, **kwargs)Uniform distribution, values on interval (low, high)
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| low | float | the lower bound of the distribution (default 0.0) | None |
| high | float | the upper bound of the distribution (default 1.0) | None |
Methods
| Name | Description |
|---|---|
| make_rvs | Specified here because uniform() doesn’t take a dtype argument |
make_rvs
distributions.uniform.make_rvs()Specified here because uniform() doesn’t take a dtype argument
weibull
distributions.weibull(c=1.0, loc=0.0, scale=1.0, **kwargs)Weibull distribution (specifically, scipy.stats.weibull_min)
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| c | float | the shape parameter, sometimes called k (default 1.0) | 1.0 |
| loc | float | the location parameter, which shifts the position of the distribution (default 0.0) | 0.0 |
| scale | float | the scale parameter, sometimes called λ (default 1.0) | 1.0 |
Methods
| Name | Description |
|---|---|
| make_rvs | Use SciPy rather than NumPy to include the scale parameter |
make_rvs
distributions.weibull.make_rvs()Use SciPy rather than NumPy to include the scale parameter
Functions
| Name | Description |
|---|---|
| link_dists | Link distributions to the sim and the module; used in module.init() and people.init() |
| make_dist | Make a distribution from a dictionary |
| str2int | Convert a string to an int to use as a random seed; not for the user |
link_dists
distributions.link_dists(
obj,
sim,
module=None,
overwrite=False,
init=False,
**kwargs,
)Link distributions to the sim and the module; used in module.init() and people.init()
make_dist
distributions.make_dist(pars=None, **kwargs)Make a distribution from a dictionary
str2int
distributions.str2int(string, modulo=1000000000)Convert a string to an int to use as a random seed; not for the user
Cannot use Python’s built-in hash() since it’s randomized for strings. Hashlib (sc.sha) is 5x slower than int.from_bytes(string.encode(), byteorder=‘big’), but should only add a couple milliseconds to a typical sim.