\documentclass[oneside]{book}
\usepackage{url,verbatim,fancyvrb}
\usepackage{pifont}
\usepackage[latin1]{inputenc}
\usepackage[pdftex]{graphicx}
%\usepackage[authoryear]{natbib}
\usepackage{color,gretl}
\usepackage[letterpaper,body={6.3in,9.15in},top=.8in,left=1.1in]{geometry}
\usepackage[pdftex,hyperfootnotes=false]{hyperref}
\usepackage{dcolumn,amsmath,bm}

%% \pdfimageresolution=120
\hypersetup{pdftitle={A Hansl Primer},
            pdfsubject={The scripting language of gretl},
            pdfauthor={Riccardo (Jack) Lucchetti},
            colorlinks=true,
            linkcolor=blue,
            urlcolor=red,
            citecolor=steel,
            bookmarks=true,
            bookmarksnumbered=true,
            plainpages=false
}

\begin{document}

\VerbatimFootnotes

\setlength{\parindent}{0pt}
\setlength{\parskip}{1ex}
\setcounter{tocdepth}{1}

%% titlepage

\thispagestyle{empty}

\begin{center}
\pdfbookmark[1]{A Hansl Primer}{titlepage}

\htitle{A Hansl Primer}

\gsubtitle{The scripting language of gretl in \pageref{LastPage} minutes}

{\large \sffamily
Allin Cottrell\\
Department of Economics\\
Wake Forest University\\

\vspace{20pt}
Riccardo (Jack) Lucchetti\\
Dipartimento di Scienze Economiche e Sociali\\
Università Politecnica delle Marche\\

\vspace{20pt}
\input date
}

\end{center}
\clearpage

%% end titlepage, start license page

\thispagestyle{empty}

\pdfbookmark[1]{License}{license}

\vspace*{2in}

Permission is granted to copy, distribute and/or modify this document
under the terms of the \emph{GNU Free Documentation License}, Version
1.1 or any later version published by the Free Software Foundation
(see \url{http://www.gnu.org/licenses/fdl.html}).

\cleardoublepage

%% end license page, start table of contents
\pdfbookmark[1]{Table of contents}{contents}

\pagenumbering{roman}
\pagestyle{headings}

\tableofcontents

\clearpage
\pagenumbering{arabic}
%\setcounter{chapter}{-1}


\chapter{Introduction}
%\addcontentsline{toc}{chapter}{Introduction}

\section*{What hansl is and what it is not}

Hansl is a recursive acronym: it stands for ``Hansl's A Neat Scripting
Language''. You might therefore expect something very general in
purpose. Not really.  Hansl was born as the scripting language for the
econometrics program \app{gretl} and its role is unlikely to change.
As a consequence, hansl should not be viewed as a fully fledged
programming language such as C, Fortran, Perl or Python. Not because
it lacks anything to be considered as such,\footnote{Hansl is in fact
  Turing-complete.} but because its aim is different. Hansl should be
considered as a special-purpose or domain-specific language, designed
to make an econometrician's life easier. Hence it incorporates a
series of conventions and choices that may irritate purists and have
some marginal impact on raw performance, but that we, as professional
econometricians, consider ``nice to have''.  This makes hansl somewhat
different from plain matrix-oriented interpreted languages, such as
the Matlab/Octave family, Ox and so on.

On the other hand, hansl is by no means just a tool to automate rote
tasks. It has several features which support advanced work: structured
programming, recursion, complex data structures, and so on.  As for
style, the language which hansl most resembles is probably that of the
bash shell.

\section*{The intent and structure of this document}

The intended readers of this document are those who already know how
to write code, and are familiar with the associated do-s and don't-s.
Such people may wish to add hansl to their toolbox, alongside
languages like C or FORTRAN, or programs such as R, Ox, Matlab, Stata
or Gauss, some of which they are already confident with. Here,
therefore, the focus is not so much on ``How do I do this?'', but
rather on ``How do I do this \emph{in hansl}?''.

As a consequence, this document aims at making the reader a reasonably
proficient hansl user in a (relatively) short time; however, not all
the features of hansl are illustrated; for those, interested readers
should consult the \GCR{} and \GUG{}.

This guide comprises two main parts. Part~\ref{part:hp-nodata}
(``Without a dataset'') concentrates on hansl as a pure
matrix-oriented programming language. Part~\ref{part:hp-data} (``With
a dataset'') exploits the fact that hansl scripts are run through
gretl, which has very nice facilities for handling statistical
datasets (interactively if necessary). This provides hansl with a
series of extra constructs and features which make it extremely easy
to write hansl scripts to perform all sorts of statistical procedures.

% A short third part (which is likely to be expanded in future) gives a
% brief account of a few ``further topics''.

In order to use hansl, you will need a working installation of
gretl. We assume you have one. If you don't, please refer to chapter 1
of \GUG.

\section*{Other resources}

If you are serious about learning hansl then after working through
this primer---or in the process of doing so---you'll want to take a
look at the following additional resources.
\begin{itemize}
\item The \GCR. This contains a complete listing of the commands and
  built-in functions available in hansl, with a full account of their
  syntax and options. Examples of usage are provided in some
  instances. This is available in an ``online'' version for handy
  reference as well as in PDF, both accessible via the \textsf{Help} menu
  in the gretl GUI.
\item The \textit{Gretl User's Guide}. Chapters 10 to 16, in
  particular, go into more detail on some of the programming topics
  discussed here (data types, loops, the definition and use of
  functions). In addition Part II of the \textit{Guide}, on
  Econometric Methods, gives many examples of hansl usage. The
  \textit{Guide} is available via gretl's \textsf{Help} menu; the
  latest version can also be found online at
  \url{http://sourceforge.net/projects/gretl/files/manual/}.
\item Sample scripts. The gretl package comes with a large number of
  sample or practice scripts, which can be found under the menu item
  \textsf{/File/Script files/Practice file}. Many of these are simple
  replication exercises for textbook problems but you will find some
  more interesting examples under the \textsf{Gretl} tab.
\item Function packages. Relatively ambitious examples of hansl coding
  can be found in the various contributed ``function packages''. You
  can download these packages via the gretl menu item
  \textsf{/Tools/Function packages/On server}. Once a package is
  downloaded it appears in the listing under \textsf{/Tools/Function
    packages/On local machine}; in that context you can right-click
  and select \textsf{View code} to examine the hansl functions.
\item The gretl-users mailing list. Most well-considered
  questions get answered quite quickly and fully. See
  \url{http://lists.wfu.edu/mailman/listinfo/gretl-users}.
\end{itemize}

\chapter{For the impatient}
\label{chap:impatient}

OK, so you're impatient. Then perhaps you're thinking ``Do I really
need to go through the whole thing? After all, I've been coding
econometric stuff for a while, and I'm pretty confident I can pick a
new scripting language if it's not too obscure.  I just need a few
tips to get me started''. If that's not what you're thinking at all,
we suggest you move along to chapter~\ref{chap:hello}; but if it is,
well then, we'll give you a one-page hansl script which exemplifies a
hefty share of the topics discussed in the rest of this primer. We
will use for our example a Vector AutoRegressive model, or VAR for
short.

As you probably know, a finite-order VAR can be estimated via
conditional maximum likelihood simply by applying OLS to each equation
individually. That amounts to solving a least-squares problem and its
solution can be easily written, in matrix notation, as $\hat{\Pi} =
(X'X)^{-1} X'Y$, where $Y$ contains your endogenous variables and $X$
contains their lags plus other exogenous terms (typically, a constant
term at least). But of course, you may choose to find the maximum of
the concentrated likelihood $\mathcal{L} = -(T/2) \ln|\hat{\Sigma}|$
numerically if you so wish.

The following example contains a hansl script which performs these
actions:
\begin{enumerate}
\item Reads data from a disk file.
\item Performs some data transformation and simple visualization.
\item Estimates the VAR via 
  \begin{enumerate}
  \item the native hansl \texttt{var} command
  \item sequential single-equation OLS
  \item matrix algebra (in 3 different ways)
  \item numerical maximization of the log-likelihood.
  \end{enumerate}
\item Prints out the results.
\end{enumerate}
The script also contains some concise comments.

\begin{scode}
open AWM.gdt --quiet                   # load data from disk

/* data transformations and visualisation */

series y = 100 * hpfilt(ln(YER))       # the "series" concept: operate on      
series u = 100 * URX                   # vectors on an element-by-element basis
series r = STN - 100*sdiff(ln(HICP))   # (but you also have special functions) 

scatters y r u --output=display        # command example with an option: graph data

/* in-house VAR */

scalar p = 2                           # strong typing: a scalar is not a
                                       # matrix nor a series

var p y r u                            # estimation command
A = $coeff                             # and corresponding accessor

/* by iterated OLS */

list X = y r u                         # the list is yet another variable type

matrix B = {}                          # initialize an empty matrix

loop foreach i X                       # loop over the 3 var equations
    ols $i const X(-1 to -p) --quiet   # using native OLS command
    B ~= $coeff                        # and store the estimated coefficients
endloop                               # as matrix columns

/* via matrices */

matrix mY = { y, r, u }                # construct a matrix from series
matrix mX = 1 ~ mlag(mY, {1,2})        # or from matrix operators/functions
mY = mY[p+1:,]                         # and select the appropriate rows
mX = mX[p+1:,]                         # via "range" syntax

C1 = mX\mY                             # matlab-style matrix inversion
C2 = mols(mY, mX)                      # or native function
C3 = inv(mX'mX) * (mX'mY)              # or algebraic primitives

/* or the hard, needlessly complicated way --- just to show off */

function scalar loglik(matrix param, const matrix X, const matrix Y)

    # this function computes the concentrated log-likelihood
    # for an unrestricted multivariate regression model

    scalar n = cols(Y)
    scalar k = cols(X)
    scalar T = rows(Y)
    matrix C = mshape(param, k, n)
    matrix E = Y - X*C
    matrix Sigma = E'E

    return -T/2 * ln(det(Sigma))
end function

matrix c = zeros(21,1)                  # initialize the parameters
mle ll = loglik(c, mX, mY)              # and maximize the log-likelihood
    params c                            # via BFGS, printing out the
end mle                                 # results when done

D = mshape(c, 7, 3)                     # reshape the results for conformability

/* print out the results */

# note: row ordering between alternatives is different 

print A B C1 C2 C3 D
\end{scode}
%$

If you were able to follow the script above in all its parts,
congratulations. You probably don't need to read the rest of this
document (though we don't mind if you do). But if you find the script
too scary, never fear: we'll take things step by step. Read on.

\part{Without a dataset}
\label{part:hp-nodata}
\include{hp-hello}
\include{hp-matrices}
\include{hp-output}
\include{hp-bundles}
\include{hp-numerical}
\include{hp-ctrlflow}
\include{hp-functions}

\part{With a dataset}
\label{part:hp-data}
\include{hp-dataset}
\include{hp-series}
\include{hp-estimate}

% \part{Further topics}
% \include{hp-further}

% \clearpage
% \include{biblio}

\end{document}
