-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
239 lines (179 loc) · 13.8 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
---
title: "Models For Markets in Equilibrium and Disequilibrium"
output:
html_document:
math_method: mathjax
theme: readable
highlight: breezedark
keep_md: false
self_contained: true
github_document:
math_method: webtex
md_document:
variant: markdown_github+tex_math_dollars
bibliography: bibliography.bib
---
<!-- badges: start -->
<!-- badges: end -->
The *markets* package provides tools to estimate and analyze an equilibrium and four disequilibrium models. The equilibrium model can be estimated with either two-stage least squares or with full information maximum likelihood. The two methods are asymptotically equivalent. The disequilibrium models are estimated using full information maximum likelihood. The likelihoods can be estimated both with independent and correlated demand and supply shocks. The optimization of the likelihoods can be performed either using analytic expressions or numerical approximations of their gradients. A detailed overview of the package's functionality, usage examples, and design traits is given in @karapanagiotis2024.
# A quick model tour
The five models of the package are described by systems of simultaneous equations, with the equilibrium system being the only linear one, while the disequilibrium systems being non-linear. All models specify the demand and the supply side of the market by a linear (in parameters) equation. The remaining equations of each model, if any, further specify the market structure.
## The equilibrium model
The equilibrium model adds the market-clearing condition to the demand and supply equations of the system. For the system to be identifiable, at least one variable on the demand side must not be present on the supply side and vice versa. This model assumes that the market observations always represent equilibrium points in which the demanded and supplied quantities are equal. The model can be estimated using two-stage least squares [@theil1953] or full information maximum likelihood [@karapanagiotis2020invisible]. Asymptotically, these methods are equivalent [@balestra1987].
$$
\begin{align}
\begin{aligned}
D_{n t} &= X_{d, n t}'\beta_{d} + P_{n t}\alpha_{d} + u_{d, n t} \\
S_{n t} &= X_{s, n t}'\beta_{s} + P_{n t}\alpha_{s} + u_{s, n t} \\
Q_{n t} &= D_{n t} = S_{n t}
\end{aligned}\tag{EM}\label{equilibrium}
\end{align}
$$
<img src='man/figures/equilibrium_model.png'/>
## The basic disequilibrium model
The basic model is the simplest disequilibrium model of the package as it basically imposes no assumption on the market structure regarding price movements [@fair1972; @maddala1974]. In contrast with the equilibrium model, the market-clearing condition is replaced by the short-side rule, which stipulates that the minimum between the demanded and supplied quantities is observed. The econometrician does not need to specify whether an observation belongs to the demand or the supply side since the estimation of the model will allocate the observations on the demand or supply side so that the likelihood is maximized.
$$
\begin{align}
\begin{aligned}
D_{n t} &= X_{d, n t}'\beta_{d} + u_{d, n t} \\
S_{n t} &= X_{s, n t}'\beta_{s} + u_{s, n t} \\
Q_{n t} &= \min\{D_{n t},S_{n t}\}
\end{aligned} \tag{BM} \label{basic}
\end{align}
$$
<img src='man/figures/diseq_basic.png'/>
## The directional disequilibrium model
The directional model attaches an additional equation to the system of the basic model. The added equation is a sample separation condition based on the direction of the price movements [@fair1972; @maddala1974]. When prices increase at a given date, an observation is assumed to belong on the supply side. When prices fall, an observation is assumed to belong on the demand side. In short, this condition separates the sample before the estimation and uses this separation as additional information in the estimation procedure. Although, when appropriate, more information improves estimations, it also, when inaccurate, intensifies misspecification problems. Therefore, the additional structure of the directional model does not guarantee better estimates in comparison with the basic model.
$$
\begin{align}
\begin{aligned}
D_{n t} &= X_{d, n t}'\beta_{d} + u_{d, n t} \\
S_{n t} &= X_{s, n t}'\beta_{s} + u_{s, n t} \\
Q_{n t} &= \min\{D_{n t},S_{n t}\} \\
\Delta P_{n t} &\ge 0 \implies D_{n t} \ge S_{n t}
\end{aligned} \tag{DM} \label{directional}
\end{align}
$$
<img src='man/figures/diseq_directional.png'/>
## A disequilibrium model with deterministic price dynamics
The separation rule of the directional model classifies observations on the demand- or supply-side based in a binary fashion, which is not always flexible, as observations that correspond to large shortages/surpluses are treated the same as observations that correspond to small shortages/ surpluses. The deterministic adjustment model of the package replaces this binary separation rule with a quantitative one [@fair1972; @maddala1974]. The magnitude of the price movements is analogous to the magnitude of deviations from the market-clearing condition. This model offers a flexible estimation alternative, with one extra degree of freedom in the estimation of price dynamics, that accounts for market forces that are in alignment with standard economic reasoning. By letting $\gamma$ approach zero, the equilibrium model can be obtained as a limiting case of this model.
$$
\begin{align}
\begin{aligned}
D_{n t} &= X_{d, n t}'\beta_{d} + P_{n t}\alpha_{d} + u_{d, n t} \\
S_{n t} &= X_{s, n t}'\beta_{s} + P_{n t}\alpha_{s} + u_{s, n t} \\
Q_{n t} &= \min\{D_{n t},S_{n t}\} \\
\Delta P_{n t} &= \frac{1}{\gamma} \left( D_{n t} - S_{n t} \right)
\end{aligned} \tag{DA} \label{deterministic_adjustment}
\end{align}
$$
<img src='man/figures/diseq_deterministic_adjustment.png'/>
## A disequilibrium model with stochastic price dynamics
The last model of the package extends the price dynamics of the deterministic adjustment model by adding additional explanatory variables and a stochastic term. The latter term, in particular, makes the price adjustment mechanism stochastic and, deviating from the structural assumptions of models $(DA)$ and $(DM)$, abstains from imposing any separation assumption on the sample [@maddala1974; @quandt1978estimating]. The estimation of this model offers the highest degree of freedom, accompanied, however, by a significant increase in estimation complexity, which can hinder the stability of the procedure and the numerical accuracy of the outcomes.
$$
\begin{align}
\begin{aligned}
D_{n t} &= X_{d, n t}'\beta_{d} + P_{n t}\alpha_{d} + u_{d, n t} \\
S_{n t} &= X_{s, n t}'\beta_{s} + P_{n t}\alpha_{s} + u_{s, n t} \\
Q_{n t} &= \min\{D_{n t},S_{n t}\} \\
\Delta P_{n t} &= \frac{1}{\gamma} \left( D_{n t} - S_{n t} \right) + X_{p, n t}'\beta_{p} + u_{p, n t}
\end{aligned} \tag{SA} \label{stochastic_adjustment}
\end{align}
$$
<img src='man/figures/diseq_stochastic_adjustment.png'/>
# Installation and documentation
The released version of [*markets*](https://CRAN.R-project.org/package=markets) can be installed from [CRAN](https://CRAN.R-project.org) with:
```r
install.packages("markets")
```
The source code of the in-development version can be downloaded from [GitHub](https://github.com/pi-kappa-devel/markets).
After installing it, there is a basic-usage example installed with it. To see it type the command
```r
vignette('basic_usage')
```
Online documentation is available for both the [released](https://www.markets.pikappa.eu) and [in-development](https://www.markets.pikappa.eu/dev/) versions of the package. The documentation files can also be accessed in `R` by typing
```r
?? markets
```
An older version of the package (see [diseq](https://CRAN.R-project.org/package=diseq)) was presented in the session Trends, Markets, Models of the [useR!2021](https://user2021.r-project.org/) conference. However, the presented user interface is deprecated and it is recommended to follow [@karapanagiotis2024] for the latest interface. The recording of the session can be found in the video that follows. The presentation slides of the talk are also available [here](https://talks.pikappa.eu/useR!2021/).
<iframe width="560" height="315" src="https://www.youtube.com/embed/Kkjkny94dgU" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
# A practical example
This is a basic example that illustrates how a model of the package can be estimated. The package is loaded in the standard way.
```{r loading}
library(markets)
```
The example uses simulated data. The *markets* package offers a function to simulate data from data-generating processes that correspond to the models that the package provides.
```{r simulation}
model_tbl <- simulate_data(
"diseq_basic", 10000, 5,
-1.9, 36.9, c(2.1, -0.7), c(3.5, 6.25),
2.8, 34.2, c(0.65), c(1.15, 4.2),
NA, NA, c(NA),
seed = 42
)
```
Models are initialized by a constructor. In this example, a basic disequilibrium model is estimated. There are also other models available (see [Design and functionality]). The constructor sets the model's parameters and performs the necessary initialization processes. The following variables specify this example's parameterization.
* The models can be estimated both with panel and time series data. The constructor expects both a subject and a time identifier in order to perform the necessary initialization operations (these are respectively given by `id` and `date` in the simulated data of this example). The observation identification of the data is automatically generated by composing the subject and time identifiers. The resulting composite key is the combination of columns that uniquely identify a record of the dataset.
* The observable traded quantity variable (given by `Q` in this example's simulated data). The demanded and supplied quantities are not observable, and they are identified either based on the market clearing condition or the short-side rule.
* The price variable, which is named after `P` in the simulated data.
* The right-hand side specifications of the demand and supply equations. The expressions are specified similarly to the expressions of formulas of linear models. Indicator variables and interactions are created automatically by the constructor.
* The verbosity level controls the level of messaging. The object displays
* error: always,
* warning: ≥ 1,
* info: ≥ 2,
* verbose: ≥ 3 and
* debug: ≥ 4.
```{r model.parameters.verbose}
verbose <- 0
```
* Should the model estimation allow for correlated demand and supply shocks?
```{r model.parameters.correlated_shocks}
correlated_shocks <- TRUE
```
The model is estimated with default options by a simple call. See the documentation of `estimate` for more details and options.
```{r model.estimate}
fit <- diseq_basic(
Q | P | id | date ~ P + Xd1 + Xd2 + X1 + X2 | P + Xs1 + X1 + X2,
model_tbl, correlated_shocks = correlated_shocks, verbose = verbose
)
```
The results can be inspected in the usual fashion via `summary`.
```{r model.summary}
summary(fit)
```
# Design and functionality
The equilibrium model can be estimated either using two-stage least squares or full information maximum likelihood. The two methods are asymptotically equivalent. The class for which both of these estimation methods are implemented is
* `equilibrium_model`.
In total, there are four disequilibrium models, which are all estimated using full information maximum likelihood. By default, the estimations use analytically calculated gradient expressions, but the user can override this behavior. The classes that implement the four disequilibrium models are
* `diseq_basic`,
* `diseq_directional`,
* `diseq_deterministic_adjustment`, and
* `diseq_stochastic_adjustment`.
The package organizes these classes in a simple object-oriented hierarchy.
<img src='man/figures/design.png' align="center" style="max-width:100%"/>
Concerning post-estimation analysis, the package offers functionality to calculate
* shortage probabilities,
* marginal effects on shortage probabilities,
* point estimates of normalized shortages,
* point estimates of relative shortages,
* aggregate demand and supply,
* post-estimation classification of observations in demand and supply,
* heteroscedasticity-adjusted (Huber-White) standard errors, and
* clustered standard errors.
# Alternative packages
The estimation of the basic model is also supported by the package [_Disequilibrium_](https://CRAN.R-project.org/package=Disequilibrium). By default, the _Disequilibrium_ package numerically approximates the gradient when optimizing the likelihood. In contrast, _markets_ uses analytically calculated expressions for the likelihood, which can reduce the duration of estimating the model. In addition, it allows the user to override this behavior and use the numerically approximated gradient. There is no alternative package that supports the out-of-the-box estimation of the other three disequilibrium models of _markets_.
# Planned extensions
The package is planned to be expanded in the following ways:
1. The package should become more inclusive by adding additional market models.
2. Single-command functionality for the market-clearing tests (e.g. [@karapanagiotis2020invisible; @hwang1980; @quandt1978tests]) should be included in the package.
3. Alternative estimation methods (e.g. [@zilinskas2006; @quandt1978estimating]) could also be implemented.
# Contributors
[Pantelis Karapanagiotis](https://www.pikappa.eu)
Feel free to join, share, contribute, and distribute.
# License
The code is distributed under the MIT License.
# References