:py:mod:`respy` =============== .. py:module:: respy .. autoapi-nested-parse:: This is the entry-point to the respy package. Include only imports which should be available using .. code-block:: import respy as rp rp. .. !! processed by numpydoc !! Subpackages ----------- .. toctree:: :titlesonly: :maxdepth: 3 pre_processing/index.rst Submodules ---------- .. toctree:: :titlesonly: :maxdepth: 1 _numba/index.rst conditional_draws/index.rst config/index.rst conftest/index.rst data/index.rst exogenous_processes/index.rst interface/index.rst interpolate/index.rst likelihood/index.rst method_of_simulated_moments/index.rst parallelization/index.rst shared/index.rst simulate/index.rst solve/index.rst state_space/index.rst Package Contents ---------------- Functions ~~~~~~~~~ .. autoapisummary:: respy.get_example_model respy.get_parameter_constraints respy.get_log_like_func respy.get_diag_weighting_matrix respy.get_flat_moments respy.get_moment_errors_func respy.get_simulate_func respy.get_solve_func .. py:function:: get_example_model(model, with_data=True) Return parameters, options and data (optional) of an example model. :Parameters: **model** : :class:`python:str` 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_data** : :ref:`bool ` 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. .. !! processed by numpydoc !! .. py:function:: get_parameter_constraints(model) Get parameter constraints for the estimation compatible with estimagic. For more information, see the `documentation of estimagic `_. :Parameters: **model** : :class:`python:str` 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: **constraints** : :class:`python:list`\[:class:`python:dict`\[:class:`python:str`, :class:`python:str`]] A list of dictionaries specifying constraints. .. rubric:: Examples >>> constr = rp.get_parameter_constraints("robinson_crusoe_basic") >>> constr [{'loc': 'shocks_sdcorr', 'type': 'sdcorr'}] .. !! processed by numpydoc !! .. py:function:: 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 :func:`functools.partial`. Thus the function can be directly passed into an optimizer or a function for taking numerical derivatives. :Parameters: **params** : :obj:`pandas.DataFrame` DataFrame containing model parameters. **options** : :class:`python:dict` Dictionary containing model options. **df** : :obj:`pandas.DataFrame` The model is fit to this dataset. **return_scalar** : :ref:`bool `, default :data:`python: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_function** : :func:`log_like` Criterion function where all arguments except the parameter vector are set. :Raises: :obj:`AssertionError` If data has not the expected format. .. rubric:: 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 :class:`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']) .. !! processed by numpydoc !! .. py:function:: get_diag_weighting_matrix(empirical_moments, weights=None) Create a diagonal weighting matrix from weights. :Parameters: **empirical_moments** : :obj:`pandas.DataFrame` or :obj:`pandas.Series` or :class:`python:dict` or :class:`python: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. **weights** : :obj:`pandas.DataFrame` or :obj:`pandas.Series` or :class:`python:dict` or :class:`python: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: :obj:`numpy.ndarray` Array contains a diagonal weighting matrix. .. !! processed by numpydoc !! .. py:function:: get_flat_moments(empirical_moments) Compute the empirical moments flat indexes. :Parameters: **empirical_moments** : :obj:`pandas.DataFrame` or :obj:`pandas.Series` or :class:`python:dict` or :class:`python: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_moments** : :obj:`pandas.DataFrame` Vector of empirical_moments with flat index. .. !! processed by numpydoc !! .. py:function:: 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: **params** : :obj:`pandas.DataFrame` or :obj:`pandas.Series` Contains parameters. **options** : :class:`python:dict` Dictionary containing model options. **calc_moments** : :func:`python:callable` or :class:`python:list` or :class:`python: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_nans** : :func:`python:callable` or :class:`python:list` or :class:`python:dict` or :data:`python:None` Functions(s) specifying how to handle missings in simulated_moments. Must match structure of empirical_moments. **empirical_moments** : :obj:`pandas.DataFrame` or :obj:`pandas.Series` or :class:`python:dict` or :class:`python: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_matrix** : :obj:`numpy.ndarray`, default :data:`python: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_periods** : :class:`python:int`, default :data:`python: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_scalar** : :ref:`bool `, default :data:`python: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 :class:`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_func** : :func:`python:callable` Function where all arguments except the parameter vector are set. :Raises: :obj:`ValueError` If replacement function cannot be broadcast (1:1 or 1:N) to simulated moments. :obj:`ValueError` If the number of functions to compute the simulated moments does not match the number of empirical moments. .. !! processed by numpydoc !! .. py:function:: get_simulate_func(params, options, method='n_step_ahead_with_sampling', df=None, n_simulation_periods=None) Get the simulation function. Return :func:`simulate` where all arguments except the parameter vector are fixed with :func:`functools.partial`. Thus, the function can be directly passed into an optimizer for estimation with simulated method of moments or other techniques. :Parameters: **params** : :obj:`pandas.DataFrame` DataFrame containing model parameters. **options** : :class:`python:dict` 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 :func:`simulate`. **df** : :obj:`pandas.DataFrame` or :data:`python:None`, default :data:`python:None` DataFrame containing one or multiple observations per individual. **n_simulation_periods** : :class:`python:int` or :data:`python:None`, default :data:`python: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_function** : :func:`simulate` Simulation function where all arguments except the parameter vector are set. .. rubric:: 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) .. !! processed by numpydoc !! .. py:function:: 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: **params** : :obj:`pandas.DataFrame` DataFrame containing parameter series. **options** : :class:`python:dict` Dictionary containing model attributes which are not optimized. :Returns: **solve** : :func:`~respy.solve.solve` Function with partialed arguments. .. rubric:: 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) .. !! processed by numpydoc !!