Gretl Command Reference

See also the Gretl Function Reference.

The following commands are documented below.

Note that brackets "[" and "]" are used to indicate that certain elements of commands are optional. The brackets should not be typed by the user.

add

Must be invoked after an estimation command. Performs a joint test for the addition of the specified variables to the last model, the results of which may be retrieved using the accessors $test and $pvalue.

By default an augmented version of the original model is estimated, including the variables in varlist. The test is a Wald test on the augmented model, which replaces the original as the "current model" for the purposes of, for example, retrieving the residuals as $uhat or doing further tests.

Alternatively, given the --lm option (available only for the models estimated via OLS), an LM test is performed. An auxiliary regression is run in which the dependent variable is the residual from the last model and the independent variables are those from the last model plus varlist. Under the null hypothesis that the added variables have no additional explanatory power, the sample size times the unadjusted R-squared from this regression is distributed as chi-square with degrees of freedom equal to the number of added regressors. In this case the original model is not replaced.

The --both option is specific to two-stage least squares: it specifies that the new variables should be added both to the list of regressors and the list of instruments, the default in this case being to add to the regressors only.

Menu path: Model window, /Tests/Add variables

adf

The --gls option can be used in conjunction with one or other of the flags --c and --ct. The effect of this option is that the series to be tested is demeaned or detrended using the GLS procedure proposed by Elliott, Rothenberg and Stock (1996), which gives a test of greater power than the standard Dickey–Fuller approach. This option is not compatible with --nc, --ctt or --seasonals.

In all cases the dependent variable in the test regression is the first difference of the specified series, y, and the key independent variable is the first lag of y. The regression is constructed such that the coefficient on lagged y equals the root in question, α, minus 1. For example, the model with a constant may be written as

Under the null hypothesis of a unit root the coefficient on lagged y equals zero. Under the alternative that y is stationary this coefficient is negative. So the test is inherently one-sided.

Selecting the lag order

The simplest version of the Dickey–Fuller test assumes that the error term in the test regression is serially uncorrelated. In practice this is unlikely to be the case and the specification is often extended by including one or more lags of the dependent variable, giving an Augmented Dickey–Fuller (ADF) test. The order argument governs the number of such lags, k, possibly depending on the sample size, T.

• For a fixed, user-specified k: give a non-negative value for order.

• For T-dependent k: give order as –1. The order is then set following the recommendation of Schwert (1989), namely the integer part of 12(T/100)^0.25.

In general, however, we don't know how many lags will be required to "whiten" the Dickey–Fuller residual. It's therefore common to specify the maximum value of k and let the data decide the actual number of lags to include. This can be done via the --test-down option. The criterion for selecting optimal k may be set using the parameter to this option, which should be one of AIC, BIC or tstat, AIC being the default.

When testing down via AIC or BIC, the final lag order for the ADF equation is that which optimizes the chosen information criterion (Akaike or Schwarz Bayesian). The exact procedure depends on whether or not the --gls option is given. When GLS is specified, AIC and BIC are the "modified" versions described in Ng and Perron (2001), otherwise they are the standard versions. In the GLS case a refinement is available. If the additional option --perron-qu is given, lag-order selection is performed via the revised method recommended by Perron and Qu (2007). In this case the data are first demeaned or detrended via OLS; GLS is applied once the lag order is determined.

When testing down via the t-statistic method is called for, the procedure is as follows:

1. Estimate the Dickey–Fuller regression with k lags of the dependent variable.

2. Is the last lag significant? If so, execute the test with lag order k. Otherwise, let k = k – 1; if k equals 0, execute the test with lag order 0, else go to step 1.

In the context of step 2 above, "significant" means that the t-statistic for the last lag has an asymptotic two-sided p-value, against the normal distribution, of 0.10 or less.

To sum up, if we accept the various arguments of Perron, Ng, Qu and Schwert referenced above, the favored command for testing a series y is likely to be:

	adf -1 y --c --gls --test-down --perron-qu

(Or substitute --ct for --c if the series seems to display a trend.) The lag order for the test will then be determined by testing down via modified AIC from the Schwert maximum, with the Perron–Qu refinement.

P-values for the Dickey–Fuller tests are based on response-surface estimates. When GLS is not applied these are taken from MacKinnon (1996). Otherwise they are taken from Cottrell (2015) or, when testing down is performed, Sephton (2021). The P-values are specific to the sample size unless they are labeled as asymptotic.

Panel data

When the adf command is used with panel data, to produce a panel unit root test, the applicable options and the results shown are somewhat different.

First, while you may give a list of variables for testing in the regular time-series case, with panel data only one variable may be tested per command. Second, the options governing the inclusion of deterministic terms become mutually exclusive: you must choose between no-constant, constant only, and constant plus trend; the default is constant only. In addition, the --seasonals option is not available. Third, the --verbose option has a different meaning: it produces a brief account of the test for each individual time series (the default being to show only the overall result).

The overall test (null hypothesis: the series in question has a unit root for all the panel units) is calculated in one or both of two ways: using the method of Im, Pesaran and Shin (Journal of Econometrics, 2003) or that of Choi (Journal of International Money and Finance, 2001). The Choi test requires that P-values are available for the individual tests; if this is not the case (depending on the options selected) it is omitted. The particular statistic given for the Im, Pesaran, Shin test varies as follows: if the lag order for the test is non-zero their W statistic is shown; otherwise if the time-series lengths differ by individual, their Z statistic; otherwise their t-bar statistic. See also the levinlin command.

Menu path: /Variable/Unit root tests/Augmented Dickey-Fuller test

anova

Unless the --quiet option is given, this command prints a table showing the sums of squares and mean squares along with an F-test. The F-test and its p-value can be retrieved using the accessors $test and $pvalue respectively.

The null hypothesis for the F-test is that the mean response is invariant with respect to the treatment type, or in words that the treatment has no effect. Strictly speaking, the test is valid only if the variance of the response is the same for all treatment types.

Note that the results shown by this command are in fact a subset of the information given by the following procedure, which is easily implemented in gretl. Create a set of dummy variables coding for all but one of the treatment types. For two-way ANOVA, in addition create a set of dummies coding for all but one of the "blocks". Then regress response on a constant and the dummies using ols. For a one-way design the ANOVA table is printed via the --anova option to ols. In the two-way case the relevant F-test is found by using the omit command. For example (assuming y is the response, xt codes for the treatment, and xb codes for blocks):

	# one-way
	list dxt = dummify(xt)
	ols y 0 dxt --anova
	# two-way
	list dxb = dummify(xb)
	ols y 0 dxt dxb
	# test joint significance of dxt
	omit dxt --quiet

Menu path: /Model/Other linear models/ANOVA

append

Opens a data file and appends the content to the current dataset, if the new data are compatible. The program will try to detect the format of the data file (native, plain text, CSV, Gnumeric, Excel, etc.). Please note that the join command offers much more control over the matching of supplementary data to the current dataset. Also note that appending data to an existing panel dataset is potentially quite tricky; see the section headed "Panel data" below.

The appended data may take the form of either additional observations on series already present in the dataset, and/or new series. In the case of adding series, compatibility requires either (a) that the number of observations for the new data equals that for the current data, or (b) that the new data carries clear observation information so that gretl can work out how to place the values. Note that if there's a "perfect match" of observation information (that is, conditions (a) and (b) are both satisfied), it is assumed that series, rather than observations, are to be added. And if it happens that there are no series names in the file whose data are to be appended that are not already present in the current dataset then nothing is done, and a warning is shown.

One case that is not supported is where the new data start earlier and also end later than the original data. To add new series in such a case you can use the --fixed-sample option; this has the effect of suppressing the adding of observations, and so restricting the operation to the addition of new series.

When a data file is selected for appending, there may be an area of overlap with the existing dataset; that is, one or more series may have one or more observations in common across the two sources. If the option --update-overlap is given, the append operation will replace any overlapping observations with the values from the selected data file, otherwise the values currently in place will be unaffected.

The additional specialized options --sheet, --coloffset, --rowoffset and --fixed-cols work in the same way as with open; see that command for explanations.

By default some information about the appended dataset is printed. The --quiet option reduces that printout to a confirmatory message stating just the path to the file. If you want the operation to be completely silent, then issue the command set verbose off before appending the data, in combination with the --quiet option.

Panel data

When new data are appended to a panel dataset, the result will be correct only if both the "units" or "individuals" and the time-periods are properly matched.

Two relatively simple cases should be handled correctly by append. Let n denote the number of cross-sectional units and T denote the number of time periods in the current panel, and let m denote the number of observations for the new data. If m = n the new data are taken to be time-invariant, and are copied into place for each time period. On the other hand, if m = T the data are treated as invariant across the panel units, and are copied into place for each unit. If T = n an ambiguity arises. In that case the new data are treated as time-invariant by default, but you can force gretl to treat them as time series (invariant across the units) via the --time-series option.

If both the current dataset and the incoming data are recognized as panel data two cases arise. (1) The time-series length, T, differs between the two. Then an error is flagged. (2) T matches. Then a very simple assumption is made, namely that the units match up, starting with the first unit in both datasets. If that assumption is not correct you must use join instead of append.

Menu path: /File/Append data

ar

Computes parameter estimates using the generalized Cochrane–Orcutt iterative procedure; see Section 9.5 of Ramanathan (2002). Iteration is terminated when successive error sums of squares do not differ by more than 0.005 percent or after 20 iterations.

lags is a list of lags in the residuals, terminated by a semicolon. In the above example, the error term is specified as

Menu path: /Model/Univariate time series/AR Errors (GLS)

ar1

The default method is the Cochrane–Orcutt iterative procedure; see for example section 9.4 of Ramanathan (2002). The criterion for convergence is that successive estimates of the autocorrelation coefficient do not differ by more than 1e-6, or if the --loose option is given, by more than 0.001. If this is not achieved within 100 iterations an error is flagged.

If the --pwe option is given, the Prais–Winsten estimator is used. This involves an iteration similar to Cochrane–Orcutt; the difference is that while Cochrane–Orcutt discards the first observation, Prais–Winsten makes use of it. See, for example, Chapter 13 of Greene (2000) for details.

If the --hilu option is given, the Hildreth–Lu search procedure is used. The results are then fine-tuned using the Cochrane–Orcutt method, unless the --no-corc flag is specified. The --no-corc option is ignored for estimators other than Hildreth–Lu.

Menu path: /Model/Univariate time series/AR Errors (GLS)

arch

This command is retained at present for backward compatibility, but you are better off using the maximum likelihood estimator offered by the garch command; for a plain ARCH model, set the first GARCH parameter to 0.

Estimates the given model specification allowing for ARCH (Autoregressive Conditional Heteroskedasticity). The model is first estimated via OLS, then an auxiliary regression is run, in which the squared residual from the first stage is regressed on its own lagged values. The final step is weighted least squares estimation, using as weights the reciprocals of the fitted error variances from the auxiliary regression. (If the predicted variance of any observation in the auxiliary regression is not positive, then the corresponding squared residual is used instead).

The alpha values displayed below the coefficients are the estimated parameters of the ARCH process from the auxiliary regression.

See also garch and modtest (the --arch option).

arima

	arma 2 1 ; y

The default is to use the "native" gretl ARMA functionality, with estimation by exact ML; estimation via conditional ML is available as an option. (If X-12-ARIMA is installed you have the option of using it instead of native code. Note that the newer X13 works as a drop-in replacement in exactly the same way.) For details regarding these options, please see chapter 31 of the Gretl User's Guide.

When native exact ML code is used, estimated standard errors are by default based on a numerical approximation to the (negative inverse of) the Hessian, with a fallback to the outer product of the gradient (OPG) if calculation of the numerical Hessian should fail. Two (mutually exclusive) option flags can be used to force the issue: the --opg option forces use of the OPG method, with no attempt to compute the Hessian, while the --hessian flag disables the fallback to OPG. Note that failure of the numerical Hessian computation is generally an indicator of a misspecified model.

The option --lbfgs is specific to estimation using native ARMA code and exact ML: it calls for use of the "limited memory" L-BFGS-B algorithm in place of the regular BFGS maximizer. This may help in some instances where convergence is difficult to achieve.

The option --y-diff-only is specific to estimation of ARIMAX models (models with a non-zero order of integration and including exogenous regressors), and applies only when gretl's native exact ML is used. For such models the default behavior is to difference both the dependent variable and the regressors, but when this option is specified only the dependent variable is differenced, the regressors remaining in level form.

The AIC value given in connection with ARIMA models is calculated according to the definition used in X-12-ARIMA, namely

where is the log-likelihood and k is the total number of parameters estimated. Note that X-12-ARIMA does not produce information criteria such as AIC when estimation is by conditional ML.

The AR and MA roots shown in connection with ARMA estimation are based on the following representation of an ARMA(p, q) process:

	(1 - a_1*L - a_2*L^2 - ... - a_p*L^p)Y =
          c + (1 + b_1*L + b_2*L^2 + ... + b_q*L^q) e_t

The AR roots are therefore the solutions to

         1 - a_1*z - a_2*z^2 - ... - a_p*L^p = 0

and stability requires that these roots lie outside the unit circle.

The "frequency" figure printed in connection with AR and MA roots is the λ value that solves z = r * exp(i*2*π*λ) where z is the root in question and r is its modulus.

Lag selection

When the --lagselect option is given, this command does not give specific estimates, but instead produces a table showing information criteria and log-likelihood for a number of ARMA or ARIMA specifications. The lag orders p and q are taken as maxima; and if a seasonal specification is provided P and Q are also taken as maxima. In each case the minimum order is taken to be 0, and results are shown for all specifications from mimima to maxima. The degrees of differencing in the command, d and/or D, are respected but not treated as subject to search. A matrix holding the results is available via the $test accessor.

Menu path: /Model/Univariate time series/ARIMA

arma

See arima; arma is an alias.

bds

Performs the BDS (Brock, Dechert, Scheinkman and LeBaron, 1996) test for nonlinearity of the series x. In an econometric context this is typically used to test a regression residual for violation of the IID condition. The test is based on a set of correlation integrals, designed to detect nonlinearity of progressively higher dimensionality, and the order argument sets the number of such integrals. This must be at least 2; the first integral establishes a baseline but does not support a test. The BDS test is of the portmanteau type: able to detect all manner of departures from linearity but not informative about how exactly the condition was violated.

Instead of giving x as a series, the --matrix option can be used to specify a matrix as input. The matrix must be a vector (column or row).

Criterion for closeness

The correlation integrals are based on a measure of "closeness" of data points, where two points are considered close if they lie within ε of each other. The test requires a specification of ε. By default gretl follows the recommendation of Kanzler (1999): ε is chosen such that the first-order correlation integral is around 0.7. A common alternative (requiring less computation) is to specify ε as a multiple of the standard deviation of the target series. The --sdcrit option supports the latter method; in the third example above ε is set to twice the standard deviation of x. The --corr1 option implies use of Kanzler's method but allows for a target correlation other than 0.7. It should be clear that these two options are mutually exclusive.

Bootstrapping

BDS test statistics are asymptotically distributed as N(0,1) but the test over-rejects quite markedly in small to moderate-sized samples. For that reason P-values are by default obtained via bootstrapping when x is of length less than 600 (but by reference to the normal distribution otherwise). If you want to use the bootstrap for larger samples you can force the issue by giving a non-zero value for the --boot option, Conversely, if you don't want bootstrapping for smaller samples, give a zero value for --boot.

When bootstrapping is performed the default number of iterations is 1999, but you can specify a different number by giving a value greater than 1 with --boot.

Accessor matrix

On successful completion of this command, $result retrieves the test results in the form of a matrix with two rows and order – 1 columns. The first row contains test statistics and the second P-values for each of the per-dimension tests under the null that x is linear/IID.

biprobit

bkw

Must follow the estimation of a model which includes at least two independent variables. Calculates and displays diagnostic information pertaining to collinearity, namely the BKW Table, based on the work of Belsley, Kuh and Welsch (1980). This table presents a sophisticated analysis of the degree and sources of collinearity, via eigenanalysis of the inverse correlation matrix. For a thorough account of the BKW approach with reference to gretl, and with several examples, see Adkins, Waters and Hill (2015).

Following this command the $result accessor may be used to retrieve the BKW table as a matrix. See also the vif command for a simpler approach to diagnosing collinearity.

There is also a function named bkw which offers greater flexibility.

Menu path: Model window, /Analysis/Collinearity

boxplot

	boxplot wage gender --factorized

Gretl's boxplots are generated using gnuplot, and it is possible to specify the plot more fully by appending additional gnuplot commands, enclosed in braces. For details, please see the help for the gnuplot command.

In interactive mode the result is displayed immediately. In batch mode the default behavior is that a gnuplot command file is written in the user's working directory, with a name on the pattern gpttmpN.plt, starting with N = 01. The actual plots may be generated later using gnuplot (under MS Windows, wgnuplot). This behavior can be modified by use of the --output=filename option. For details, please see the gnuplot command.

Menu path: /View/Graph specified vars/Boxplots

break

Break out of a loop. This command can be used only within a loop; it causes command execution to break out of the current (innermost) loop. See also loop, continue.

catch

This is not a command in its own right but can be used as a prefix to most regular commands: the effect is to prevent termination of a script if an error occurs in executing the command. If an error does occur, this is registered in an internal error code which can be accessed as $error (a zero value indicates success). The value of $error should always be checked immediately after using catch, and appropriate action taken if the command failed.

The catch keyword cannot be used before if, elif or endif. In addition it should not be used on calls to user-defined functions; it is intended for use only with gretl commands and calls to "built-in" functions or operators. Furthermore, catch cannot be used in conjunction with "back-arrow" assignment of models or plots to session icons (see chapter 3 of the Gretl User's Guide).

chow

clear

coeffsum

Note the difference between this and omit, which tests the null hypothesis that the coefficients on a specified subset of independent variables are all equal to zero.

The --quiet option may be useful if one just wants access to the $test and $pvalue values that are recorded on successful completion.

Menu path: Model window, /Tests/Sum of coefficients

coint

The Engle–Granger (1987) cointegration test. The default procedure is: (1) carry out Dickey–Fuller tests on the null hypothesis that each of the variables listed has a unit root; (2) estimate the cointegrating regression; and (3) run a DF test on the residuals from the cointegrating regression. If the --skip-df flag is given, step (1) is omitted.

If the specified lag order is positive all the Dickey–Fuller tests use that order, with this qualification: if the --test-down option is given, the given value is taken as the maximum and the actual lag order used in each case is obtained by testing down. See the adf command for details of this procedure.

By default, the cointegrating regression contains a constant. If you wish to suppress the constant, add the --nc flag. If you wish to augment the list of deterministic terms in the cointegrating regression with a linear or quadratic trend, add the --ct or --ctt flag. These option flags are mutually exclusive. You also have the option of adding seasonal dummy variables (in the case of quarterly or monthly data).

P-values for this test are based on MacKinnon (1996). The relevant code is included by kind permission of the author.

For the cointegration tests due to Søren Johansen, see johansen.

Menu path: /Model/Multivariate time series

continue

This command can be used only within a loop; it has the effect of skipping the subsequent statements within the current iteration of the current (innermost) loop. See also loop, break

corr

If varlist contains more than two series and gretl is not in batch mode, a "heatmap" plot of the correlation matrix is shown. This can be adjusted via the --plot option. The acceptable parameters to this option are none (to suppress the plot); display (to display a plot even when in batch mode); or a file name. The effect of providing a file name is as described for the --output option of the gnuplot command. When plotting is active the option --triangle can be used to show only the lower triangle of the matrix plot.

If the alternative form is given, using a named matrix rather than a list of series, the --spearman and --kendall options are not available—but see the npcorr function.

The $result accessor can be used to obtain the correlations as a matrix. Note that if it's this matrix that's of interest, not just the pairwise coefficients, then in the presence of missing values it's advisable to use the --uniform option. Unless a single, common sample is used it is not guaranteed that the correlation matrix will be positive semidefinite, as it ought to be by construction.

Menu path: /View/Correlation matrix

corrgm

By default, if gretl is not in batch mode a plot of the correlogram is shown. This can be adjusted via the --plot option. The acceptable parameters to this option are none (to suppress the plot); display (to show a plot even when in batch mode); or a file name. The effect of providing a file name is as described for the --output option of the gnuplot command.

Accessors

Upon successful completion, the accessors $test and $pvalue can be used to retrieve the Q statistic and its P-value, evaluated at the maximum lag. Note that if you just want this test you can use use the ljungbox function instead.

Menu path: /Variable/Correlogram

cusum

In the case of the CUSUM test, the Harvey–Collier t-statistic for testing the null hypothesis of parameter stability is also printed. See Greene's Econometric Analysis for details. For the CUSUMSQ test, the 95 percent confidence band is calculated using the algorithm given in Edgerton and Wells (1994).

By default, if gretl is not in batch mode a plot of the cumulated series and confidence band is shown. This can be adjusted via the --plot option. The acceptable parameters to this option are none (to suppress the plot); display (to display a plot even when in batch mode); or a file name. The effect of providing a file name is as described for the --output option of the gnuplot command.

Menu path: Model window, /Tests/CUSUM(SQ)

data

Reads the variables in varlist from a database file (native gretl, RATS 4.0 or PcGive), which must have been opened previously using the open command. The data command can also be used to import series from DB.NOMICS or from an ODBC database; for details on those variants see gretl + DB.NOMICS or chapter 42 of the Gretl User's Guide, respectively.

The data frequency and sample range may be established via the setobs and smpl commands prior to using this command. Here's an example:

	open fedstl.bin
	setobs 12 2000:01
	smpl ; 2019:12
	data unrate cpiaucsl

The commands above open the database named fedstl.bin (which is supplied with gretl), establish a monthly dataset starting in January 2000 and ending in December of 2019, and then import the series named unrate (unemployment rate) and cpiaucsl (all-items CPI).

If setobs and smpl are not specified in this way, the data frequency and sample range are set using the first variable read from the database.

If the series to be read are of higher frequency than the working dataset, you may specify a compaction method as below:

	data LHUR PUNEW --compact=average

The five available compaction methods are "average" (takes the mean of the high frequency observations), "last" (uses the last observation), "first", "sum" and "spread". If no method is specified, the default is to use the average. The "spread" method is special: no information is lost, rather it is spread across multiple series, one per sub-period. So for example when adding a monthly series to a quarterly dataset three series are created, one for each month of the quarter; their names bear the suffixes m01, m02 and m03.

If the series to be read are of lower frequency than the working dataset the values of the added data are simply repeated as required, but note that the tdisagg function can then be used to distribution or interpolation ("temporal disaggregation").

In the case of native gretl databases (only), the "glob" characters * and ? can be used in varlist to import series that match the given pattern. For example, the following will import all series in the database whose names begin with cpi:

	data cpi*

The --name option can be used to set a name for the imported series other than the original name in the database. The parameter must be a valid gretl identifier. This option is restricted to the case where a single series is specified for importation.

The --no-align option applies only to importation of series via ODBC. By default we require that the ODBC query returns information telling gretl on which rows of the dataset to place the incoming data—or at least that the number of incoming values matches either the length of the dataset or the length of the current sample range. Setting the --no-align option relaxes this requirement: failing the conditions just mentioned, incoming values are simply placed consecutively starting at the first row of the dataset. If there are fewer such values than rows in the dataset the trailing rows are filled with NAs; if there are more such values than rows the extra values are discarded. For more on ODBC importation see chapter 42 of the Gretl User's Guide.

Menu path: /File/Databases

dataset

expand: This action is only available for annual or quarterly time series data: annual data can be expanded to quarterly or monthly, and quarterly data to monthly. All series in the data set are padded out to the new frequency by repeating the existing values. If the original dataset is annual the default expansion is to quarterly but expand can be followed by 12 to request monthly. See the tdisagg function for more sophisticated means of converting data to higher frequency.

transpose: No additional parameter required. Transposes the current data set. That is, each observation (row) in the current data set will be treated as a variable (column), and each variable as an observation. This action may be useful if data have been read from some external source in which the rows of the data table represent variables.

sortby: The name of a single series or list is required. If one series is given, the observations on all variables in the dataset are re-ordered by increasing value of the specified series. If a list is given, the sort proceeds hierarchically: if the observations are tied in sort order with respect to the first key variable then the second key is used to break the tie, and so on until the tie is broken or the keys are exhausted. Note that this action is available only for undated data.

dsortby: Works as sortby except that the re-ordering is by decreasing value of the key series.

resample: Constructs a new dataset by random sampling, with replacement, of the rows of the current dataset. One argument is required, namely the number of rows to include. This may be less than, equal to, or greater than the number of observations in the original data. The original dataset can be retrieved via the command smpl full.

renumber: Requires the name of an existing series followed by an integer between 1 and the number of series in the dataset minus one. Moves the specified series to the specified position in the dataset, renumbering the other series accordingly. (Position 0 is occupied by the constant, which cannot be moved.)

pad-daily: Valid only if the current dataset contains dated daily data with an incomplete calendar. The effect is to pad the data out to a complete calendar by inserting blank rows (that is, rows containing nothing but NAs). This option requires an integer parameter, namely the number of days per week, which must be 5, 6 or 7, and must be greater than or equal to the current data frequency. On successful completion, the data calendar will be "complete" relative to this value. For example if days-per-week is 5 then all weekdays will be represented, whether or not any data are available for those days.

unpad-daily: Valid only if the current dataset contains dated daily data, in which case it performs the inverse operation of pad-daily. That is, any rows that contain nothing but NAs are removed, while the time-series property of the dataset is preserved along with the dates of the individual observations.

Menu path: /Data

delete

In the first form above, varlist is a list of series, given by name or ID number. Note that when you delete series any series with higher ID numbers than those on the deletion list will be re-numbered. If the --db option is given, this command deletes the listed series not from the current dataset but from a gretl database, assuming that a database has been opened, and the user has write permission for file in question. See also the open command.

In the second form, the name of a scalar, matrix, string or bundle may be given for deletion. The --db option is not applicable in this case. Note that series and variables of other types should not be mixed in a given call to delete.

In the third form, the --type option must be accompanied by one of the following type-names: matrix, bundle, string, list, scalar or array. The effect is to delete all variables of the given type. In this case no argument other than the option should be given.

The fourth form can be used to unload a function package. In this case the .gfn suffix must be supplied, as in

	delete somepkg.gfn

Note that this does not delete the package file, it just unloads the package from memory.

Deleting variables in a loop

In general it is not permitted to delete variables in the context of a loop, since this may threaten the integrity of the loop code. However, if you are confident that deleting a certain variable is safe you can override this prohibition by appending the --force flag to the delete command.

Menu path: Main window pop-up (single selection)

diff

	d_x = x(t) - x(t-1)
	d_y = y(t) - y(t-1)

difftest

On successful completion the accessors $test and $pvalue are available. If one just wants to obtain these values the --quiet flag can be appended to the command.

discrete

Marks each variable in varlist as being discrete. By default all variables are treated as continuous; marking a variable as discrete affects the way the variable is handled in frequency plots, and also allows you to select the variable for the command dummify.

If the --reverse flag is given, the operation is reversed; that is, the variables in varlist are marked as being continuous.

Menu path: /Variable/Edit attributes

dpanel

In the case of 2-step estimation, standard errors are by default computed using the finite-sample correction suggested by Windmeijer (2005). The standard asymptotic standard errors associated with the 2-step estimator are generally reckoned to be an unreliable guide to inference, but if for some reason you want to see them you can use the --asymptotic option to turn off the Windmeijer correction.

If the --time-dummies option is given, a set of time dummy variables is added to the specified regressors. The number of dummies is one less than the maximum number of periods used in estimation, to avoid perfect collinearity with the constant. The dummies are entered in differenced form unless the --dpdstyle option is given, in which case they are entered in levels.

As with other estimation commands, a $model bundle is available after estimation. In the case of dpanel, the --keep-extra option can be used to save additional information in this bundle, namely the GMM weight and instrument matrices.

For further details and examples, please see chapter 24 of the Gretl User's Guide.

Menu path: /Model/Panel/Dynamic panel model

dummify

	ols y dummify(x)

duration

Please see chapter 38 of the Gretl User's Guide for details.

Menu path: /Model/Limited dependent variable/Duration data

elif

See if.

else

See if. Note that else requires a line to itself, before the following conditional command. You can append a comment, as in

	else # OK, do something different

But you cannot append a command, as in

	else x = 5 # wrong!

end

Ends a block of commands of some sort. For example, end system terminates an equation system.

endif

See if.

endloop

Marks the end of a command loop. See loop.

eqnprint

Must follow the estimation of a model. Prints the estimated model in the form of a LaTeX equation. If a filename is specified using the --output option output goes to that file, otherwise it goes to a file with a name of the form equation_N.tex, where N is the number of models estimated to date in the current session. See also tabprint.

The output file will be written in the currently set workdir, unless the filename string contains a full path specification.

If the --complete flag is given, the LaTeX file is a complete document, ready for processing; otherwise it must be included in a document.

Menu path: Model window, /LaTeX

equation

Specifies an equation within a system of equations (see system). The syntax for specifying an equation within an SUR system is the same as that for, e.g., ols. For an equation within a Three-Stage Least Squares system you may either (a) give an OLS-type equation specification and provide a common list of instruments using the instr keyword (again, see system), or (b) use the same equation syntax as for tsls.

estimate

Calls for estimation of a system of equations, which must have been previously defined using the system command. The name of the system should be given first, surrounded by double quotes if the name contains spaces. The estimator, which must be one of ols, tsls, sur, 3sls, fiml or liml, is preceded by the string method=. These arguments are optional if the system in question has already been estimated and occupies the place of the "last model"; in that case the estimator defaults to the previously used value.

If the system in question has had a set of restrictions applied (see the restrict command), estimation will be subject to the specified restrictions.

If the estimation method is sur or 3sls and the --iterate flag is given, the estimator will be iterated. In the case of SUR, if the procedure converges the results are maximum likelihood estimates. Iteration of three-stage least squares, however, does not in general converge on the full-information maximum likelihood results. The --iterate flag is ignored for other methods of estimation.

If the equation-by-equation estimators ols or tsls are chosen, the default is to apply a degrees of freedom correction when calculating standard errors. This can be suppressed using the --no-df-corr flag. This flag has no effect with the other estimators; no degrees of freedom correction is applied in any case.

By default, the formula used in calculating the elements of the cross-equation covariance matrix is

If the --geomean flag is given, a degrees of freedom correction is applied: the formula is

where the ks denote the number of independent parameters in each equation.

If the --verbose option is given and an iterative method is specified, details of the iterations are printed.

eval

	=sqrt(x)

In most contexts print can be used in place of eval to much the same effect. See also printf for the case where you wish to combine textual and numerical output.

fcast

If the last model estimated is a single equation, then the optional vname argument has the following effect: the forecast values are not printed, but are saved to the dataset under the given name. If the last model is a system of equations, vname has a different effect, namely selecting a particular endogenous variable for forecasting (the default being to produce forecasts for all the endogenous variables). In the system case, or if vname is not given, the forecast values can be retrieved using the accessor $fcast, and the standard errors, if available, via $fcse.

Static and dynamic forecasts

The choice between a static and a dynamic forecast applies only in the case of dynamic models, with an autoregressive error process or including one or more lagged values of the dependent variable as regressors. Static forecasts are one step ahead, based on realized values from the previous period, while dynamic forecasts employ the chain rule of forecasting. For example, if a forecast for y in 2008 requires as input a value of y for 2007, a static forecast is impossible without actual data for 2007. A dynamic forecast for 2008 is possible if a prior forecast can be substituted for y in 2007.

The default is to give a static forecast for any portion of the forecast range that lies within the sample range over which the model was estimated, and a dynamic forecast (if relevant) out of sample. The --dynamic option requests a dynamic forecast from the earliest possible date, and the --static option requests a static forecast even out of sample.

Recursive forecasts

The --recursive option is presently available only for single-equation models estimated via OLS. When this option is given the forecasts are recursive. That is, each forecast is generated from an estimate of the given model using data from a fixed starting point (namely, the start of the sample range for the original estimation) up to the forecast date minus k, where k is the number of steps ahead, which must be given in the steps-ahead argument. The forecasts are always dynamic if this is applicable. Note that the steps-ahead argument should be given only in conjunction with the --recursive option.

Ordered and multinomial models

When estimation is via ordered logit or probit, or multinomial logit, one may be interested in the estimated probabilities of each of the discrete outcomes rather than just a "most likely" outcome for each observation. This is supported by the --all-probs option: the output of fcast is then a matrix with one column per possible outcome. The vname argument can be used to name this matrix, in which case nothing is printed. If vname is not given the matrix can be retrieved via $fcast. The --plot option is incompatible with --all-probs.

Forecast plots

The --plot option calls for a plot file to be produced, containing a graphical representation of the forecast. In the system case this option is available only when the vname argument is used to select a single variable for forecasting. The suffix of the filename argument to this option controls the format of the plot: .eps for EPS, .pdf for PDF, .png for PNG, .plt for a gnuplot command file. The dummy filename display can be used to force display of the plot in a window. For example,

	fcast --plot=fc.pdf

will generate a graphic in PDF format. Absolute pathnames are respected, otherwise files are written to the gretl working directory.

Standard errors

The nature of the forecast standard errors (if available) depends on the nature of the model and the forecast. For static linear models standard errors are computed using the method outlined by Davidson and MacKinnon (2004); they incorporate both uncertainty due to the error process and parameter uncertainty (summarized in the covariance matrix of the parameter estimates). For dynamic models, forecast standard errors are computed only in the case of a dynamic forecast, and they do not incorporate parameter uncertainty. For nonlinear models, forecast standard errors are not presently available.

Menu path: Model window, /Analysis/Forecasts

flush

       set echo off
       scalar n = 10
       loop i=1..n
           # do some time-consuming operation
           loop 100 --quiet
               a = mnormal(200,200)
               b = inv(a)
           endloop
           # print some results
           printf "Iteration %2d done\n", i
           if i < n
               flush
           endif
       endloop

foreign

	list Rlist = x1 x2 x3
	foreign language=R --send-data=Rlist

See chapter 44 of the Gretl User's Guide for details and examples.

fractint

Tests the specified series for fractional integration ("long memory"). The null hypothesis is that the integration order of the series is zero. By default the local Whittle estimator (Robinson, 1995) is used but if the --gph option is given the GPH test (Geweke and Porter-Hudak, 1983) is performed instead. If the --all flag is given then the results of both tests are printed.

For details on this sort of test, see Phillips and Shimotsu (2004).

If the optional order argument is not given the order for the test(s) is set automatically as the lesser of T/2 and T^0.6.

The estimated fractional integration orders and their standard errors are available via the $result accessor. With the --all option, the Local Whittle estimate will be in the first row and the GPH estimate in the second one.

The results of the test can be retrieved using the accessors $test and $pvalue. These values are based on the Local Whittle Estimator unless the --gph option is given.

Menu path: /Variable/Unit root tests/Fractional integration

freq

With no options given, displays the frequency distribution for the series var (given by name or number) in tabular form, with the number of bins and their size chosen automatically, with or without an accompanying plot as explained below. Upon successful completion of the command, the frequency table can be retrieved as a matrix using the $result accessor.

If the --matrix option is given, var (which must be an integer) is instead interpreted as a 1-based index that selects a column from the named matrix. If the matrix in question is in fact a column vector, the var argument may be omitted.

By default the frequency distribution employs an automatically calculated number of bins if the data are continuous, or no binning if the data are discrete. To control this point you can (a) use the discrete command to set the status of var or (b), if the data are continuous, specify either the number of bins or the minimum value and the width of the bins, as shown in the last two examples above. The --min option sets the lower limit of the left-most bin.

If the --normal option is given, the Doornik–Hansen chi-square test for normality is computed. If the --gamma option is given, the test for normality is replaced by Locke's nonparametric test for the null hypothesis that the variable follows the gamma distribution; see Locke (1976), Shapiro and Chen (2001). Note that the parameterization of the gamma distribution used in gretl is (shape, scale).

By default, if gretl is not in batch mode a plot of the distribution is shown. This can be adjusted via the --plot option. The acceptable parameters to this option are none (to suppress the plot); display (to display a plot even when in batch mode); or a file name. The effect of providing a file name is as described for the --output option of the gnuplot command.

The --silent flag suppresses the usual text output. This might be used in conjunction with one or other of the distribution test options: the test statistic and its p-value are recorded, and can be retrieved using the accessors $test and $pvalue. It might also be used along with the --plot option if you just want a histogram and don't care to see the accompanying text.

Note that gretl does not have a function that matches this command, but it is possible to use the aggregate function to achieve the same purpose. In addition, the frequency distribution constructed by freq can be obtained in matrix form via the $result accessor.

Menu path: /Variable/Frequency distribution

funcerr

Applicable only in the context of a user-defined function (see function). Causes execution of the current function to terminate with an error condition flagged.

The optional message argument can take the form of a string literal or the name of a string variable; if present it is printed as part of the error message shown to the caller of the function.

See also the closely related function, errorif.

function

Opens a block of statements in which a function is defined. This block must be closed with end function. (An exception is the case when a user-defined function shall be deleted, which is achieved by the single command line function foo delete for a function named "foo".) See chapter 14 of the Gretl User's Guide for details.

garch

Arguments:	p q ; depvar [ indepvars ]
Options:	--robust (robust standard errors)
	--verbose (print details of iterations)
	--quiet (don't print anything)
	--vcv (print covariance matrix)
	--nc (do not include a constant)
	--stdresid (standardize the residuals)
	--fcp (use Fiorentini, Calzolari, Panattoni algorithm)
	--arma-init (initial variance parameters from ARMA)
Examples:	garch 1 1 ; y
	garch 1 1 ; y 0 x1 x2 --robust
	See also garch.inp, sw_ch14.inp

Estimates a GARCH model (GARCH = Generalized Autoregressive Conditional Heteroskedasticity), either a univariate model or, if indepvars are specified, including the given exogenous variables. The integer values p and q (which may be given in numerical form or as the names of pre-existing scalar variables) represent the lag orders in the conditional variance equation:

The parameter p therefore represents the Generalized (or "AR") order, while q represents the regular ARCH (or "MA") order. If p is non-zero, q must also be non-zero otherwise the model is unidentified. However, you can estimate a regular ARCH model by setting q to a positive value and p to zero. The sum of p and q must be no greater than 5. Note that a constant is automatically included in the mean equation unless the --nc option is given.

By default native gretl code is used in estimation of GARCH models, but you also have the option of using the algorithm of Fiorentini, Calzolari and Panattoni (1996). The former uses the BFGS maximizer while the latter uses the information matrix to maximize the likelihood, with fine-tuning via the Hessian.

Several variant estimators of the covariance matrix are available with this command. By default, the Hessian is used unless the --robust option is given, in which case the QML (White) covariance matrix is used. Other possibilities (e.g. the information matrix, or the Bollerslev–Wooldridge estimator) can be specified via the garch_vcv keyword under the set command.

By default, the estimates of the variance parameters are initialized using the unconditional error variance from initial OLS estimation for the constant, and small positive values for the coefficients on the past values of the squared error and the error variance. The flag --arma-init calls for the starting values of these parameters to be set using an initial ARMA model, exploiting the relationship between GARCH and ARMA set out in Chapter 21 of Hamilton's Time Series Analysis. In some cases this may improve the chances of convergence.

The GARCH residuals and estimated conditional variance can be retrieved as $uhat and $h respectively. For example, to get the conditional variance:

	series ht = $h

If the --stdresid option is given, the $uhat values are divided by the square root of h_t.

Menu path: /Model/Univariate time series/GARCH

genr

NOTE: this command has undergone numerous changes and enhancements since the following help text was written, so for comprehensive and updated info on this command you'll want to refer to chapter 10 of the Gretl User's Guide. On the other hand, this help does not contain anything actually erroneous, so take the following as "you have this, plus more".

In the appropriate context, series, scalar, matrix, string, bundle and array are synonyms for this command.

Creates new variables, often via transformations of existing variables. See also diff, logs, lags, ldiff, sdiff and square for shortcuts. In the context of a genr formula, existing variables must be referenced by name, not ID number. The formula should be a well-formed combination of variable names, constants, operators and functions (described below). Note that further details on some aspects of this command can be found in chapter 10 of the Gretl User's Guide.

A genr command may yield either a series or a scalar result. For example, the formula x2 = x * 2 naturally yields a series if the variable x is a series and a scalar if x is a scalar. The formulae x = 0 and mx = mean(x) naturally return scalars. Under some circumstances you may want to have a scalar result expanded into a series or vector. You can do this by using series as an "alias" for the genr command. For example, series x = 0 produces a series all of whose values are set to 0. You can also use scalar as an alias for genr. It is not possible to coerce a vector result into a scalar, but use of this keyword indicates that the result should be a scalar: if it is not, an error occurs.

When a formula yields a series result, the range over which the result is written to the target variable depends on the current sample setting. It is possible, therefore, to define a series piecewise using the smpl command in conjunction with genr.

Supported arithmetical operators are, in order of precedence: ^ (exponentiation); *, / and % (modulus or remainder); + and -.

The available Boolean operators are (again, in order of precedence): ! (negation), && (logical AND), || (logical OR), >, <, == (is equal to), >= (greater than or equal), <= (less than or equal) and != (not equal). The Boolean operators can be used in constructing dummy variables: for instance (x > 10) returns 1 if x > 10, 0 otherwise.

Built-in constants are pi and NA. The latter is the missing value code: you can initialize a variable to the missing value with scalar x = NA.

The genr command supports a wide range of mathematical and statistical functions, including all the common ones plus several that are special to econometrics. In addition it offers access to numerous internal variables that are defined in the course of running regressions, doing hypothesis tests, and so on. For a listing of functions and accessors, see the Gretl Function Reference.

Besides the operators and functions noted above there are some special uses of genr:

• genr time creates a time trend variable (1,2,3,...) called time. genr index does the same thing except that the variable is called index.

• genr dummy creates dummy variables up to the periodicity of the data. In the case of quarterly data (periodicity 4), the program creates dq1 = 1 for first quarter and 0 in other quarters, dq2 = 1 for the second quarter and 0 in other quarters, and so on. With monthly data the dummies are named dm1, dm2, and so on; with daily data they are named dd1, dd2, and so on; and with other frequencies the names are dummy_1, dummy_2, etc.

• genr unitdum and genr timedum create sets of special dummy variables for use with panel data. The first codes for the cross-sectional units and the second for the time period of the observations.

Note: In the command-line program, genr commands that retrieve model-related data always reference the model that was estimated most recently. This is also true in the GUI program, if one uses genr in the "gretl console" or enters a formula using the "Define new variable" option under the Add menu in the main window. With the GUI, however, you have the option of retrieving data from any model currently displayed in a window (whether or not it's the most recent model). You do this under the "Save" menu in the model's window.

The special variable obs serves as an index of the observations. For instance series dum = (obs==15) will generate a dummy variable that has value 1 for observation 15, 0 otherwise. You can also use this variable to pick out particular observations by date or name. For example, series d = (obs>1986:4), series d = (obs>"2008-04-01"), or series d = (obs=="CA"). If daily dates or observation labels are used in this context, they should be enclosed in double quotes. Quarterly and monthly dates (with a colon) may be used unquoted. Note that in the case of annual time series data, the year is not distinguishable syntactically from a plain integer; therefore if you wish to compare observations against obs by year you must use the function obsnum to convert the year to a 1-based index value, as in series d = (obs>obsnum(1986)).

Scalar values can be pulled from a series in the context of a genr formula, using the syntax varname[obs]. The obs value can be given by number or date. Examples: x[5], CPI[1996:01]. For daily data, the form YYYY-MM-DD should be used, e.g. ibm[1970-01-23].

An individual observation in a series can be modified via genr. To do this, a valid observation number or date, in square brackets, must be appended to the name of the variable on the left-hand side of the formula. For example, genr x[3] = 30 or genr x[1950:04] = 303.7.

Menu path: /Add/Define new variable

gmm

Please see chapter 27 of the Gretl User's Guide for details on this command. Here we just illustrate with a simple example.

	gmm e = y - X*b
	  orthog e ; W
	  weights V
	  params b
	end gmm

In the example above we assume that y and X are data matrices, b is an appropriately sized vector of parameter values, W is a matrix of instruments, and V is a suitable matrix of weights. The statement

	orthog e ; W

indicates that the residual vector e is in principle orthogonal to each of the instruments composing the columns of W.

Parameter names

In estimating a nonlinear model it is often convenient to name the parameters tersely. In printing the results, however, it may be desirable to use more informative labels. This can be achieved via the additional keyword param_names within the command block. For a model with k parameters the argument following this keyword should be a double-quoted string literal holding k space-separated names, the name of a string variable that holds k such names, or the name of an array of k strings.

Menu path: /Model/Instrumental variables/GMM

gnuplot

The series in the list yvars are graphed against xvar. For a time series plot you may either give time as xvar or use the option flag --time-series. See also the plot and panplot commands.

By default, data-points are shown as points; this can be overridden by giving one of the options --with-lines, --with-lp (lines and points), --with-impulses or --with-steps. If more than one variable is to be plotted on the y axis, the effect of these options may be confined to a subset of the variables by using the varspec parameter. This should take the form of a comma-separated listing of the names or numbers of the variables to be plotted with lines or impulses respectively. For instance, the final example above shows how to plot y1 and y2 against x, such that y2 is represented by a line but y1 by points.

When yvars contains more than one variable it may be preferable to use two y axes (left and right). By default this is handled automatically, via a heuristic based on the relative scales of the variables, but two (mutually exclusive) options can be used to override the default. As you'd expect, --single-yaxis prevents use of a second axis, while --y2axis=yvar specifies that a selected variable (only) be plotted relative to a second axis.

If the --dummy option is selected, exactly three variables should be given: a single y variable, an x variable, and dvar, a discrete variable. The effect is to plot yvar against xvar with the points shown in different colors depending on the value of dvar at the given observation.

The --control option is similar, in that exactly three variables should be given: a single y variable and two "explanatory" variables x and z. The effect is to plot y against x controlling for z. Such plot can be useful to visualize the relationship between x and y, taking into account the effect that z can have on both. Statistically, this would be equivalent to a regression of y on x and z.

You can specify the scale for the y axis as logarithmic rather than linear by using the --ylogscale option, together with a base parameter. For example,

	gnuplot y x --ylogscale=2

plots the data such that the vertical axis is expressed as powers of 2. If the base is omitted, it defaults to 10.

Taking data from a matrix

In the primary case the arguments yvars and xvar are required, and refer to series in the current dataset (given either by name or ID number). But if a named matrix is supplied via the --matrix option these arguments become optional: if the specified matrix has k columns, by default the first k – 1 columns are treated as the yvars and the last column as xvar. But if the --time-series option is given all k columns are plotted against time. If you wish to plot selected columns of the matrix, you should specify yvars and xvar in the form of 1-based column numbers. For example if you want a scatterplot of column 2 of matrix M against column 1, you can do:

	gnuplot 2 1 --matrix=M

Showing a line of best fit

The --fit option is applicable only for bivariate scatterplots and single time-series plots. The default behavior for a scatterplot is to show the OLS fit if the slope coefficient is significant at the 10 percent level, while the default behavior for time-series is not to show any fitted line. You can call for different behavior by using this option along with one of the following fitspec parameter values. Note that if the plot is a single time series the place of x is taken by time.

• linear: show the OLS fit regardless of its level of statistical significance.

• none: don't show any fitted line.

• inverse, quadratic, cubic, semilog or linlog: show a fitted line based on a regression of the specified type. By semilog, we mean a regression of log y on x; the fitted line represents the conditional expectation of y, obtained by exponentiation. By linlog we mean a regression of y on the log of x.

• loess: show the fit from a robust locally weighted regression (also is sometimes known as "lowess").

Plotting a band

The --band option can be used for plotting a "band" of some sort (typically representing a confidence interval) along with other data. The recommended way of specifying such a band is via a bundle, whose name is given as a parameter to the option. A band bundle has two required elements: under the key center, the name of a series for the center of the band, and under the key width the name of a series representing the width of the band—both being given as quoted strings. In addition four optional elements are supported, as follows.

• Under the key factor, a scalar giving a factor by which width should be multiplied (the default value being 1).

• Under the key style, a string to specify how the band is represented, which must be one of line (the default) fill, dash, bars or step.

• Under the key color, a color for the band, either as a string holding a gnuplot color name or as a hexadecimal RGB representation (given as a string or a scalar). By default the color is selected automatically.

• Under the key title, a title for the band, to appear in the key or legend of the plot. By default bands are untitled.

Note that you can access the list of color names recognized by gnuplot by issuing the command "show colornames" in gnuplot itself, or in the gretl console by doing

	eval readfile("@gretldir/data/gnuplot/gpcolors.txt")

Here are two examples of usage, employing the shorthand syntax _() for defining a bundle. The first just satisfies the minimum requirement while the second exercises all three options. We assume that y, x and w are all series in the current dataset.

	bundle b1 = _(center="x", width="w")
	gnuplot y --time-series --with-lines --band=b1
	bundle b2 = _(center="x", width="w", factor=1.96, style="fill")
	b2.color=0xcccccc
	b2.title = "95% interval"
	gnuplot y --time-series --with-lines --band=b2

If the plot is to contain two or more such bands, the option flag should be given in the plural and its parameter must be the name of an array of bundles, as in (following on from the example above):

	bundles bb = defarray(b1, b2)
	gnuplot y --time-series --with-lines --bands=bb

When plotting matrix rather than series data, the only difference is that the center and width elements of the band bundle are replaced by a single element under the key bandmat; this should be the quoted name of a two-column matrix with the center in column 1 and the width in column 2.

Legacy band syntax

The syntax described above was introduced in gretl 2023c. Prior to that release only one band could be specified per plot and the syntax was somewhat different. The old approach, which is still accepted until further notice, split the band details over two options. First, the --band option required as parameter the names of two series, separated by a comma, giving center and width. The multiplicative factor for the width could be added as a third comma-separated term. Examples:

	gnuplot ... --band=x,w
	gnuplot ... --band=x,w,1.96

A second option, --band-style, accepted one or both of the style and color specifiers, in that order and again separated by a comma, as in these examples.

	gnuplot ... --band-style=fill
	gnuplot ... --band-style=dash,0xbbddff
	gnuplot ... --band-style=,black
	gnuplot ... --band-style=bars,blue

Recession bars

The "band" option can also be used to add "recession bars" to a plot. By this we mean vertical bars occupying the full y-dimension of the plot and indicating the presence (bar) or absence (no bar) of some qualitative feature in a time-series plot. Such bars are commonly used to flag periods of recession; they could also be used to indicate periods of war, or anything that can be coded in a 0/1 dummy variable.

In this context the band bundle has a single required element: under the key dummy, the quoted name of a 0/1 series (or in the case of matrix data, the quoted name of a suitable column vector). The vertical bars will be "on" for observations where this series or vector has value 1 and "off" when it's 0. The center, width, factor and style keys are not relevant, but color can be used. Note that only one such specification can be used per plot. Here's an example:

	open AWM17 --quiet
	series dum = obs >= 1990:1 && obs <= 1994:2
	bundle b = _(dummy="dum", color=0xcccccc)
	gnuplot YER URX --with-lines --time-series \
	  --band=b --output=display {set key top left;}

Controlling the output

In interactive mode the plot is displayed immediately. In batch mode the default behavior is that a gnuplot command file is written in the user's working directory, with a name on the pattern gpttmpN.plt, starting with N = 01. The actual plots may be generated later using gnuplot (under MS Windows, wgnuplot). This behavior can be modified by use of the --output=filename option. This option controls the filename used, and at the same time allows you to specify a particular output format via the three-letter extension of the file name, as follows: .eps results in the production of an Encapsulated PostScript (EPS) file; .pdf produces PDF; .png produces PNG format, .emf calls for EMF (Enhanced MetaFile), .fig calls for an Xfig file, .svg for SVG (Scalable Vector Graphics) and .html for an HTML canvas. If the dummy filename "display" is given then the plot is shown on screen as in interactive mode. If a filename with any extension other than those just mentioned is given, a gnuplot command file is written.

An alternative means of directing output is the --outbuf=stringname option. This writes gnuplot commands to the named string or "buffer". Note that --output and --outbuf are mutually incompatible.

Specifying a font

The --font option can be used to specify a particular font for the plot. The fontspec parameter should take the form of the name of a font, optionally followed by a size in points separated from the name by a comma or space, all wrapped in double quotes, as in

	--font="serif,12"

Note that the fonts available to gnuplot will vary by platform, and if you're writing a plot command that is intended to be portable it is best to restrict the font name to the generic sans or serif.

Adding gnuplot commands

A further option to this command is available: following the specification of the variables to be plotted and the option flag (if any), you may add literal gnuplot commands to control the appearance of the plot (for example, setting the plot title and/or the axis ranges). These commands should be enclosed in braces, and each gnuplot command must be terminated with a semi-colon. A backslash may be used to continue a set of gnuplot commands over more than one line. Here is an example of the syntax:

	{ set title 'My Title'; set yrange [0:1000]; }

Menu path: /View/Graph specified vars

graphpg

	grf1 <- gnuplot Y X
	graphpg add

	graphpg fontscale 1.5

	graphpg --output="myfile.pdf"

The output file will be written in the currently set workdir, unless the filename string contains a full path specification.

In this context the output uses colored lines by default; to use dot/dash patterns instead of colors you can append the --monochrome flag.

gridplot

This command takes two or more individual plot specifications and arranges them in a grid to produce a composite plot. The single required argument, plotspecs, takes the form of an array of strings, each specifying a plot. The companion command gpbuild offers an easy way of creating such an array.

Specifying the grid

The shape of the grid can be set by any one of the three mutually incompatible options --rows, --cols and --layout. If no such option is given the number of rows is set to the square root of the number of plots (the size of the input array), rounded up to the nearest integer if necessary. Then the number of columns is set to the number of plots divided by the number of rows, again rounded up if necessary. The plots are placed in the grid by row, in their array order. If the --rows option is given this takes the place of the automatic setting, but the number of columns is set automatically as described above. If the --cols option is given instead, the number of rows is set automatically.

The --layout option, which requires a matrix parameter, offers a more flexible alternative. The matrix specifies the grid layout thus: 0 elements call for empty cells in the grid, and integer elements 1 to n refer to the subplots in their array order. So for example,

	matrix m = {1,0,0; 2,3,0; 4,5,6}
	gridplot ... --layout=m ...

calls for a lower-triangular layout of six plots in a 3 x 3 grid. Using this option one can omit some subplots, or even repeat some.

Output options

The --output option can be used to specify display (show the plot immediately) or the name of an output file. Alternatively --outbuf can be used to direct output, in the form of a gnuplot commands buffer, to a named string. In the absence of these options the output is an automatically named gnuplot command file. See gnuplot for details.

gpbuild

This command starts a block in which any commands or function calls which produce plots are treated specially, in order to produce an array of plot-specification strings for use with gridplot: the plotspecs argument supplies the name for this array. Such a block is terminated by the command "end gpbuild".

Two restrictions

Within a gpbuild block only plotting commands get special treatment; all other commands are executed normally. There are just two restrictions to note.

• Plotting commands should not include an output specification in this context, since that would conflict with the automatic redirection of output to the plotspecs array. An exception to this rule is allowed for --output=display (which is quite common as the default in plot-related function packages); this directive is silently ignored in favour of the automatic treatment.

• Plots that invoke gnuplot's "multiplot" directive are not suitable for inclusion in a gpbuild block. That is because gridplot employs multiplot internally, and these constructs cannot be nested.

Manual alternative

It is possible to prepare an array of plot specifications for use with gridplot without using a gpbuild block, as in the following example:

	open data4-10
	strings MyPlots = array(3)
	gnuplot ENROLL CATHOL --outbuf=MyPlots[1]
	gnuplot ENROLL INCOME --outbuf=MyPlots[2]
	gnuplot ENROLL COLLEGE --outbuf=MyPlots[3]

The above is essentially equivalent to

	open data4-10
	gpbuild MyPlots
	   gnuplot ENROLL CATHOL
	   gnuplot ENROLL INCOME
	   gnuplot ENROLL COLLEGE
	end gpbuild

heckit

By default, the parameters are estimated by maximum likelihood. The covariance matrix of the parameters is computed using the negative inverse of the Hessian. If two-step estimation is desired, use the --two-step option. In this case, the covariance matrix of the parameters of the outcome equation is appropriately adjusted as per Heckman (1979).

Menu path: /Model/Limited dependent variable/Heckit

help

If no arguments are given, prints a list of available commands. If the single argument functions is given, prints a list of available functions (see genr).

help command describes command (e.g. help smpl). help function describes function (e.g. help ldet). Some functions have the same names as related commands (e.g. diff): in that case the default is to print help for the command, but you can get help on the function by using the --func option.

Menu path: /Help

hfplot

For details on the effect of the --output option, please see the gnuplot command.

hsk

hurst

Calculates the Hurst exponent (a measure of persistence or long memory) for a time-series variable having at least 128 observations. The result (together with its standard error) can be retrieved via the $result accessor.

The Hurst exponent is discussed by Mandelbrot (1983). In theoretical terms it is the exponent, H, in the relationship

where RS is the "rescaled range" of the variable x in samples of size n and a is a constant. The rescaled range is the range (maximum minus minimum) of the cumulated value or partial sum of x over the sample period (after subtraction of the sample mean), divided by the sample standard deviation.

As a reference point, if x is white noise (zero mean, zero persistence) then the range of its cumulated "wandering" (which forms a random walk), scaled by the standard deviation, grows as the square root of the sample size, giving an expected Hurst exponent of 0.5. Values of the exponent significantly in excess of 0.5 indicate persistence, and values less than 0.5 indicate anti-persistence (negative autocorrelation). In principle the exponent is bounded by 0 and 1, although in finite samples it is possible to get an estimated exponent greater than 1.

In gretl, the exponent is estimated using binary sub-sampling: we start with the entire data range, then the two halves of the range, then the four quarters, and so on. For sample sizes smaller than the data range, the RS value is the mean across the available samples. The exponent is then estimated as the slope coefficient in a regression of the log of RS on the log of sample size.

By default, if gretl is not in batch mode a plot of the rescaled range is shown. This can be adjusted via the --plot option. The acceptable parameters to this option are none (to suppress the plot); display (to display a plot even when in batch mode); or a file name. The effect of providing a file name is as described for the --output option of the gnuplot command.

Menu path: /Variable/Hurst exponent

if

	# simple form
	if condition
	    commands
	endif

	# two branches
	if condition
	    commands1
	else
	    commands2
	endif

	# three or more branches
	if condition1
	    commands1
	elif condition2
	    commands2
	else
	    commands3
	endif

condition must be a Boolean expression, for the syntax of which see genr. More than one elif block may be included. In addition, if ... endif blocks may be nested.

include

See also run.

info

intreg

johansen

Carries out the Johansen test for cointegration among the variables in ylist for the given lag order. For details of this test see chapter 33 of the Gretl User's Guide or Hamilton (1994), Chapter 20. P-values are computed via Doornik's gamma approximation (Doornik, 1998). Two sets of p-values are shown for the trace test, straight asymptotic values and values adjusted for the sample size. By default the $pvalue accessor gets the adjusted variant, but the --asy flag may be used to record the asymptotic values instead.

The inclusion of deterministic terms in the model is controlled by the option flags. The default if no option is specified is to include an "unrestricted constant", which allows for the presence of a non-zero intercept in the cointegrating relations as well as a trend in the levels of the endogenous variables. In the literature stemming from the work of Johansen (see for example his 1995 book) this is often referred to as "case 3". The first four options given above, which are mutually exclusive, produce cases 1, 2, 4 and 5 respectively. The meaning of these cases and the criteria for selecting a case are explained in chapter 33 of the Gretl User's Guide.

The optional lists xlist and rxlist allow you to control for specified exogenous variables: these enter the system either unrestrictedly (xlist) or restricted to the cointegration space (rxlist). These lists are separated from ylist and from each other by semicolons.

The --seasonals option, which may be combined with any of the other options, specifies the inclusion of a set of centered seasonal dummy variables. This option is available only for quarterly or monthly data.

The following table is offered as a guide to the interpretation of the results shown for the test, for the 3-variable case. H0 denotes the null hypothesis, H1 the alternative hypothesis, and c the number of cointegrating relations.

         Rank     Trace test         Lmax test
                  H0     H1          H0     H1
         ---------------------------------------
          0      c = 0  c = 3       c = 0  c = 1
          1      c = 1  c = 3       c = 1  c = 2
          2      c = 2  c = 3       c = 2  c = 3
         ---------------------------------------

See also the vecm command, and coint if you want the Engle–Granger cointegration test.

Menu path: /Model/Multivariate time series

join

This command imports one or more data series from the source filename (which must be either a delimited text data file or a "native" gretl data file) under the name varname. For details please see chapter 7 of the Gretl User's Guide; here we just give a brief summary of the available options. See also append for simpler joining operations.

The --data option can be used to specify the column heading of the data in the source file, if this differs from the name by which the data should be known in gretl.

The --filter option can be used to specify a criterion for filtering the source data (that is, selecting a subset of observations).

The --ikey and --okey options can be used to specify a mapping between observations in the current dataset and observations in the source data (for example, individuals can be matched against the household to which they belong).

The --aggr option is used when the mapping between observations in the current dataset and the source is not one-to-one.

The --tkey option is applicable only when the current dataset has a time-series structure. It can be used to specify the name of a column containing dates to be matched to the dataset and/or the format in which dates are represented in that column.

Importing more than one series at once

The join command can handle the importation of several series at once. This happens when (a) the varname argument is a space-separated list of names rather than a single name, or (b) when it points to an array of strings: the elements of this array should be the names of the series to import.

This methods has some limitations, however: the --data option is not available. When importing multiple series you are obliged to accept their "outer" names. The other options apply uniformly to all the series imported via a given command.

kdplot

The option --output has the effect of sending the output to the specified file; use "display" to force output to the screen. See the gnuplot command for more detail on this option.

For a more flexible means of generating kernel density estimates, with the option of retrieving the result as a matrix, see the kdensity function.

Menu path: /Variable/Estimated density plot

kpss

Computes the KPSS test (Kwiatkowski et al, Journal of Econometrics, 1992) for stationarity, for each of the specified variables (or their first difference, if the --difference option is selected). The null hypothesis is that the variable in question is stationary, either around a level or, if the --trend option is given, around a deterministic linear trend.

The order argument determines the size of the window used for Bartlett smoothing. If a negative value is given this is taken as a signal to use an automatic window size of 4(T/100)^0.25, where T is the sample size.

If the --verbose option is chosen the results of the auxiliary regression are printed, along with the estimated variance of the random walk component of the variable.

The critical values shown for the test statistic are based on response surfaces estimated in the manner set out by Sephton (Economics Letters, 1995), which are more accurate for small samples than the values given in the original KPSS article. When the test statistic lies between the 10 percent and 1 percent critical values a p-value is shown; this is obtained by linear interpolation and should not be taken too literally. See the kpsscrit function for a means of obtaining these critical values programmatically.

Panel data

When the kpss command is used with panel data, to produce a panel unit root test, the applicable options and the results shown are somewhat different. While you may give a list of variables for testing in the regular time-series case, with panel data only one variable may be tested per command. And the --verbose option has a different meaning: it produces a brief account of the test for each individual time series (the default being to show only the overall result).

When possible, the overall test (null hypothesis: the series in question is stationary for all the panel units) is calculated using the method of Choi (Journal of International Money and Finance, 2001). This is not always straightforward, the difficulty being that while the Choi test is based on the p-values of the tests on the individual series, we do not currently have a means of calculating p-values for the KPSS test statistic; we must rely on a few critical values.

If the test statistic for a given series falls between the 10 percent and 1 percent critical values, we are able to interpolate a p-value. But if the test falls short of the 10 percent value, or exceeds the 1 percent value, we cannot interpolate and can at best place a bound on the global Choi test. If the individual test statistic falls short of the 10 percent value for some units but exceeds the 1 percent value for others, we cannot even compute a bound for the global test.

Menu path: /Variable/Unit root tests/KPSS test

labels

With the option --to-file, writes to the named file the labels for all series in the dataset, one per line. If no labels are present an error is flagged; if some series have labels and others do not, a blank line is printed for series with no label. The output file will be written in the currently set workdir, unless the filename string contains a full path specification.

With the option --from-file, reads the specified file (which should be plain text) and assigns labels to the series in the dataset, reading one label per line and taking blank lines to indicate blank labels.

The --delete option does what you'd expect: it removes all the series labels from the dataset.

Menu path: /Data/Variable labels

lad

Note that this method can be slow when the sample is large or there are many regressors; in that case it may be preferable to use the quantreg command. Given a dependent variable y and a list of regressors X, the following commands are basically equivalent, except that the quantreg method uses the faster Frisch–Newton algorithm and provides analytical rather than bootstrapped standard errors.

	lad y const X
	quantreg 0.5 y const X

Menu path: /Model/Robust estimation/Least Absolute Deviation

lags

	x_1 = x(t-1)
	x_2 = x(t-2)
	x_3 = x(t-3)
	x_4 = x(t-4)

This facility is also available as a function: see lags.

Menu path: /Add/Lags of selected variables

ldiff

	ld_x = log(x) - log(x(-1))
	ld_y = log(y) - log(y(-1))

leverage

Must follow an ols command. Calculates the leverage (h, which must lie in the range 0 to 1) for each data point in the sample on which the previous model was estimated. Displays the residual (u) for each observation along with its leverage and a measure of its influence on the estimates, uh/(1 – h). "Leverage points" for which the value of h exceeds 2k/n (where k is the number of parameters being estimated and n is the sample size) are flagged with an asterisk. For details on the concepts of leverage and influence see Davidson and MacKinnon (1993), Chapter 2.

DFFITS values are also computed: these are Studentized residuals (residuals divided by their standard errors) multiplied by the square root of h(1 – h). They give a measure of the difference in fit for observation i depending on whether or not that observation is included in the sample for estimation. For more on this point see chapter 12 of Maddala's Introduction to Econometrics or Belsley, Kuh and Welsch (1980). For more on Studentized residuals see the section headed Accessor matrix below.

If the --save flag is given with this command, the leverage, influence and DFFITS values are added to the current data set; in this context the --quiet flag may be used to suppress the printing of results. The default names of the saved series are, respectively, lever, influ and dffits. If series of these names already exist, what happens depends on whether the --overwrite option is given. If so, the existing series are overwritten; if not, the names will be adjusted to ensure uniqueness. In the latter case the newly generated series will always be the highest-numbered three series in the dataset.

After execution, the $test accessor returns the cross-validation criterion, which is defined as the sum of squared deviations of the dependent variable from its forecast value, the forecast for each observation being based on a sample from which that observation is excluded. (This is known as the leave-one-out estimator). For a broader discussion of the cross-validation criterion, see Davidson and MacKinnon's Econometric Theory and Methods, pages 685–686, and the references therein.

By default, if this command is invoked interactively a plot of the leverage and influence values is shown. This can be adjusted via the --plot option. The acceptable parameters to this option are none (to suppress the plot); display (to display a plot even when in script mode); or a file name. The effect of providing a file name is as described for the --output option of the gnuplot command.

Accessor matrix

Besides the --save option noted above, results from this command can be retrieved in the form of a three-column matrix via the $result accessor. The first two columns of this matrix contain leverage and influence values (as with --save) but the third column holds Studentized residuals rather than DFFITS values. These are "externally Studentized" or "jackknifed" residuals—that is, the standard error in the divisor for observation i uses the residual mean square with that observation omitted. Such a residual can be interpreted as a t statistic for the hypothesis that a 0/1 dummy variable coding specifically for observation i would have a true coefficient of zero. For further discussion of Studentized residuals see Chatterjee and Hadi (1986).

DFFITS values may be obtained from the $result matrix as follows:

	R = $result
	dffits = R[,3] .* sqrt(R[,1] ./ (1-R[,1]))

Or using series:

	series h = $result[,1]  # leverage
	series sr = $result[,3] # Studentized residual
	series dffits = sr * sqrt(h/(1-h))

Menu path: Model window, /Analysis/Influential observations

levinlin

Carries out the panel unit-root test described by Levin, Lin and Chu (2002). The null hypothesis is that all of the individual time series exhibit a unit root, and the alternative is that none of the series has a unit root. (That is, a common AR(1) coefficient is assumed, although in other respects the statistical properties of the series are allowed to vary across individuals.)

By default the test ADF regressions include a constant; to suppress the constant use the --nc option, or to add a linear trend use the --ct option. (See the adf command for explanation of ADF regressions.)

The (non-negative) order for the test (governing the number of lags of the dependent variable to include in the ADF regressions) may be given in either of two forms. If a scalar value is given, this is applied to all the individuals in the panel. The alternative is to provide a matrix containing a specific lag order for each individual; this must be a vector with as many elements as there are individuals in the current sample range. Such a matrix can be specified by name, or constructed using braces as illustrated in the last example above.

When the --verbose option is given, the following results are printed for each unit in the panel: delta, the coefficient on the lagged level in each ADF regression; s2e, the estimated variance of the innovations; and s2y, the estimated long-run variance of the differenced series.

Note that panel unit-root tests can also be conducted using the adf and kpss commands.

Menu path: /Variable/Unit root tests/Levin-Lin-Chu test

logistic

Arguments:	depvar indepvars
Options:	--ymax=value (specify maximum of dependent variable)
	--robust (robust standard errors)
	--cluster=clustvar (see logit for explanation)
	--vcv (print covariance matrix)
	--fixed-effects (see below)
	--quiet (don't print anything)
Examples:	logistic y const x
	logistic y const x --ymax=50

Logistic regression: carries out an OLS regression using the logistic transformation of the dependent variable,

In the case of panel data the specification may include individual fixed effects.

The dependent variable must be strictly positive. If all its values lie between 0 and 1, the default is to use a y^* value (the asymptotic maximum of the dependent variable) of 1; if its values lie between 0 and 100, the default y^* is 100.

If you wish to set a different maximum, use the --ymax option. Note that the supplied value must be greater than all of the observed values of the dependent variable.

The fitted values and residuals from the regression are automatically adjusted using the inverse of the logistic transformation:

where x represents either a fitted value or a residual from the OLS regression using the logistic dependent variable. The reported values are therefore comparable with the original dependent variable. The need for approximation arises because the inverse transformation is nonlinear and therefore does not conserve expectation.

The --fixed-effects option is applicable only if the dataset takes the form of a panel. In that case we subtract the group means from the logistic transform of the dependent variable and estimation proceeds as usual for fixed effects.

Note that if the dependent variable is binary, you should use the logit command instead.

Menu path: /Model/Limited dependent variable/Logistic

Menu path: /Model/Panel/FE logistic

logit

By default, standard errors are computed using the negative inverse of the Hessian. If the --robust flag is given, then QML or Huber–White standard errors are calculated instead. In this case the estimated covariance matrix is a "sandwich" of the inverse of the estimated Hessian and the outer product of the gradient; see chapter 10 of Davidson and MacKinnon (2004). But if the --cluster option is given, then "cluster-robust" standard errors are produced; see chapter 22 of the Gretl User's Guide for details.

By default the pseudo-R-squared statistic suggested by McFadden (1974) is shown, but in the binary case if the --estrella option is given, the variant recommended by Estrella (1998) is shown instead. This variant arguably mimics more closely the properties of the regular R² in the context of least-squares estimation.

If the dependent variable is binary, logit coefficients represent the log of the odds ratio (the ratio of the probability of y = 1 to that of y = 0). In this case the $model bundle available after estimation includes an the extra element named oddsratios, a matrix with four columns holding the exponentiated coefficient (odds ratio) plus standard error computed via the delta method and 95 percent confidence interval, for each regressor. Note, however, that the confidence interval is calculated as the exponential of that for the original coefficient.

If the dependent variable is not binary but is discrete, then by default it is interpreted as an ordinal response, and Ordered Logit estimates are obtained. However, if the --multinomial option is given, the dependent variable is interpreted as an unordered response, and Multinomial Logit estimates are produced. (In either case, if the variable selected as dependent is not discrete an error is flagged.) The accessor $allprobs is available after estimation, to get a matrix containing the estimated probabilities of the outcomes at each observation (observations in rows, outcomes in columns).

If you want to use logit for analysis of proportions (where the dependent variable is the proportion of cases having a certain characteristic, at each observation, rather than a 1 or 0 variable indicating whether the characteristic is present or not) you should not use the logit command, but rather construct the logit variable, as in

	series lgt_p = log(p/(1 - p))

and use this as the dependent variable in an OLS regression. See chapter 12 of Ramanathan (2002).

Menu path: /Model/Limited dependent variable/Logit

logs

loop

See chapter 13 of the Gretl User's Guide for full details and examples. The effect of the --progressive option (which is designed for use in Monte Carlo simulations) is explained there. Not all gretl commands may be used within a loop; the commands available in this context are also set out there.

By default, execution of commands proceeds more quietly within loops than in other contexts. If you want more feedback on what's going on in a loop, give the --verbose option.

mahal

Argument:	varlist
Options:	--quiet (don't print anything)
	--save (add distances to the dataset)
	--vcv (print covariance matrix)

Computes the Mahalanobis distances between the series in varlist. The Mahalanobis distance is the distance between two points in a k-dimensional space, scaled by the statistical variation in each dimension of the space. For example, if p and q are two observations on a set of k variables with covariance matrix C, then the Mahalanobis distance between the observations is given by

where (p – q) is a k-vector. This reduces to Euclidean distance if the covariance matrix is the identity matrix.

The space for which distances are computed is defined by the selected variables. For each observation in the current sample range, the distance is computed between the observation and the centroid of the selected variables. This distance is the multidimensional counterpart of a standard z-score, and can be used to judge whether a given observation "belongs" with a group of other observations.

If the --vcv option is given, the covariance matrix and its inverse are printed. If the --save option is given, the distances are saved to the dataset under the name mdist (or mdist1, mdist2 and so on if there is already a variable of that name).

Menu path: /View/Mahalanobis distances

---

makepkg

markers

The options --to-file and --to-array provide means of saving the observation marker strings from the current dataset, either to a named file or a named array. If no such strings are present an error is flagged. In the file case output will be written in the current workdir unless the filename string contains a full path specification. The markers are written one per line. In the array case, if name is the identifier of an existing array of strings it will be overwritten, otherwise a new array will be created.

With the option --from-file, reads the specified file (which should be UTF-8 text) and assigns observation markers to the rows in the dataset, reading one marker per line. In general there should be at least as many markers in the file as observations in the dataset, but if the dataset is a panel it is also acceptable if the number of markers in the file matches the number of cross-sectional units (in which case the markers are repeated for each time period.) The --from-array option works similarly, reading from a named array of strings.

The option --from-series offers a convenient way of creating observation markers by copying from a string-valued series. An error is flagged if the specified series does not have string values.

The --delete option does what you'd expect: it removes the observation marker strings from the dataset.

Menu path: /Data/Observation markers

meantest

By default the test statistic is calculated on the assumption that the variances are equal for the two variables. With the --unequal-vars option the variances are assumed to be different; in this case the degrees of freedom for the test statistic are approximated as per Satterthwaite (1946).

Menu path: /Tools/Test statistic calculator

midasreg

Carries out least-squares estimation (either NLS or OLS, depending on the specification) of a MIDAS (Mixed Data Sampling) model. Such models include one or more independent variables that are observed at a higher frequency than the dependent variable; for a good brief introduction see Armesto, Engemann and Owyang (2010).

The variables in indepvars should be of the same frequency as the dependent variable. This list should usually include const or 0 (intercept) and typically includes one or more lags of the dependent variable. The high-frequency terms are given after a semicolon; each one takes the form of a number of comma-separated arguments within parentheses, prefixed by either mds or mdsl.

mds: this variant generally requires 5 arguments, as follows: the name of a MIDAS list, two integers giving the minimum and maximum high-frequency lags, an integer between 0 and 4 (or string, see below) specifying the type of parameterization to use, and the name of a vector holding initial values of the parameters. The example below calls for lags 3 to 11 of the high-frequency series represented by the list X, using parameterization type 1 (exponential Almon, see below) with initializer theta.

	mds(X, 3, 11, 1, theta)

mdsl: generally requires 3 arguments: the name of a list of MIDAS lags, an integer (or string, see below) to specify the type of parameterization and the name of an initialization vector. In this case the minimum and maximum lags are implicit in the initial list argument. In the example below Xlags should be a list which already holds all the required lags; such a list can be constructed using the hflags function.

	mdsl(XLags, 1, theta)

The supported types of parameterization are shown below; in the context of mds and mdsl specifications these may be given in the form of numeric codes or the double-quoted strings shown after the numbers.

0 or "umidas": unrestricted MIDAS or U-MIDAS (each lag has its own coefficient)

1 or "nealmon": normalized exponential Almon; requires at least one parameter, commonly uses two

2 or "beta0": normalized beta with a zero last lag; requires exactly two parameters

3 or "betan": normalized beta with non-zero last lag; requires exactly three parameters

4 or "almonp": (non-normalized) Almon polynomial; requires at least one parameter

5 or "beta1": as beta0, but with the first parameter fixed at 1, leaving a single free parameter.

When the parameterization is U-MIDAS, the final initializer argument is not required. In other cases you can request an automatic initialization by substituting one or other of these two forms for the name of an initial parameter vector:

• The keyword null: this is accepted if the parameterization has a fixed number of terms (the beta cases, with 2 or 3 parameters). It's also accepted for the exponential Almon case, implying the default of 2 parameters.

• An integer value giving the required number of parameters.

The estimation method used by this command depends on the specification of the high-frequency terms. In the case of U-MIDAS the method is OLS, otherwise it is nonlinear least squares (NLS). When the normalized exponential Almon or normalized beta parameterization is specified, the default NLS method is a combination of constrained BFGS and OLS, but the --levenberg option can be given to force use of the Levenberg–Marquardt algorithm.

Menu path: /Model/Univariate time series/MIDAS

mle

This help text assumes use of the default BFGS maximizer. For information on using Newton's method please see chapter 26 of the Gretl User's Guide.

Simple example: Suppose we have a series X with values 0 or 1 and we wish to obtain the maximum likelihood estimate of the probability, p, that X = 1. (In this simple case we can guess in advance that the ML estimate of p will simply equal the proportion of Xs equal to 1 in the sample.)

The parameter p must first be added to the dataset and given an initial value. For example, scalar p = 0.5.

We then construct the MLE command block:

	mle loglik = X*log(p) + (1-X)*log(1-p)
	  deriv p = X/p - (1-X)/(1-p)
	end mle

The first line above specifies the log-likelihood function. It starts with the keyword mle, then a dependent variable is specified and an expression for the log-likelihood is given (using the same syntax as in the genr command). The next line (which is optional) starts with the keyword deriv and supplies the derivative of the log-likelihood function with respect to the parameter p. If no derivatives are given, you should include a statement using the keyword params which identifies the free parameters: these are listed on one line, separated by spaces and can be either scalars, or vectors, or any combination of the two. For example, the above could be changed to:

	mle loglik = X*log(p) + (1-X)*log(1-p)
	  params p
	end mle

in which case numerical derivatives would be used.

Note that any option flags should be appended to the ending line of the MLE block. For example:

	mle loglik = X*log(p) + (1-X)*log(1-p)
	  params p
	end mle --quiet

Covariance matrix and standard errors

If the log-likelihood function returns a series or vector giving per-observation values then estimated standard errors are by default based on the Outer Product of the Gradient (OPG), while if the --hessian option is given they are instead based on the negative inverse of the Hessian, which is approximated numerically. If the --robust option is given, a QML estimator is used (namely, a sandwich of the negative inverse of the Hessian and the OPG). If the hac parameter is added to this option the OPG is augmented in the manner of Newey and West to allow for serial correlation of the gradient. (This only makes sense with time-series data.) However, if the log-likelihood function just returns a scalar value, the OPG is not available (and so neither is the QML estimator), and standard errors are of necessity computed using the numerical Hessian.

In the event that you just want the primary parameter estimates you can give the --auxiliary option, which suppresses computation of the covariance matrix and standard errors; this will save some CPU cycles and memory usage.

Checking analytical derivatives

If you supply analytical derivatives, by default gretl runs a numerical check on their plausibility. Occasionally this may produce false positives, instances where correct derivatives appear to be wrong and estimation is refused. To counter this, or to achieve a little extra speed, you can give the option --no-gradient-check. Obviously, you should do this only if you are confident that the gradient you have specified is right.

Parameter names

In estimating a nonlinear model it is often convenient to name the parameters tersely. In printing the results, however, it may be desirable to use more informative labels. This can be achieved via the additional keyword param_names within the command block. For a model with k parameters the argument following this keyword should be a double-quoted string literal holding k space-separated names, the name of a string variable that holds k such names, or the name of an array of k strings.

For an in-depth description of mle please refer to chapter 26 of the Gretl User's Guide.

Menu path: /Model/Maximum likelihood

modeltab

Manipulates the gretl "model table". See chapter 3 of the Gretl User's Guide for details. The sub-commands have the following effects: add adds the last model estimated to the model table, if possible; show displays the model table in a window; and free clears the table.

To call for printing of the model table, use the flag --output= plus a filename. If the filename has the suffix ".tex", the output will be in TeX format; if the suffix is ".rtf" the output will be RTF; otherwise it will be plain text. In the case of TeX output the default is to produce a "fragment", suitable for inclusion in a document; if you want a stand-alone document instead, use the --complete option, for example

	modeltab --output="myfile.tex" --complete

The --options= flag, which requires the name of a gretl bundle, can be used to control certain aspects of the formatting of the model table. The following keys are recognized:

• colheads: integer from 1 to 4, selects from the four supported column-head styles: Arabic numbering, Roman numbering, alphabetical, or using the names under which models have been saved. The default is 1 (Arabic numbering).

• tstats: boolean, replace standard errors with t-statistics or not (default 0).

• pvalues: boolean, include P-values or not (default 0).

• asterisks: boolean, show significance-level asterisks or not (default 1).

• digits: integer from 2 to 6, selects the number of significant digits shown (default 4).

• decplaces: integer from 2 to 6, selects the number of decimal places shown.

Note that the last two keys are mutually exclusive. They offer alternative ways of specifying the precision to which numerical values are shown: either in terms of significant digits or decimal places. The default is 4 significant digits.

An options bundle can be supplied via a stand-alone command (as in the last of the examples above) or it can be combined with the show action or --output option. For example, the following script builds a simple model table and displays it, with P-values shown instead of significance asterisks:

	open data9-7
	ols 1 0 2 3 4
	modeltab add
	ols 1 0 2 3
	modeltab add
	bundle myopts = _(pvalues=1, asterisks=0)
	modeltab show --options=myopts

Menu path: Session icon window, Model table icon

modprint

The output file will be written in the currently set workdir, unless the filename string contains a full path specification.

modtest

Must immediately follow an estimation command. The discussion below applies to usage of the command following estimation of a single-equation model; see chapter 32 of the Gretl User's Guide for an account of how modtest operates after estimation of a VAR.

Depending on the option given, this command carries out one of the following: the Doornik–Hansen test for the normality of the error term; a Lagrange Multiplier test for nonlinearity (logs or squares); White's test (with or without cross-products) or the Breusch–Pagan test (Breusch and Pagan, 1979) for heteroskedasticity; the LMF test for serial correlation (Kiviet, 1986); a test for ARCH (Autoregressive Conditional Heteroskedasticity; see also the arch command); a test of the common factor restriction implied by AR(1) estimation; or a test for cross-sectional dependence in panel-data models. With the exception of the normality, common factor and cross-sectional dependence tests most of the options are only available for models estimated via OLS, but see below for details regarding two-stage least squares.

The optional order argument is relevant only in case the --autocorr or --arch options are selected. The default is to run these tests using a lag order equal to the periodicity of the data, but this can be adjusted by supplying a specific lag order.

The --robust option applies only when the Breusch–Pagan test is selected; its effect is to use the robust variance estimator proposed by Koenker (1981), making the test less sensitive to the assumption of normality.

The --panel option is available only when the model is estimated on panel data: in this case a test for groupwise heteroskedasticity is performed (that is, for a differing error variance across the cross-sectional units).

The --comfac option is available only when the model is estimated via an AR(1) method such as Hildreth–Lu. The auxiliary regression takes the form of a relatively unrestricted dynamic model, which is used to test the common factor restriction implicit in the AR(1) specification.

The --xdepend option is available only for models estimated on panel data. The test statistic is that developed by Pesaran (2004). The null hypothesis is that the error term is independently distributed across the cross-sectional units or individuals.

By default, the program prints the auxiliary regression on which the test statistic is based, where applicable. This may be suppressed by using the --quiet flag (minimal printed output) or the --silent flag (no printed output). The test statistic and its p-value may be retrieved using the accessors $test and $pvalue respectively.

When a model has been estimated by two-stage least squares (see tsls), the LM principle breaks down and gretl offers some equivalents: the --autocorr option computes Godfrey's test for autocorrelation (Godfrey, 1994) while the --white option yields the HET1 heteroskedasticity test (Pesaran and Taylor, 1999).

For additional diagnostic tests on models, see chow, cusum, reset and qlrtest.

Menu path: Model window, /Tests

mpi

The mpi command starts a block of statements (which must be ended with end mpi) to be executed using MPI (Message Passing Interface) parallelization. See gretl-mpi.pdf for a full account of this facility.

mpols

	export GRETL_MP_BITS=1024

	mpols y 0 x ; 2 3 4

negbin

The optional offset series works in the same way as for the poisson command. The Poisson model is a restricted form of the Negative Binomial in which α = 0 by construction.

By default, standard errors are computed using a numerical approximation to the Hessian at convergence. But if the --opg option is given the covariance matrix is based on the Outer Product of the Gradient (OPG), or if the --robust option is given QML standard errors are calculated, using a "sandwich" of the inverse of the Hessian and the OPG.

Menu path: /Model/Limited dependent variable/Count data

nls

	1   open greene11_3.gdt
	2   ols C 0 Y
	3   scalar a = $coeff(0)
	4   scalar b = $coeff(Y)
	5   scalar g = 1.0
	6   nls C = a + b * Y^g
	7    deriv a = 1
	8    deriv b = Y^g
	9    deriv g = b * Y^g * log(Y)
	10  end nls --vcv

	params a b g

For further details on NLS estimation please see chapter 25 of the Gretl User's Guide.

Menu path: /Model/Nonlinear Least Squares

normtest

The test statistic and its p-value may be retrieved using the accessors $test and $pvalue. Please note that if the --all option is given, the result recorded is that from the Doornik–Hansen test.

Menu path: /Variable/Normality test

nulldata

Establishes a "blank" data set, containing only a constant and an index variable, with periodicity 1 and the specified number of observations. This may be used for simulation purposes: functions such as uniform() and normal() will generate artificial series from scratch to fill out the data set. This command may be useful in conjunction with loop. See also the "seed" option to the set command.

By default, this command cleans out all data in gretl's current workspace: not only series but also matrices, scalars, strings, etc. If you give the --preserve option, however, any currently defined variables other than series are retained.

Menu path: /File/New data set

ols

Besides coefficient estimates and standard errors, the program also prints p-values for t (two-tailed) and F-statistics. A p-value below 0.01 indicates statistical significance at the 1 percent level and is marked with ***. ** indicates significance between 1 and 5 percent and * indicates significance between the 5 and 10 percent levels. Model selection statistics (the Akaike Information Criterion or AIC and Schwarz's Bayesian Information Criterion) are also printed. The formula used for the AIC is that given by Akaike (1974), namely minus two times the maximized log-likelihood plus two times the number of parameters estimated.

If the option --no-df-corr is given, the usual degrees of freedom correction is not applied when calculating the estimated error variance (and hence also the standard errors of the parameter estimates).

The option --print-final is applicable only in the context of a loop. It arranges for the regression to be run silently on all but the final iteration of the loop. See chapter 13 of the Gretl User's Guide for details.

Various internal variables may be retrieved following estimation. For example

	series uh = $uhat

saves the residuals under the name uh. See the "accessors" section of the gretl function reference for details.

The specific formula ("HC" version) used for generating robust standard errors when the --robust option is given can be adjusted via the set command. The --jackknife option has the effect of selecting an hc_version of 3a. The --cluster overrides the selection of HC version, and produces robust standard errors by grouping the observations by the distinct values of clustvar; see chapter 22 of the Gretl User's Guide for details.

Menu path: /Model/Ordinary Least Squares

omit

This command must follow an estimation command. In its primary form, it calculates a Wald test for the joint significance of the variables in varlist, which should be a subset (though not necessarily a proper subset) of the independent variables in the model last estimated. The results of the test may be retrieved using the accessors $test and $pvalue.

Unless the restriction removes all the original regressors, by default the restricted model is estimated and it replaces the original as the "current model" for the purposes of, for example, retrieving the residuals as $uhat or doing further tests. This behavior may be suppressed via the --test-only option.

By default the F-form of the Wald test is recorded; the --chi-square option may be used to record the chi-square form instead.

If the restricted model is both estimated and printed, the --vcv option has the effect of printing its covariance matrix, otherwise this option is ignored.

Alternatively, if the --auto flag is given, sequential elimination is performed: at each step the variable with the highest p-value is omitted, until all remaining variables have a p-value no greater than some cutoff. The default cutoff is 10 percent (two-sided); this can be adjusted by appending "=" and a value between 0 and 1 (with no spaces), as in the fourth example above. If varlist is given this process is confined to the listed variables, otherwise all regressors aside from the constant are treated as candidates for omission. Note that the --auto and --test-only options cannot be combined.

Menu path: Model window, /Tests/Omit variables

open

Opens a data file or database—see chapter 4 of the Gretl User's Guide for an explanation of this distinction. The effect is somewhat different in the two cases. When a data file is opened, its content is read into gretl's workspace, replacing the current dataset (if any). To add data to the current dataset instead of replacing, see append or (for greater flexibility) join. When a database is opened this does not immediately load any data; rather, it sets the source for subsequent invocations of the data command, which is used to import selected series. For specifics regarding databases see the section headed "Opening a database" below.

If filename is not given as a full path, gretl will search some relevant paths to try to find the file, with workdir as a first choice. If no filename suffix is given (as in the first example above), gretl assumes a native datafile with suffix .gdt. Based on the name of the file and various heuristics, gretl will try to detect the format of the data file (native, plain text, CSV, MS Excel, Stata, SPSS, etc.).

If the --frompkg option is used, gretl will look for the specified data file in the subdirectory associated with the function package specified by pkgname.

If the filename argument takes the form of a URI starting with http:// or https://, then gretl will attempt to download the indicated data file before opening it.

By default, opening a new data file clears the current gretl session, which includes deletion of all named variables, including matrices, scalars and strings. If you wish to keep your currently defined variables (other than series, which are necessarily cleared out), use the --preserve option.

Spreadsheet files

When opening a data file in a spreadsheet format (Gnumeric, Open Document or MS Excel), you may give up to three additional parameters following the filename. First, you can select a particular worksheet within the file. This is done either by giving its (1-based) number, using the syntax, e.g., --sheet=2, or, if you know the name of the sheet, by giving the name in double quotes, as in --sheet="MacroData". The default is to read the first worksheet. You can also specify a column and/or row offset into the worksheet via, e.g.,

	--coloffset=3 --rowoffset=2

which would cause gretl to ignore the first 3 columns and the first 2 rows. The default is an offset of 0 in both dimensions, that is, to start reading at the top-left cell.

Delimited text files

With plain text files, gretl generally expects to find the data columns delimited in some standard manner (generally via comma, tab, space or semicolon). By default gretl looks for observation labels or dates in the first column if its heading is empty or is a suggestive string such as "year", "date" or "obs". You can prevent gretl from treating the first column specially by giving the --all-cols option.

Fixed format text

A "fixed format" text data file is one without column delimiters, but in which the data are laid out according to a known set of specifications such as "variable k occupies 8 columns starting at column 24". To read such files, you should append a string --fixed-cols=colspec, where colspec is composed of comma-separated integers. These integers are interpreted as a set of pairs. The first element of each pair denotes a starting column, measured in bytes from the beginning of the line with 1 indicating the first byte; and the second element indicates how many bytes should be read for the given field. So, for example, if you say

	open fixed.txt --fixed-cols=1,6,20,3

then for variable 1 gretl will read 6 bytes starting at column 1; and for variable 2, 3 bytes starting at column 20. Lines that are blank, or that begin with #, are ignored, but otherwise the column-reading template is applied, and if anything other than a valid numerical value is found an error is flagged. If the data are read successfully, the variables will be named v1, v2, etc. It's up to the user to provide meaningful names and/or descriptions using the commands rename and/or setinfo.

By default, when you import a file that contains string-valued series, a text box will open showing you the contents of string_table.txt, a file which contains the mapping between strings and their numeric coding. You can suppress this behavior via the --quiet option.

Loading selected series

Use of open with a data file argument (as opposed to the database case, see below) generally implies loading all series from the specified file. However, in the case of native gretl files (gdt and gdtb) only, it is possible to specify by name a subset of series to load. This is done via the --select option, which requires an accompanying argument in one of three forms: the name of a single series; a list of names, separated by spaces and enclosed in double quotes; or the name of an array of strings. Examples:

	# single series
	open somefile.gdt --select=x1
	# more than one series
	open somefile.gdt --select="x1 x5 x27"
	# alternative method
	strings Sel = defarray("x1", "x5", "x27")
	open somefile.gdt --select=Sel

Opening a database

As mentioned above, the open command can be used to open a database file for subsequent reading via the data command. Supported file-types are native gretl databases, RATS 4.0 and PcGive.

Besides reading a file of one of these types on the local machine, three further cases are supported. First, if the --www option is given, gretl will try to access a native gretl database of the given name on the gretl server—for instance the Federal Reserve interest rates database fedbog.bin in the third example shown above. Second, the command "open dbnomics" can be used to set DB.NOMICS as the source for database reads; on this see dbnomics for gretl. Third, if the --odbc option is given gretl will try to access an ODBC database. This option is explained at length in chapter 42 of the Gretl User's Guide.

Menu path: /File/Open data

orthdev

outfile

The first variant shown above sends output to a file named by the filename argument. By default a new file is created (or an existing one is overwritten). The output file will be written in the currently set workdir, unless the filename string contains a full path specification to the contrary. If you wish to append output to an existing file instead, use the --append flag.

A simple example follows, where the output from a particular regression is written to a named file.

	open data4-10
	outfile regress.txt
	  ols ENROLL 0 CATHOL INCOME COLLEGE
	end outfile

Special dummy filenames

Three special values for filename are supported, as follows:

• null: printed output is suppressed until redirection is ended.

• stdout: output is redirected to the "standard output" stream.

• stderr: output is redirected to the "standard error" stream.

Diversion to a string buffer

The --buffer option is used to store output in a string variable. The required parameter for this option must be the name of an existing string variable, whose content will be over-written. We show below the example given above, revised to write to a string. In this case printing model_out will display the redirected output.

	open data4-10
	string model_out = ""
	outfile --buffer=model_out
	  ols ENROLL 0 CATHOL INCOME COLLEGE
	end outfile
	print model_out

Diversion to a temporary file

The --tempfile option is used to direct output to a temporary file, with an automatically constructed name that is guaranteed to be unique, in the user's "dot" directory. As in the redirection to buffer case, the option parameter should be the name of a string variable: in this case its content is over-written with the name of the temporary file. Please note: files written to the dot directory are cleaned up on exit from the program, so don't use this form if you want the output to be preserved after your gretl session.

We repeat the simple example from above, with a couple of extra lines to illustrate the points that strvar tells you where the output went, and you can retrieve it using the readfile function.

	open data4-10
	string mytemp
	outfile --tempfile=mytemp
	  ols ENROLL 0 CATHOL INCOME COLLEGE
	end outfile
	printf "Output went to %s\n", mytemp
	printf "The output was:\n%s\n", readfile(mytemp)
	# clean up if the file is no longer needed
	remove(mytemp)

In some cases you may wish to exercise some control over the name of the temporary file. You can do this by supplying a string variable which contains six consecutive Xs, as in

	string mytemp = "tmpXXXXXX.csv"
	outfile --tempfile=mytemp
	...

In this case XXXXXX will be replaced by random characters that ensure uniqueness of the filename, but the ".csv" suffix will be preserved. As in the simpler case above, the file is automatically written into the user's "dot" directory and the content of the string variable passed via the option flag is modified to hold the full path to the temporary file.

Quietness

The effect of the --quiet option is to turn off the echoing of commands and the printing of auxiliary messages while output is redirected. It is equivalent to doing

	set echo off
	set messages off

except that when redirection is ended the original values of the echo and messages variables are restored. This option is available in all cases.

Decimal character

The effect of the --decpoint option is ensure that the decimal point character (as opposed to comma) is in force while output is redirected. When the outfile block ends the decimal character reverts to whatever was in place before it. This option is especially useful if the text file to be created is meant as an input for some other program that requires digits to follow the English convention, as would be the case, for example, of a gnuplot or R script.

Levels of redirection

In general only one file can be opened in this way at any given time, so calls to this command cannot be nested. However, use of this command is permitted inside user-defined functions (provided the output file is also closed from inside the same function) such that output can be temporarily diverted and then given back to an original output file, in case outfile is currently in use by the caller. For example, the code

	function void f (string s)
	    outfile inner.txt
	      print s
	    end outfile
	end function

	outfile outer.txt --quiet
	  print "Outside"
	  f("Inside")
	  print "Outside again"
	end outfile

will produce a file called "outer.txt" containing the two lines

	Outside
	Outside again

and a file called "inner.txt" containing the line

	Inside

panel

If the --random-effects flag is given, random effects estimates are computed, by default using the method of Swamy and Arora (1972). In this case (only) the option --matrix-diff forces use of the matrix-difference method (as opposed to the regression method) for carrying out the Hausman test for the consistency of the random effects estimator. Also specific to the random effects estimator is the --nerlove flag, which selects the method of Nerlove (1971) as opposed to Swamy and Arora.

Alternatively, if the --unit-weights flag is given, the model is estimated via weighted least squares, with the weights based on the residual variance for the respective cross-sectional units in the sample. In this case (only) the --iterate flag may be added to produce iterative estimates: if the iteration converges, the resulting estimates are Maximum Likelihood.

As a further alternative, if the --between flag is given, the between-groups model is estimated (that is, an OLS regression using the group means).

The default means of calculating robust standard errors in panel-data models is the HAC estimator of Arellano (2003) (clustered by panel unit). Alternatives are "Panel Corrected Standard Errors" (Beck and Katz, 1995) and "Spatial Correlation Consistent" standard errors (Driscoll and Kraay, 1998). These can be selected via the command set panel_robust with arguments pcse and scc, respectively. Other alternatives to these three options are available via the --cluster option; please see chapter 22 of the Gretl User's Guide for details. When robust standard errors are specified the joint F test on the fixed effects is performed using the robust method of Welch (1951).

The --unbalanced option is available only for random effects models: it can be used to choose an ANOVA method for use with an unbalanced panel. By default gretl uses the Swamy–Arora method as for balanced panels, except that the harmonic mean of the individual time-series lengths is used in place of a common T. Under this option you can specify either bc, to use the method of Baltagi and Chang (1994), or stata, to emulate the sa option to the xtreg command in Stata.

For more details on panel estimation, please see chapter 23 of the Gretl User's Guide.

Menu path: /Model/Panel

panplot

	smpl 1 100 --unit
	panplot x --overlay
	smpl full

The --output=filename option can be used to control the form and destination of the output; see the gnuplot command for details.

panspec

On successful completion the accessors $test and $pvalue retrieve 3-vectors holding test statistics and p-values for the three tests noted above: poolability (Wald), poolability (Breusch–Pagan), and Hausman. If you just want the results in this form you can give the --quiet option to skip printed output.

Note that after estimating the random effects specification via the panel command, the Hausman test is automatically carried out and the results can be retrieved via the $hausman accessor.

Menu path: Model window, /Tests/Panel specification

pca

See also the princomp function.

Menu path: /View/Principal components

pergm

By default, if gretl is not in batch mode a plot of the periodogram is shown. This can be adjusted via the --plot option. The acceptable parameters to this option are none (to suppress the plot); display (to display a plot even when in batch mode); or a file name. The effect of providing a file name is as described for the --output option of the gnuplot command.

Menu path: /Variable/Periodogram

pkg

install: In the most basic form, with no option flag and the pkgname argument given as the "plain" name of a gretl function package (as in the first example above), the effect is to download the specified package from the gretl server (unless pkgname starts with http://) and install it on the local machine. In this case it is not necessary to supply a filename extension. If the --local option is given, however, pkgname should be the path to an uninstalled package file on the local machine, with the correct extension (.gfn or .zip). In this case the effect is to copy the file into place (gfn), or unzip it into place (zip), "into place" meaning where the include command will find it.

query: The default effect is to print basic information about the specified package (author, version, etc.). If the package includes extra resources (data files and/or additional scripts) a listing of these files is included. If the --quiet option is appended nothing is printed; the package information is instead stored in the form of a gretl bundle, which can be accessed via $result. If no information can be found this bundle will be empty.

run-sample: Provides a command-line means of running the sample script included in the specified package.

unload: pkgname should be given in plain form, without path or suffix as in the last example above. The effect is to unload the package in question from gretl's memory, if it is currently loaded, and also to remove it from the GUI menu to which it is attached, if any.

remove: performs the actions noted for unload and in addition deletes the file(s) associated with the package from disk.

index: is a special case in which pkgname must be replaced by the keyword "addons": the effect is to update the index of the standard packages known as addons. Such updating is performed automatically from time to time but in some cases a manual update may be useful. In this case the --verbose flag produces a printout of where gretl has searched and what it has found. To be clear, here's the way to get full indexing output:

	pkg index addons --verbose

Data file packages

Besides its usage with function packages, the pkg install command can also be used with data file packages of the tar.gz type, as listed at https://gretl.sourceforge.net/gretl_data.html. For example, to install the Verbeek data files one can do

        pkg install verbeek.tar.gz

Note that install is the only action supported operation for such files.

Staging

The --staging option is a convenience item for developers and is available only in conjunction with the install action as applied to a function package. Its effect is that the package in question is downloaded from the staging area at sourceforge rather than the public area. Packages in staging are not yet approved for general use, so ignore this option unless you know what you're doing.

Menu path: /File/Function packages/On server

plot

The plot block provides an alternative to the gnuplot command which may be more convenient when you are producing an elaborate plot (with several options and/or gnuplot commands to be inserted into the plot file). In addition to the following explanation, please also refer to chapter 6 of the Gretl User's Guide for some further examples.

A plot block starts with the command-word plot. This is commonly followed by a data argument, which specifies data to be plotted: this should be the name of a list, a matrix, or a single series. If no input data are specified the block must contain at least one directive to plot a formula instead; such directives may be given via literal or printf lines (see below).

If a list or matrix is given, the last element (list) or column (matrix) is assumed to be the x-axis variable and the other(s) the y-axis variable(s), unless the --time-series option is given in which case all the specified data go on the y axis. The option of supplying a single series name is restricted to time-series data, in which case it is assumed that a time-series plot is wanted; otherwise an error is flagged.

The starting line may be prefixed with the "savename <-" apparatus to save a plot as an icon in the GUI program. The block ends with end plot.

Inside the block you have zero or more lines of these types, identified by an initial keyword:

• option: specify a single option.

• options: specify multiple options on a single line, separated by spaces.

• literal: a command to be passed to gnuplot literally.

• printf: a printf statement whose result will be passed to gnuplot literally.

Note that besides --output and --outbuf, which should be appended to the line that ends the block, all the options supported by the gnuplot command are also supported by plot, but should be given within the block using the syntax described above. In this context it is not necessary to supply the customary double-dash before the option specifier. For details on the effects of the various options see gnuplot.

The intended use of the plot block is best illustrated by example:

	string title = "My title"
	string xname = "My x-variable"
	plot plotmat
	    options with-lines fit=none
	    literal set linetype 3 lc rgb "#0000ff"
	    literal set nokey
	    printf "set title '%s'", title
	    printf "set xlabel '%s'", xname
	end plot --output=display

This example assumes that plotmat is the name of a matrix with at least 2 columns (or a list with at least two members). Note that it is considered good practice to place the --output option (only) on the last line of the block; other options should be placed within the block.

Plotting without data

The following example shows a case of specifying a plot without a data source.

	plot
	    literal set title 'CRRA utility'
	    literal set xlabel 'c'
	    literal set ylabel 'u(c)'
	    literal set xrange[1:3]
	    literal set key top left
	    literal crra(x,s) = (x**(1-s) - 1)/(1-s)
	    printf "plot crra(x, 0) t 'sigma=0', \\"
	    printf " log(x) t 'sigma=1', \\"
	    printf " crra(x,3) t 'sigma=3"
	end plot --output=display

poisson

Arguments:	depvar indepvars [ ; offset ]
Options:	--robust (robust standard errors)
	--cluster=clustvar (see logit for explanation)
	--vcv (print covariance matrix)
	--verbose (print details of iterations)
	--quiet (don't print results)
Examples:	poisson y 0 x1 x2
	poisson y 0 x1 x2 ; S
	See also camtriv.inp, greene19_3.inp

Estimates a poisson regression. The dependent variable is taken to represent the occurrence of events of some sort, and must take on only non-negative integer values.

If a discrete random variable Y follows the Poisson distribution, then

for y = 0, 1, 2,.... The mean and variance of the distribution are both equal to v. In the Poisson regression model, the parameter v is represented as a function of one or more independent variables. The most common version (and the only one supported by gretl) has

or in other words the log of v is a linear function of the independent variables.

Optionally, you may add an "offset" variable to the specification. This is a scale variable, the log of which is added to the linear regression function (implicitly, with a coefficient of 1.0). This makes sense if you expect the number of occurrences of the event in question to be proportional, other things equal, to some known factor. For example, the number of traffic accidents might be supposed to be proportional to traffic volume, other things equal, and in that case traffic volume could be specified as an "offset" in a Poisson model of the accident rate. The offset variable must be strictly positive.

By default, standard errors are computed using the negative inverse of the Hessian. If the --robust flag is given, then QML or Huber–White standard errors are calculated instead. In this case the estimated covariance matrix is a "sandwich" of the inverse of the estimated Hessian and the outer product of the gradient.

See also negbin.

Menu path: /Model/Limited dependent variable/Count data

print

Please note that print is a rather "basic" command (primarily intended for printing the values of series); see printf and eval for more advanced, and less restrictive, alternatives.

In the first variant shown above (also see the first example), varlist should be a list of series (either a named list or a list specified via the names or ID numbers of series, separated by spaces). In that case this command prints the values of the listed series. By default the data are printed "by variable", but if the --byobs flag is added they are printed by observation. When printing by observation, the default is to show the date (with time-series data) or the observation marker string (if any) at the start of each line. The --no-dates option suppresses the printing of dates or markers; a simple observation number is shown instead. See the final paragraph of this entry for the effect of the --midas option (which applies only to a named list of series).

If no argument is given (the second variant shown above) then the action is similar to the first case except that all series in the current dataset are printed. The supported options are as decribed above.

The third variant (with the object-names argument; see the second example) expects a space-separated list of names of primary gretl objects other than series (scalars, matrices, strings, bundles, arrays). The value(s) of these objects are displayed. In the case of bundles, their members are sorted by type and alphabetically.

In the fourth form (third example), string-literal should be a string enclosed in double-quotes (and there should be nothing else following on the command line). The string in question is printed, followed by a newline character.

The --range option can be used to control the amount of information printed. The start and stop (integer) values refer to observations for series and lists, rows for matrices, elements for arrays, and lines of text for strings. In all cases the minimum start value is 1 and the maximum stop value is the "row-wise size" of the object in question. Negative values for these indices are taken to indicate a count back from the end. The indices may be given in numeric form or as the names of predefined scalar variables. If start is omitted that is taken as an implicit 1 and if stop is omitted that means go all the way to the end. Note that with series and lists the indices are relative to the current sample range.

The --tree option is specific to the printing of a gretl bundle: the effect is that if the specified bundle contains further bundles, or arrays of bundles, their contents are listed. Otherwise only the top-level members of the bundle are listed.

The --midas option is specific to the printing of a list of series, and moreover it is specific to datasets that contain one or more high-frequency series, each represented by a MIDAS list. If one such list is given as argument and this option is appended, the series is printed by observation at its "native" frequency.

Menu path: /Data/Display values

printf

	ols 1 0 2 3
	scalar b = $coeff[2]
	scalar se_b = $stderr[2]
	printf "b = %.8g, standard error %.8g, t = %.4f\n",
          b, se_b, b/se_b

	printf "The name of variable %d is %s\n", i, varname(i)
	printf "The date of observation %d is %s\n", j, date(j)

	scalar width = 12
	scalar precision = 6
	printf "x = %*.*f\n", width, precision, x

probit

By default the pseudo-R-squared statistic suggested by McFadden (1974) is shown, but in the binary case if the --estrella option is given, the variant recommended by Estrella (1998) is shown instead. This variant arguably mimics more closely the properties of the regular R² in the context of least-squares estimation.

If the dependent variable is not binary but is discrete, then Ordered Probit estimates are obtained. (If the variable selected as dependent is not discrete, an error is flagged.)

Probit for panel data

With the --random-effects option, the error term is assumed to be composed of two normally distributed components: one time-invariant term that is specific to the cross-sectional unit or "individual" (and is known as the individual effect); and one term that is specific to the particular observation.

Evaluation of the likelihood for this model involves the use of Gauss-Hermite quadrature for approximating the value of expectations of functions of normal variates. The number of quadrature points used can be chosen through the --quadpoints option (the default is 32). Using more points will increase the accuracy of the results, but at the cost of longer compute time; with many quadrature points and a large dataset estimation may be quite time consuming.

Besides the usual parameter estimates (and associated statistics) relating to the included regressors, certain additional information is presented on estimation of this sort of model:

• lnsigma2: the maximum likelihood estimate of the log of the variance of the individual effect;

• sigma_u: the estimated standard deviation of the individual effect; and

• rho: the estimated share of the individual effect in the composite error variance (also known as the intra-class correlation).

The Likelihood Ratio test of the null hypothesis that rho equals zero provides a means of assessing whether the random effects specification is needed. If the null is not rejected that suggests that a simple pooled probit specification is adequate.

Menu path: /Model/Limited dependent variable/Probit

pvalue

qlrtest

For each potential break point within the central 70 percent of the observations, a Chow test is performed. See chow for details; as with the regular Chow test, this is a robust Wald test if the original model was estimated with the --robust option, an F-test otherwise. The QLR statistic is then the maximum of the individual test statistics.

An asymptotic p-value is obtained using the method of Bruce Hansen (1997).

Besides the standard hypothesis test accessors $test and $pvalue, $qlrbreak can be used to retrieve the index of the observation at which the test statistic is maximized.

The --limit-to option can be used to limit the set of interactions with the split dummy variable in the Chow tests to a subset of the original regressors. The parameter for this option must be a named list, all of whose members are among the original regressors. The list should not include the constant.

When this command is run interactively (only), a plot of the Chow test statistic is displayed by default. This can be adjusted via the --plot option. The acceptable parameters to this option are none (to suppress the plot); display (to display a plot even when not in interactive mode); or a file name. The effect of providing a file name is as described for the --output option of the gnuplot command.

Menu path: Model window, /Tests/QLR test

qqplot

The option --output has the effect of sending the output to the specified file; use "display" to force output to the screen. See the gnuplot command for more detail on this option.

Given two series arguments, y and x, displays a plot of the empirical quantiles of y against those of x. The data values are not standardized.

Menu path: /Variable/Normal Q-Q plot

Menu path: /View/Graph specified vars/Q-Q plot

quantreg

Quantile regression. The first argument, tau, is the conditional quantile for which estimates are wanted. It may be given either as a numerical value or as the name of a pre-defined scalar variable; the value must be in the range 0.01 to 0.99. (Alternatively, a vector of values may be given for tau; see below for details.) The second and subsequent arguments compose a regression list on the same pattern as ols.

Without the --intervals option, standard errors are printed for the quantile estimates. By default, these are computed according to the asymptotic formula given by Koenker and Bassett (1978), but if the --robust option is given, standard errors that are robust with respect to heteroskedasticity are calculated using the method of Koenker and Zhao (1994).

When the --intervals option is chosen, confidence intervals are given for the parameter estimates instead of standard errors. These intervals are computed using the rank inversion method, and in general they are asymmetrical about the point estimates. The specifics of the calculation are inflected by the --robust option: without this, the intervals are computed on the assumption of IID errors (Koenker, 1994); with it, they use the robust estimator developed by Koenker and Machado (1999).

By default, 90 percent confidence intervals are produced. You can change this by appending a confidence level (expressed as a decimal fraction) to the intervals option, as in --intervals=0.95.

Vector-valued tau: instead of supplying a scalar, you may give the name of a pre-defined matrix. In this case estimates are computed for all the given tau values and the results are printed in a special format, showing the sequence of quantile estimates for each regressor in turn.

Menu path: /Model/Robust estimation/Quantile regression

quit

rename

reset

The --silent option may be used if one plans to make use of the $test and/or $pvalue accessors to grab the results of the test.

The --robust option is implicit if the regression to be tested employed robust standard errors.

Menu path: Model window, /Tests/Ramsey's RESET

restrict

In the case of a system of equations (defined via the system command), the initial "restrict" may be followed by the name of a previously defined system of equations. If this is omitted and the last model was a system then the restrictions are applied to the last model. By default the restrictions are evaluated when the system is next estimated, using the estimate command. But if the --wald option is given the restriction is tested right away, via a Wald chi-square test on the covariance matrix. Note that this option will produce an error if a system has been defined but not yet estimated.

Depending on the context, the restrictions to be tested may be expressed in various ways. The simplest form is as follows: each restriction is given as an equation, with a linear combination of parameters on the left and a scalar value to the right of the equals sign (either a numerical constant or the name of a scalar variable).

In the single-equation case, parameters may be referenced in the form b[i], where i represents the position in the list of regressors (starting at 1), or b[varname], where varname is the name of the regressor in question. In the system case, parameters are referenced using b plus two numbers in square brackets. The leading number represents the position of the equation within the system and the second number indicates position in the list of regressors. For example b[2,1] denotes the first parameter in the second equation, and b[3,2] the second parameter in the third equation. The b terms in the equation representing a restriction may be prefixed with a numeric multiplier, for example 3.5*b[4].

Here is an example of a set of restrictions for a previously estimated model:

	restrict
	 b[1] = 0
	 b[2] - b[3] = 0
	 b[4] + 2*b[5] = 1
	end restrict

And here is an example of a set of restrictions to be applied to a named system. (If the name of the system does not contain spaces, the surrounding quotes are not required.)

	restrict "System 1"
	 b[1,1] = 0
	 b[1,2] - b[2,2] = 0
	 b[3,4] + 2*b[3,5] = 1
	end restrict

In the single-equation case the restrictions are by default evaluated via a Wald test, using the covariance matrix of the model in question. If the original model was estimated via OLS then the restricted coefficient estimates are printed; to suppress this, append the --quiet option flag to the initial restrict command. As an alternative to the Wald test, for models estimated via OLS or WLS only, you can give the --bootstrap option to perform a bootstrapped test of the restriction.

In the system case, the test statistic depends on the estimator chosen: a Likelihood Ratio test if the system is estimated using a Maximum Likelihood method, or an asymptotic F-test otherwise.

Linear restrictions: alternative syntax

There are two alternatives to the method of expressing restrictions described above. First, a set of g restrictions on a k-vector of parameters, β, may be written compactly as Rβ – q = 0, where R is an g x k matrix and q is a g-vector. You can specify a restriction by giving the names of pre-defined, conformable matrices to be used as R and q, as in

	restrict
	  R = Rmat
	  q = qvec
	end restrict

Second, in a variant that may be useful when restrict is used within a function, you can construct the set of restriction statements in the form of an array of strings. You then use the inject keyword with the name of the array. Here's a simple example:

	strings RS = array(2)
	RS[1] = "b[1,2] = 0"
	RS[2] = "b[2,1] = 0"
	restrict
	  inject RS
	end restrict

In actual usage of this method one would likely use sprintf to construct the strings, based on input to a function.

Nonlinear restrictions

If you wish to test a nonlinear restriction (this is currently available for single-equation models only) you should give the restriction as the name of a function, preceded by "rfunc = ", as in

	restrict
	  rfunc = myfunction
	end restrict

The constraint function should take a single const matrix argument; this will be automatically filled out with the parameter vector. And it should return a vector which is zero under the null hypothesis, non-zero otherwise. The length of the vector is the number of restrictions. This function is used as a "callback" by gretl's numerical Jacobian routine, which calculates a Wald test statistic via the delta method.

Here is a simple example of a function suitable for testing one nonlinear restriction, namely that two pairs of parameter values have a common ratio.

	function matrix restr (const matrix b)
	  matrix v = b[1]/b[2] - b[4]/b[5]
	  return v
	end function

On successful completion of the restrict command the accessors $test and $pvalue give the test statistic and its p-value.

When testing restrictions on a single-equation model estimated via OLS, or on a VECM, the --full option can be used to set the restricted estimates as the "last model" for the purposes of further testing or the use of accessors such as $coeff and $vcv. Note that some special considerations apply in the case of testing restrictions on Vector Error Correction Models. Please see chapter 33 of the Gretl User's Guide for details.

Menu path: Model window, /Tests/Linear restrictions

rmplot

Besides the graph, gretl displays the means and ranges for each subsample, along with the slope coefficient for an OLS regression of the range on the mean and the p-value for the null hypothesis that this slope is zero. If the slope coefficient is significant at the 10 percent significance level then the fitted line from the regression of range on mean is shown on the graph. The t-statistic for the null, and the corresponding p-value, are recorded and may be retrieved using the accessors $test and $pvalue respectively.

If the --trim option is given, the minimum and maximum values in each sub-sample are discarded before calculating the mean and range. This makes it less likely that outliers will distort the analysis.

If the --quiet option is given, no graph is shown and no output is printed; only the t-statistic and p-value are recorded. Otherwise the form of the plot can be controlled via the --output option; this works as described in connection with the gnuplot command.

Menu path: /Variable/Range-mean graph

run

See also include.

Menu path: Run icon in script window

runs

	series signx1 = x1 - median(x1)
	runs signx1

scatters

For details on usage of the --output option, please see the gnuplot command.

If a named matrix is specified as the data source the x and y lists should be given as 1-based column numbers. Alternatively, if no lists are given, all the columns are plotted against time or an index variable.

See also tsplots for a simple means of producing multiple time-series plots, and gridplot for a more flexible way of combining plots in a grid.

Menu path: /View/Multiple graphs/X-Y scatters

sdiff

set

The most common use of this command is the first variant shown above, where it is used to set the value of a selected program parameter. This is discussed in detail below. The other uses are: with --to-file, to write a script file containing all the current parameter settings; with --from-file to read a script file containing parameter settings and apply them to the current session; with stopwatch to zero the gretl "stopwatch" which can be used to measure CPU time (see the entry for the $stopwatch accessor); or, if the word set is given alone, to print the current settings.

Values set via this comand remain in force for the duration of the gretl session unless they are changed by a further call to set. The parameters that can be set in this way are enumerated below. Note that the settings of hc_version, hac_lag and hac_kernel are used when the --robust option is given to an estimation command.

The available settings are grouped under the following categories: program interaction and behavior, numerical methods, random number generation, robust estimation, filtering, time series estimation, and interaction with GNU R.

Program interaction and behavior

These settings are used for controlling various aspects of the way gretl interacts with the user.

• workdir: path. Sets the default directory for writing and reading files, whenever full paths are not specified.

• use_cwd: on or off (the default). Governs the setting of workdir at start-up: if it's on, the working directory is inherited from the shell, otherwise it is set to whatever was selected in the previous gretl session.

• echo: off or on (the default). Suppress or resume the echoing of commands in gretl's output.

• messages: off or on (the default). Suppress or resume the printing of non-error messages associated with various commands, for example when a new variable is generated or when the sample range is changed.

• verbose: off, on (the default) or comments. Acts as a "master switch" for echo and messages (see above), turning them both off or on simultaneously. The comments argument turns off echo and messages but preserves printing of comments in a script.

• warnings: off or on (the default). Suppress or resume the printing of warning messages when numerical problems arise, for example a computation produces non-finite values or the convergence of an optimizer is questionable.

• csv_delim: either comma (the default), space, tab or semicolon. Sets the column delimiter used when saving data to file in CSV format.

• csv_write_na: the string used to represent missing values when writing data to file in CSV format. Maximum 7 characters; the default is NA.

• csv_read_na: the string taken to represent missing values (NAs) when reading data in CSV format. Maximum 7 characters. The default depends on whether a data column is found to contain numerical data (mostly) or string values. For numerical data the following are taken as indicating NAs: an empty cell, or any of the strings NA, N.A., na, n.a., N/A, #N/A, NaN, .NaN, ., .., -999, and -9999. For string-valued data only a blank cell, or a cell containing an empty string, is counted as NA. These defaults can be reimposed by giving default as the value for csv_read_na. To specify that only empty cells are read as NAs, give a value of "". Note that empty cells are always read as NAs regardless of the setting of this variable.

• csv_digits: a positive integer specifying the number of significant digits to use when writing data in CSV format. By default up to 15 digits are used depending on the precision of the original data. Note that CSV output employs the C library's fprintf function with "%g" conversion, which means that trailing zeros are dropped.

• display_digits: an integer from 3 to 6, specifying the number of significant digits to use when displaying regression coefficients and standard errors (the default being 6). This setting can also be used to limit the number of digits shown by the summary command; in this case the default (and also the maximum) is 5.

• mwrite_g: on or off (the default). When writing a matrix to file as text, gretl by default uses scientific notation with 18-digit precision, hence ensuring that the stored values are a faithful representation of the numbers in memory. When writing primary data with no more than 6 digits of precision it may be preferable to use %g format for a more compact and human-readable file; you can make this switch via set mwrite_g on.

• force_decpoint: on or off (the default). Force gretl to use the decimal point character, in a locale where another character (most likely the comma) is the standard decimal separator.

• loop_maxiter: one non-negative integer value (default 100000). Sets the maximum number of iterations that a while loop is allowed before halting (see loop). Note that this setting only affects the while variant; its purpose is to guard against inadvertently infinite loops. Setting this value to 0 has the effect of disabling the limit; use with caution.

• max_verbose: off (the default), on or full. Controls the verbosity of commands and functions that use numerical optimization methods. The on choice applies only to functions (such as BFGSmax and NRmax) which work silently by default; the effect is to print basic iteration information. The full setting can be used to trigger more detailed output, including parameter values and their respective gradient for the objective function at each iteration. This choice applies both to functions of the above-mentioned sort and to commands that rely on numerical optimization such as arima, probit and mle. In the case of commands the effect is to make their --verbose option produce more detail. See also chapter 37 of the Gretl User's Guide.

• debug: 1, 2 or 0 (the default). This is for use with user-defined functions. Setting debug to 1 is equivalent to turning messages on within all such functions; setting this variable to 2 has the additional effect of turning on max_verbose within all functions.

• shell_ok: on or off (the default). Enable launching external programs from gretl via the system shell. This is disabled by default for security reasons, and can only be enabled via the graphical user interface (Tools/Preferences/General). However, once set to on, this setting will remain active for future sessions until explicitly disabled.

• bfgs_verbskip: one integer. This setting affects the behavior of the --verbose option to those commands that use BFGS as an optimization algorithm and is used to compact output. if bfgs_verbskip is set to, say, 3, then the --verbose switch will only print iterations 3, 6, 9 and so on.

• skip_missing: on (the default) or off. Controls gretl's behavior when contructing a matrix from data series: the default is to skip data rows that contain one or more missing values but if skip_missing is set off missing values are converted to NaNs.

• matrix_mask: the name of a series, or the keyword null. Offers greater control than skip_missing when constructing matrices from series: the data rows selected for matrices are those with non-zero (and non-missing) values in the specified series. The selected mask remains in force until it is replaced, or removed via the null keyword.

• quantile_type: must be one of Q6 (the default), Q7 or Q8. Selects the specific method used by the quantile function. For details see Hyndman and Fan (1996) or the Wikipedia entry at https://en.wikipedia.org/wiki/Quantile.

• huge: a large positive number (by default, 1.0E100). This setting controls the value returned by the accessor $huge.

• assert: off (the default), warn or stop. Controls the consequences of failure (return value of 0) from the assert function.

• datacols: an integer from 1 to 15, with default value 5. Sets the maximum number of series shown side-by-side when data are displayed by observation.

• plot_collection: on, auto or off. This setting affects the way plots are displayed during interactive use. If it's on, plots of the same pixel size are gathered in a "plot collection", that is a single output window in which you can browse through the various plots going back and forth. With the off setting, instead, a different window for each plot will be generated, as in older gretl versions. Finally, the auto setting has the effect of enabling the plot collection mode only for graphs that are generated within 1.25 seconds from one another (for example, as a result of executing plotting commands in a loop).

Numerical methods

These settings are used for controlling the numerical algorithms that gretl uses for estimation.

• optimizer: either auto (the default), BFGS or newton. Sets the optimization algorithm used for various ML estimators, in cases where both BFGS and Newton–Raphson are applicable. The default is to use Newton–Raphson where an analytical Hessian is available, otherwise BFGS.

• bhhh_maxiter: one integer, the maximum number of iterations for gretl's internal BHHH routine, which is used in the arma command for conditional ML estimation. If convergence is not achieved after bhhh_maxiter, the program returns an error. The default is set at 500.

• bhhh_toler: one floating point value, or the string default. This is used in gretl's internal BHHH routine to check if convergence has occurred. The algorithm stops iterating as soon as the increment in the log-likelihood between iterations is smaller than bhhh_toler. The default value is 1.0E–06; this value may be re-established by typing default in place of a numeric value.

• bfgs_maxiter: one integer, the maximum number of iterations for gretl's BFGS routine, which is used for mle, gmm and several specific estimators. If convergence is not achieved in the specified number of iterations, the program returns an error. The default value depends on the context, but is typically of the order of 500.

• bfgs_toler: one floating point value, or the string default. This is used in gretl's BFGS routine to check if convergence has occurred. The algorithm stops as soon as the relative improvement in the objective function between iterations is smaller than bfgs_toler. The default value is the machine precision to the power 3/4; this value may be re-established by typing default in place of a numeric value.

• bfgs_maxgrad: one floating point value. This is used in gretl's BFGS routine to check if the norm of the gradient is reasonably close to zero when the bfgs_toler criterion is met. A warning is printed if the norm of the gradient exceeds 1; an error is flagged if the norm exceeds bfgs_maxgrad. At present the default is the permissive value of 5.0.

• bfgs_richardson: on or off (the default). Use Richardson extrapolation when computing numerical derivatives in the context of BFGS maximization.

• initvals: the name of a predefined matrix. Allows manual setting of the initial parameter vector for certain estimation commands that involve numerical optimization: arma, garch, logit and probit, tobit and intreg, biprobit, duration, poisson, negbin, and also when imposing certain sorts of restriction associated with VECMs. Unlike other settings, initvals is not persistent: it resets to the default initializer after its first use. For details in connection with ARMA estimation see chapter 31 of the Gretl User's Guide.

• lbfgs: on or off (the default). Use the limited-memory version of BFGS (L-BFGS-B) instead of the ordinary algorithm. This may be advantageous when the function to be maximized is not globally concave.

• lbfgs_mem: an integer value in the range 3 to 20 (with a default value of 8). This determines the number of corrections used in the limited memory matrix when L-BFGS-B is employed.

• nls_toler: a floating-point value. Sets the tolerance used in judging whether or not convergence has occurred in nonlinear least squares estimation using the nls command. The default value is the machine precision to the power 3/4; this value may be re-established by typing default in place of a numeric value.

• svd: on or off (the default). Use SVD rather than Cholesky or QR decomposition in least squares calculations. This option applies to the mols function as well as various internal calculations, but not to the regular ols command.

• force_qr: on or off (the default). This applies to the ols command. By default this command computes OLS estimates using Cholesky decomposition (the fastest method), with a fallback to QR if the data seem too ill-conditioned. You can use force_qr to skip the Cholesky step; in "doubtful" cases this may ensure greater accuracy.

• fcp: on or off (the default). Use the algorithm of Fiorentini, Calzolari and Panattoni rather than native gretl code when computing GARCH estimates.

• gmm_maxiter: one integer, the maximum number of iterations for gretl's gmm command when in iterated mode (as opposed to one- or two-step). The default value is 250.

• nadarwat_trim: one integer, the trim parameter used in the nadarwat function.

• fdjac_quality: one integer (0, 1 or 2), the algorithm used by the fdjac function; the default is 0.

• gmp_bits: one integer, which should be an integral power of 2 (default and minimum value 256, maximum 8192). Controls the number of bits used to represent a floating point number when GMP (the GNU Multiple Precision Arithmetic Library) is called, primarily via the mpols command. Larger values give greater precision at the cost of longer compute time. This setting can also be controlled by the environment variable GRETL_MP_BITS.

Random number generation

• seed: an unsigned integer or the keyword auto. Sets the seed for the pseudo-random number generator. By default this is set from the system time; if you want to generate repeatable sequences of random numbers you must set the seed manually. To reset the seed to a time-based automatic value, use auto.

Robust estimation

• bootrep: an integer. Sets the number of replications for the restrict command with the --bootstrap option.

• garch_vcv: unset, hessian, im (information matrix) , op (outer product matrix), qml (QML estimator), bw (Bollerslev–Wooldridge). Specifies the variant that will be used for estimating the coefficient covariance matrix, for GARCH models. If unset is given (the default) then the Hessian is used unless the "robust" option is given for the garch command, in which case QML is used.

• arma_vcv: hessian (the default) or op (outer product matrix). Specifies the variant to be used when computing the covariance matrix for ARIMA models.

• force_hc: off (the default) or on. By default, with time-series data and when the --robust option is given with ols, the HAC estimator is used. If you set force_hc to "on", this forces calculation of the regular Heteroskedasticity Consistent Covariance Matrix (HCCM), which does not take autocorrelation into account. Note that VARs are treated as a special case: when the --robust option is given the default method is regular HCCM, but the --robust-hac flag can be used to force the use of a HAC estimator.

• robust_z: off (the default) or on. This controls the distribution used when calculating p-values based on robust standard errors in the context of least-squares estimators. By default gretl uses the Student t distribution but if robust_z is turned on the normal distribution is used.

• hac_lag: nw1 (the default), nw2, nw3 or an integer. Sets the maximum lag value or bandwidth, p, used when calculating HAC (Heteroskedasticity and Autocorrelation Consistent) standard errors using the Newey-West approach, for time series data. nw1 and nw2 represent two variant automatic calculations based on the sample size, T: for nw1, , and for nw2, . nw3 calls for data-based bandwidth selection. See also qs_bandwidth and hac_prewhiten below.

• hac_kernel: bartlett (the default), parzen, or qs (Quadratic Spectral). Sets the kernel, or pattern of weights, used when calculating HAC standard errors.

• hac_prewhiten: on or off (the default). Use Andrews-Monahan prewhitening and re-coloring when computing HAC standard errors. This also implies use of data-based bandwidth selection.

• hac_missvals: es (the default), am or off. Sets the policy regarding calculation of HAC standard errors when the estimation sample includes incomplete observations: es invokes the Equal Spacing method of Datta and Du (2012); am selects the Amplitude Modulation method of Parzen (1963); and off causes gretl to refuse such estimation. See chapter 22 of the Gretl User's Guide for details.

• hc_version: 0, 1, 2, 3 or 3a. Sets the variant used when calculating Heteroskedasticity Consistent standard errors with cross-sectional data. The first four options correspond to the HC0, HC1, HC2 and HC3 discussed by Davidson and MacKinnon in Econometric Theory and Methods, chapter 5. HC0 produces what are usually called "White's standard errors". Variant 3a is the MacKinnon–White "jackknife" procedure. The default setting is normally 1, but this can be changed in the GUI client, via the "HCCME" tab under "/Tools/Preferences/General". Note that a setting made via the GUI persists across gretl sessions, as opposed to use of the set command which just affects the current session.

• panel_robust: arellano (the default), pcse or scc. This selects the robust covariance matrix estimator for use with panel-data models. See the panel command and chapter 22 of the Gretl User's Guide for details.

• qs_bandwidth: Bandwidth for HAC estimation in the case where the Quadratic Spectral kernel is selected. (Unlike the Bartlett and Parzen kernels, the QS bandwidth need not be an integer.)

Time series

• horizon: one integer (the default is based on the frequency of the data). Sets the horizon for impulse responses and forecast variance decompositions in the context of vector autoregressions.

• vecm_norm: phillips (the default), diag, first or none. Used in the context of VECM estimation via the vecm command for identifying the cointegration vectors. See the chapter 33 of the Gretl User's Guide for details.

• boot_iters: one integer, B. Sets the number of bootstrap iterations used when computing impulse response functions with confidence intervals. The default is 1999. It is recommended that B + 1 is evenly divisible by 100α/2, so for example with α = 0.1 B + 1 should be a multiple of 5. The minimum acceptable value is 499.

Interaction with R

• R_lib: on (the default) or off. When sending instructions to be executed by R, use the R shared library by preference to the R executable, if the library is available.

• R_functions: off (the default) or on. Recognize functions defined in R as if they were native functions (the namespace prefix "R." is required). See chapter 44 of the Gretl User's Guide for details on this and the previous item.

Miscellaneous

• mpi_use_smt: on or off (the default). This switch affects the default number of processes launched in an mpi block within a script. If the switch is off the default number of processes equals the number of physical cores on the local machine; if it's on the default is the maximum number of threads, which will be twice the number of physical cores if the cores support SMT (Simultaneous MultiThreading, also known as Hyper-Threading). This applies only if the user has not specified a number of processes, either directly or indirectly (by specifying a hosts file for use with MPI).

• graph_theme: a string, one of altpoints, classic, dark2 (the current default), ethan, iwanthue or sober. This sets the "theme" used for graphs produced by gretl. The classic option reverts to the single theme that was in force prior to version 2020c of gretl.