Terminology and code around time

[sbenthall]

In the meeting today, CDC suggested we get a consensus around the use of terms relating to time, with an eye to seeing if we can simplify some of the code around time.

The time-handling in HARK comes up in some other tickets, such as : #890 #983 #798 #872 #718 #571 #95

As a kind of draft on this, I thought I'd jot down my current/preferred understanding of relevant terms.

• period and time refers specifically to the t primitive used in the stochastic dynamic programming/Bellman equation paradigm
  • If there is more than one control variable within a period, the problem may be broken down into a sequence of Bellman equations with other primitives besides t, such as s.
  • These complete Bellman sub-problems are stages.
• age refers to an agent-specific variable that increments deterministically with time. In a multi-agent model, there can be multiple agents with different ages.
• a lifecycle element is an element of a problem that varies by agae.
  • for example, lifecycle parameters are parameters that vary over a problem by age, perhaps according to an age-dependent process.
  • a problem might also vary with age. For example, the decision of whether or not to go to college can be limited to a specific age range.
• A model has a set of model variables and transition equations defining the structural transitions between the variables. These typically recur each period.
• frame refers to a set of transitions that change the state of model variables. At its most granular, a frame can be the update of one model variable, such as a shock.
  • The frames together are a partition of the problem's model variables.
  • The members of each part should be adjacent/contiguous in the graph implied by the models' structural equations.

There is also a notion of "seasonal" or "cyclical" problem, such as the problem of the person whose income varies by quarter (e.g. they are ski instructor). This is exemplified here.

The idea in these models is that a cycle spans over multiple time periods, and that this is supported by a cyclically 'time-varying' property. This is different from the 'lifecycle' version because an agent can pass through multiple cycles during their lifetime.

[sbenthall]

I'll take the opportunity to jot down a couple other related ideas.

First: the proposed 'glossary' in the original post is in the context of a single "microeconomic" HARK agent or AgentType. I am less familiar with how market equilibria are expressed in the structural equations in economics literature. But if the current core.py code is representative, than the market too has a time parameter t which increments in sync with the time parameters of the individual agents.

The makes sense to me, and indeed I'd suggest we consider the macroeconomics step to be an additional frame on top of the microeconomic steps within the same time period. This can be visualized in a rather straightforward way using plate notation: basically, put a big box around all the micro-agent internals to indicate that there are multiple copies of them, but have the market aggregation step sit outside the box.

Second: I'm very sympathetic to the idea of reforming the way "time-varying parameters" are handled.

"Lifecycle" and "cycle" time varying parameters actually have different semantics and it requires a lot of knowledge of the HARK internals to decipher that they cannot be combined, especially in the context of a Market equilibrium. The cycles AgentType parameter is intended to settle this as a binary flag (?).

If I'm not mistaken, this means that HARK cannot support:

• dynamic market models with seasonal labor variations, in which agents are born into different seasons
• models with both age-based survival probabilities and seasonal labor shocks

As a solution to this, I propose:

• (a) clarifying the terminology, especially around "cycles", as suggested by CDC, and
• (b) replacing the current way of specifying time-varying parameters as a list with a Process class that captures their intertemporal dynamics. This is closer to what Dolo does and would be easy to implement. There could be (at least) two kinds of processes. CyclicProcess could capture seasonal dynamics. AgeProcess could be a process that varies by agent age. Later on, we can implement or bring in from dolo AR1Process for income, etc.

[sbenthall]

Variable	Equation	Operation	Stage	Utility
\Risky	~Dist	Shock	c	--
\TranShk	~Dist	Shock	c	--
\PermShk	~Dist	Shock	c	--
\Rport	\Rport = \PortShare * \Risky + (1 - \PortShare) * R	Update	c	--
b	b_{t} = a_{t-1} \RPort	Update	c	--
p	p_{t}=p_{t-1}\PermShk_{t}	Update	c	--
y	y_{t} = p_{t}\TranShk_{t}	Update	c	--
m	m_{t} = b_{t} + y_{t}	Update	c	--
c	c	Control	c	U(c)
a	a_{t} = m_{t} - c_{t}	Update	portshare	--
\PortShare	\PortShare	Control	portshare	0

The transition equations refer to a more compressed version of this information that the economics community is used to.

[sbenthall]

At the end of the last conversation between CDC and I, the question remains: what, if anything, is a frame?

I think a frame is a set of continuous variables which may be grouped together for the purpose of efficient computation.

[sbenthall]

The idea that time-varying values should be defined by a process is discussed here: #664

I have some ideas about how to proceed with the implementation of this. I think a good first place to start would be to support the explicit definition of Shock distributions as way of configuring an agent by providing transition equations. See #620

[sbenthall]

Dolo does things a little differently from HARK.

Rather than treat the transition equations for the income process as the same as other transition equations, it separates this out into a separate exogenous AR1 process.

See:
https://github.com/EconForge/dolo.py/blob/master/examples/models_/consumption_savings.yaml#L30-L32

@llorracc I know you are keen on making HARK as similar to Dolo as possible, but also making HARK a useful tool for macroeconomists using more traditional methods. I wonder what your view is of Dolo's modeling the income process as an exogenous time-varying shock.

[sbenthall]

Now, stage and step are terms being used for new HARK constructs.

See #1186

"frame" may be deprecated or transformed into "equation", an element of a stage.

[sbenthall]

Wiki page made for this here: https://github.com/econ-ark/HARK/wiki/Terminology-for-Time