\chapter{Gretl and \TeX}
\label{gretltex}
\section{Introduction}
\label{tex-intro}
\TeX\ --- initially developed by Donald Knuth of Stanford University
and since enhanced by hundreds of contributors around the world --- is
the gold standard of scientific typesetting. \app{Gretl} provides
various hooks that enable you to preview and print econometric results
using the \TeX\ engine, and to save output in a form suitable for
further processing with \TeX.
This chapter explains the finer points of \app{gretl}'s \TeX-related
functionality. The next section describes the relevant menu items;
section~\ref{tex-tune} discusses ways of fine-tuning \TeX\ output;
section~\ref{tex-encode} explains how to handle the encoding of
characters not found in English; and section~\ref{tex-install} gives
some pointers on installing (and learning) \TeX\ if you do not already
have it on your computer. (Just to be clear: \TeX\ is not included
with the \app{gretl} distribution; it is a separate package, including
several programs and a large number of supporting files.)
Before proceeding, however, it may be useful to set out briefly the
stages of production of a final document using \TeX. For the most
part you don't have to worry about these details, since, in regard to
previewing at any rate, \app{gretl} handles them for you. But having
some grasp of what is going on behind the scences will enable you to
understand your options better.
The first step is the creation of a plain text ``source'' file,
containing the text or mathematics to be typset, interspersed with
mark-up that defines how it should be formatted. The second step is
to run the source through a processing engine that does the actual
formatting. Typically this is either:
\begin{itemize}
\item a program called \app{latex} that generates so-called DVI
(device-independent) output, or
\item a program called \app{pdflatex} that generates PDF
output.\footnote{Experts will be aware of something called ``plain
\TeX'', which is processed using the program \app{tex}. The great
majority of \TeX\ users, however, use the \LaTeX\ macros,
initially developed by Leslie Lamport. \app{Gretl} does not
support plain \TeX.}
\end{itemize}
For previewing, one uses either a DVI viewer (typically \app{xdvi} on
GNU/Linux systems) or a PDF viewer (for example, Adobe's Acrobat
Reader or \app{xpdf}), depending on how the source was processed. If
the DVI route is taken, there's then a third step to produce printable
output, typically using the program \app{dvips} to generate a
PostScript file. If the PDF route is taken, the output is ready for
printing without any further processing.
On the MS Windows and Mac OS X platforms, \app{gretl} calls
\app{pdflatex} to process the source file, and expects the operating
system to be able to find the default viewer for PDF output; DVI is
not supported. On GNU/Linux the default is to take the DVI route, but
if you prefer to use PDF you can do the following: select the menu
item ``Tools, Preferences, General'' then the ``Programs'' tab. Find
the item titled ``Command to compile TeX files'', and set this to
\texttt{pdflatex}. Make sure the ``Command to view PDF files'' is set
to something appropriate.
\section{\TeX-related menu items}
\label{tex-menus}
\subsection{The model window}
The fullest \TeX\ support in \app{gretl} is found in the GUI model
window. This has a menu item titled ``LaTeX'' with sub-items
``View'', ``Copy'', ``Save'' and ``Equation options'' (see
Figure~\ref{fig:latex-menu}).
\begin{figure}[htbp]
\caption{\LaTeX\ menu in model window}
\label{fig:latex-menu}
\begin{center}
\includegraphics[scale=0.75]{figures/latex_menu}
\end{center}
\end{figure}
The first three sub-items have branches titled ``Tabular'' and
``Equation''. By ``Tabular'' we mean that the model is represented in
the form of a table; this is the fullest and most explicit
presentation of the results. See Table~\ref{tab:mod1} for an example;
this was pasted into the manual after using the ``Copy, Tabular'' item
in \app{gretl} (a few lines were edited out for brevity).
\begin{table}[htbp]
\caption{Example of \LaTeX\ tabular output}
\label{tab:mod1}
\begin{center}
Model 1: OLS estimates using the 51 observations 1--51\\
Dependent variable: ENROLL\\
\vspace{1em}
\begin{tabular*}{.8\textwidth}{@{\extracolsep{\fill}}
l% col 1: varname
D{.}{.}{-1}% col 2: coeff
D{.}{.}{-1}% col 3: sderr
D{.}{.}{-1}% col 4: t-stat
D{.}{.}{4}}% col 5: p-value (or slope)
Variable &
\multicolumn{1}{c}{Coefficient} &
\multicolumn{1}{c}{Std.\ Error} &
\multicolumn{1}{c}{$t$-statistic} &
\multicolumn{1}{c}{p-value} \\[1ex]
const &
0.241105 &
0.0660225 &
3.6519 &
0.0007 \\
CATHOL &
0.223530 &
0.0459701 &
4.8625 &
0.0000 \\
PUPIL &
-0.00338200 &
0.00271962 &
-1.2436 &
0.2198 \\
WHITE &
-0.152643 &
0.0407064 &
-3.7499 &
0.0005 \\
\end{tabular*}
\vspace{1em}
\begin{tabular}{lD{.}{.}{-1}}
Mean of dependent variable & 0.0955686 \\
S.D. of dependent variable & 0.0522150 \\
Sum of squared residuals & 0.0709594 \\
Standard error of residuals ($\hat{\sigma}$) & 0.0388558 \\
Unadjusted $R^2$ & 0.479466 \\
Adjusted $\bar{R}^2$ & 0.446241 \\
$F(3, 47)$ & 14.4306 \\
\end{tabular}
\end{center}
\end{table}
The ``Equation'' option is fairly self-explanatory --- the results are
written across the page in equation format, as below:
%%% the following needs the amsmath LaTeX package
\begin{gather}
\widehat{\rm ENROLL} =
\underset{(0.066022)}{0.241105}
+\underset{(0.04597)}{0.223530}\,\mbox{CATHOL}
-\underset{(0.0027196)}{0.00338200}\,\mbox{PUPIL}
-\underset{(0.040706)}{0.152643}\,\mbox{WHITE}
\notag \\
T = 51 \quad \bar{R}^2 = 0.4462 \quad F(3,47) = 14.431 \quad \hat{\sigma} = 0.038856\notag \\
\centerline{(standard errors in parentheses)} \notag
\end{gather}
The distinction between the ``Copy'' and ``Save'' options (for both
tabular and equation) is twofold. First, ``Copy'' puts the \TeX\
source on the clipboard while with ``Save'' you are prompted for the
name of a file into which the source should be saved. Second, with
``Copy'' the material is copied as a ``fragment'' while with ``Save''
it is written as a complete file. The point is that a well-formed
\TeX\ source file must have a header that defines the
\texttt{documentclass} (article, report, book or whatever) and tags
that say \verb|\begin{document}| and \verb|\end{document}|. This
material is included when you do ``Save'' but not when you do
``Copy'', since in the latter case the expectation is that you will
paste the data into an existing \TeX\ source file that already has the
relevant apparatus in place.
The items under ``Equation options'' should be self-explanatory: when
printing the model in equation form, do you want standard errors or
$t$-ratios displayed in parentheses under the parameter estimates?
The default is to show standard errors; if you want $t$-ratios, select
that item.
\subsection{Other windows}
Several other sorts of output windows also have \TeX\ preview, copy
and save enabled. In the case of windows having a graphical toolbar,
look for the \TeX\ button. Figure~\ref{fig:tex-icon} shows this icon
(second from the right on the toolbar) along with the dialog that
appears when you press the button.
\begin{figure}[htbp]
\caption{\TeX\ icon and dialog}
\label{fig:tex-icon}
\begin{center}
\includegraphics[scale=0.75]{figures/texdialog}
\end{center}
\end{figure}
One aspect of \app{gretl}'s \TeX\ support that is likely to be
particularly useful for publication purposes is the ability to produce
a typeset version of the ``model table'' (see
section~\ref{model-table}). An example of this is shown in
Table~\ref{tab:modeltab}.
\begin{table}[htbp]
\caption{Example of model table output}
\label{tab:modeltab}
\begin{center}
OLS estimates\\
Dependent variable: ENROLL \\
\vspace{1em}
\begin{tabular}{lccc}
& Model 1 & Model 2 & Model 3 \\ [6pt]
const & $\,\,$0.2907$^{**}$ & $\,\,$0.2411$^{**}$ & 0.08557 \\
& \footnotesize{(0.07853)} & \footnotesize{(0.06602)} & \footnotesize{(0.05794)} \\ [4pt]
CATHOL & $\,\,$0.2216$^{**}$ & $\,\,$0.2235$^{**}$ & $\,\,$0.2065$^{**}$ \\
& \footnotesize{(0.04584)} & \footnotesize{(0.04597)} & \footnotesize{(0.05160)} \\ [4pt]
PUPIL & $-$0.003035 & $-$0.003382 & $-$0.001697 \\
& \footnotesize{(0.002727)} & \footnotesize{(0.002720)} & \footnotesize{(0.003025)} \\ [4pt]
WHITE & $\,\,$$-$0.1482$^{**}$ & $\,\,$$-$0.1526$^{**}$ & \\
& \footnotesize{(0.04074)} & \footnotesize{(0.04071)} & \\ [4pt]
ADMEXP & $-$0.1551 & & \\
& \footnotesize{(0.1342)} & & \\ [4pt]
$n$ & 51 & 51 & 51 \\
$\bar R^2$ & 0.4502 & 0.4462 & 0.2956 \\
$\ell$ & 96.09 & 95.36 & 88.69 \\
\end{tabular}
\vspace{1em}
Standard errors in parentheses\\
{}* indicates significance at the 10 percent level\\
{}** indicates significance at the 5 percent level\\
\end{center}
\end{table}
\section{Fine-tuning typeset output}
\label{tex-tune}
There are three aspects to this: adjusting the appearance of the
output produced by \app{gretl} in \LaTeX\ preview mode; adjusting the
formatting of \app{gretl}'s tabular output for models when using the
\texttt{tabprint} command; and incorporating \app{gretl}'s output into
your own \TeX\ files.
\subsection{Previewing in the GUI}
As regards \emph{preview mode}, you can control the appearance of
\app{gretl}'s output using a file named \verb+gretlpre.tex+, which
should be placed in your \app{gretl} user directory (see the \GCR).
If such a file is found, its contents will be used as the ``preamble''
to the \TeX\ source. The default value of the preamble is as follows:
\begin{code}
\documentclass[11pt]{article}
\usepackage[latin1]{inputenc} %% but see below
\usepackage{amsmath}
\usepackage{dcolumn,longtable}
\begin{document}
\thispagestyle{empty}
\end{code}
Note that the \verb+amsmath+ and \verb+dcolumn+ packages are required.
(For some sorts of output the \verb+longtable+ package is also
needed.) Beyond that you can, for instance, change the type size or
the font by altering the \texttt{documentclass} declaration or
including an alternative font package.
The line \verb|\usepackage[latin1]{inputenc}| is automatically
changed if \app{gretl} finds itself running on a system where UTF-8
is the default character encoding --- see section~\ref{tex-encode}
below.
In addition, if you should wish to typeset \app{gretl} output in more
than one language, you can set up per-language preamble files. A
``localized'' preamble file is identified by a name of the form
\verb|gretlpre_xx.tex|, where \texttt{xx} is replaced by the first two
letters of the current setting of the \texttt{LANG} environment
variable. For example, if you are running the program in Polish,
using \verb|LANG=pl_PL|, then \app{gretl} will do the following when
writing the preamble for a \TeX\ source file.
\begin{enumerate}
\item Look for a file named \verb|gretlpre_pl.tex| in the \app{gretl}
user directory. If this is not found, then
\item look for a file named \verb|gretlpre.tex| in the \app{gretl}
user directory. If this is not found, then
\item use the default preamble.
\end{enumerate}
Conversely, suppose you usually run \app{gretl} in a language other
than English, and have a suitable \verb|gretlpre.tex| file in place
for your native language. If on some occasions you want to produce
\TeX\ output in English, then you could create an additional
file \verb|gretlpre_en.tex|: this file will be used for the preamble
when \app{gretl} is run with a language setting of, say,
\verb|en_US|.
\subsection{Command-line options}
After estimating a model via a script --- or interactively via the
\app{gretl} console or using the command-line program \app{gretlcli}
--- you can use the commands \texttt{tabprint} or \texttt{eqnprint} to
print the model to file in tabular format or equation format
respectively. These options are explained in the \GCR{}.
If you wish alter the appearance of \app{gretl}'s tabular output for
models in the context of the \texttt{tabprint} command, you can
specify a custom row format using the \option{format} flag. The
format string must be enclosed in double quotes and must be tied to
the flag with an equals sign. The pattern for the format string is as
follows. There are four fields, representing the coefficient,
standard error, $t$-ratio and p-value respectively. These fields
should be separated by vertical bars; they may contain a
\texttt{printf}-type specification for the formatting of the numeric
value in question, or may be left blank to suppress the printing of
that column (subject to the constraint that you can't leave all the
columns blank). Here are a few examples:
\begin{code}
--format="%.4f|%.4f|%.4f|%.4f"
--format="%.4f|%.4f|%.3f|"
--format="%.5f|%.4f||%.4f"
--format="%.8g|%.8g||%.4f"
\end{code}
The first of these specifications prints the values in all columns
using 4 decimal places. The second suppresses the p-value and prints
the $t$-ratio to 3 places. The third omits the $t$-ratio. The last
one again omits the $t$, and prints both coefficient and standard
error to 8 significant figures.
Once you set a custom format in this way, it is remembered and used
for the duration of the gretl session. To revert to the default
formatting you can use the special variant \verb|--format=default|.
\subsection{Further editing}
Once you have pasted \app{gretl}'s \TeX\ output into your own
document, or saved it to file and opened it in an editor, you can of
course modify the material in any wish you wish. In some cases,
machine-generated \TeX\ is hard to understand, but \app{gretl}'s
output is intended to be human-readable and -editable. In addition,
it does not use any non-standard style packages. Besides the standard
\LaTeX\ document classes, the only files needed are, as noted above,
the \verb+amsmath+, \verb+dcolumn+ and \verb+longtable+ packages.
These should be included in any reasonably full \TeX\ implementation.
\section{Character encodings}
\label{tex-encode}
People using \app{gretl} in English-speaking locales are unlikely to
have a problem with this, but if you're generating \TeX\ output in a
locale where accented characters (not in the ASCII character set) are
employed, you may want to pay attention here.
\app{Gretl} generates \TeX\ output using whatever character encoding
is standard on the local system. If the system encoding is in the
ISO-8859 family, this will probably be OK wihout any special effort on
the part of the user. Newer GNU/Linux systems, however, typically use
Unicode (UTF-8). This is also OK so long as your \TeX\ system can
handle UTF-8 input, which requires use of the \app{latex-ucs} package.
So: if you are using \app{gretl} to generate \TeX\ in a non-English
locale, where the system encoding is UTF-8, you will need to ensure
that the \app{latex-ucs} package is installed. This package may or
may not be installed by default when you install \TeX{}.
For reference, if \app{gretl} detects a UTF-8 environment, the
following lines are used in the \TeX\ preamble:
%
\begin{code}
\usepackage{ucs}
\usepackage[utf8x]{inputenc}
\end{code}
\section{Installing and learning \TeX}
\label{tex-install}
This is not the place for a detailed exposition of these matters, but
here are a few pointers.
So far as we know, every GNU/Linux distribution has a package or set
of packages for \TeX, and in fact these are likely to be installed by
default. Check the documentation for your distribution. For MS
Windows, several packaged versions of \TeX\ are available: one of the
most popular is MiK\TeX\, at \url{http://www.miktex.org/}. For Mac OS
X a nice implementation is i\TeX{}Mac, at
\url{http://itexmac.sourceforge.net/}. An essential starting point for
online \TeX\ resources is the Comprehensive
\TeX\ Archive Network (CTAN) at \url{http://www.ctan.org/}.
As for learning \TeX, many useful resources are available both online
and in print. Among online guides, Tony Roberts' ``\LaTeX: from quick
and dirty to style and finesse'' is very helpful, at
\url{http://www.sci.usq.edu.au/staff/robertsa/LaTeX/latexintro.html}
An excellent source for advanced material is \emph{The \LaTeX\
Companion} (Goossens \textit{et al.}, 2004).
%%% Local Variables:
%%% mode: latex
%%% TeX-master: "gretl-guide"
%%% End:
