\SweaveOpts{results=hide, prefix.string=vigpics/threesls}
\include{zinput}
%\VignetteIndexEntry{ Three Stage Least Squares}
%\VignetteDepends{Zelig}
%\VignetteKeyWords{model,continuous, least squares,error term}
%\VignettePackage{Zelig}
\begin{document}
\nobibliography*
<<beforepkgs, echo=FALSE>>=
 before=search()
@
<<loadLibrary, echo=F,results=hide>>=
library(Zelig)
@ 

\section{{\tt threesls}: Three Stage Least Squares}
\label{threesls}

\texttt{threesls} is a combination of two stage least squares
and seemingly unrelated regression. It provides consistent estimates for linear regression models with 
explanatory variables correlated with the error term. It also extends ordinary least squares 
analysis to estimate system of linear equations with correlated error terms
\subsubsection{Syntax}
<<Syntax.list>>=
 fml <- list ("mu1"  = Y1 ~ X1 + Z1,
               "mu2"  = Y2 ~ X2 + Z2,
               "inst1" = Z1 ~ W1 + X1,
               "inst2" = Z2 ~ W2 + X2)
@ 
\begin{verbatim}
> z.out <- zelig(formula = fml, model = "treesls", data = mydata)
> x.out <- setx(z.out)
> s.out <- sim(z.out, x = x.out)
\end{verbatim}
\subsubsection{Inputs}
\texttt{threesls} regression specification requires at least two sets of equations. The first set of $M$ euqations
corresponds to the $M$ dependent variables ($Y_1,\ldots,Y_M$) to be estimated. The second set of equations ($Z$)
corresponds to the instrumental variables in the $M$ equations.
\begin{itemize}
\item \texttt{formula}:a list of the system of equations and instrumental variable 
equations. The system of equations is listed first as \texttt{mu}s. The equations
for the instrumental variables are listed next as \texttt{inst}s.
For example:
<<Inputs.list>>=
 fml <- list ("mu1"  = Y1 ~ X1 + Z1,
               "mu2"  = Y2 ~ X2 + Z2,
               "inst1" = Z1 ~ W1 + X1,
               "inst2" = Z2 ~ W2 + X2)
