doc/tex/gretltex.tex

\chapter{Gretl and \TeX}
\label{chap: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.  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 gretl's \TeX-related
functionality.  The next section describes the relevant menu items;
section~\ref{tex-tune} discusses ways of fine-tuning \TeX\ output; 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 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, 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 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.  gretl does
  not support plain \TeX.} (In times gone by it was a program called
\app{latex} that generated so-called DVI (device-independent) output.)

So gretl calls \app{pdflatex} to process the source file. On MS
Windows and Mac OS X, gretl expects the operating system to find the
default viewer for PDF output. On GNU/Linux you can specify your
preferred PDF viewer via the menu item ``Tools, Preferences,
General,'' under the ``Programs'' tab.

\section{\TeX-related menu items}
\label{tex-menus}

\subsection{The model window}

The fullest \TeX\ support in 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 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 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 gretl in \LaTeX\ preview mode; adjusting the
formatting of gretl's tabular output for models when using the
\texttt{tabprint} command; and incorporating gretl's output into
your own \TeX\ files.


\subsection{Previewing in the GUI}

As regards \emph{preview mode}, you can control the appearance of
gretl's output using a file named \verb+gretlpre.tex+, which
should be placed in your 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[utf8]{inputenc}
\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.

In addition, if you wish to typeset 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 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 gretl
  user directory.  If this is not found, then
\item look for a file named \verb|gretlpre.tex| in the gretl
  user directory.  If this is not found, then
\item use the default preamble.
\end{enumerate}

Conversely, suppose you usually run 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 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 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 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 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 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{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} \citep{goossens04}.


%%% Local Variables:
%%% mode: latex
%%% TeX-master: "gretl-guide"
%%% End: