Skip to content

Commit 7c7ad1c

Browse files
bashtagebashtage
committed
DOC: Improve documentation for SUR
Improve SUR background documentation
1 parent 9b26eed commit 7c7ad1c

File tree

5 files changed

+146
-12
lines changed

5 files changed

+146
-12
lines changed

‎doc/source/system/mathematical-detail.lyx‎

Lines changed: 110 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -253,7 +253,7 @@ When residuals are assumed to be homoskedastic, the covariance can be consistent
253253
ly estimated by
254254
\begin_inset Formula
255255
\[
256-
\left(X^{\prime}\Delta^{-1}X\right)^{-1}\left(X^{\prime}\Delta^{-\frac{1}{2}}\hat{\Omega}\Delta^{-\frac{1}{2}}X\right)\left(X^{\prime}\Delta^{-1}X\right)^{-1}
256+
\left(X^{\prime}\Delta^{-1}X\right)^{-1}\left(X^{\prime}\Delta^{-1}\hat{\Omega}\Delta^{-1}X\right)\left(X^{\prime}\Delta^{-1}X\right)^{-1}
257257
\]
258258

259259
\end_inset
@@ -273,7 +273,7 @@ where
273273
\end_inset
274274

275275
while in FGLS
276-
\begin_inset Formula $\Delta=I_{N}\otimes\hat{\Sigma}$
276+
\begin_inset Formula $\Delta=\hat{\Omega}$
277277
\end_inset
278278

279279
.
@@ -407,6 +407,101 @@ is the sum of the scores across models
407407

408408
\end_layout
409409

410+
\begin_layout Standard
411+
\noindent
412+
413+
\series bold
414+
Debiased Estimators
415+
\end_layout
416+
417+
\begin_layout Standard
418+
\noindent
419+
When the debiased flag is set, a small sample adjustment if applied so that
420+
element
421+
\begin_inset Formula $ij$
422+
\end_inset
423+
424+
of
425+
\begin_inset Formula $\hat{\Sigma}$
426+
\end_inset
427+
428+
is scaled by
429+
\begin_inset Formula
430+
\[
431+
\frac{T}{\sqrt{\left(T-P_{i}\right)\left(T-P_{j}\right)}}.
432+
\]
433+
434+
\end_inset
435+
436+
437+
\end_layout
438+
439+
\begin_layout Subsubsection*
440+
Other Statistics
441+
\end_layout
442+
443+
\begin_layout Standard
444+
\noindent
445+
446+
\series bold
447+
Goodness of fit
448+
\end_layout
449+
450+
\begin_layout Standard
451+
\noindent
452+
The reported
453+
\begin_inset Formula $R^{2}$
454+
\end_inset
455+
456+
is always for the data, or weighted data is weights are used, for either
457+
OLS or GLS.
458+
The means that the reported
459+
\begin_inset Formula $R^{2}$
460+
\end_inset
461+
462+
for the GLS estimator may be negative
463+
\end_layout
464+
465+
\begin_layout Standard
466+
\noindent
467+
468+
\series bold
469+
F statistics
470+
\end_layout
471+
472+
\begin_layout Standard
473+
\noindent
474+
When the debiased covariance estimator is used (small sample adjustment)
475+
the reported
476+
\begin_inset Formula $F$
477+
\end_inset
478+
479+
statistics use
480+
\begin_inset Formula $K\left(T-\bar{P}\right)$
481+
\end_inset
482+
483+
where
484+
\begin_inset Formula $\bar{P}=K^{-1}\sum_{i=1}^{K}P_{i}$
485+
\end_inset
486+
487+
where
488+
\begin_inset Formula $P_{i}$
489+
\end_inset
490+
491+
is the number of variables including the constant in model
492+
\begin_inset Formula $i$
493+
\end_inset
494+
495+
.
496+
When models include restrictions it may be the case that the covariance
497+
is singular.
498+
When this occurs, the
499+
\begin_inset Formula $F$
500+
\end_inset
501+
502+
statistic cannot be calculated.
503+
\end_layout
504+
410505
\begin_layout Subsection*
411506
Memory efficient calculations
412507
\end_layout
@@ -521,5 +616,18 @@ solve
521616
.
522617
\end_layout
523618

619+
\begin_layout Standard
620+
\begin_inset Note Note
621+
status open
622+
623+
\begin_layout Plain Layout
624+
TODO: Explain restrictions
625+
\end_layout
626+
627+
\end_inset
628+
629+
630+
\end_layout
631+
524632
\end_body
525633
\end_document

‎doc/source/system/mathematical-detail.txt‎

Lines changed: 31 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -79,14 +79,14 @@ Covariance Estimation
7979
When residuals are assumed to be homoskedastic, the covariance can be
8080
consistently estimated by
8181

