Utilites¶

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.CARAutility(c, alpha)¶

Evaluates constant absolute risk aversion (CARA) utility of consumption c given risk aversion parameter alpha.

Parameters:	c (float) – Consumption value alpha (float) – Risk aversion
Returns:	(unnamed) – Utility
Return type:	float

HARK.utilities.CARAutilityP(c, alpha)¶

Evaluates constant absolute risk aversion (CARA) marginal utility of consumption c given risk aversion parameter alpha.

Parameters:	c (float) – Consumption value alpha (float) – Risk aversion
Returns:	(unnamed) – Marginal utility
Return type:	float

HARK.utilities.CARAutilityPP(c, alpha)¶

Evaluates constant absolute risk aversion (CARA) marginal marginal utility of consumption c given risk aversion parameter alpha.

Parameters:	c (float) – Consumption value alpha (float) – Risk aversion
Returns:	(unnamed) – Marginal marginal utility
Return type:	float

HARK.utilities.CARAutilityPPP(c, alpha)¶

Evaluates constant absolute risk aversion (CARA) marginal marginal marginal utility of consumption c given risk aversion parameter alpha.

Parameters:	c (float) – Consumption value alpha (float) – Risk aversion
Returns:	(unnamed) – Marginal marginal marginal utility
Return type:	float

HARK.utilities.CARAutilityP_inv(u, alpha)¶

Evaluates the inverse of constant absolute risk aversion (CARA) marginal utility function at marginal utility uP given risk aversion parameter alpha.

Parameters:	u (float) – Utility value alpha (float) – Risk aversion
Returns:	(unnamed) – Consumption value corresponding to uP
Return type:	float

HARK.utilities.CARAutility_inv(u, alpha)¶

Evaluates inverse of constant absolute risk aversion (CARA) utility function at utility level u given risk aversion parameter alpha.

Parameters:	u (float) – Utility value alpha (float) – Risk aversion
Returns:	(unnamed) – Consumption value corresponding to u
Return type:	float

HARK.utilities.CARAutility_invP(u, alpha)¶

Evaluates the derivative of inverse of constant absolute risk aversion (CARA) utility function at utility level u given risk aversion parameter alpha.

Parameters:	u (float) – Utility value alpha (float) – Risk aversion
Returns:	(unnamed) – Marginal onsumption value corresponding to u
Return type:	float

HARK.utilities.CRRAutility(c, gam)¶

Evaluates constant relative risk aversion (CRRA) utility of consumption c given risk aversion parameter gam.

Parameters:

c (float) – Consumption value
gam (float) – Risk aversion

Returns:

(unnamed) (float) – Utility
Tests
—–
Test a value which should pass
>>> c, gamma = 1.0, 2.0 # Set two values at once with Python syntax
>>> utility(c=c, gam=gamma)
-1.0

HARK.utilities.CRRAutilityP(c, gam)¶

Evaluates constant relative risk aversion (CRRA) marginal utility of consumption c given risk aversion parameter gam.

Parameters:	c (float) – Consumption value gam (float) – Risk aversion
Returns:	(unnamed) – Marginal utility
Return type:	float

HARK.utilities.CRRAutilityPP(c, gam)¶

Evaluates constant relative risk aversion (CRRA) marginal marginal utility of consumption c given risk aversion parameter gam.

Parameters:	c (float) – Consumption value gam (float) – Risk aversion
Returns:	(unnamed) – Marginal marginal utility
Return type:	float

HARK.utilities.CRRAutilityPPP(c, gam)¶

Evaluates constant relative risk aversion (CRRA) marginal marginal marginal utility of consumption c given risk aversion parameter gam.

Parameters:	c (float) – Consumption value gam (float) – Risk aversion
Returns:	(unnamed) – Marginal marginal marginal utility
Return type:	float

HARK.utilities.CRRAutilityPPPP(c, gam)¶

