\documentclass[oneside]{book} \usepackage{url,verbatim,fancyvrb} \usepackage{pifont} \usepackage[utf8]{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,longtable} %% \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 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/Example scripts}. 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{https://gretlml.univpm.it/postorius/lists/}. \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 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{Reference} \label{part:hp-reference} \include{hp-reference} \include{operators} \include{hp-greeks} % \part{Further topics} % \include{hp-further} % \clearpage % \include{biblio} \end{document} %%% Local Variables: %%% mode: latex %%% TeX-master: t %%% End: