:py:mod:`respy.state_space` =========================== .. py:module:: respy.state_space .. autoapi-nested-parse:: Everything related to the state space of a structural model. .. !! processed by numpydoc !! Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: respy.state_space.StateSpace Functions ~~~~~~~~~ .. autoapisummary:: respy.state_space.create_state_space_class respy.state_space._create_core_state_space respy.state_space._create_core_from_choice_experiences respy.state_space._create_core_state_space_per_period respy.state_space._add_lagged_choice_to_core_state_space respy.state_space._filter_core_state_space respy.state_space._add_initial_experiences_to_core_state_space respy.state_space._create_dense_state_space_grid respy.state_space._create_dense_state_space_covariates respy.state_space.create_is_inadmissible respy.state_space._create_indexer respy.state_space._create_core_period_choice respy.state_space._create_dense_period_choice respy.state_space._get_continuation_values respy.state_space._collect_child_indices .. py:function:: create_state_space_class(optim_paras, options) Create the state space of the model. .. !! processed by numpydoc !! .. py:class:: StateSpace(core, indexer, dense, dense_period_cores, core_key_to_complex, core_key_to_core_indices, optim_paras, options) The state space of a structural model. :Attributes: **core** : :class:`python:dict` of :obj:`pandas.DataFrame` The core state space is a :class:`pandas.DataFrame` that contains all states of core dimensions. A core dimension is a dimension whose value is uniquely determined by past choices and time. Core dimensions include choices, experiences, lagged choices and periods. **dense_key_to_core_indices** : :obj:`Dict`\[:class:`python:int`, :obj:`Array`\[:class:`python:int`]] A mapping from dense keys to ``.loc`` locations in the ``core``. .. !! processed by numpydoc !! .. py:method:: _create_conversion_dictionaries() Create mappings between state space location indices and properties. See :ref:`state space location indices `. .. !! processed by numpydoc !! .. py:method:: create_arrays_for_expected_value_functions() Create a container for expected value functions. .. !! processed by numpydoc !! .. py:method:: create_objects_for_exogenous_processes() Create mappings for the implementation of the exogenous processes. .. !! processed by numpydoc !! .. py:method:: get_continuation_values(period) Get continuation values. The function takes the expected value functions from the previous periods and then uses the indices of child states to put these expected value functions in the correct format. If period is equal to self.n_periods - 1 the function returns arrays of zeros since we are in terminal states. Otherwise we retrieve expected value functions for next period and call :func:`_get_continuation_values` to assign continuation values to all choices within a period. (The object `subset_expected_value_functions` is required because we need a Numba typed dict but the function :meth:`StateSpace.get_attribute_from_period` just returns a normal dict) :Returns: **continuation_values** : :obj:`numba.typed.Dict` The continuation values for each dense key in a :class:`numpy.ndarray`. .. seealso:: :obj:`_get_continuation_values` A more theoretical explanation can be found here: See :ref:`get continuation values `. .. !! processed by numpydoc !! .. py:method:: collect_child_indices() Collect for each state the indices of its child states. To collect continuation values, one needs to find the child state. This function searches for all states except for the last period their possible successors by taking every possible combination defined by the law of motion. .. seealso:: :obj:`_collect_child_indices` A more theoretical explanation can be found here: See :ref:`collect child indices `. .. !! processed by numpydoc !! .. py:method:: create_draws(options) Get draws. .. !! processed by numpydoc !! .. py:method:: get_dense_keys_from_period(period) Get dense indices from one period. .. !! processed by numpydoc !! .. py:method:: get_attribute_from_period(attribute, period) Get an attribute of the state space sliced to a given period. :Parameters: **attribute** : :class:`python:str` Attribute name, e.g. ``"states"`` to retrieve ``self.states``. **period** : :class:`python:int` Attribute is retrieved from this period. .. !! processed by numpydoc !! .. py:method:: set_attribute_from_keys(attribute, value) Set attributes by keys. This function allows to modify the period part of a certain state space object. It allows to set values for all dense period choice cores within one period. During the model solution this method in period :math:`t + 1` communicates with get continuation values in period :math:`t`. Note that the values are changed in-place. :Parameters: **attribute** : :class:`python:str` The name of the state space attribute which is changed in-place. **value** : :obj:`numpy.ndarray` The value to which the Numpy array is set. .. !! processed by numpydoc !! .. py:function:: _create_core_state_space(optim_paras, options) Create the core state space. The state space of the model are all feasible combinations of the period, experiences, lagged choices and types. Creating the state space involves two steps. First, the core state space is created which abstracts from levels of initial experiences and instead uses the minimum initial experience per choice. Secondly, the state space is adjusted by all combinations of initial experiences and also filtered, excluding invalid states. .. seealso:: :obj:`_create_core_from_choice_experiences` .. :obj:`_create_core_state_space_per_period` .. :obj:`_filter_core_state_space` .. :obj:`_add_initial_experiences_to_core_state_space` .. :obj:`_create_indexer` .. .. rubric:: Notes Here are some details on the implementation. - In the process of creating this function, we came up with several different ideas. Basically, there two fringe cases to find all valid states in the state space. First, all combinations of state attributes are created. Then, only valid states are selected. The problem with this approach is that the state space is extremely sparse. The number of combinations created by using ``itertools.product`` or ``np.meshgrid`` is much higher than the number of valid states. Because of that, we ran into memory or runtime problems which seemed unsolvable. The second approach is more similar to the actual process were states are created by incrementing experiences from period to period. In an extreme case, a function mimics an agent in one period and recursively creates updates of itself in future periods. Using this approach, we ran into the Python recursion limit and runtime problems, but it might be feasible. These two approaches build the frame for thinking about a solution to this problem where filtering is, first, applied after creating a massive amount of candidate states, or, secondly, before creating states. A practical solution must take into account that some restrictions to the state space are more important than others and should be applied earlier. Others can be delayed. As a compromise, we built on the former approach in :func:`~respy.tests._former_code._create_state_space_kw94` which loops over choices and possible experience values. Thus, it incorporates some fundamental restrictions like time limits and needs less filtering. - The former implementation, :func:`~respy.tests._former_code._create_state_space_kw94`, had four hard-coded choices and a loop for every choice with experience accumulation. Thus, this function is useless if the model requires additional or less choices. For each number of choices with and without experience, a new function had to be programmed. The following approach uses the same loops over choices with experiences, but they are dynamically created by the recursive function :func:`_create_core_state_space_per_period`. - There are characteristics of the state space which are independent from all other state space attributes like types (and almost lagged choices). These attributes only duplicate the existing state space and can be taken into account in a later stage of the process. .. !! processed by numpydoc !! .. py:function:: _create_core_from_choice_experiences(optim_paras) Create the core state space from choice experiences. The core state space abstracts from initial experiences and uses the maximum range between initial experiences and maximum experiences to cover the whole range. The combinations of initial experiences are applied later in :func:`_add_initial_experiences_to_core_state_space`. .. seealso:: :obj:`_create_core_state_space_per_period` .. .. !! processed by numpydoc !! .. py:function:: _create_core_state_space_per_period(period, additional_exp, optim_paras, experiences, pos=0) Create core state space per period. First, this function returns a state combined with all possible lagged choices and types. Secondly, if there exists a choice with experience in ``additional_exp[pos]``, loop over all admissible experiences, update the state and pass it to the same function, but moving to the next choice which accumulates experience. :Parameters: **period** : :class:`python:int` Number of period. **additional_exp** : :obj:`numpy.ndarray` Array with shape (n_choices_w_exp,) containing integers representing the additional experience per choice which is admissible. This is the difference between the maximum experience and minimum of initial experience per choice. **experiences** : :data:`python:None` or :obj:`numpy.ndarray`, default :data:`python:None` Array with shape (n_choices_w_exp,) which contains current experience of state. **pos** : :class:`python:int`, default 0 Index for current choice with experience. If index is valid for array ``experiences``, then loop over all admissible experience levels of this choice. Otherwise, ``experiences[pos]`` would lead to an :exc:`IndexError`. .. !! processed by numpydoc !! .. py:function:: _add_lagged_choice_to_core_state_space(df, optim_paras) .. py:function:: _filter_core_state_space(df, options) Apply filters to the core state space. Sometimes, we want to apply filters to a group of choices. Thus, use the following shortcuts. - ``i`` is replaced with every choice with experience. - ``j`` is replaced with every choice without experience. - ``k`` is replaced with every choice with a wage. :Parameters: **df** : :obj:`pandas.DataFrame` .. **options** : :class:`python:dict` .. .. !! processed by numpydoc !! .. py:function:: _add_initial_experiences_to_core_state_space(df, optim_paras) Add initial experiences to core state space. As the core state space abstracts from differences in initial experiences, this function loops through all combinations from initial experiences and adds them to existing experiences. After that, we need to check whether the maximum in experiences is still binding. .. !! processed by numpydoc !! .. py:function:: _create_dense_state_space_grid(optim_paras) Create a grid of dense variables. The function loops through all potential realizations of each dense dimension and returns a list of all possible joint realizations of dense variables. :Parameters: **optim_paras** : :class:`python:dict` Contains parsed model parameters. :Returns: **dense_state_space_grid** : :class:`python:list` Contains all dense states as tuples. .. !! processed by numpydoc !! .. py:function:: _create_dense_state_space_covariates(dense_grid, optim_paras, options) Obtain covariates for all dense states. .. !! processed by numpydoc !! .. py:function:: create_is_inadmissible(df, optim_paras, options) Compute is_inadmissible for passed states. .. !! processed by numpydoc !! .. py:function:: _create_indexer(core, core_key_to_core_indices, optim_paras) Create indexer of core state space. :Returns: **indexer** : :obj:`numba.typed.Dict` Maps a row of the core state space into its position within the period_choice_cores. c: core_state -> (core_key,core_index) .. !! processed by numpydoc !! .. py:function:: _create_core_period_choice(core, optim_paras, options) Create the core separated into period-choice cores. :Returns: **core_period_choice** : :class:`python:dict` c: (period, choice_set) -> core_indices .. !! processed by numpydoc !! .. py:function:: _create_dense_period_choice(core, dense, core_key_to_core_indices, core_key_to_complex, optim_paras, options) Create dense period choice parts of the state space. We loop over all dense combinations and calculate choice restrictions for each particular dense state space. The information allows us to compile a dict that maps a combination of period, choice_set and dense_index into core_key! Note that we do not allow for choice restrictions that interact between core and dense covariates. In order to do so we would have to rewrite this function and return explicit state space position instead of core indices! :Returns: **dense_period_choice** : :class:`python:dict` d: (period, choice_set, dense_index) -> core_key .. !! processed by numpydoc !! .. py:function:: _get_continuation_values(dense_complex_index, choice_set, core_indices, child_indices, core_index_and_dense_vector_to_dense_index, expected_value_functions) Get continuation values from child states. The continuation values are the discounted expected value functions from child states. This method allows to retrieve continuation values that were obtained in the model solution. In particular the function assigns continuation values to state choice combinations by using the child indices created in :func:`_collect_child_indices`. :Returns: **continuation_values** : :obj:`numpy.ndarray` Array with shape ``(n_states, n_choices)``. Maps core_key and choice into continuation value. .. !! processed by numpydoc !! .. py:function:: _collect_child_indices(complex_, choice_set, indexer, optim_paras, options) Collect child indices for states. The function takes the states of one dense key, applies the law of motion for each available choice and maps the resulting states to core keys and core indices. :Parameters: **complex_** : :class:`python:tuple` See :ref:`complex`. **choice_set** : :class:`python:tuple` Tuple representing admissible choices **indexer** : :obj:`numba.typed.Dict` A dictionary with core states as keys and the core key and core index as values. **optim_paras** : :class:`python:dict` Contains model parameters. **options** : :class:`python:dict` Contains model options. :Returns: **indices** : :obj:`numpy.ndarray` Array with shape ``(n_states, n_choices * 2)``. Represents the mapping (core_index, choice) -> (dense_key, core_index). .. !! processed by numpydoc !!