\chapter{Getting started}
\label{getting-started}


\section{Let's run a regression}
\label{starting-regression}

This introduction is mostly angled towards the graphical client
program; please see Chapter~\ref{cli} below and the \GCR\ for details
on the command-line program, \app{gretlcli}.
    
You can supply the name of a data file to open as an argument to
gretl, but for the moment let's not do that: just fire up the
program.\footnote{For convenience we refer to the graphical client
  program simply as gretl in this manual. Note, however, that
  the specific name of the program differs according to the computer
  platform.  On Linux it is called \verb+gretl_x11+ while on MS
  Windows it is \verb+gretl.exe+. On Linux systems a wrapper script
  named \verb+gretl+ is also installed --- see also the \GCR.}  You
should see a main window (which will hold information on the data set
but which is at first blank) and various menus, some of them disabled
at first.
    
What can you do at this point?  You can browse the supplied data files
(or databases), open a data file, create a new data file, read the
help items, or open a command script.  For now let's browse the
supplied data files.  Under the File menu choose ``Open data, Sample
file''.  A second notebook-type window will open, presenting the sets
of data files supplied with the package (see
Figure~\ref{fig-datafiles}).  Select the first tab, ``Ramanathan''.
The numbering of the files in this section corresponds to the chapter
organization of \cite{ramanathan02}, which contains discussion of the
analysis of these data. The data will be useful for practice purposes
even without the text.
    
\begin{figure}[htbp]
  \begin{center}
    \includegraphics[scale=0.5]{figures/datafiles}
  \end{center}
  \caption{Practice data files window}
  \label{fig-datafiles}
\end{figure}

If you select a row in this window and click on ``Info'' this opens a
window showing information on the data set in question (for example,
on the sources and definitions of the variables).  If you find a file
that is of interest, you may open it by clicking on ``Open'', or just
double-clicking on the file name. For the moment let's open
\verb+data3-6+.  

\tip{In gretl windows containing lists, double-clicking on a
  line launches a default action for the associated list entry: e.g.\
  displaying the values of a data series, opening a file.}

This file contains data pertaining to a classic
econometric ``chestnut'', the consumption function.  The data window
should now display the name of the current data file, the overall data
range and sample range, and the names of the variables along with
brief descriptive tags---see Figure~\ref{fig-mainwin}.
    
\begin{figure}[htbp]
  \begin{center}
    \includegraphics[scale=0.5]{figures/mainwin}
  \end{center}
  \caption{Main window, with a practice data file open}
  \label{fig-mainwin}
\end{figure}

OK, what can we do now?  Hopefully the various menu options should be
fairly self explanatory.  For now we'll dip into the Model menu; a
brief tour of all the main window menus is given in
Section~\ref{menus} below.
    
Gretl's Model menu offers numerous various econometric estimation
routines.  The simplest and most standard is Ordinary Least Squares
(OLS). Selecting OLS pops up a dialog box calling for a \emph{model
  specification}---see Figure~\ref{fig-selector}.
    
\begin{figure}[htbp]
  \begin{center}
    \includegraphics[scale=0.5]{figures/selector}
  \end{center}
  \caption{Model specification dialog}
  \label{fig-selector}
\end{figure}

To select the dependent variable, highlight the variable you want in
the list on the left and click the arrow that points to the Dependent
variable slot.  If you check the ``Set as default'' box this variable
will be pre-selected as dependent when you next open the model dialog
box. Shortcut: double-clicking on a variable on the left selects it as
dependent and also sets it as the default. To select independent
variables, highlight them on the left and click the green arrow (or
right-click the highlighted variable); to remove variables from the
selected list, use the rad arrow.  To select several variable in
the list box, drag the mouse over them; to select several
non-contiguous variables, hold down the \verb+Ctrl+ key and click on
the variables you want.  To run a regression with consumption as the
dependent variable and income as independent, click \verb+Ct+ into the
Dependent slot and add \verb+Yt+ to the Independent variables list.


\section{Estimation output}
\label{est-output}

Once you've specified a model, a window displaying the regression
output will appear.  The output is reasonably comprehensive and in a
standard format (Figure~\ref{fig-modelwin}).
    
\begin{figure}[htbp]
  \begin{center}
    \includegraphics[scale=0.5]{figures/modelwin}
  \end{center}
  \caption{Model output window}
  \label{fig-modelwin}
\end{figure}

The output window contains menus that allow you to inspect or graph
the residuals and fitted values, and to run various diagnostic tests
on the model. 

For most models there is also an option to print the regression
output in {\LaTeX} format.  See Chapter~\ref{gretltex} for details.

To import gretl output into a word processor, you may copy and
paste from an output window, using its \textsf{Edit} menu (or Copy
button, in some contexts) to the target program.  Many (not all)
gretl windows offer the option of copying in RTF (Microsoft's
``Rich Text Format'') or as {\LaTeX}. If you are pasting into a word
processor, RTF may be a good option because the tabular formatting of
the output is preserved.\footnote{Note that when you copy as RTF under
  MS Windows, Windows will only allow you to paste the material into
  applications that ``understand'' RTF.  Thus you will be able to
  paste into MS Word, but not into notepad.  Note also that there
  appears to be a bug in some versions of Windows, whereby the paste
  will not work properly unless the ``target'' application (e.g.\  MS
  Word) is already running prior to copying the material in question.}
Alternatively, you can save the output to a (plain text) file then
import the file into the target program.  When you finish a
gretl session you are given the option of saving all the output
from the session to a single file.

 Note that on the \app{gnome} desktop and under MS Windows, the
 \textsf{File} menu includes a command to send the output directly to
 a printer.

 \tip{When pasting or importing plain text gretl output into a
   word processor, select a monospaced or typewriter-style font (e.g.\
   Courier) to preserve the output's tabular formatting.  Select a
   small font (10-point Courier should do) to prevent the output lines
   from being broken in the wrong place.}

\section{The main window menus}
\label{menus}

Reading left to right along the main window's menu bar, we find the
File, Tools, Data, View, Add, Sample, Variable, Model and Help menus.

\begin{center}
  \includegraphics[scale=0.75]{figures/menubar}
\end{center}

\begin{itemize}
\item \textsf{File menu}
  \begin{itemize}
  \item \textsf{Open data}: Open a native gretl data file or
    import from other formats.  See Chapter~\ref{datafiles}.
  \item \textsf{Append data}: Add data to the current working data
    set, from a gretl data file, a comma-separated values file
    or a spreadsheet file.
  \item \textsf{Save data}: Save the currently open native gretl
    data file.
  \item \textsf{Save data as}: Write out the current data set in
    native format, with the option of using gzip data compression. See
    Chapter~\ref{datafiles}.
  \item \textsf{Export data}: Write out the current data set in Comma
    Separated Values (CSV) format, or the formats of GNU R or GNU
    Octave. See Chapter~\ref{datafiles} and also
    Appendix~\ref{app-advanced}.
  \item \textsf{Send to}: Send the current data set as an e-mail
    attachment.
  \item \textsf{New data set}: Allows you to create a blank data set,
    ready for typing in values or for importing series from a
    database.  See below for more on databases.
  \item \textsf{Clear data set}: Clear the current data set out of
    memory.  Generally you don't have to do this (since opening a new
    data file automatically clears the old one) but sometimes it's
    useful.
  \item \textsf{Script files}: A ``script'' is a file containing a
    sequence of gretl commands.  This item contains entries
    that let you open a script you have created previously (``User
    file''), open a sample script, or open an editor window in which
    you can create a new script.
  \item \textsf{Session files}: A ``session'' file contains a snapshot
    of a previous gretl session, including the data set used
    and any models or graphs that you saved.  Under this item you
    can open a saved session or save the current session.
  \item \textsf{Databases}: Allows you to browse various large
    databases, either on your own computer or, if you are connected
    to the internet, on the gretl database server.  See
    Section~\ref{dbase} for details.
  \item \textsf{Function files}: Handles ``function packages'' (see
    Section~\ref{sec:func-packages}), which allow you to access
    functions written by other users and share the ones written by
    you.
  \item \textsf{Exit}: Quit the program.  You'll be prompted to save
    any unsaved work.
  \end{itemize}

