respy.state_space#

Everything related to the state space of a structural model.

Module Contents#

Classes#

StateSpace

The state space of a structural model.

Functions#

create_state_space_class(optim_paras, options)

Create the state space of the model.

_create_core_state_space(optim_paras, options)

Create the core state space.

_create_core_from_choice_experiences(optim_paras)

Create the core state space from choice experiences.

_create_core_state_space_per_period(period, ...[, pos])

Create core state space per period.

_add_lagged_choice_to_core_state_space(df, optim_paras)

_filter_core_state_space(df, options)

Apply filters to the core state space.

_add_initial_experiences_to_core_state_space(df, ...)

Add initial experiences to core state space.

_create_dense_state_space_grid(optim_paras)

Create a grid of dense variables.

_create_dense_state_space_covariates(dense_grid, ...)

Obtain covariates for all dense states.

create_is_inadmissible(df, optim_paras, options)

Compute is_inadmissible for passed states.

_create_indexer(core, core_key_to_core_indices, ...)

Create indexer of core state space.

_create_core_period_choice(core, optim_paras, options)

Create the core separated into period-choice cores.

_create_dense_period_choice(core, dense, ...)

Create dense period choice parts of the state space.

_get_continuation_values(dense_complex_index, ...)

Get continuation values from child states.

_collect_child_indices(complex_, choice_set, indexer, ...)

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:
coredict of 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.

dense_key_to_core_indicesDict[int, Array[int]]

A mapping from dense keys to .loc locations in the core.

_create_conversion_dictionaries()[source]#

Create mappings between state space location indices and properties.

See state space location indices.

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 function StateSpace.get_attribute_from_period() just returns a normal dict)

Returns:
continuation_valuesnumba.typed.Dict

The continuation values for each dense key in a numpy.ndarray.

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.

create_draws(options)[source]#

Get draws.

get_dense_keys_from_period(period)[source]#

Get dense indices from one period.

get_attribute_from_period(attribute, period)[source]#

Get an attribute of the state space sliced to a given period.

Parameters:
attributestr

Attribute name, e.g. "states" to retrieve self.states.

periodint

Attribute is retrieved from this 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:
attributestr

The name of the state space attribute which is changed in-place.

valuenumpy.ndarray

The value to which the Numpy array is set.

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.

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 _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().

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:
periodint

Number of period.

additional_expnumpy.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.

experiencesNone or numpy.ndarray, default None

Array with shape (n_choices_w_exp,) which contains current experience of state.

posint, 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 IndexError.

respy.state_space._add_lagged_choice_to_core_state_space(df, optim_paras)[source]#
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:
dfpandas.DataFrame
optionsdict
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.

Parameters:
optim_parasdict

Contains parsed model parameters.

Returns:
dense_state_space_gridlist

Contains all dense states as tuples.

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:
indexernumba.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)

respy.state_space._create_core_period_choice(core, optim_paras, options)[source]#

Create the core separated into period-choice cores.

Returns:
core_period_choicedict

c: (period, choice_set) -> core_indices

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_choicedict

d: (period, choice_set, dense_index) -> core_key

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_valuesnumpy.ndarray

Array with shape (n_states, n_choices). Maps core_key and choice into continuation value.

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:
complex_tuple

See Complex.

choice_settuple

Tuple representing admissible choices

indexernumba.typed.Dict

A dictionary with core states as keys and the core key and core index as values.

optim_parasdict

Contains model parameters.

optionsdict

Contains model options.

Returns:
indicesnumpy.ndarray

Array with shape (n_states, n_choices * 2). Represents the mapping (core_index, choice) -> (dense_key, core_index).