# Getting started

## Let's run a regression

This introduction is mostly angled towards the graphical client program; please see and below for details on the command-line program, 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. For convenience I will 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 `gretl_x11` while on MS Windows it is `gretlw32.exe`. On Linux systems a wrapper script named `gretl` is also installed — see also . 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, Ramanathan…. A second window should open, presenting a list of data files supplied with the package (see ). The numbering of the files 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.

### Practice data files window

Practice data files window

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 `data3-6`.

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 .

### Main window, with a practice data file open

Main window

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 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 model specification — see .

### Model specification dialog

Model specification dialog

To select the dependent variable, highlight the variable you want in the list on the left and click the Choose button 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 Add button (or click the right mouse button over the highlighted variable). To select several variable in the list box, drag the mouse over them; to select several non-contiguous variables, hold down the `Ctrl` key and click on the variables you want.

To run a regression with consumption as the dependent variable and income as independent, click `Ct` into the Dependent slot and add `Yt` to the Independent variables list.

## Estimation 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 ().

### Model output window

Model window

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 reprint the regression output in &latex; format. You can print the results in a tabular format (similar to what's in the output window, but properly typeset) or as an equation, across the page. For each of these options you can choose to preview the typeset product, or save the output to file for incorporation in a &latex; document. Previewing requires that you have a functioning &tex; system on your computer. You can control the appearance of gretl's &latex; output using a file named `gretlpre.tex`, which should be placed in your gretl user directory (see ). If a file of this name is found, its contents will be used as the &latex; preamble. The default value of the preamble is as follows:

          \documentclass[11pt]{article}
          \usepackage[latin1]{inputenc}
          \usepackage{amsmath}
          \usepackage{dcolumn,longtable}
          \begin{document}
          \thispagestyle{empty}

Note that the `amsmath` and `dcolumn` packages are required.

To import gretl output into a word processor, you may copy and paste from an output window, using its 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. 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 gnome desktop and under MS Windows, the File menu includes a command to send the output directly to a printer.

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.

## The main window menus

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

- File menu

  - Open data: Open a native gretl data file or import from other formats. See .

  - Append data: Add data to the current working data set, from a gretl data file, a comma-separated values file or a spreadsheet file.

  - Save data: Save the currently open native gretl data file.

  - Save data as: Write out the current data set in native format, with the option of using gzip data compression. See .

  - Export data: Write out the current data set in Comma Separated Values (CSV) format, or the formats of GNU R or GNU Octave. See and also .

  - 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 (see ).

  - Browse databases: See and .

  - Create data set: Initialize the built-in spreadsheet for entering data manually. See .

  - View command log: Open a window containing a record of the commands executed so far.

  - Open command file: Open a file of gretl commands, either one you have created yourself or one of the practice files supplied with the package. If you want to create a command file from scratch use the next item, New command file.

  - Preferences: Set the paths to various files gretl needs to access. Choose the font in which gretl displays text output. Select or unselect expert mode. (If this mode is selected various warning messages are suppressed.) Activate or suppress gretl's messaging about the availability of program updates. Configure or turn on/off the main-window toolbar. See for details.

  - Exit: Quit the program. If expert mode is not selected you'll be prompted to save any unsaved work.

- Utilities menu

  - Statistical tables: Look up critical values for commonly used distributions (normal or Gaussian, t, chi-square, F and Durbin–Watson).

  - p-value finder: Open a window which enables you to look up p-values from the Gaussian, t, chi-square, F or gamma distributions. See also the `pvalue` command in .

  - 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). The relevant sample statistics must be already available for entry into the dialog box. For some simple tests that take as input data series rather than pre-computed sample statistics, see Difference of means and Difference of variances under the Data menu.

  - Gretl console: Open a console window into which you can type commands as you would using the command-line program, gretlcli (as opposed to using point-and-click). See .

  - Start Gnu R: Start R (if it is installed on your system), and load a copy of the data set currently open in gretl. See .

  - 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.

