respy

This is the entry-point to the respy package.

Include only imports which should be available using

import respy as rp

rp.<func>

Package Contents

Functions

get_example_model(model, with_data=True)

Return parameters, options and data (optional) of an example model.

get_parameter_constraints(model)

Get parameter constraints for the estimation compatible with estimagic.

get_diag_weighting_matrix(empirical_moments, weights=None)

Create a diagonal weighting matrix from weights.

get_flat_moments(empirical_moments)

Compute the empirical moments flat indexes.

get_msm_func(params, options, calc_moments, replace_nans, empirical_moments, weighting_matrix, n_simulation_periods=None, return_scalar=True, return_simulated_moments=False, return_comparison_plot_data=False)

Get the MSM function.

get_simulate_func(params, options, method='n_step_ahead_with_sampling', df=None, n_simulation_periods=None)

Get the simulation function.

get_solve_func(params, options)

Get the solve function.

add_noise_to_params(params, options, delta_low_high=(-0.2, 0.2), wages_percent_absolute=(0, 0.2), wages_low_high=None, wages_null_low_high=(-0.2, 0.2), nonpecs_percent_absolute=(0, 0.2), nonpecs_low_high=None, nonpecs_null_low_high=(-5000, 5000), cholesky_low_high=(-0.5, 0.5), meas_sd_low_high=(1e-06, 0.5), ic_probabilities_low_high=False, ic_logit_low_high=False, seed=None)

Add noise to parameters.

respy.get_example_model(model, with_data=True)[source]

Return parameters, options and data (optional) of an example model.

Parameters
modelstr

Choose one model name in {"robinson_crusoe_basic", "robinson_crusoe_extended", kw_94_one", "kw_94_two", "kw_94_three", "kw_97_basic", "kw_97_extended" "kw_2000"}.

with_databool

Whether the accompanying data set should be returned. For some data sets, real data can be provided, for others, a simulated data set will be produced.

respy.get_parameter_constraints(model)[source]

Get parameter constraints for the estimation compatible with estimagic.

For more information, see the documentation of estimagic.

Parameters
modelstr

Choose one model name in {"robinson_crusoe_basic", "robinson_crusoe_extended", kw_94_one", "kw_94_two", "kw_94_three", "kw_97_basic", "kw_97_extended" "kw_2000"}.

Returns
constraintslist[dict[str, str]]

A list of dictionaries specifying constraints.

Examples

>>> constr = rp.get_parameter_constraints("robinson_crusoe_basic")
>>> constr
[{'loc': 'shocks_sdcorr', 'type': 'sdcorr'}]
respy.get_diag_weighting_matrix(empirical_moments, weights=None)[source]

Create a diagonal weighting matrix from weights.

Parameters
empirical_momentspandas.DataFrame or pandas.Series or dict or list

Contains the empirical moments calculated for the observed data. Moments should be saved to pandas.DataFrame or pandas.Series that can either be passed to the function directly or as items of a list or dictionary.

weightspandas.DataFrame or pandas.Series or dict or list

Contains weights (usually variances) of empirical moments. Must match structure of empirical_moments i.e. if empirical_moments is a list of pandas.DataFrames, weights be list of pandas.DataFrames as well where each DataFrame entry contains the weight for the corresponding moment in empirical_moments.

Returns
numpy.ndarray

Array contains a diagonal weighting matrix.

respy.get_flat_moments(empirical_moments)[source]

Compute the empirical moments flat indexes.

Parameters
empirical_momentspandas.DataFrame or pandas.Series or dict or list

containing pandas.DataFrame or pandas.Series. Contains the empirical moments calculated for the observed data. Moments should be saved to pandas.DataFrame or pandas.Series that can either be passed to the function directly or as items of a list or dictionary.

Returns
flat_empirical_momentspandas.DataFrame

Vector of empirical_moments with flat index.

respy.get_msm_func(params, options, calc_moments, replace_nans, empirical_moments, weighting_matrix, n_simulation_periods=None, return_scalar=True, return_simulated_moments=False, return_comparison_plot_data=False)[source]

Get the MSM function.

Parameters
paramspandas.DataFrame or pandas.Series

Contains parameters.

optionsdict

Dictionary containing model options.

calc_momentscallable() or list

Function(s) used to calculate simulated moments. Must match structure of empirical moments i.e. if empirical_moments is a list of pandas.DataFrames, calc_moments must be a list of the same length containing functions that correspond to the moments in empirical_moments.

replace_nanscallable() or list

Functions(s) specifying how to handle missings in simulated_moments. Must match structure of empirical_moments. Exception: If only one replacement function is specified, it will be used on all sets of simulated moments.

empirical_momentspandas.DataFrame or pandas.Series or dict or list

Contains the empirical moments calculated for the observed data. Moments should be saved to pandas.DataFrame or pandas.Series that can either be passed to the function directly or as items of a list or dictionary. Index of pandas.DataFrames can be of type MultiIndex, but columns cannot.

weighting_matrixnumpy.ndarray

Square matrix of dimension (NxN) with N denoting the number of empirical_moments. Used to weight squared moment errors.

n_simulation_periodsint, default None

Dictates the number of periods in the simulated dataset. This option does not affect options["n_periods"] which controls the number of periods for which decision rules are computed.

return_scalarbool, default True

Indicates whether to return moment error vector (False) or weighted square product of moment error vectors (True).

return_simulated_moments: bool, default False

Indicates whether simulated moments should be returned with other output. If True will return simulated moments of the same type as empirical_moments.

return_comparison_plot_data: bool, default False

Indicator for whether a pandas.DataFrame with empirical and simulated moments for the visualization with estimagic should be returned. Data contains the following columns: - moment_column: Contains the column names of the moment DataFrames/Series names. - moment_index: Contains the index of the moment DataFrames/Series. MultiIndex indices will be joined to one string. - value: Contains moment values. - moment_set: Indicator for each set of moments, will use keys if empirical_moments are specified in a dict. Moments input as lists will be numbered according to position. - kind: Indicates whether moments are empirical or simulated.

Returns
——-
msm_func: callable

MSM function where all arguments except the parameter vector are set.

respy.get_simulate_func(params, options, method='n_step_ahead_with_sampling', df=None, n_simulation_periods=None)[source]

Get the simulation function.

Return simulate() where all arguments except the parameter vector are fixed with functools.partial(). Thus, the function can be directly passed into an optimizer for estimation with simulated method of moments or other techniques.

Parameters
paramspandas.DataFrame

DataFrame containing model parameters.

optionsdict

Dictionary containing model options.

method{“n_step_ahead_with_sampling”, “n_step_ahead_with_data”, “one_step_ahead”}

The simulation method which can be one of three and is explained in more detail in simulate().

dfpandas.DataFrame or None, default None

DataFrame containing one or multiple observations per individual.

n_simulation_periodsint or None, default None

Simulate data for a number of periods. This options does not affect options["n_periods"] which controls the number of periods for which decision rules are computed.

Returns
simulate_functionsimulate()

Simulation function where all arguments except the parameter vector are set.

respy.get_solve_func(params, options)[source]

Get the solve function.

This function takes a model specification and returns the state space of the model along with components of the solution such as covariates, non-pecuniary rewards, wages, continuation values and expected value functions as attributes of the class.

Parameters
paramspandas.DataFrame

DataFrame containing parameter series.

optionsdict

Dictionary containing model attributes which are not optimized.

Returns
solvesolve()

Function with partialed arguments.

respy.add_noise_to_params(params, options, delta_low_high=- 0.2, 0.2, wages_percent_absolute=0, 0.2, wages_low_high=None, wages_null_low_high=- 0.2, 0.2, nonpecs_percent_absolute=0, 0.2, nonpecs_low_high=None, nonpecs_null_low_high=- 5000, 5000, cholesky_low_high=- 0.5, 0.5, meas_sd_low_high=1e-06, 0.5, ic_probabilities_low_high=False, ic_logit_low_high=False, seed=None)[source]

Add noise to parameters.

The function allows to vary the noise based on the absolute value for non-zero parameters or to simply add noise in forms of bounded random variables.

The function ensures that special parameters are valid:

  • Probabilities are between 0 and 1.

  • Correlations are between -1 and 1.

  • Diagonal elements of the Cholesky factor have 1e-6 as the lower bound.

  • The standard deviations of the measurement error have 1e-6 as the lower bound.

Parameters
paramspandas.DataFrame

The parameters in a DataFrame.

optionsdict

The options of the model.

delta_low_hightuple[float]

Lower and upper bound to shock to discount factor.

wages_percent_absolutefloat or tuple[float]

The deviation in percentages of the absolute value of a non-zero parameter is either a constant percentage for all parameters or a random percentage between upper and lower bounds.

wages_low_hightuple[float]

The deviation for a non-zero parameter value is between an lower and upper bound.

wages_null_low_hightuple[float]

The deviation for a parameter with value zero is between the lower and upper bound.

nonpecs_percent_absolutefloat or tuple[float]

The deviation in percentages of the absolute value of a non-zero parameter is either a constant percentage for all parameters or a random percentage between upper and lower bounds.

nonpecs_low_hightuple[float]

The deviation for a non-zero parameter value is between an lower and upper bound.

nonpecs_null_low_hightuple[float]

The deviation for a parameter with value zero is between the lower and upper bound.

cholesky_low_hightuple[float]

Lower and upper bound for a shock applied to the Cholesky factor of the shock matrix. To ensure proper scaling, the shock is multiplied with the square root of the product of diagonal elements for this entry. The shock for the diagonal elements is between zero and the upper bound and the resulting diagonal element in the Cholesky factor has 1e-6 as the lower bound.

meas_sd_low_hightuple[float]

Lower and upper bound for shock to measurement error standard deviations.

ic_probabilities_low_hightuple[float]

Lower and upper bound for shocks to the probabilities in the initial conditions.

ic_logit_low_hightuple[float]

Lower and upper bound for shocks to the logit coefficients in the initial conditions.

seedint or None

Seed to replicate the perturbation.

Returns
paramspandas.DataFrame

The new parameters.