Evaluates constant relative risk aversion (CRRA) marginal marginal marginal marginal utility of consumption c given risk aversion parameter gam.

Parameters:	c (float) – Consumption value gam (float) – Risk aversion
Returns:	(unnamed) – Marginal marginal marginal marginal utility
Return type:	float

HARK.utilities.CRRAutilityP_inv(uP, gam)¶

Evaluates the inverse of the CRRA marginal utility function (with risk aversion parameter gam) at a given marginal utility level uP.

Parameters:	uP (float) – Marginal utility value gam (float) – Risk aversion
Returns:	(unnamed) – Consumption corresponding to given marginal utility value.
Return type:	float

HARK.utilities.CRRAutilityP_invP(uP, gam)¶

Evaluates the derivative of the inverse of the CRRA marginal utility function (with risk aversion parameter gam) at a given marginal utility level uP.

Parameters:	uP (float) – Marginal utility value gam (float) – Risk aversion
Returns:	(unnamed) – Consumption corresponding to given marginal utility value
Return type:	float

HARK.utilities.CRRAutility_inv(u, gam)¶

Evaluates the inverse of the CRRA utility function (with risk aversion para- meter gam) at a given utility level u.

Parameters:	u (float) – Utility value gam (float) – Risk aversion
Returns:	(unnamed) – Consumption corresponding to given utility value
Return type:	float

HARK.utilities.CRRAutility_invP(u, gam)¶

Evaluates the derivative of the inverse of the CRRA utility function (with risk aversion parameter gam) at a given utility level u.

Parameters:	u (float) – Utility value gam (float) – Risk aversion
Returns:	(unnamed) – Marginal consumption corresponding to given utility value
Return type:	float

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.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.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.determine_platform()¶

Untility function to return the platform currenlty in use.

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

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

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.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.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.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.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.make_grid_exp_mult(ming, maxg, ng, timestonest=20)¶

Make a multi-exponentially spaced grid.

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 (np.array) – A multi-exponentially spaced grid
Original Matab code can be found in Chris Carroll’s
[Solution Methods for Microeconomic Dynamic Optimization Problems]
(http (//www.econ2.jhu.edu/people/ccarroll/solvingmicrodsops/) toolkit.)
Latest update (01 May 2015)

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

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.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.uFunc_CRRA_stone_geary(c, CRRA, stone_geary)¶

Evaluates Stone-Geary version of a constant relative risk aversion (CRRA) utility of consumption c wiht given risk aversion parameter CRRA and Stone-Geary intercept parameter stone_geary

Parameters:

c (float) – Consumption value
CRRA (float) – Relative risk aversion
stone_geary (float) – Intercept in Stone-Geary utility

Returns:

(unnamed) (float) – Utility
Tests
—–
Test a value which should pass
>>> c, CRRA, stone_geary = 1.0, 2.0, 0.0
>>> utility(c=c, CRRA=CRRA, stone_geary=stone_geary )
-1.0

HARK.utilities.uPFunc_CRRA_stone_geary(c, CRRA, stone_geary)¶

Marginal utility of Stone-Geary version of a constant relative risk aversion (CRRA) utility of consumption c wiht given risk aversion parameter CRRA and Stone-Geary intercept parameter stone_geary

Parameters:	c (float) – Consumption value CRRA (float) – Relative risk aversion stone_geary (float) – Intercept in Stone-Geary utility
Returns:	(unnamed) – marginal utility
Return type:	float

HARK.utilities.uPPFunc_CRRA_stone_geary(c, CRRA, stone_geary)¶

Marginal marginal utility of Stone-Geary version of a CRRA utilty function with risk aversion parameter CRRA and Stone-Geary intercept parameter stone_geary

Parameters:	c (float) – Consumption value CRRA (float) – Relative risk aversion stone_geary (float) – Intercept in Stone-Geary utility
Returns:	(unnamed) – marginal utility
Return type:	float