respy.state_space
#
Everything related to the state space of a structural model.
Module Contents#
Classes#
The state space of a structural model. |
Functions#
|
Create the state space of the model. |
|
Create the core state space. |
|
Create the core state space from choice experiences. |
|
Create core state space per period. |
|
|
|
Apply filters to the core state space. |
Add initial experiences to core state space. |
|
|
Create a grid of dense variables. |
|
Obtain covariates for all dense states. |
|
Compute is_inadmissible for passed states. |
|
Create indexer of core state space. |
|
Create the core separated into period-choice cores. |
|
Create dense period choice parts of the state space. |
|
Get continuation values from child states. |
|
Collect child indices for states. |
- respy.state_space.create_state_space_class(optim_paras, options)[source]#
Create the state space of the model.
- class respy.state_space.StateSpace(core, indexer, dense, dense_period_cores, core_key_to_complex, core_key_to_core_indices, optim_paras, options)[source]#
The state space of a structural model.
- Attributes:
- core
dict
ofpandas.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.- dense_key_to_core_indices
Dict
[int
,Array
[int
]] A mapping from dense keys to
.loc
locations in thecore
.
- core
- _create_conversion_dictionaries()[source]#
Create mappings between state space location indices and properties.
- create_arrays_for_expected_value_functions()[source]#
Create a container for expected value functions.
- create_objects_for_exogenous_processes()[source]#
Create mappings for the implementation of the exogenous processes.
- get_continuation_values(period)[source]#
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 functionStateSpace.get_attribute_from_period()
just returns a normal dict)- Returns:
- continuation_values
numba.typed.Dict
The continuation values for each dense key in a
numpy.ndarray
.
- continuation_values
See also
_get_continuation_values
A more theoretical explanation can be found here: See get continuation values.
- collect_child_indices()[source]#
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.
See also
_collect_child_indices
A more theoretical explanation can be found here: See collect child indices.
- get_attribute_from_period(attribute, period)[source]#
Get an attribute of the state space sliced to a given period.
- set_attribute_from_keys(attribute, value)[source]#
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.
- Parameters:
- attribute
str
The name of the state space attribute which is changed in-place.
- value
numpy.ndarray
The value to which the Numpy array is set.
- attribute
- respy.state_space._create_core_state_space(optim_paras, options)[source]#
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.
See also
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
ornp.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
_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,
_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()
.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.
- respy.state_space._create_core_from_choice_experiences(optim_paras)[source]#
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
_add_initial_experiences_to_core_state_space()
.See also
- respy.state_space._create_core_state_space_per_period(period, additional_exp, optim_paras, experiences, pos=0)[source]#
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
int
Number of period.
- additional_exp
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
None
ornumpy.ndarray
, defaultNone
Array with shape (n_choices_w_exp,) which contains current experience of state.
- pos
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 anIndexError
.
- period
- respy.state_space._filter_core_state_space(df, options)[source]#
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
pandas.DataFrame
- options
dict
- df
- respy.state_space._add_initial_experiences_to_core_state_space(df, optim_paras)[source]#
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.
- respy.state_space._create_dense_state_space_grid(optim_paras)[source]#
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.
- respy.state_space._create_dense_state_space_covariates(dense_grid, optim_paras, options)[source]#
Obtain covariates for all dense states.
- respy.state_space.create_is_inadmissible(df, optim_paras, options)[source]#
Compute is_inadmissible for passed states.
- respy.state_space._create_indexer(core, core_key_to_core_indices, optim_paras)[source]#
Create indexer of core state space.
- Returns:
- indexer
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)
- indexer
- respy.state_space._create_core_period_choice(core, optim_paras, options)[source]#
Create the core separated into period-choice cores.
- Returns:
- core_period_choice
dict
c: (period, choice_set) -> core_indices
- core_period_choice
- respy.state_space._create_dense_period_choice(core, dense, core_key_to_core_indices, core_key_to_complex, optim_paras, options)[source]#
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
dict
d: (period, choice_set, dense_index) -> core_key
- dense_period_choice
- respy.state_space._get_continuation_values(dense_complex_index, choice_set, core_indices, child_indices, core_index_and_dense_vector_to_dense_index, expected_value_functions)[source]#
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
_collect_child_indices()
.- Returns:
- continuation_values
numpy.ndarray
Array with shape
(n_states, n_choices)
. Maps core_key and choice into continuation value.
- continuation_values
- respy.state_space._collect_child_indices(complex_, choice_set, indexer, optim_paras, options)[source]#
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:
- Returns:
- indices
numpy.ndarray
Array with shape
(n_states, n_choices * 2)
. Represents the mapping (core_index, choice) -> (dense_key, core_index).
- indices