82-
.. math:: \left(X^{\prime}\Delta^{-1}X\right)^{-1}\left(X^{\prime}\Delta^{-\frac{1}{2}}\hat{\Omega}\Delta^{-\frac{1}{2}}X\right)\left(X^{\prime}\Delta^{-1}X\right)^{-1}
82+
.. math:: \left(X^{\prime}\Delta^{-1}X\right)^{-1}\left(X^{\prime}\Delta^{-1}\hat{\Omega}\Delta^{-1}X\right)\left(X^{\prime}\Delta^{-1}X\right)^{-1}
8383

8484
where :math:`\Delta` is the weighting matrix used in the parameter
8585
estimator. For example, in OLS :math:`\Delta=I_{NK}` while in
86-
FGLS\ :math:`\Delta=I_{N}\otimes\hat{\Sigma}`. The estimator supports
87-
using FGLS with an assumption that :math:`\hat{\Sigma}` is diagonal or
88-
using a user-specified value of :math:`\Sigma`. When the FGLS estimator
89-
is used, this simplifies to
86+
FGLS\ :math:`\Delta=\hat{\Omega}`. The estimator supports using FGLS
87+
with an assumption that :math:`\hat{\Sigma}` is diagonal or using a
88+
user-specified value of :math:`\Sigma`. When the FGLS estimator is used,
89+
this simplifies to
9090

9191
.. math:: \left(X^{\prime}\Delta^{-1}X\right)^{-1}
9292

@@ -124,6 +124,32 @@ is the sum of the scores across models :math:`\left(j\right)` that have
124124
the same observation index :math:`i`. This estimator allows arbitrary
125125
correlation of residuals with the same observation index.
126126

127+
**Debiased Estimators**
128+
129+
When the debiased flag is set, a small sample adjustment if applied so
130+
that element :math:`ij` of :math:`\hat{\Sigma}` is scaled by
131+
132+
.. math:: \frac{T}{\sqrt{\left(T-P_{i}\right)\left(T-P_{j}\right)}}.
133+
134+
Other Statistics
135+
~~~~~~~~~~~~~~~~
136+
137+
**Goodness of fit**
138+
139+
The reported :math:`R^{2}` is always for the data, or weighted data is
140+
weights are used, for either OLS or GLS. The means that the reported
141+
:math:`R^{2}` for the GLS estimator may be negative
142+
143+
**F statistics**
144+
145+
When the debiased covariance estimator is used (small sample adjustment)
146+
the reported :math:`F` statistics use :math:`K\left(T-\bar{P}\right)`
147+
where :math:`\bar{P}=K^{-1}\sum_{i=1}^{K}P_{i}` where :math:`P_{i}` is
148+
the number of variables including the constant in model :math:`i`. When
149+
models include restrictions it may be the case that the covariance is
150+
singular. When this occurs, the :math:`F` statistic cannot be
151+
calculated.
152+
127153
Memory efficient calculations
128154
-----------------------------
129155

‎linearmodels/system/_utility.py‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -230,7 +230,6 @@ def _compute_transform(self):
230230
vals = np.real(vals)
231231
vecs = np.real(vecs)
232232
idx = np.argsort(vals)[::-1]
233-
vals = vals[idx]
234233
vecs = vecs[:, idx]
235234
t, l = vecs[:, :k - c], vecs[:, k - c:]
236235
q = self._qa[:, None]

‎linearmodels/system/covariance.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
from numpy import eye, ones, sqrt, vstack, zeros
22
from numpy.linalg import inv
33

4-
from linearmodels.system._utility import blocked_diag_product, blocked_inner_prod, inv_matrix_sqrt
4+
from linearmodels.system._utility import (blocked_diag_product, blocked_inner_prod,
5+
inv_matrix_sqrt)
56

67

78
class HomoskedasticCovariance(object):

‎linearmodels/system/model.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
from numpy import (asarray, cumsum, diag, eye, hstack, inf, nanmean,
1818
ones_like, reshape, sqrt, zeros)
1919
from numpy.linalg import inv, solve
20-
from pandas import DataFrame, Series
20+
from pandas import Series
2121
from patsy.highlevel import dmatrices
2222
from patsy.missing import NAAction
2323

@@ -569,7 +569,7 @@ def _common_results(self, beta, cov, method, iter_count, nobs, cov_type,
569569

570570
return results
571571

572-
def _gls_finalize(self, beta, sigma, full_sigma, sigma_m12, gls_eps, eps,
572+
def _gls_finalize(self, beta, sigma, full_sigma, gls_eps, eps,
573573
cov_type, iter_count, **cov_config):
574574
"""Collect results to return after GLS estimation"""
575575
wx = self._wx
@@ -746,7 +746,7 @@ def fit(self, *, method=None, full_cov=True, iterate=False, iter_limit=100, tol=
746746
x = blocked_diag_product(self._x, eye(k))
747747
eps = y - x @ beta
748748

749-
return self._gls_finalize(beta, sigma, full_sigma, sigma_m12, gls_eps,
749+
return self._gls_finalize(beta, sigma, full_sigma, gls_eps,
750750
eps, cov_type, iter_count, **cov_config)
751751

752752
@property

0 commit comments

Comments
 (0)