respy

This is the entry-point to the respy package.

Include only imports which should be available using

import respy as rp

rp.<func>

Subpackages

• respy.pre_processing
  • respy.pre_processing.data_checking
  • respy.pre_processing.model_checking
  • respy.pre_processing.model_processing
  • respy.pre_processing.process_covariates
  • respy.pre_processing.specification_helpers

Submodules

• respy._numba
• respy.conditional_draws
• respy.config
• respy.conftest
• respy.data
• respy.exogenous_processes
• respy.interface
• respy.interpolate
• respy.likelihood
• respy.method_of_simulated_moments
• respy.parallelization
• respy.shared
• respy.simulate
• respy.solve
• respy.state_space

Package Contents

Functions

get_example_model(model[, with_data])	Return parameters, options and data (optional) of an example model.
get_parameter_constraints(model)	Get parameter constraints for the estimation compatible with estimagic.
get_log_like_func(params, options, df[, return_scalar])	Get the criterion function for maximum likelihood estimation.
get_diag_weighting_matrix(empirical_moments[, weights])	Create a diagonal weighting matrix from weights.
get_flat_moments(empirical_moments)	Compute the empirical moments flat indexes.
get_moment_errors_func(params, options, calc_moments, ...)	Get the moment errors function for MSM estimation.
get_simulate_func(params, options[, method, df, ...])	Get the simulation function.
get_solve_func(params, options)	Get the solve function.

respy.get_example_model(model, with_data=True)

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)

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_log_like_func(params, options, df, return_scalar=True)

Get the criterion function for maximum likelihood estimation.

Return a version of the likelihood functions in respy where all arguments except the parameter vector are fixed with functools.partial(). Thus the function can be directly passed into an optimizer or a function for taking numerical derivatives.

Parameters:

paramspandas.DataFrame

DataFrame containing model parameters.

optionsdict

Dictionary containing model options.

dfpandas.DataFrame

The model is fit to this dataset.

return_scalarbool, default False

Indicator for whether the mean log likelihood should be returned. If False will return a dictionary with the following key and value pairs: - “value”: mean log likelihood (float) - “contributions”: log likelihood contributions (numpy.array) - “comparison_plot_data” : DataFrame with various contributions for the visualization with estimagic. Data contains the following columns:

• identifier : Individual identifiers derived from input df.

• period : Periods derived from input df.

• choice : Choice that value is connected to.

• value : Value of log likelihood contribution.

• kind : Kind of contribution (e.g choice or wage).

• type and log_type_probability`: Will be included in models with

types.

Returns:

criterion_functionlog_like()

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

Raises:

AssertionError

If data has not the expected format.

Examples

>>> import respy as rp
>>> params, options, data = rp.get_example_model("robinson_crusoe_basic")

At default the function returns the log likelihood as a scalar value.

>>> log_like = rp.get_log_like_func(params=params, options=options, df=data)
>>> scalar = log_like(params)

Alternatively, a dictionary containing the log likelihood, as well as log likelihood contributions and a pandas.DataFrame can be returned.

>>> log_like = rp.get_log_like_func(params=params, options=options, df=data,
...     return_scalar=False
... )
>>> outputs = log_like(params)
>>> outputs.keys()
dict_keys(['value', 'contributions', 'comparison_plot_data'])

respy.get_diag_weighting_matrix(empirical_moments, weights=None)

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 must 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)

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_moment_errors_func(params, options, calc_moments, replace_nans, empirical_moments, weighting_matrix=None, n_simulation_periods=None, return_scalar=True)

Get the moment errors function for MSM estimation.

Parameters:

paramspandas.DataFrame or pandas.Series

Contains parameters.

optionsdict

Dictionary containing model options.

calc_momentscallable() or list or dict

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 or dict or None

Functions(s) specifying how to handle missings in simulated_moments. Must match structure of empirical_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, default None

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

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 the scalar value of weighted square product of moment error vector or dictionary that additionally contains vector of (weighted) moment errors, simulated moments that follow the structure of empirical moments, and simulated as well as empirical moments in a pandas.DataFrame that adheres to a tidy data format. The dictionary will contain the following key and value pairs:

• “value”: Scalar vale of weighted moment errors (float)

• “root_contributions”: Moment error vectors multiplied with root of weighting matrix (numpy.ndarray)

• “simulated_moments”: Simulated moments for given parametrization. Will be in

the same data format as empirical_moments (pandas.Series or pandas.DataFrame or list or dict) - “comparison_plot_data”: A pandas.DataFrame that contains both empirical and simulated moments in a tidy data format (pandas.DataFrame). 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:

moment_errors_funccallable()

Function where all arguments except the parameter vector are set.

Raises:

ValueError

If replacement function cannot be broadcast (1:1 or 1:N) to simulated moments.

ValueError

If the number of functions to compute the simulated moments does not match the number of empirical moments.

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

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.

Examples

>>> import respy as rp
>>> params, options = rp.get_example_model("robinson_crusoe_basic", with_data=False)
>>> simulate = rp.get_simulate_func(params, options)
>>> data = simulate(params)

respy.get_solve_func(params, options)

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.

Examples

>>> import respy as rp
>>> params, options = rp.get_example_model("robinson_crusoe_basic", with_data=False)
>>> solve = rp.get_solve_func(params, options)
>>> state_space = solve(params)