:py:mod:`respy.method_of_simulated_moments` =========================================== .. py:module:: respy.method_of_simulated_moments .. autoapi-nested-parse:: Estimate models with the method of simulated moments (MSM). The method of simulated moments is developed by [Rce4bf42141d8-1]_, [Rce4bf42141d8-2]_, and [Rce4bf42141d8-3]_ and an estimation technique where the distance between the moments of the actual data and the moments implied by the model parameters is minimized. References ---------- .. [Rce4bf42141d8-1] McFadden, D. (1989). A method of simulated moments for estimation of discrete response models without numerical integration. Econometrica: Journal of the Econometric Society, 995-1026. .. [Rce4bf42141d8-2] Lee, B. S., & Ingram, B. F. (1991). Simulation estimation of time-series models. Journal of Econometrics, 47(2-3), 197-205. .. [Rce4bf42141d8-3] Duffie, D., & Singleton, K. (1993). Simulated Moments Estimation of Markov Models of Asset Prices. Econometrica, 61(4), 929-952. .. !! processed by numpydoc !! Module Contents --------------- Functions ~~~~~~~~~ .. autoapisummary:: respy.method_of_simulated_moments.get_moment_errors_func respy.method_of_simulated_moments.moment_errors respy.method_of_simulated_moments.get_diag_weighting_matrix respy.method_of_simulated_moments.get_flat_moments respy.method_of_simulated_moments._harmonize_input respy.method_of_simulated_moments._flatten_index respy.method_of_simulated_moments._create_comparison_plot_data_msm respy.method_of_simulated_moments._create_tidy_data respy.method_of_simulated_moments._reconstruct_input_from_dict respy.method_of_simulated_moments._return_input .. 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:: moment_errors(params, simulate, calc_moments, replace_nans, empirical_moments, weighting_matrix, return_scalar, are_empirical_moments_dict) Loss function for MSM estimation. :Parameters: **params** : :obj:`pandas.DataFrame` or :obj:`pandas.Series` Contains model parameters. **simulate** : :func:`python:callable` Function used to simulate data for MSM estimation. **calc_moments** : :class:`python:dict` Dictionary of function(s) used to calculate simulated moments. Must match length of empirical_moments i.e. calc_moments contains a moments function for each item in empirical_moments. **replace_nans** : :class:`python:dict` Dictionary of functions(s) specifying how to handle missings in simulated_moments. Must match length of empirical_moments. **empirical_moments** : :class:`python:dict` Contains the empirical moments calculated for the observed data. Each item in the dict constitutes a set of moments saved to a pandas.DataFrame or pandas.Series. Index of pandas.DataFrames can be of type MultiIndex, but columns cannot. **weighting_matrix** : :obj:`numpy.ndarray` Square matrix of dimension (NxN) with N denoting the number of empirical_moments. Used to weight squared moment errors. **return_scalar** : :ref:`bool ` Indicates whether to return the scalar value of weighted square product of moment error vector or dictionary that additionally contains vector of (root 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. **are_empirical_moments_dict** : :ref:`bool ` Indicates whether empirical_moments are originally saved to a dict. Used for return of simulated moments in the same form when return_scalar is False. :Returns: **out** : :class:`python:float` or :class:`python:dict` .. .. !! 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:: _harmonize_input(x) Harmonize different types of inputs by turning all inputs into dicts. - pandas.DataFrames/Series and callable functions will turn into a dict containing a single item (i.e. the input). - Dictionaries will be left as is. :Parameters: **x** : :obj:`pandas.DataFrame` or :obj:`pandas.Series` or :func:`python:callable` or :class:`python:list` or :class:`python:dict` .. :Returns: **x** : :class:`python:dict` .. .. !! processed by numpydoc !! .. py:function:: _flatten_index(moments) Flatten the index as a combination of the former index and the columns. :Parameters: **moments** : :class:`python:dict` .. :Returns: :obj:`pandas.DataFrame` .. .. !! processed by numpydoc !! .. py:function:: _create_comparison_plot_data_msm(empirical_moments, simulated_moments) Create pandas.DataFrame for estimagic comparison plots. Returned object contains empirical and simulated moments. :Parameters: **empirical_moments** : :class:`python:dict` .. **simulated_moments** : :class:`python:dict` .. :Returns: :obj:`pandas.DataFrame` .. .. !! processed by numpydoc !! .. py:function:: _create_tidy_data(moments) Create tidy data from dict containing pandas.DataFrames and/or pandas.Series. :Parameters: **moments** : :class:`python:dict` .. :Returns: :obj:`pandas.DataFrame` .. .. !! processed by numpydoc !! .. py:function:: _reconstruct_input_from_dict(x) Reconstruct input from dict back to a list or single object. :Parameters: **x** : :class:`python:dict` .. :Returns: **out** : :obj:`pandas.DataFrame` or :obj:`pandas.Series` or :func:`python:callable` or :class:`python:list` .. .. !! processed by numpydoc !! .. py:function:: _return_input(x)