\item \textsf{Tools menu}
  \begin{itemize}
  \item \textsf{Statistical tables}: Look up critical values for
    commonly used distributions (normal or Gaussian, \emph{t},
    chi-square, \emph{F} and Durbin--Watson).
  \item \textsf{P-value finder}: Look up p-values from the Gaussian,
    \emph{t}, chi-square, \emph{F}, gamma, binomial or Poisson
    distributions. See also the \cmd{pvalue} command in the \GCR.
  \item \textsf{Distribution graphs}: Produce graphs of various
    probability distributions.  In the resulting graph window,
    the pop-up menu includes an item ``Add another curve'', which
    enables you to superimpose a further plot (for example, you
    can draw the \emph{t} distribution with various different degrees
    of freedom).
  \item \textsf{Test statistic calculator}: Calculate test statistics
    and p-values for a range of common hypothesis tests (population
    mean, variance and proportion; difference of means, variances and
    proportions).  
  \item \textsf{Nonparametric tests}: Calculate test statistics
    for various nonparametric tests (Sign test, Wilcoxon rank sum
    test, Wilcoxon signed rank test, Runs test).
  \item \textsf{Seed for random numbers}: Set the seed for the random
    number generator (by default this is set based on the system time
    when the program is started).
  \item \textsf{Command log}: Open a window containing a record
    of the commands executed so far.
  \item \textsf{Gretl console}: Open a ``console'' window into which
    you can type commands as you would using the command-line program,
    \app{gretlcli} (as opposed to using point-and-click).
  \item \textsf{Start Gnu R}: Start \app{R} (if it is installed on
    your system), and load a copy of the data set currently open in
    gretl.  See Appendix~\ref{app-advanced}.
  \item \textsf{Sort variables}: Rearrange the listing of variables in
    the main window, either by ID number or alphabetically by name.
  \item \textsf{NIST test suite}: Check the numerical accuracy of
    gretl against the reference results for linear regression
    made available by the (US) National Institute of Standards and
    Technology.
  \item \textsf{Preferences}: Set the paths to various files
    gretl needs to access. Choose the font in which gretl
    displays text output.  Activate or suppress gretl's
    messaging about the availability of program updates, and so on.
    See the \GCR\ for further details.
  \end{itemize}

