\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 \app{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 \app{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+gretlw32.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 Ramanathan (2002), 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 \app{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. \app{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 \app{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) \app{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 \app{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 \app{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 \app{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 \app{gretl} data file, a comma-separated values file or a spreadsheet file. \item \textsf{Save data}: Save the currently open native \app{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 \app{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 \app{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 \app{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 \app{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 \app{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 \app{gretl} needs to access. Choose the font in which gretl displays text output. Activate or suppress \app{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{Mahalonobis distances}: Computes the Mahalonobis 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 \app{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 \app{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: has the same effect as selecting ``Refresh window'' from the ``Data'' menu. \\ \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 \app{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 \app{gretl} 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 \app{gretl}, and any other data file collections that have been installed. \end{enumerate} %%% Local Variables: %%% mode: latex %%% TeX-master: "gretl-guide" %%% End: