Utilities#

General purpose / miscellaneous functions. Includes functions to approximate continuous distributions with discrete ones, utility functions (and their derivatives), manipulation of discrete distributions, and basic plotting tools.

class HARK.utilities.get_it_from(name)#

Bases: object

Class whose instances act as a special case trivial constructor that merely grabs an attribute or entry from the named attribute. This is useful when there are constructed model inputs that are “built together”. Simply have a constructor that makes a dictionary (or object) containing the several inputs, then use get_it_from(that_dict_name) as the constructor for each of them.

Parameters:: name (str) – Name of the parent dictionary or object from which to take the object.

HARK.utilities.get_arg_names(function)#

Returns a list of strings naming all of the arguments for the passed function.

Parameters:: function (function) – A function whose argument names are wanted.
Returns:: argNames – The names of the arguments of function.
Return type:: [string]

class HARK.utilities.NullFunc#

Bases: object

A trivial class that acts as a placeholder “do nothing” function.

distance(other)#

Trivial distance metric that only cares whether the other object is also an instance of NullFunc. Intentionally does not inherit from HARKobject as this might create dependency problems.

Parameters:: other (any) – Any object for comparison to this instance of NullFunc.
Returns:: (unnamed) – The distance between self and other. Returns 0 if other is also a NullFunc; otherwise returns an arbitrary high number.
Return type:: float

HARK.utilities.apply_fun_to_vals(fun, vals)#

Applies a function to the arguments defined in vals. This is equivalent to fun(**vals), except that vals may contain keys that are not named arguments of fun.

Parameters:

fun (callable)
vals (dict)

HARK.utilities.make_assets_grid(aXtraMin, aXtraMax, aXtraCount, aXtraExtra, aXtraNestFac)#

Constructs the base grid of post-decision states, representing end-of-period assets above the absolute minimum. Has three modes, depending on aXtraNestFac:

aXtraNestFac = -1 : Uniformly spaced grid. aXtraNestFac = 0 : Ordinary exponentially spaced grid. aXtraNestFac >= 1 : Multi-exponentially nested grid.

See HARK.utilities.make_grid_exp_mult() for more info

Parameters:

aXtraMin (float) – Minimum value for the assets-above-minimum grid.
aXtraMax (float) – Maximum value for the assets-above-minimum grid.
aXtraCount (int) – Number of nodes in the assets-above-minimum grid, not counting extra values.
aXtraExtra ([float]) – Additional values to insert in the assets-above-minimum grid.
aXtraNestFac (int) – Level of exponential nesting for grid. If -1, the grid is linearly spaced.

Returns:

aXtraGrid – Base array of values for the post-decision-state grid.

Return type:

np.ndarray

HARK.utilities.make_grid_exp_mult(ming, maxg, ng, timestonest=20)#

Makes a multi-exponentially spaced grid. If the function \(\ln(1+x)\) were applied timestonest times, the grid would become linearly spaced. If timestonest is 0, the grid is exponentially spaced. If timestonest is -1, the grid is linearly spaced.

Parameters:

ming (float) – Minimum value of the grid
maxg (float) – Maximum value of the grid
ng (int) – The number of grid points
timestonest (int) – the number of times to nest the exponentiation

Returns:

points – A multi-exponentially spaced grid

Return type:

np.array

Notes

