# Distribution¶

class HARK.distribution.Bernoulli(p=0.5, seed=0)

A Bernoulli distribution.

Parameters: p (float or [float]) – Probability or probabilities of the event occurring (True). seed (int) – Seed for random number generator.
draw(N)

Generates arrays of booleans drawn from a simple Bernoulli distribution. The input p can be a float or a list-like of floats; its length T determines the number of entries in the output. The t-th entry of the output is an array of N booleans which are True with probability p[t] and False otherwise.

Parameters: N (int) – Number of draws in each row. draws (np.array or [np.array]) – T-length list of arrays of Bernoulli draws each of size N, or a single array of size N (if sigma is a scalar).
p = None
class HARK.distribution.DiscreteDistribution(pmf, X, seed=0)

A representation of a discrete probability distribution.

Parameters: pmf (np.array) – An array of floats representing a probability mass function. X (np.array) – Discrete point values for each probability mass. For multivariate distributions, the last dimension of X must index “nature” or the random realization. For instance, if X.shape == (2,6,4), the random variable has 4 possible realizations and each of them has shape (2,6). seed (int) – Seed for random number generator.
X = None
dim()
draw(N, X=None, exact_match=False)

Simulates N draws from a discrete distribution with probabilities P and outcomes X.

Parameters: N (int) – Number of draws to simulate. X (None, int, or np.array) – If None, then use this distribution’s X for point values. If an int, then the index of X for the point values. If an np.array, use the array for the point values. exact_match (boolean) – Whether the draws should “exactly” match the discrete distribution (as closely as possible given finite draws). When True, returned draws are a random permutation of the N-length list that best fits the discrete distribution. When False (default), each draw is independent from the others and the result could deviate from the input. draws – An array of draws from the discrete distribution; each element is a value in X. np.array
draw_events(n)

Draws N ‘events’ from the distribution PMF. These events are indices into X.

pmf = None
class HARK.distribution.Distribution(seed=0)

Bases: object

Base class for all probability distributions.

Parameters: seed (int) – Seed for random number generator.
reset()

Reset the random number generator of this distribution.

class HARK.distribution.IndexDistribution(engine, conditional, RNG=None, seed=0)

This class provides a way to define a distribution that is conditional on an index.

The current implementation combines a defined distribution class (such as Bernoulli, LogNormal, etc.) with information about the conditions on the parameters of the distribution.

For example, an IndexDistribution can be defined as a Bernoulli distribution whose parameter p is a function of a different inpute parameter.

Parameters: engine (Distribution class) – A Distribution subclass. conditional (dict) – Information about the conditional variation on the input parameters of the engine distribution. Keys should match the arguments to the engine class constructor. seed (int) – Seed for random number generator.
approx(N, **kwds)

Approximation of the distribution.

Parameters: N (init) – Number of discrete points to approximate continuous distribution into. kwds (dict) – Other keyword arguments passed to engine distribution approx() method. Returns – ------------ – dists ([DiscreteDistribution]) – A list of DiscreteDistributions that are the approximation of engine distribution under each condition. TODO: It would be better if there were a conditional discrete distribution representation. But that integrates with the solution code. This implementation will return the list of distributions representations expected by the solution code.
conditional = None
draw(condition)

Generate arrays of draws. The input is an array containing the conditions. The output is an array of the same length (axis 1 dimension) as the conditions containing random draws of the conditional distribution.

Parameters: condition (np.array) – The input conditions to the distribution. Returns – ------------ – draws (np.array) –
engine = None
class HARK.distribution.Lognormal(mu=0.0, sigma=1.0, seed=0)

A Lognormal distribution

Parameters: mu (float or [float]) – One or more means of underlying normal distribution. Number of elements T in mu determines number of rows of output. sigma (float or [float]) – One or more standard deviations of underlying normal distribution. Number of elements T in sigma determines number of rows of output. seed (int) – Seed for random number generator.
approx(N, tail_N=0, tail_bound=None, tail_order=2.718281828459045)

Construct a discrete approximation to a lognormal distribution with underlying normal distribution N(mu,sigma). Makes an equiprobable distribution by default, but user can optionally request augmented tails with exponentially sized point masses. This can improve solution accuracy in some models.

Parameters: N (int) – Number of discrete points in the “main part” of the approximation. tail_N (int) – Number of points in each “tail part” of the approximation; 0 = no tail. tail_bound ([float]) – CDF boundaries of the tails vs main portion; tail_bound is the lower tail bound, tail_bound is the upper tail bound. Inoperative when tail_N = 0. Can make “one tailed” approximations with 0.0 or 1.0. tail_order (float) – Factor by which consecutive point masses in a “tail part” differ in probability. Should be >= 1 for sensible spacing. d – Probability associated with each point in array of discrete points for discrete probability mass function. DiscreteDistribution
draw(N)

Generate arrays of lognormal draws. The sigma parameter can be a number or list-like. If a number, output is a length N array of draws from the lognormal distribution with standard deviation sigma. If a list, output is a length T list whose t-th entry is a length N array of draws from the lognormal with standard deviation sigma[t].

Parameters: N (int) – Number of draws in each row. Returns – ------------ – draws (np.array or [np.array]) – T-length list of arrays of mean one lognormal draws each of size N, or a single array of size N (if sigma is a scalar).
classmethod from_mean_std(mean, std, seed=0)

Construct a LogNormal distribution from its mean and standard deviation.

This is unlike the normal constructor for the distribution, which takes the mu and sigma for the normal distribution that is the logarithm of the Log Normal distribution.

Parameters: mean (float or [float]) – One or more means. Number of elements T in mu determines number of rows of output. std (float or [float]) – One or more standard deviations. Number of elements T in sigma determines number of rows of output. seed (int) – Seed for random number generator. LogNormal
mu = None
sigma = None
class HARK.distribution.MVNormal(mu=array([1, 1]), Sigma=array([[1, 0], [0, 1]]), seed=0)

A Multivariate Normal distribution.

Parameters: mu (numpy array) – Mean vector. Sigma (2-d numpy array. Each dimension must have length equal to that of) – mu. Variance-covariance matrix. seed (int) – Seed for random number generator.
Sigma = None
approx(N, equiprobable=False)

Returns a discrete approximation of this distribution.

The discretization will have N**M points, where M is the dimension of the multivariate normal.

It uses the fact that:
• Being positive definite, Sigma can be factorized as Sigma = QVQ’, with V diagonal. So, letting A=Q*sqrt(V), Sigma = A*A’.
• If Z is an N-dimensional multivariate standard normal, then A*Z ~ N(0,A*A’ = Sigma).

The idea therefore is to construct an equiprobable grid for a standard normal and multiply it by matrix A.

draw(N)

Generate an array of multivariate normal draws.

Parameters: N (int) – Number of multivariate draws. draws – Array of dimensions N x M containing the random draws, where M is the dimension of the multivariate normal and N is the number of draws. Each row represents a draw. np.array
mu = None
class HARK.distribution.MarkovProcess(transition_matrix, seed=0)

A representation of a discrete Markov process.

Parameters: transition_matrix (np.array) – An array of floats representing a probability mass for each state transition. seed (int) – Seed for random number generator.
draw(state)

Draw new states fromt the transition matrix.

Parameters: state (int or nd.array) – The state or states (1-D array) from which to draw new states. new_state – New states. int or nd.array
transition_matrix = None
class HARK.distribution.MeanOneLogNormal(sigma=1.0, seed=0)
class HARK.distribution.Normal(mu=0.0, sigma=1.0, seed=0)

A Normal distribution.

Parameters: mu (float or [float]) – One or more means. Number of elements T in mu determines number of rows of output. sigma (float or [float]) – One or more standard deviations. Number of elements T in sigma determines number of rows of output. seed (int) – Seed for random number generator.
approx(N)

Returns a discrete approximation of this distribution.

approx_equiprobable(N)
draw(N)

Generate arrays of normal draws. The mu and sigma inputs can be numbers or list-likes. If a number, output is a length N array of draws from the normal distribution with mean mu and standard deviation sigma. If a list, output is a length T list whose t-th entry is a length N array with draws from the normal distribution with mean mu[t] and standard deviation sigma[t].

