Distributions¶

The distributions module provides probability distributions used for shocks and initial conditions. Continuous distributions support both drawing random samples and discretization into point-mass approximations.

Note

Normal and Lognormal are parameterized by the distribution’s mean and standard deviation in levels, not by the log-space parameters \((\mu, \sigma)\) familiar from other libraries. A standard deviation of zero produces a degenerate point mass at the mean argument.

Distribution classes that provide compatibility with scipy.stats and torch.distributions for better integration with neural network methods while maintaining API compatibility.

class skagent.distributions.Bernoulli(p=0.5, backend='scipy', rng=None)¶

Bernoulli distribution compatible with skagent.distributions.Bernoulli

Parameters:

p (float)
backend (str)
rng (Generator | None)

discretize(**kwargs)¶

Bernoulli is already discrete

Return type:: DiscreteDistribution

icdf(u)¶

Bernoulli’s quantile function.

Neither backend supplies a usable one: torch.distributions.Bernoulli raises NotImplementedError, and scipy’s ppf maps u = 0, which rng.random can return, to -1.

Return type:: ndarray

property mean: float¶: Mean of the distribution

property std: float¶: Standard deviation of the distribution

class skagent.distributions.DiscreteDistribution(points, weights, var_names=None, rng=None)¶

A discrete distribution representation for labeled discrete distributions

Parameters:

points (ndarray)
weights (ndarray)
var_names (list[str] | None)
rng (Generator | None)

draw(n=1)¶

Draw samples from the discrete distribution

Parameters:: n (int)
Return type:: ndarray

class skagent.distributions.DiscreteDistributionLabeled(points, weights, var_names=None, rng=None)¶

Labeled discrete distribution with variable names

Parameters:

points (ndarray)
weights (ndarray)
var_names (list[str] | None)
rng (Generator | None)

classmethod from_unlabeled(unlabeled_dist, var_names)¶

Create labeled distribution from unlabeled one

Parameters:: var_names (list[str])

class skagent.distributions.Distribution(backend='scipy', rng=None)¶

Base class for all distributions, providing a common interface that works with both scipy and torch backends.

Parameters:

backend (str)
rng (Generator | None)

abstractmethod discretize(**kwargs)¶

Discretize the distribution

Return type:: DiscreteDistribution

draw(n=1)¶

Draw n samples from the distribution.

Samples are taken by inverting the distribution at uniform draws from self.rng, so that two distributions sharing a generator state and differing slightly in their parameters produce samples that differ slightly, rather than a different sample path.

Parameters:: n (int)
Return type:: ndarray

icdf(u)¶

Quantile function: the value below which a proportion u of the mass lies.

Parameters:: u (array_like) – Probabilities in [0, 1].
Return type:: ndarray

log_prob(x)¶

Log density (or log mass, for a discrete distribution) at x.

Parameters:: x (array_like) – Points in the support of the distribution.
Return type:: ndarray

abstract property mean: float¶: Mean of the distribution

abstract property std: float¶: Standard deviation of the distribution

class skagent.distributions.IndexDistribution(dist_class, params_dict, rng=None)¶

Distribution that varies by index (like age), compatible with skagent.distributions.IndexDistribution

Parameters:

params_dict (dict[str, list])
rng (Generator | None)

draw(conditions)¶

Draw samples based on conditions (typically ages)

Parameters:: conditions (ndarray)
Return type:: ndarray

class skagent.distributions.Lognormal(mean=1.0, std=1.0, backend='scipy', rng=None)¶

Lognormal distribution compatible with skagent.distributions.Lognormal

Parameters:

mean (float)
std (float)
backend (str)
rng (Generator | None)

discretize(n_points=7, N=None, **kwargs)¶

Discretize using Gauss-Hermite quadrature on the log

Parameters:

n_points (int)
N (int | None)

Return type:

DiscreteDistribution

icdf(u)¶

Quantile function: the value below which a proportion u of the mass lies.

Parameters:: u (array_like) – Probabilities in [0, 1].
Return type:: ndarray

property mean: float¶: Mean of the distribution

property std: float¶: Standard deviation of the distribution

class skagent.distributions.MeanOneLogNormal(sigma=1.0, backend='scipy', rng=None)¶

Lognormal distribution with mean normalized to 1.0

Parameters:

sigma (float)
backend (str)
rng (Generator | None)

class skagent.distributions.Normal(mu=0.0, sigma=1.0, backend='scipy', rng=None)¶

Normal distribution compatible with skagent.distributions.Normal

Parameters:

mu (float)
sigma (float)
backend (str)
rng (Generator | None)

discretize(n_points=7, sigma_range=3.0, N=None, **kwargs)¶

Discretize using Gauss-Hermite quadrature or uniform grid

Parameters:

n_points (int)
sigma_range (float)
N (int | None)

Return type:

DiscreteDistribution

icdf(u)¶

Quantile function: the value below which a proportion u of the mass lies.

Parameters:: u (array_like) – Probabilities in [0, 1].
Return type:: ndarray

property mean: float¶: Mean of the distribution

property std: float¶: Standard deviation of the distribution

class skagent.distributions.TimeVaryingDiscreteDistribution(distributions)¶

Time-varying discrete distribution for compatibility

Parameters:: distributions (list[DiscreteDistribution])

draw(conditions)¶

Draw samples based on time conditions

Parameters:: conditions (ndarray)
Return type:: ndarray

class skagent.distributions.Uniform(low=0.0, high=1.0, backend='scipy', rng=None)¶

Uniform distribution

Parameters:

low (float)
high (float)
backend (str)
rng (Generator | None)

discretize(n_points=7, N=None, **kwargs)¶

Discretize using Gauss-Hermite quadrature or uniform grid

Parameters:

n_points (int)
N (int | None)

Return type:

DiscreteDistribution

icdf(u)¶

Quantile function: the value below which a proportion u of the mass lies.

Parameters:: u (array_like) – Probabilities in [0, 1].
Return type:: ndarray

property mean: float¶: Mean of the distribution

property std: float¶: Standard deviation of the distribution

skagent.distributions.combine_indep_dstns(*distributions)¶

Combine independent discrete distributions into a joint distribution Compatible with skagent.distributions.combine_indep_dstns

Return type:: DiscreteDistribution

skagent.distributions.expected(func, dist)¶

Compute expected value of a function over a discrete distribution Compatible with skagent.distributions.expected

Parameters:: dist (DiscreteDistribution)
Return type:: float

skagent.distributions.set_rng(obj, rng)¶

Point obj and everything it draws through at rng.

A distribution that holds other distributions draws through the ones it holds, so its own generator is not the one that produces its values: IndexDistribution draws through distributions[condition] and Aggregate through dist. Seeding such an object means seeding what it defers to, which is why this recurses rather than assigning one attribute.

Every reachable distribution is pointed at the same generator, so one stream produces the whole draw and the sequence is reproducible from the seed that generator was built with.

Parameters:

obj (any) – A distribution, or an object wrapping one. Objects carrying none of rng, dist or distributions are left alone.
rng (Generator) – The generator to draw from.

Return type:

None