respy.state_space
Everything related to the state space of a structural model.
StateSpace(core, indexer, dense, dense_period_cores, core_key_to_complex, core_key_to_core_indices, optim_paras, options)
StateSpace
The state space of a structural model.
create_state_space_class(optim_paras, options)
create_state_space_class
Create the state space of the model.
_create_core_state_space(optim_paras, options)
_create_core_state_space
Create the core state space.
_create_core_from_choice_experiences(optim_paras)
_create_core_from_choice_experiences
Create the core state space from choice experiences.
_create_core_state_space_per_period(period, additional_exp, optim_paras, experiences, pos=0)
_create_core_state_space_per_period
Create core state space per period.
_add_lagged_choice_to_core_state_space(df, optim_paras)
_add_lagged_choice_to_core_state_space
_filter_core_state_space(df, options)
_filter_core_state_space
Apply filters to the core state space.
_add_initial_experiences_to_core_state_space(df, optim_paras)
_add_initial_experiences_to_core_state_space
Add initial experiences to core state space.
_create_dense_state_space_grid(optim_paras)
_create_dense_state_space_grid
Create a grid of dense variables.
_create_dense_state_space_covariates(dense_grid, optim_paras, options)
_create_dense_state_space_covariates
Obtain covariates for all dense states.
create_is_inadmissible(df, optim_paras, options)
create_is_inadmissible
Compute is_inadmissible for passed states.
_create_indexer(core, core_key_to_core_indices, optim_paras)
_create_indexer
Create indexer of core state space.
_create_core_period_choice(core, optim_paras, options)
_create_core_period_choice
Create the core separated into period-choice cores.
_create_dense_period_choice(core, dense, core_key_to_core_indices, core_key_to_complex, optim_paras, options)
_create_dense_period_choice
Create dense period choice parts of the state space.
_insert_indices_of_child_states(states, indexer, choice_set, n_choices, n_choices_w_exp, n_lagged_choices)
_insert_indices_of_child_states
Collect indices of child states for each parent state.
_get_continuation_values(core_indices, dense_complex_index, child_indices, core_index_and_dense_vector_to_dense_index, expected_value_functions)
_get_continuation_values
Get continuation values from child states.
_collect_child_indices(core, core_indices, choice_set, indexer, optim_paras)
_collect_child_indices
Collect child indices for one particular dense choice core.
respy.state_space.
dict
pandas.DataFrame
The core state space is a 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.
_create_conversion_dictionaries
Create mappings between state space location indices and properties.
Creates mappings between state space location indices and other state space location indices or state space properties. Some of these mappings are numba typed dicts instead of ordinary dicts for performance reasons. A short description of the state space location indices follows below:
Core indices are row indices for states in the core state space. They are continued over different periods and choice sets in the core.
A core_key is an index for a set of states in the core state space which are in the same period and share the same choice set.
core_key
A dense vector is combination of values in the dense dimensions.
A dense index is a position in the dense grid.
A dense_key is an index for a set of states in the dense state space which are in the same period, share the same choice set, and the same dense vector.
dense_key
A complex key is the basis for core_key and dense_key it is a tuple of a period and a tuple for the choice set which contains booleans for whether a choice is available. The complex index for a dense index also contains the dense vector in the last position.
create_arrays_for_expected_value_functions
Create a container for expected value functions.
get_continuation_values
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 _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 StateSpace.get_attribute_from_period() just returns a normal dict)
_get_continuation_values()
StateSpace.get_attribute_from_period()
numba.typed.Dict
The continuation values for each dense key in a numpy.ndarray.
numpy.ndarray
See also
A more theoretical explanation can be found here: See get continuation values.
collect_child_indices
Collect for each state the indices of its child states.
A more theoretical explanation can be found here: See collect child indices.
create_draws
Get draws.
get_dense_keys_from_period
Get dense indices from one period.
get_attribute_from_period
Get an attribute of the state space sliced to a given period.
str
Attribute name, e.g. "states" to retrieve self.states.
"states"
self.states
int
Attribute is retrieved from this period.
set_attribute_from_keys
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 \(t + 1\) communicates with get continuation values in period \(t\).
Note that the values are changed in-place.
The name of the state space attribute which is changed in-place.
The value to which the Numpy array is set.
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.
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.
itertools.product
np.meshgrid
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 _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.
_create_state_space_kw94()
The former implementation, _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 _create_core_state_space_per_period().
_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.
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 _add_initial_experiences_to_core_state_space().
_add_initial_experiences_to_core_state_space()
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.
additional_exp[pos]
Number of period.
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.
None
Array with shape (n_choices_w_exp,) which contains current experience of state.
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 IndexError.
experiences
experiences[pos]
IndexError
Sometimes, we want to apply filters to a group of choices. Thus, use the following shortcuts.
i is replaced with every choice with experience.
i
j is replaced with every choice without experience.
j
k is replaced with every choice with a wage.
k
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.
The function loops through all potential realizations of each dense dimension and returns a list of all possible joint realizations of dense variables.
Contains parsed model parameters.
list
Contains all dense states as tuples.
Maps a row of the core state space into its position within the period_choice_cores. c: core_state -> (core_key,core_index)
c: (period, choice_set) -> core_indices
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!
d: (period, choice_set, dense_index) -> core_key
Subset of core state space containing all core dimensions that arise within a particular dense period choice core.
Number of admissible choices within a particular dense period choice core.
Number of total choices with experience accumulation.
Number of lagged choices to be kept accounted for in the core.
Array with shape (n_states, n_choices * 2). Represents the mapping (core_index, choice) -> (dense_key, core_index).
(n_states, n_choices * 2)
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 _collect_child_indices().
_collect_child_indices()
Array with shape (n_states, n_choices). Maps core_key and choice into continuation value.
(n_states, n_choices)
Particularly creates some auxiliary objects to call _insert_indices_of_child_state thereafter.
core state space
Indices of core positions belonging to a particular dense period choice core.
tuple
Tuple representing admissible choices
respy.solve