@ 
\texttt{"mu1"} is the first equation in the two equation model with \texttt{Y1}
as the dependent variable and \texttt{X1} and \texttt{Z1} as
the explanatory variables. \texttt{"mu2"} is the second equation with 
\texttt{Y2} as the dependent variable
and \texttt{X2} and \texttt{Z2} as the explanatory variables. 
\texttt{Z1} and \texttt{Z2} are also problematic endogenous variables, so
they are estimated through instruments in the \texttt{"inst1"} 
and \texttt{"inst2"} equations.
\item \texttt{Y}: dependent variables of interest in the system of equations.
\item \texttt{Z}: the problematic explanatory variables correlated with 
the error term.
\item \texttt{W}: exogenous instrument variables used to estimate the 
problematic explanatory variables (\texttt{Z})
\end{itemize}
\subsubsection{Additional Inputs}
\texttt{threesls} takes the following additional inputs for model
specifications:
\begin{itemize}
\item \texttt{TX}: an optional matrix to transform the regressor
matrix and, hence, also the coefficient vector (see details). Default is \texttt{NULL}.
\item \texttt{maxiter}: maximum number of iterations.
\item \texttt{tol}: tolerance level indicating when to stop the iteration.
\item \texttt{rcovformula}: formula to calculate the estimated residual covariance
matrix (see details). Default is equal to 1.
\item \texttt{formulathreesls}: formula for calculating the threesls estimator, one of ``GLS'',
``IV'', ``GMM'', ``Schmidt'', or ``Eviews'' (see details.)
\item \texttt{probdfsys}: use the degrees of freedom of the whole system
(in place of the degrees of freedom of the single equation to calculate probability
values for the t-test of individual parameters. 
\item \texttt{single.eq.sigma}: use different $\sigma^2$ for each single
equation to calculate the covariance matrix and the standard errors of the coefficients.
\item \texttt{solvetol}: tolerance level for detecting linear dependencies when 
inverting a matrix or calculating a determinant. Default is \texttt {solvetol}=.Machine\$double.eps.
\item \texttt{saveMemory}: logical. Save memory by omitting some calculation that are
not crucial for the basic estimate (e.g McElroy's $R^2$).
\end{itemize}
\subsubsection{Details}
The matrix \texttt{TX} transforms the regressor matrix ($X$) by $X\ast=X \times TX$. Thus,
the vector of coefficients is now $b=TX \times b\ast$ where $b$ is the original(stacked) 
vector of all coefficients and $b\ast$ is the new coefficient vector that is estimated instead.
Thus, the elements of vector $b$ and $b_i = \sum_j TX_{ij}\times b_j\ast$. The $TX$ matrix can be
used to change the order of the coefficients and also to restrict coefficients (if $TX$ has 
less columns than it has rows). 
If iterated (with \texttt{maxit}>1), the covergence criterion is
\begin{eqnarray*}
\sqrt{\frac{\sum_i(b_{i,g}-b_{i,g-1})^2}{\sum_ib_{i,g-1}^2}} < tol
\end{eqnarray*}
where $b_{i,g}$ is the ith coefficient of the gth iteration step.
The formula (\texttt{rcovformula} to calculate the estimated covariance matrix of the residuals($\hat{\Sigma}$)can be one
of the following (see Judge et al., 1955, p.469):
if \texttt{rcovformula}= 0:
\begin{eqnarray*}
\hat{\sigma_{ij}}= \frac{\hat{e_i}\prime\hat{e_j}}{T}
\end{eqnarray*}
if \texttt{rcovformula}= 1 or \texttt{rcovformula}='geomean':
\begin{eqnarray*}
\hat{\sigma_{ij}}= \frac{\hat{e_i}\prime\hat{e_j}}{\sqrt{(T-k_i)\times (T-k_j)}}
\end{eqnarray*}
if \texttt{rcovformula}= 2 or \texttt{rcovformula}='Theil':
\begin{eqnarray*}
\hat{\sigma_{ij}}= \frac{\hat{e_i}\prime\hat{e_j}}{T-k_i-k_j+tr[X_i(X_i\prime X_i)^{-1}X_i\prime X_j(X_j\prime X_j)^{-1}X_j\prime]}
\end{eqnarray*}
if \texttt{rcovformula}= 3 or \texttt{rcovformula}='max':
\begin{eqnarray*}
\hat{\sigma_{ij}}= \frac{\hat{e_i}\prime\hat{e_j}}{T-max(k_i,k_j)}
\end{eqnarray*}
If $i = j$, formula 1, 2, and 3 are equal. All these three formulas yield unbiased estimators
for the diagonal elements of the residual covariance matrix. If $i neq j$, only formula 2
yields an unbiased estimator for the residual covariance matrix, but it is not necessarily
positive semidefinit. Thus, it is doubtful whether formula 2 is really superior to formula 1
(Theil, 1971, p.322).
The formulas to calculate the threesls estimator lead to identical results 
if the same instruments are used in all equations. If different instruments 
are used in the different equations, only the GMM-threesls estimator (``GMM'') 
and the threesls estimator proposed by Schmidt (1990) (``Schmidt'') are consistent, whereas 
``GMM'' is efficient relative to ``Schmidt'' (see Schmidt, 1990).
\subsubsection{Examples}
Attaching the example dataset:
<<Examples.data>>=
   data(kmenta)
@ 
 Formula:
<<Examples.list>>=
 formula <- list(mu1= q ~ p + d,
                mu2=q ~ p + f + a,
                inst =~ d + f+ a )
@ 
Estimating the model using \texttt{threesls}:
<<Examples.zelig>>=
 z.out <- zelig(formula=formula, model ="threesls",data=kmenta)
 summary(z.out)
@ 

Set explanatory variables to their default (mean/mode) values
<<Examples.setx>>=
 x.out <- setx(z.out)
@ 

Simulate draws from the posterior distribution:
<<Examples.sim>>=
 s.out <- sim(z.out, x=x.out)
 summary(s.out)
@
Plot the quantities of interest
\begin{center}
<<label=Examplesthreesls, fig=true, echo=false>>=
plot(s.out)
@ 
\end{center}
\clearpage

\subsubsection{Model}
\subsubsection{See Also}
For information about two stage least square regression, see 
\Sref{2sls} and \texttt{help(2sls)}.
For information about seemingly unrelated regression, see
\Sref{sur} and \texttt{help(sur)}.
\subsubsection{Quantities of Interest}
\subsubsection{Output Values}
The output of each Zelig command contains useful information which you may
view. For example, if you run:
\begin{verbatim}
z.out <- zelig(formula=fml, model = "threesls", data)
\end{verbatim}
\noindent then you may examine the available information in \texttt{z.out} by
using \texttt{names(z.out)}, see the draws from the posterior distribution of
the \texttt{coefficients} by using \texttt{z.out\$coefficients}, and view a default
summary of information through \texttt{summary(z.out)}. Other elements
available through the \texttt{\$} operator are listed below:
\begin{itemize}
\item \texttt{rcovest}: residual covariance matrix used for estimation.
\item \texttt{mcelr2}: McElroys R-squared value for the system.
\item \texttt{h}: matrix of all (diagonally stacked) instrumental variables.
\item \texttt{formulathreesls}: formula for calculating the threesls estimator 

\end{itemize}
\input{systemfit_output}
\begin{itemize}
\item \texttt{inst*}: instruments of the ith equation.
\item \texttt{h*}: matrix of instrumental variables of the ith equation. 
   \item {\tt zelig.data}: the input data frame if {\tt save.data = TRUE}.  
\end{itemize}

\subsection* {How to Cite} 

\input{cites/threesls}
\input{citeZelig}

\subsection* {See also}
The threesls function is adapted from the \texttt{systemfit} library
\citep{HamHen05}.

\bibliographystyle{asa}
\bibliography{gk,gkpubs}
<<afterpkgs, echo=FALSE>>=
 after <- search()
 torm <- setdiff(after,before)
 for (pkg in torm)
 detach(pos=match(pkg,search()))
@
\end{document}

