\chapter{Estimation methods}
\label{chap:estimation}

You can, of course, estimate econometric models via hansl without
having a dataset (in the sense in which we're using that term here) in
place---just as you might in \textsf{Matlab}, for instance. You'll
need \textit{data}, but these can be loaded in matrix form (see the
\texttt{mread} function in the \GCR), or generated artificially via
functions such as \texttt{mnormal} or \texttt{muniform}. You can roll
your own estimator using hansl's linear algebra primitives, and you
also have access to more specialized functions such as \texttt{mols}
(see section \ref{sec:mat-op}) and \texttt{mrls} (restricted least
squares) if you need them.

However, unless you need to use an estimation method which is not
currently supported by gretl, or have a strong desire to reinvent the
wheel, you will probably want to make use of the built-in estimation
commands available in hansl. These commands are series-oriented and
therefore require a dataset. They fall into two main categories:
``canned'' procedures, and generic tools that can be used to estimate
a wide variety of models based on common principles.

\section{Canned estimation procedures}
\label{sec:canned}

``Canned'' maybe doesn't sound very appetizing but it's the term
that's commonly used. Basically it means two things, neither of them
in fact unappetizing.
\begin{itemize}
\item The user is presented with a fairly simple interface. A few
  inputs must be specified, and perhaps a few options selected, then
  the heavy lifting is done within the gretl library. Full results
  are printed (parameter estimates plus numerous auxiliary
  statistics). 
\item The algorithm is written in C, by experienced coders. It is
  therefore faster (possibly \textit{much} faster) than an
  implementation in an interpreted language such as hansl.
\end{itemize}

Most such procedures share the syntax
\begin{flushleft}
\quad \textsl{commandname parameters options}
\end{flushleft}
where \textsl{parameters} usually takes the form of a listing of
series: the dependent variable followed by the regressors.

The line-up of procedures can be crudely categorized as follows:

\begin{center}
\begin{tabular}{l>{\raggedright\arraybackslash}p{.6\textwidth}}
Linear, single equation: & \cmd{ols}, \cmd{tsls}, \cmd{ar1},
\cmd{mpols} \\
Linear, multi-equation: & \cmd{system}, \cmd{var}, \cmd{vecm} \\
Nonlinear, single equation: & 
 \cmd{logit}, \cmd{probit}, \cmd{poisson}, \cmd{negbin}, \cmd{tobit},
 \cmd{intreg}, \cmd{logistic}, \cmd{duration} \\
Panel: & \cmd{panel}, \cmd{dpanel} \\
Miscellaneous: & \cmd{arima}, \cmd{garch}, \cmd{heckit},
  \cmd{quantreg}, \cmd{lad}, \cmd{biprobit}
\end{tabular}
\end{center}

Don't let names deceive you: for example, the \cmd{probit} command can
estimate ordered models, random-effect panel probit models, \dots{}
The hansl ``house style'' is to keep to a relatively small number of
command words and to distinguish variants within a class of estimators
such as Probit by means of options, or the character of the data
supplied.

Simultaneous systems (SUR, FIML and so on) constitute the main
exception to the syntax summary above; these require a \cmd{system}
block---see the chapter on Multivariate models in \GUG.

\section{Generic estimation tools}
\label{sec:est-blocks}

Hansl offers three main toolkits for defining estimators beyond the
canned selection. Here's a quick overview:

\begin{center}
\begin{tabular}{lll}
command & estimator & \textit{User's Guide} \\[4pt]
\cmd{nls} & nonlinear least squares & chapter 20 \\
\cmd{mle} & maximum likelihood estimation & chapter 21\\
\cmd{gmm} & generalized method of moments & chapter 22
\end{tabular}
\end{center}

Each of these commands takes the form of a block of statements (e.g.\
\texttt{nls} \dots{} \textrm{end nls}). The user must supply a
function to compute the fitted dependent variable (\texttt{nls}), the
log-likelihood (\texttt{mle}), or the GMM residuals
(\texttt{gmm}). With \texttt{nls} and \texttt{mle}, analytical
derivatives of the function in question with respect to the parameters
may (optionally) be supplied.

The most widely used of these tools is probably \texttt{mle}. Hansl
offers several canned ML estimators, but if you come across a model
that you want to estimate via maximum likelihood and it is not
supported natively, all you have to do is write down the
log-likelihood in hansl's notation and run it through the \texttt{mle}
apparatus.

\section{Post-estimation accessors}
\label{sec:postest-accessors}

All of the methods mentioned above are \textit{commands}, not
functions; they therefore do not \textit{return} any values. However,
after estimating a model---either using a canned procedure or one of
the toolkits---you can grab most of the quantities you might wish to
have available for further analysis via accessors.

Some such accessors are generic, and are available after using just
about any estimator. Examples include \dollar{coeff} and
\dollar{stderr} (to get the vectors of coefficients and standard
errors, respectively), \dollar{uhat} and \dollar{yhat} (residuals and
fitted values), and \dollar{vcv} (the covariance matrix of the
coefficients). Some, on the other hand, are specific to certain
estimators. Examples here include \dollar{jbeta} (the cointegration
matrix, following estimation of a VECM), \dollar{h} (the estimated
conditional variance series following GARCH estimation), and
\dollar{mnlprobs} (the matrix of per-outcome probabilities following
multinomial logit estimation).

A full listing and description of accessors can be found in the
\GCR.

\section{Formatting the results of estimation}
\label{sec:model-format}

The commands mentioned in this chapter produce by default quite
verbose (and, hopefully, nicely formatted) output. However, in some
cases you may want to use built-in commands as auxiliary steps in
implementing an estimator that is not itself built in. In that context
the standard printed output may be inappropriate and you may want to
take charge of presenting the results yourself. 

This can be accomplished quite easily. First, you can suppress the
usual output by using the \option{quiet} option with built-in
estimation commands.\footnote{For some commands, \option{quiet}
  reduces but does not eliminate gretl's usual output. In these cases
  you can give the \option{silent} option. Consult the \GCR\ to
  determine which commands accept this option.} Second, you can
use the \cmd{modprint} command to generate the desired output.
As usual, see the \GCR\ for details.

\section{Named models}

We said above that estimation commands in hansl don't return
anything. This should be qualified in one respect: it is possible to
use a special syntax to push a model onto a stack of named models.
Rather than the usual assignment symbol, the form ``\verb|<-|'' is
used for this purpose. This is mostly intended for use in the gretl
GUI but it can also be used in hansl scripting.

Once a model is saved in this way, the accessors mentioned above can
be used in a special way, joined by a dot to the name of the target
model. A little example follows. (Note that \dollar{ess} accesses the
error sum of squares, or sum of squared residuals, for models
estimated via least squares.)

\begin{code}
diff y x
ADL <- ols y const y(-1) x(0 to -1)
ECM <- ols d_y const d_x y(-1) x(-1)
# the following two values should be equal
ssr_a = ADL.$ess
ssr_e = ECM.$ess
\end{code}

%% \label{LastPage}

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "hansl-primer"
%%% End: 