Parameters: N (int) – Number of draws in each row. draws – T-length list of arrays of normal draws each of size N, or a single array of size N (if sigma is a scalar). np.array or [np.array]
mu = None
sigma = None
class HARK.distribution.TimeVaryingDiscreteDistribution(distributions, seed=0)

This class provides a way to define a discrete distribution that is conditional on an index.

Wraps a list of discrete distributions.

Parameters: distributions ([DiscreteDistribution]) – A list of discrete distributions seed (int) – Seed for random number generator.
distributions = []
draw(condition)

Generate arrays of draws. The input is an array containing the conditions. The output is an array of the same length (axis 1 dimension) as the conditions containing random draws of the conditional distribution.

Parameters: condition (np.array) – The input conditions to the distribution. Returns – ------------ – draws (np.array) –
class HARK.distribution.Uniform(bot=0.0, top=1.0, seed=0)

A Uniform distribution.

Parameters: bot (float or [float]) – One or more bottom values. Number of elements T in mu determines number of rows of output. top (float or [float]) – One or more top values. Number of elements T in top determines number of rows of output. seed (int) – Seed for random number generator.
approx(N)

Makes a discrete approximation to this uniform distribution.

Parameters: N (int) – The number of points in the discrete approximation d – Probability associated with each point in array of discrete points for discrete probability mass function. DiscreteDistribution
bot = None
draw(N)

Generate arrays of uniform draws. The bot and top inputs can be numbers or list-likes. If a number, output is a length N array of draws from the uniform distribution on [bot,top]. If a list, output is a length T list whose t-th entry is a length N array with draws from the uniform distribution on [bot[t],top[t]].

Parameters: N (int) – Number of draws in each row. draws – T-length list of arrays of uniform draws each of size N, or a single array of size N (if sigma is a scalar). np.array or [np.array]
top = None
class HARK.distribution.Weibull(scale=1.0, shape=1.0, seed=0)

A Weibull distribution.

Parameters: scale (float or [float]) – One or more scales. Number of elements T in scale determines number of rows of output. shape (float or [float]) – One or more shape parameters. Number of elements T in scale determines number of rows of output. seed (int) – Seed for random number generator.
draw(N)

Generate arrays of Weibull draws. The scale and shape inputs can be numbers or list-likes. If a number, output is a length N array of draws from the Weibull distribution with the given scale and shape. If a list, output is a length T list whose t-th entry is a length N array with draws from the Weibull distribution with scale scale[t] and shape shape[t].

Note: When shape=1, the Weibull distribution is simply the exponential dist.

Mean: scale*Gamma(1 + 1/shape)

Parameters: N (int) – Number of draws in each row. Returns – ------------ – draws (np.array or [np.array]) – T-length list of arrays of Weibull draws each of size N, or a single array of size N (if sigma is a scalar).
scale = None
shape = None
HARK.distribution.add_discrete_outcome(distribution, x, p, sort=False)

Adds a discrete outcome of x with probability p to an existing distribution, holding constant the relative probabilities of other outcomes.

Parameters: distribution (DiscreteDistribution) – One-dimensional distribution to which the outcome is to be added. x (float) – The new value to be added to the distribution. p (float) – The probability of the discrete outcome x occuring. d – Probability associated with each point in array of discrete points for discrete probability mass function. DiscreteDistribution
HARK.distribution.add_discrete_outcome_constant_mean(distribution, x, p, sort=False)

Adds a discrete outcome of x with probability p to an existing distribution, holding constant the relative probabilities of other outcomes and overall mean.

Parameters: distribution (DiscreteDistribution) – A one-dimensional DiscreteDistribution. x (float) – The new value to be added to the distribution. p (float) – The probability of the discrete outcome x occuring. sort (bool) – Whether or not to sort X before returning it d – Probability associated with each point in array of discrete points for discrete probability mass function. DiscreteDistribution
HARK.distribution.approx_beta(N, a=1.0, b=1.0)

Calculate a discrete approximation to the beta distribution. May be quite slow, as it uses a rudimentary numeric integration method to generate the discrete approximation.

Parameters: N (int) – Size of discrete space vector to be returned. a (float) – First shape parameter (sometimes called alpha). b (float) – Second shape parameter (sometimes called beta). d – Probability associated with each point in array of discrete points for discrete probability mass function. DiscreteDistribution
HARK.distribution.approx_lognormal_gauss_hermite(N, mu=0.0, sigma=1.0, seed=0)
HARK.distribution.calc_expectation(dstn, func=<function <lambda>>, *args)