\item \textsf{Data menu}
  \begin{itemize}
  \item \textsf{Select all}: Several menu items act upon those
    variables that are currently selected in the main window.  This
    item lets you select all the variables.
  \item \textsf{Display values}: Pops up a window with a simple (not
    editable) printout of the values of the selected variable or
    variables.
  \item \textsf{Edit values}: Opens a spreadsheet window where you
    can edit the values of the selected variables. 
  \item \textsf{Add observations}: Gives a dialog box in which you can
    choose a number of observations to add at the end of the current
    dataset; for use with forecasting.
  \item \textsf{Remove extra observations}: Active only if extra
    observations have been added automatically in the process of
    forecasting; deletes these extra observations.
  \item \textsf{Read info}, \textsf{Edit info}: ``Read info'' just
    displays the summary information for the current data file; ``Edit
    info'' allows you to make changes to it (if you have permission to
    do so).
  \item \textsf{Print description}: Opens a window containing a full
    account of the current dataset, including the summary information
    and any specific information on each of the variables.
  \item \textsf{Add case markers}: Prompts for the name of a text file
    containing ``case markers'' (short strings identifying the
    individual observations) and adds this information to the data
    set. See Chapter~\ref{datafiles}.
  \item \textsf{Remove case markers}: Active only if the dataset has
    case markers identifying the observations; removes these case
    markers.
  \item \textsf{Dataset structure}: invokes a series of dialog boxes
    which allow you to change the structural interpretation of the
    current dataset.  For example, if data were read in as a cross
    section you can get the program to interpret them as time series
    or as a panel.  See also section~\ref{sec:data-structure}.
  \item \textsf{Compact data}: For time-series data of higher than
    annual frequency, gives you the option of compacting the data to a
    lower frequency, using one of four compaction methods (average,
    sum, start of period or end of period).
  \item \textsf{Expand data}: For time-series data, gives you the
    option of expanding the data to a higher frequency.
  \item \textsf{Transpose data}: Turn each observation into a variable
    and vice versa (or in other words, each row of the data matrix
    becomes a column in the modified data matrix); can be useful with
    imported data that have been read in ``sideways''.
  \end{itemize}

\item \textsf{View menu} 
  \begin{itemize}
  \item \textsf{Icon view}: Opens a window showing the content of
    the current session as a set of icons; see section~\ref{session}.
  \item \textsf{Graph specified vars}: Gives a choice between a time
    series plot, a regular X--Y scatter plot, an X--Y plot using
    impulses (vertical bars), an X--Y plot ``with factor separation''
    (i.e.\ with the points colored differently depending to the value
    of a given dummy variable), boxplots, and a 3-D graph. Serves up a
    dialog box where you specify the variables to graph. See
    Chapter~\ref{chap-graphs} for details.
  \item \textsf{Multiple graphs}: Allows you to compose a set of up to
    six small graphs, either pairwise scatter-plots or time-series
    graphs.  These are displayed together in a single window.
  \item \textsf{Summary statistics}: Shows a full set of
    descriptive statistics for the variables selected in the main
    window.
  \item \textsf{Correlation matrix}: Shows the pairwise correlation
    coefficients for the selected variables.
  \item \textsf{Cross Tabulation}: Shows a cross-tabulation of the
    selected variables.  This works only if at least two variables
    in the data set have been marked as discrete (see
    Chapter~\ref{chap:discrete}).  
  \item \textsf{Principal components}: Produces a Principal Components
    Analysis for the selected variables.
  \item \textsf{Mahalanobis distances}: Computes the Mahalanobis
    distance of each observation from the centroid of the selected set
    of variables.
  \item \textsf{Cross-correlogram}: Computes and graphs the
    cross-correlogram for two selected variables.
  \end{itemize}

\item \textsf{Add menu} Offers various standard transformations
  of variables (logs, lags, squares, etc.) that you may wish to add to
  the data set. Also gives the option of adding random variables, and
  (for time-series data) adding seasonal dummy variables (e.g.\
  quarterly dummy variables for quarterly data).

\item \textsf{Sample menu}
  \begin{itemize}
  \item \textsf{Set range}: Select a different starting and/or ending
    point for the current sample, within the range of data available.
  \item \textsf{Restore full range}: self-explanatory.
  \item \textsf{Define, based on dummy}: Given a dummy (indicator)
    variable with values 0 or 1, this drops from the current sample
    all observations for which the dummy variable has value 0.
  \item \textsf{Restrict, based on criterion}: Similar to the item
    above, except that you don't need a pre-defined variable: you
    supply a Boolean expression (e.g.\ \verb+sqft > 1400+) and the
    sample is restricted to observations satisfying that condition.
    See the entry for \cmd{genr} in the \GCR\
    for details on the Boolean operators that can be used.
  \item \textsf{Random sub-sample}: Draw a random sample from the full dataset.
  \item \textsf{Drop all obs with missing values}: Drop from the
    current sample all observations for which at least one variable
    has a missing value (see Section~\ref{missing-data}).
  \item \textsf{Count missing values}: Give a report on observations
    where data values are missing. May be useful in examining a panel
    data set, where it's quite common to encounter missing values.
  \item \textsf{Set missing value code}: Set a numerical value that
    will be interpreted as ``missing'' or ``not available''.  This is
    intended for use with imported data, when gretl has not
    recognized the missing-value code used.
  \end{itemize}