Original Matab code can be found in Chris Carroll’s [Solution Methods for Microeconomic Dynamic Optimization Problems] (https://www.econ2.jhu.edu/people/ccarroll/solvingmicrodsops/) toolkit. Latest update: 01 May 2015

HARK.utilities.get_percentiles(data, weights=None, percentiles=None, presorted=False)#

Calculates the requested percentiles of (weighted) data. Median by default.

Parameters:

data (numpy.array) – A 1D array of float data.
weights (np.array) – A weighting vector for the data.
percentiles ([float]) – A list or numpy.array of percentiles to calculate for the data. Each element should be in (0,1).
presorted (boolean) – Indicator for whether data has already been sorted.

Returns:

pctl_out – The requested percentiles of the data.

Return type:

numpy.array

HARK.utilities.get_lorenz_shares(data, weights=None, percentiles=None, presorted=False)#

Calculates the Lorenz curve at the requested percentiles of (weighted) data. Median by default.

Parameters:

data (numpy.array) – A 1D array of float data.
weights (numpy.array) – A weighting vector for the data.
percentiles ([float]) – A list or numpy.array of percentiles to calculate for the data. Each element should be in (0,1).
presorted (boolean) – Indicator for whether data has already been sorted.

Returns:

lorenz_out – The requested Lorenz curve points of the data.

Return type:

numpy.array

HARK.utilities.calc_subpop_avg(data, reference, cutoffs, weights=None)#

Calculates the average of (weighted) data between cutoff percentiles of a reference variable.

Parameters:

data (numpy.array) – A 1D array of float data.
reference (numpy.array) – A 1D array of float data of the same length as data.
cutoffs ([(float,float)]) – A list of doubles with the lower and upper percentile bounds (should be in [0,1]).
weights (numpy.array) – A weighting vector for the data.

Returns:

The (weighted) average of data that falls within the cutoff percentiles of reference.

Return type:

slice_avg

HARK.utilities.epanechnikov_kernel(x, ref_x, h=1.0)#

The Epanechnikov kernel, which has been shown to be the most efficient kernel for non-parametric regression.

Parameters:

x (np.array) – Values at which to evaluate the kernel
x_ref (float) – The reference point
h (float) – Kernel bandwidth

Returns:

out – Kernel values at each value of x

Return type:

np.array

HARK.utilities.triangle_kernel(x, ref_x, h=1.0)#

The triangle or “hat” kernel.

Parameters:

x (np.array) – Values at which to evaluate the kernel
x_ref (float) – The reference point
h (float) – Kernel bandwidth

Returns:

out – Kernel values at each value of x

Return type:

np.array

HARK.utilities.kernel_regression(x, y, bot=None, top=None, N=500, h=None, kernel='epanechnikov')#

Performs a non-parametric Nadaraya-Watson 1D kernel regression on given data with optionally specified range, number of points, and kernel bandwidth.

Parameters:

x (np.array) – The independent variable in the kernel regression.
y (np.array) – The dependent variable in the kernel regression.
bot (float) – Minimum value of interest in the regression; defaults to min(x).
top (float) – Maximum value of interest in the regression; defaults to max(y).
N (int) – Number of points to compute.
h (float) – The bandwidth of the (Epanechnikov) kernel. To-do: GENERALIZE.

Returns:

regression – A piecewise locally linear kernel regression: y = f(x).

Return type:

LinearInterp

HARK.utilities.make_polynomial_params(coeffs, T, offset=0.0, step=1.0)#

Make a T-length array of parameters using polynomial coefficients.

Parameters:

coeffs ([float]) – Arbitrary length list of polynomial coefficients.
T (int) – Number of elements in the output.
offset (float, optional) – Value at which the X values should start. The default is 0.0.
step (float, optional) – Increment of the X values. The default is 1.0.

Returns:

param_vals – T-length array of parameter values calculated using the polynomial coefficients.

Return type:

np.array

HARK.utilities.jump_to_grid_1D(m_vals, probs, Dist_mGrid)#

Distributes values onto a predefined grid, maintaining the means.

Parameters:

m_vals (np.array) – Market resource values
probs (np.array) – Shock probabilities associated with combinations of m_vals. Can be thought of as the probability mass function of (m_vals).
dist_mGrid (np.array) – Grid over normalized market resources

Returns:

probGrid.flatten() – Probabilities of each gridpoint on the combined grid of market resources

Return type:

np.array

HARK.utilities.jump_to_grid_2D(m_vals, perm_vals, probs, dist_mGrid, dist_pGrid)#

Distributes values onto a predefined grid, maintaining the means. m_vals and perm_vals are realizations of market resources and permanent income while dist_mGrid and dist_pGrid are the predefined grids of market resources and permanent income, respectively. That is, m_vals and perm_vals do not necesarily lie on their respective grids. Returns probabilities of each gridpoint on the combined grid of market resources and permanent income.

Parameters:

m_vals (np.array) – Market resource values
perm_vals (np.array) – Permanent income values
probs (np.array) – Shock probabilities associated with combinations of m_vals and perm_vals. Can be thought of as the probability mass function of (m_vals, perm_vals).
dist_mGrid (np.array) – Grid over normalized market resources
dist_pGrid (np.array) – Grid over permanent income

Returns:

probGrid.flatten() – Probabilities of each gridpoint on the combined grid of market resources and permanent income

Return type:

np.array

HARK.utilities.gen_tran_matrix_1D(dist_mGrid, bNext, shk_prbs, perm_shks, tran_shks, LivPrb, NewBornDist)#

Computes Transition Matrix across normalized market resources. This function is built to non-stochastic simulate the IndShockConsumerType. This function is used exclusively when Harmenberg Neutral Measure is applied and/or if permanent income is not a state variable For more information, see https://econ-ark.org/materials/harmenberg-aggregation?launch

Parameters:

dist_mGrid (np.array) – Grid over normalized market resources
bNext (np.array) – Grid over bank balances
shk_prbs (np.array) – Array of shock probabilities over combinations of permanent and transitory shocks
perm_shks (np.array) – Array of shocks to permanent income. Shocks should follow Harmenberg neutral measure
tran_shks (np.array) – Array of shocks to transitory
LivPrb (float) – Probability of not dying
NewBornDist (np.array) – array representing distribution of newborns across grid of normalized market resources and grid of permanent income.

Returns:

TranMatrix – Transition Matrix over normalized market resources grid.

Return type:

np.array

HARK.utilities.gen_tran_matrix_2D(dist_mGrid, dist_pGrid, bNext, shk_prbs, perm_shks, tran_shks, LivPrb, NewBornDist)#

Computes Transition Matrix over normalized market resources and permanent income. This function is built to non-stochastic simulate the IndShockConsumerType.

Parameters:

dist_mGrid (np.array) – Grid over normalized market resources
dist_pGrid (np.array) – Grid over permanent income
bNext (np.array) – Grid over bank balances
shk_prbs (np.array) – Array of shock probabilities over combinations of perm and tran shocks
perm_shks (np.array) – Array of shocks to permanent income
tran_shks (np.array) – Array of shocks to transitory income
LivPrb (float) – Probability of not dying
NewBornDist (np.array) – array representing distribution of newborns across grid of normalized market resources and grid of permanent income.

Returns:

TranMatrix – Transition Matrix over normalized market resources grid and permanent income grid

Return type:

np.array

HARK.utilities.plot_funcs(functions, bottom, top, N=1000, legend_kwds=None)#

Plots 1D function(s) over a given range.

Parameters:

functions ([function] or function) – A single function, or a list of functions, to be plotted.
bottom (float) – The lower limit of the domain to be plotted.
top (float) – The upper limit of the domain to be plotted.
N (int) – Number of points in the domain to evaluate.
legend_kwds (None, or dictionary) – If not None, the keyword dictionary to pass to plt.legend

Return type:

none

HARK.utilities.plot_funcs_der(functions, bottom, top, N=1000, legend_kwds=None)#

Plots the first derivative of 1D function(s) over a given range.

Parameters:

function (function) – A function or list of functions, the derivatives of which are to be plotted.
bottom (float) – The lower limit of the domain to be plotted.
top (float) – The upper limit of the domain to be plotted.
N (int) – Number of points in the domain to evaluate.
legend_kwds (None, or dictionary) – If not None, the keyword dictionary to pass to plt.legend

Return type:

none

HARK.utilities.determine_platform()#

Utility function to return the platform currenlty in use.

Returns:: pf – ‘darwin’ (MacOS), ‘debian’(debian Linux) or ‘win’ (windows)
Return type:: str

HARK.utilities.test_latex_installation(pf)#

Test to check if latex is installed on the machine.

Parameters:: pf (str (platform)) – output of determine_platform()
Returns:: bool – True if latex found, else installed in the case of debian otherwise ImportError raised to direct user to install latex manually
Return type:: Boolean

HARK.utilities.in_ipynb()#

If the ipython process contains ‘terminal’ assume not in a notebook.

Returns:: bool – True if called from a jupyter notebook, else False
Return type:: Boolean

HARK.utilities.setup_latex_env_notebook(pf, latexExists)#

This is needed for use of the latex_envs notebook extension which allows the use of environments in Markdown.

Parameters:: pf (str (platform)) – output of determine_platform()

HARK.utilities.make_figs(figure_name, saveFigs, drawFigs, target_dir='Figures')#

Utility function to save figure in multiple formats and display the image.

Parameters:

figure_name (str) – name of the figure
saveFigs (bool) – True if the figure needs to be written to disk else False
drawFigs (bool) – True if the figure should be displayed using plt.draw()
target_dir (str, default = 'Figures/') – Name of folder to save figures to in the current directory

HARK.utilities.find_gui()#

Quick fix to check if matplotlib is running in a GUI environment.

Returns:: bool – True if it’s a GUI environment, False if not.
Return type:: Boolean

HARK.utilities.benchmark(agent, sort_by='tottime', max_print=10, filename='restats', return_output=False)#

Profiling tool for HARK models. Calling benchmark on agents calls the solver for the agents and provides time to solve as well as the top max_print function calls in terms of sort_by. Optionally allows for saving a text copy of the profile as well as returning the Stats object for further inspection.

For more details on the python profilers, see https://docs.python.org/3/library/profile.html#the-stats-class

Parameters:

agent (AgentType) – A HARK AgentType with a solve() method.
sort_by (string) – A string to sort the stats by.
max_print (int) – Number of lines to print
filename (string) – Optional filename to save output.
return_output (bool) – Boolean to determine whether Stats object should be returned.

Returns:

stats – Profiling object with call statistics.

Return type:

Stats (optional)

HARK.utilities.mround(match)#

HARK.utilities.round_in_file(filename)#

HARK.utilities.files_in_dir(mypath)#