Distribution¶

class
HARK.distribution.
Bernoulli
(p=0.5, seed=0)¶ Bases:
HARK.distribution.Distribution
A Bernoulli distribution.
Parameters: 
draw
(N)¶ Generates arrays of booleans drawn from a simple Bernoulli distribution. The input p can be a float or a listlike of floats; its length T determines the number of entries in the output. The tth 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. Returns:  draws (np.array or [np.array]) – Tlength 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)¶ Bases:
HARK.distribution.Distribution
A representation of a discrete probability distribution.
Parameters:  pmf (np.array) – An array of floats representing a probability mass function.
 X (np.array or [np.array]) – Discrete point values for each probability mass. May be multivariate (list of arrays).
 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 Nlength 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.
Returns: draws – An array of draws from the discrete distribution; each element is a value in X.
Return type: 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
Parameters: seed (int) – Seed for random number generator. 
reset
()¶ Reset the random number generator of this distribution.


class
HARK.distribution.
Lognormal
(mu=0.0, sigma=1.0, seed=0)¶ Bases:
HARK.distribution.Distribution
A Lognormal distribution
Parameters: 
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[0] is the lower tail bound, tail_bound[1] 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.
Returns: d – Probability associated with each point in array of discrete points for discrete probability mass function.
Return type:

draw
(N)¶ Generate arrays of lognormal draws. The sigma input can be a number or listlike. 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 tth entry is a length N array of draws from the lognormal with standard deviation sigma[t].
Parameters:

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: Returns: Return type: LogNormal

mu
= None¶

sigma
= None¶


class
HARK.distribution.
MarkovProcess
(transition_matrix, seed=0)¶ Bases:
HARK.distribution.Distribution
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 (1D array) from which to draw new states. Returns: new_state – New states. Return type: int or nd.array

transition_matrix
= None¶

class
HARK.distribution.
MeanOneLogNormal
(sigma=1.0, seed=0)¶ Bases:
HARK.distribution.Lognormal

class
HARK.distribution.
Normal
(mu=0.0, sigma=1.0, seed=0)¶ Bases:
HARK.distribution.Distribution
A Normal distribution.
Parameters: 
approx
(N)¶ Returns a discrete approximation of this distribution.

draw
(N)¶ Generate arrays of normal draws. The mu and sigma inputs can be numbers or listlikes. 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 tth 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. Returns: draws – Tlength list of arrays of normal draws each of size N, or a single array of size N (if sigma is a scalar). Return type: np.array or [np.array]

mu
= None¶

sigma
= None¶


class
HARK.distribution.
Uniform
(bot=0.0, top=1.0, seed=0)¶ Bases:
HARK.distribution.Distribution
A Uniform distribution.
Parameters: 
approx
(N)¶ Makes a discrete approximation to this uniform distribution.
Parameters: N (int) – The number of points in the discrete approximation Returns: d – Probability associated with each point in array of discrete points for discrete probability mass function. Return type: DiscreteDistribution

bot
= None¶

draw
(N)¶ Generate arrays of uniform draws. The bot and top inputs can be numbers or listlikes. 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 tth 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. Returns: draws – Tlength list of arrays of uniform draws each of size N, or a single array of size N (if sigma is a scalar). Return type: np.array or [np.array]

top
= None¶


class
HARK.distribution.
Weibull
(scale=1.0, shape=1.0, seed=0)¶ Bases:
HARK.distribution.Distribution
A Weibull distribution.
Parameters: 
draw
(N)¶ Generate arrays of Weibull draws. The scale and shape inputs can be numbers or listlikes. 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 tth 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]) – Tlength 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: Returns: d – Probability associated with each point in array of discrete points for discrete probability mass function.
Return type:

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: Returns: d – Probability associated with each point in array of discrete points for discrete probability mass function.
Return type:

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: Returns: d – Probability associated with each point in array of discrete points for discrete probability mass function.
Return type:

HARK.distribution.
approx_lognormal_gauss_hermite
(N, mu=0.0, sigma=1.0, seed=0)¶

HARK.distribution.
calc_expectation
(dstn, func=<function <lambda>>, *args)¶ Calculate the expectation of a stochastic function at an array of values.
Parameters:  dstn (DiscreteDistribution) – The Nvalued distribution over which the function is to be evaluated.
 func (function) – The function to be evaluated. This function should take an array of size N x M. It may also take other arguments *args Please see numpy.apply_along_axis() for guidance on design of func. Defaults to identity function.
 *args (scalar or np.array) – One or more constants or arrays of input values for func, representing the nonstochastic arguments. The arrays must all have the same shape, and the expectation is computed at f(dstn, args[0], args[1],…,args[M]).
Returns: f_exp – The expectation of the function at the queried values. Scalar if only one value.
Return type: 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 lists (or tuples) whose elements represent n independent, discrete probability spaces (probabilities and values), construct a joint pmf over all combinations of these independent points. Can take multivariate discrete distributions as inputs.
Parameters: distributions ([np.array]) – Arbitrary number of distributions (pmfs). Each pmf is a list or tuple. For each pmf, the first vector is probabilities and all subsequent vectors are values. For each pmf, this should be true: len(X_pmf[0]) == len(X_pmf[j]) for j in range(1,len(distributions)) Returns:  A DiscreteDistribution, consisting of
 P_out (np.array) – Probability associated with each point in X_out.
 X_out (np.array (as many as in *distributions)) – Discrete points for the joint discrete probability mass function.

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.
Returns: p_vec – A stochastic vector with probability weights for each x in x_grid.
Return type: 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.
Returns: p_vec – A stochastic vector with probability weights for each x in x_grid.
Return type: numpy.array

HARK.distribution.
make_tauchen_ar1
(N, sigma=1.0, rho=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: Returns:  y (np.array) – Grid points on which the discretized process takes values
 trans_matrix (np.array) – Markov transition array for the discretized process