\item \textsf{Variable menu} Most items under here operate on a single
  variable at a time.  The ``active'' variable is set by highlighting
  it (clicking on its row) in the main data window.  Most options will
  be self-explanatory.  Note that you can rename a variable and can
  edit its descriptive label under ``Edit attributes''. You can also
  ``Define a new variable'' via a formula (e.g.\ involving some
  function of one or more existing variables). For the syntax of such
  formulae, look at the online help for ``Generate variable syntax''
  or see the \cmd{genr} command in the \GCR.
  One simple example:
          
\begin{code} 
foo = x1 * x2
\end{code}

  will create a new variable \verb+foo+ as the product of the existing
  variables \verb+x1+ and \verb+x2+.  In these formulae, variables
  must be referenced by name, not number.

\item \textsf{Model menu} For details on the various estimators
  offered under this menu please consult the \GCR.  Also see
  Chapter~\ref{chap-nls} regarding the estimation of nonlinear models.

\item \textsf{Help menu} Please use this as needed! It gives details
  on the syntax required in various dialog entries.
\end{itemize}


\section{Keyboard shortcuts}
\label{keyb-accel}

When working in the main gretl window, some common operations
may be performed using the keyboard, as shown in the table below.

\begin{center}
\begin{tabular}{lp{5in}}
  \texttt{Return} & Opens a window displaying the values of the currently
  selected variables: it is the same as selecting ``Data, Display
  Values''. \\
  \texttt{Delete} & Pressing this key has the effect of deleting the
  selected variables. A confirmation is required, to prevent
  accidental deletions. \\
  \texttt{e} & Has the same effect as selecting ``Edit
  attributes'' from the ``Variable'' menu. \\
  \texttt{F2} & Same as ``e''. Included for compatibility with other
  programs.\\
  \texttt{g} & Has the same effect as selecting ``Define new
  variable'' from the ``Variable'' menu (which maps onto the
  \texttt{genr} command).\\
  \texttt{h} & Opens a help window for gretl commands.\\
  \texttt{F1} & Same as ``h''. Included for compatibility with other
  programs.\\
  \texttt{r} & Refreshes the variable list in the main window. \\
  \texttt{t} & Graphs the selected variable; a line graph is used for
  time-series datasets, whereas a distribution plot is used for
  cross-sectional data. 
\end{tabular}
\end{center}

\section{The gretl toolbar}
\label{toolbar}

At the bottom left of the main window sits the toolbar.

\begin{center}
  \includegraphics[scale=0.75]{figures/toolbar}
\end{center}

The icons have the following functions, reading from left to right:

\begin{enumerate}
\item Launch a calculator program.  A convenience function in case you
  want quick access to a calculator when you're working in
  gretl.  The default program is \verb+calc.exe+ under MS
  Windows, or \verb+xcalc+ under the X window system.  You can change
  the program under the ``Tools, Preferences, General'' menu,
  ``Programs'' tab.
\item Start a new script.  Opens an editor window in which you can
  type a series of commands to be sent to the program as a batch.
\item Open the gretl console.  A shortcut to the ``Gretl console''
  menu item (Section~\ref{menus} above).
\item Open the session icon window.
\item Open a window displaying available gretl function packages.
\item Open this manual in PDF format.
\item Open the help item for script commands syntax (i.e.\ a listing
  with details of all available commands).
\item Open the dialog box for defining a graph.
\item Open the dialog box for estimating a model using ordinary least
  squares.
\item Open a window listing the sample datasets supplied with
  gretl, and any other data file collections that have been
  installed.
\end{enumerate}

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

