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.

HARK.utilities.memoize(obj)#

A decorator to (potentially) make functions more efficient.

With this decorator, functions will “remember” if they have been evaluated with given inputs before. If they have, they will “remember” the outputs that have already been calculated for those inputs, rather than calculating them again.

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.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.

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.calc_weighted_avg(data, weights)#

Generates a weighted average of simulated data. The Nth row of data is averaged and then weighted by the Nth element of weights in an aggregate average.

Parameters:

data (numpy.array) – An array of data with N rows of J floats
weights (numpy.array) – A length N array of weights for the N rows of data.

Returns:

weighted_sum – The weighted sum of the data.

Return type:

float

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.kernel_regression(x, y, bot=None, top=None, N=500, h=None)#

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.epanechnikov_kernel(x, ref_x, h=1.0)#

The Epanechnikov 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.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_type, 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_type (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)#