Expectation of a function, given an array of configurations of its inputs along with a DiscreteDistribution object that specifies the probability of each configuration.

Parameters: dstn (DiscreteDistribution) – The distribution over which the function is to be evaluated. func (function) – The function to be evaluated. This function should take an array of shape dstn.dim() and return either arrays of arbitrary shape or scalars. It may also take other arguments *args. *args – Other inputs for func, representing the non-stochastic arguments. The the expectation is computed at f(dstn, *args). f_exp – The expectation of the function at the queried values. Scalar if only one value. np.array or scalar
HARK.distribution.calc_lognormal_style_pars_from_normal_pars(mu_normal, std_normal)
HARK.distribution.calc_normal_style_pars_from_lognormal_pars(avg_lognormal, std_lognormal)
HARK.distribution.combine_indep_dstns(*distributions, seed=0)

Given n independent vector-valued discrete distributions, construct their joint discrete distribution. Can take multivariate discrete distributions as inputs.

Parameters: distributions (DiscreteDistribution) – Arbitrary number of discrete distributionss to combine. Their realizations must be vector-valued (for each D in distributions, it must be the case that len(D.dim())==1). A DiscreteDistribution representing the joint distribution of the given random variables.
HARK.distribution.distr_of_function(dstn, func=<function <lambda>>, *args)

Finds the distribution of a random variable Y that is a function of discrete random variable X, Y=f(X).

Parameters: dstn (DiscreteDistribution) – The distribution over which the function is to be evaluated. func (function) – The function to be evaluated. This function should take an array of shape dstn.dim(). It may also take other arguments *args. *args – Additional non-stochastic arguments for func, The function is computed at f(dstn, *args). f_dstn – The distribution of func(dstn). DiscreteDistribution
HARK.distribution.make_markov_approx_to_normal(x_grid, mu, sigma, K=351, bound=3.5)

Creates an approximation to a normal distribution with mean mu and standard deviation sigma, returning a stochastic vector called p_vec, corresponding to values in x_grid. If a RV is distributed x~N(mu,sigma), then the expectation of a continuous function f() is E[f(x)] = numpy.dot(p_vec,f(x_grid)).

Parameters: x_grid (numpy.array) – A sorted 1D array of floats representing discrete values that a normally distributed RV could take on. mu (float) – Mean of the normal distribution to be approximated. sigma (float) – Standard deviation of the normal distribution to be approximated. K (int) – Number of points in the normal distribution to sample. bound (float) – Truncation bound of the normal distribution, as +/- bound*sigma. p_vec – A stochastic vector with probability weights for each x in x_grid. numpy.array
HARK.distribution.make_markov_approx_to_normal_by_monte_carlo(x_grid, mu, sigma, N_draws=10000)

Creates an approximation to a normal distribution with mean mu and standard deviation sigma, by Monte Carlo. Returns a stochastic vector called p_vec, corresponding to values in x_grid. If a RV is distributed x~N(mu,sigma), then the expectation of a continuous function f() is E[f(x)] = numpy.dot(p_vec,f(x_grid)).

Parameters: x_grid (numpy.array) – A sorted 1D array of floats representing discrete values that a normally distributed RV could take on. mu (float) – Mean of the normal distribution to be approximated. sigma (float) – Standard deviation of the normal distribution to be approximated. N_draws (int) – Number of draws to use in Monte Carlo. p_vec – A stochastic vector with probability weights for each x in x_grid. numpy.array
HARK.distribution.make_tauchen_ar1(N, sigma=1.0, ar_1=0.9, bound=3.0)

Function to return a discretized version of an AR1 process. See http://www.fperri.net/TEACHING/macrotheory08/numerical.pdf for details

Parameters: N (int) – Size of discretized grid sigma (float) – Standard deviation of the error term ar_1 (float) – AR1 coefficient bound (float) – The highest (lowest) grid point will be bound (-bound) multiplied by the unconditional standard deviation of the process y (np.array) – Grid points on which the discretized process takes values trans_matrix (np.array) – Markov transition array for the discretized process