- Session menu

  - Icon view: Open a window showing the current gretl session as a set of icons. For details see .

  - Open: Open a previously saved session file.

  - Save: Save the current session to file.

  - Save as: Save the current session to file under a chosen name.

- Data menu

  - Display values: Pops up a window with a simple (not editable) printout of the values of the variables (either all of them or a selected subset).

  - Edit values: Pops up a spreadsheet window where you can make changes, add new variables, and extend the number of observations.

  - Sort variables: Rearrange the listing of variables in the main window, either by ID number or alphabetically by name.

  - 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 for details.

  - Multiple scatterplots: Show a collection of (at most six) pairwise plots, with either a given variable on the y axis plotted against several different variables on the x axis, or several y variables plotted against a given x. May be useful for exploratory data analysis.

  - Read info, 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).

  - 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.

  - Summary statistics: Shows a fairly full set of descriptive statistics for all variables in the data set, or for selected variables.

  - Correlation matrix: Shows the pairwise correlation coefficients for all variables in the data set, or selected variables

  - Principal components: Active only if two or more variables are selected; produces a Principal Components Analysis of the selected variables.

  - Mahalonobis distances: Active only if two or more variables are selected; computes the Mahalonobis distance of each observation from the centroid of the selected set of variables.

  - Difference of means: Calculates the t statistic for the null hypothesis that the population means are equal for two selected variables and shows its p-value.

  - Difference of variances: Calculates the F statistic for the null hypothesis that the population variances are equal for two selected variables and shows its p-value.

  - Add variables: Gives a sub-menu of 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). Includes an item for seeding the program's pseudo-random number generator.

  - 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.

  - Remove extra observations: Active only if extra observations have been added automatically in the process of forecasting; deletes these extra observations.

  - Refresh window: Sometimes gretl commands generate new variables. The refresh item ensures that the listing of variables visible in the main data window is in sync with the program's internal state.

- Sample menu

  - Set range: Select a different starting and/or ending point for the current sample, within the range of data available.

  - Restore full range: self-explanatory.

  - 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 .

  - 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).

  - 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.

  - 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. `sqft > 1400`) and the sample is restricted to observations satisfying that condition. See the help for `genr` in for details on the Boolean operators that can be used.

  - Drop all obs with missing values: Drop from the current sample all observations for which at least one variable has a missing value (see ).

  - 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.

  - Set missing value code: Set a numerical value that will be interpreted as missing or not available.

  - 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 .

  - Remove case markers: Active only if the dataset has case markers indentifying the observations; removes these case markers.

  - Restructure panel: Allows the conversion of a panel data set in stacked cross-section form into stacked time series or vice versa. (Unlike the Dataset structure menu item above, this one actually changes the organization of the data.)

  - 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.

- 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 `genr` command in . One simple example:

      	    foo = x1 * x2

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

- Model menu For details on the various estimators offered under this menu please consult and below, and/or the online help under Help, Estimation. Also see regarding the estimation of nonlinear models.

- Help menu Please use this as needed! It gives details on the syntax required in various dialog entries.

## The gretl toolbar

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

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

1. 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 `calc.exe` under MS Windows, or `xcalc` under the X window system. You can change the program under the File, Preferences, General menu, Programs tab.

2. 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.

3. Open the gretl console. A shortcut to the Gretl console menu item ( above).

4. Open the gretl session window.

5. Open the gretl website in your web browser. This will work only if you are connected to the Internet and have a properly configured browser.

6. Open the current version of this manual, in PDF format. As with the previous item, this requires an Internet connection; it also requires that your browser knows how to handle PDF files.

7. Open the help item for script commands syntax (i.e. a listing with details of all available commands).

8. Open the dialog box for defining a graph.

9. Open the dialog box for estimating a model using ordinary least squares.

10. Open a window listing the datasets associated with Ramanathan's Introductory Econometrics (and also the datasets from Jeffrey Wooldridge's text, if these are installed — see ).

If you don't care to have the toolbar displayed, you can turn it off under the File, Preferences, General menu. Go to the Toolbar tab and uncheck the show gretl toolbar box.