Must follow the estimation of a fixed-effects or random-effects panel data model. Returns a series containing the estimates of the individual effects.

Must follow estimation via ordered probit or logit, or multinomial logit. Returns an n x j matrix, where n is the number of observations used and j is the number of possible outcomes, holding the estimated probability of each outcome at each observation.

Returns the overall chi-square statistic from the last estimated model, if available.

Must follow the estimation of a model; returns the command word, for example ols or probit.

Must follow the estimation of a VAR or a VECM; returns the companion matrix.

Returns an integer value representing the sort of dataset that is currently loaded: 0 = no data; 1 = cross-sectional (undated) data; 2 = time-series data; 3 = panel data.

Must follow the estimation of a single-equation model; returns the name of the dependent variable.

Returns the degrees of freedom of the last estimated model. If the last model was in fact a system of equations, the value returned is the degrees of freedom per equation; if this differs across the equations then the value given is the number of observations minus the mean number of coefficients per equation (rounded up to the nearest integer).

Returns the Durbin–Watson statistic for first-order serial correlation from the model last estimated (if available).

Must follow the estimation of a VECM; returns a matrix containing the error correction terms. The number of rows equals the number of observations used and the number of columns equals the cointegration rank of the system.

Returns the error sum of squares of the last estimated model, if available.

Must follow the estimation of a VECM; returns a vector containing the eigenvalues that are used in computing the trace test for cointegration.

Must follow estimation of a VAR. Returns a matrix containing the forecast error variance decomposition (FEVD). This matrix has h rows where h is the forecast horizon, which can be chosen using set horizon or otherwise is set automatically based on the frequency of the data.

For a VAR with p variables, the matrix has p² columns: the first p columns contain the FEVD for the first variable in the VAR; the second p columns the FEVD for the second variable; and so on. The (decimal) fraction of the forecast error for variable i attributable to innovation in variable j is therefore found in column (i – 1)p + j.

Returns the overall F-statistic from the last estimated model, if available.

Must follow a gmm block. Returns the value of the GMM objective function at its minimum.

Must follow a garch command. Returns the estimated conditional variance series.

Must follow estimation of a model via either tsls or panel with the random effects option. Returns a 1 x 3 vector containing the value of the Hausman test statistic, the corresponding degrees of freedom and the p-value for the test, in that order.

Must follow the estimation of a VECM, and returns the loadings matrix. It has as many rows as variables in the VECM and as many columns as the cointegration rank.

Must follow the estimation of a VECM, and returns the cointegration matrix. It has as many rows as variables in the VECM (plus the number of exogenous variables that are restricted to the cointegration space, if any), and as many columns as the cointegration rank.

Must follow the estimation of a VECM, and returns the estimated covariance matrix for the elements of the cointegration vectors.

In the case of unrestricted estimation, this matrix has a number of rows equal to the unrestricted elements of the cointegration space after the Phillips normalization. If, however, a restricted system is estimated via the restrict command with the --full option, a singular matrix with (n+m)r rows will be returned (n being the number of endogenous variables, m the number of exogenous variables that are restricted to the cointegration space, and r the cointegration rank).

Example: the code

	  open denmark.gdt
	  vecm 2 1 LRM LRY IBO IDE --rc --seasonals -q
	  s0 = $jvbeta

	  restrict --full
	    b[1,1] = 1
	    b[1,2] = -1
	    b[1,3] + b[1,4] = 0
	  end restrict
	  s1 = $jvbeta

	  print s0
	  print s1

produces the following output.

	  s0 (4 x 4)

          0.019751     0.029816  -0.00044837   -0.12227
          0.029816     0.31005   -0.45823      -0.18526
         -0.00044837  -0.45823    1.2169       -0.035437
         -0.12227     -0.18526   -0.035437      0.76062

	  s1 (5 x 5)

	  0.0000       0.0000       0.0000       0.0000       0.0000
	  0.0000       0.0000       0.0000       0.0000       0.0000
	  0.0000       0.0000      0.27398     -0.27398    -0.019059
	  0.0000       0.0000     -0.27398      0.27398     0.019059
	  0.0000       0.0000    -0.019059     0.019059    0.0014180

Returns a string representing the national language in force currently, if this can be determined. The string is composed of a two-letter ISO 639-1 language code (for example, en for English, jp for Japanese, el for Greek) followed by an underscore plus a two-letter ISO 3166-1 country code. Thus for example Portuguese in Portugal gives pt_PT while Portuguese in Brazil gives pt_BR.

If the national language cannot be determined, the string "unknown" is returned.

For selected models estimated via Maximum Likelihood, returns the series of per-observation log-likelihood values. At present this is supported only for binary logit and probit, tobit and heckit.

Returns the log-likelihood for the last estimated model (where applicable).

Returns the value of "machine epsilon", which gives an upper bound on the relative error due to rounding in double-precision floating point arithmetic.

Must follow estimation of a single-equation model; returns a bundle containing many items of data pertaining to the model. All the regular model accessors are included: these are referenced by keys that are the same as the regular accessor names, minus the leading dollar sign. So for example the residuals appear under the key uhat and the error sum of squares under ess.

Depending on the estimator, additional information may be available; the keys for such information should hopefully be fairly self-explanatory. To see what's available you can get a copy of the bundle and print its content, as in

	  ols y 0 x
	  bundle b = $model
	  print b

If gretl is built with MPI support, and the program is running in MPI mode, returns the 0-based "rank" or ID number of the current process. Otherwise returns –1.

If gretl is built with MPI support, and the program is running in MPI mode, returns the number of MPI processes currently running. Otherwise returns 0.

Returns the total number of coefficients estimated in the last model.

Returns the number of series in the dataset (including the constant). Since const is always present in any dataset a return value of 0 indicates that no dataset is in place. Note that if this accessor is used within a function, the number of series currently accessible may well fall short of that given by $nvars.

Returns a series holding the "major" or low-frequency component of each observation. This means the year for annual, quarterly or monthly time series; the day for hourly data; or the individual in the case of panel data. If the data are cross-sectional the series returned is just a 1-based index of the observations.

Applicable when the observations in the current dataset have a major:minor:micro structure, as in dated daily time series (year:month:day). Returns a series holding the micro or highest-frequency component of each observation (for example, the day).

Applicable when the observations in the current dataset have a major:minor structure, as in quarterly time series (year:quarter), monthly time series (year:month), hourly data (day:hour) and panel data (individual:period). Returns a series holding the minor or high-frequency component of each observation (for example, the month).

In the case of dated daily data, $obsminor gets the month of each observation.

Returns the frequency or periodicity of the data (e.g. 4 for quarterly data). In the case of panel data the value returned is the total time-series length.

Returns the value of π in double precision.

A special facility for use by authors of function packages. Returns an empty string unless a packaged function is executing, in which case it returns the full (platform dependent) path under which the package is installed. For instance the return value might be

	  /usr/share/gretl/functions/foo

if that's the directory in which foo.gfn is located. This enables package writers to access resources such as matrix files that they have included in their package.

Without arguments, returns the first-order autoregressive coefficient for the residuals of the last model. After estimating a model via the ar command, the syntax $rho(n) returns the corresponding estimate of ρ(n).

Returns the unadjusted R² from the last estimated model, if available. Usually this will be the regular (centered) R² but if the specification contains no constant (and no set of regressors that "add up to" a constant) it will be the uncentered version. In that case the centered version can be accessed as $model.centered_R2.

Must follow estimation of a single-equation model. Returns a dummy series with value 1 for observations used in estimation, 0 for observations within the currently defined sample range but not used (presumably because of missing values), and NA for observations outside of the current range.

If you wish to compute statistics based on the sample that was used for a given model, you can do, for example:

	  ols y 0 xlist
	  series sdum = $sample
	  smpl sdum --dummy

Must follow a tsls command. Returns a 1 x 3 vector, containing the value of the Sargan over-identification test statistic, the corresponding degrees of freedom and p-value, in that order. If the model is exactly identified, the statistic is unavailable, and trying to access it provokes an error.

Returns the value with which gretl's random number generator was seeded. If you set the seed yourself there's no need to use this accessor, but it may be of interest if the seed was set automatically (based on the time that execution of the program started).

Requires that a model has been estimated. If the last model was a single equation, returns the (scalar) Standard Error of the Regression (or in other words, the standard deviation of the residuals, with an appropriate degrees of freedom correction). If the last model was a system of equations, returns the cross-equation covariance matrix of the residuals.

With no arguments, $stderr returns a column vector containing the standard error of the coefficients for the last model. With the optional string argument it returns a scalar, namely the standard error of the parameter named s.

If the "model" in question is actually a system, the result depends on the characteristics of the system: for VARs and VECMs the value returned is a matrix with one column per equation, otherwise it is a column vector containing the coefficients from the first equation followed by those from the second equation, and so on.

Must be preceded by set stopwatch, which activates the measurement of CPU time. The first use of this accessor yields the seconds of CPU time that have elapsed since the set stopwatch command. At each access the clock is reset, so subsequent uses of $stopwatch yield the seconds of CPU time since the previous access.

When a user-defined function is executing, the set stopwatch command and $stopwatch accessor are specific to that function—that is, timing within a function does not disrupt any "global" timing that may be going on in the main script.

Returns a bundle containing information on the capabilities of the gretl build and the system on which gretl is running. The members of the bundle are as follows:

• gui_mode: integer, equals 1 if libgretl is being called by the GUI program, otherwise 0.

• mpi: integer, equals 1 if the system supports MPI (Message Passing Interface), otherwise 0.

• omp: integer, equals 1 if gretl is built with support for Open MP, otherwise 0.

• ncores: integer, the number of physical processor cores available.

• nproc: integer, the number of processors available, which will be greater than ncores if hyper-threading is enabled.

• mpimax: integer, the maximum number of MPI processes that can be run in parallel. This is zero if MPI is not supported, otherwise it equals the local nproc value unless an MPI hosts file has been specified, in which case it is the sum of the number of processors or "slots" across all the machines referenced in that file.

• wordlen: integer, either 32 or 64 for 32- and 64-bit systems respectively.

• os: string representing the operating system, either linux, macos, windows or other. Note that versions of gretl prior to 2021e gave the string osx for the Mac operating system; a version-independent test for Mac is therefore instring($sysinfo.os, "os")

• hostname: the name of the host machine on which the current gretl process is running (with a fallback of localhost in case the name cannot be determined).

• mem: a 2-vector holding total physical memory and free or available memory, expressed in MB. This information may not be available on all systems but should be on Windows, macOS and Linux.

• blas: string identifying the supplier of the BLAS (Basic Linear Algebra Subprograms) library in use by gretl.

• blas_version: string identifying the version number of the blas library in use.

• blascore: (if applicable) a string identifying the CPU type for which the current blas library is optimized.

• compiler: a string identifying the compiler used when building libgretl.

• cpuid: a string identifying the vendor and model of the CPU on which libgretl is running.

• gnuplot: a string identifying the version of gnuplot available to gretl for plotting, in the form of three dot-separated numbers giving major version, minor version and patchlevel.

• foreign: a sub-bundle containing 0/1 indicators for the presence on the host system of each of the "foreign" programs supported by gretl, under the keys julia, octave, ox, python, Rbin, Rlib and stata. The two keys pertaining to R represent the R executable and shared library, respectively.

Note that individual elements in the bundle can be accessed using "dot" notation without any need to copy the whole bundle under a user-specified name. For example,

	  if $sysinfo.os == "linux"
	      # do something linux-specific
	  endif

Returns the number of observations used in estimating the last model.

Returns the 1-based index of the first observation in the currently selected sample.

Returns the 1-based index of the last observation in the currently selected sample.

For time-series or panel data, creates a 1-based index of the time period. In the panel case the sequence of values repeats for each cross-sectional unit.

The command "genr time" is an alternative, with the difference that the genr variant automatically creates a series called time while the naming of the series is up to the caller when using $time, as in

	  series trend = $time

This accessor is not available for cross-sectional data.

Returns TR² (sample size times R-squared) from the last model, if available.

Returns the residuals from the last model. This may have different meanings for different estimators. For example, after an ARMA estimation $uhat will contain the one-step-ahead forecast error; after a probit model, it will contain the generalized residuals.

If the "model" in question is actually a system (a VAR or VECM, or system of simultaneous equations), $uhat retrieves the matrix of residuals, one column per equation.

Valid for panel datasets only. Returns a series with value 1 for all observations on the first unit or group, 2 for observations on the second unit, and so on.

Must follow the estimation of a VECM; returns a matrix in which the Gamma matrices (coefficients on the lagged differences of the cointegrated variables) are stacked side by side. Each row represents an equation; for a VECM of lag order p there are p – 1 sub-matrices.

Returns an integer value that codes for the program version. The current gretl version string takes the form of a 4-digit year followed by a letter from a to j representing the sequence of releases within the year (for example, 2015d). The return value from this accessor is formed as 10 times the year plus the zero-based lexical order of the letter, so 2015d translates to 20153.

Prior to gretl 2015d, version identifiers took the form x.y.z (three integers separated by dots), and in that case the accessor value was calculated as 10000*x + 100*y + z, so that for example 1.10.2 (the last release under the old scheme) translates as 11002. Numerical order of $version values is therefore preserved across the change in versioning scheme.

Returns 1 if gretl is running on MS Windows, otherwise 0. By conditioning on the value of this variable you can write shell calls that are portable across different operating systems.

Following estimation of a VAR or VECM (only), returns X'X^-1, where X is the common matrix of regressors used in each of the equations. While this accessor is available for a VECM estimated with a restriction imposed on α (the "loadings" matrix), it should be borne in mind that in that case not all coefficients of the regressors are freely varying.

Returns the fitted values from the last regression.

If the last model estimated was a VAR, VECM or simultaneous system, returns the associated list of endogenous variables. If the last model was a single equation, this accessor gives a list with a single element, the dependent variable. In the special case of the biprobit model the list contains two elements.

Built-in strings

Yields the full path of the directory gretl uses for temporary files. To use it in string-substitution mode, prepend the at-sign (@dotdir).

Yields the path to the gnuplot executable. To use it in string-substitution mode, prepend the at-sign (@gnuplot).

Yields the full path of the gretl installation directory. To use it in string-substitution mode, prepend the at-sign (@gretldir).

Yields the path to the tramo executable. To use it in string-substitution mode, prepend the at-sign (@tramo)

Yields the path string of the tramo data directory. To use it in string-substitution mode, prepend the at-sign (@tramodir).

Yields the path to the x-12-arima executable. To use it in string-substitution mode, prepend the at-sign (@x12a).

Yields the path of the x-12-arima data directory. To use it in string-substitution mode, prepend the at-sign (@x12adir).

Functions proper

Returns the absolute value of x.

Returns the arc cosine of x, that is, the value whose cosine is x. The result is in radians; the input should be in the range –1 to 1.

Most of the following assumes that the first two arguments to this function take the form of series or lists, but see "Matrix input" below for alternative usage.

In the most minimal usage, x is set to null, byvar is a single series and the third argument is omitted, or set to null. In this case, the return value is a matrix with two columns holding, respectively, the distinct values of byvar, sorted in ascending order, and the count of observations at which byvar takes on each of these values. For example,

	  open data4-1
	  eval aggregate(null, bedrms)

will show that the series bedrms has values 3 (with count 5) and 4 (with count 9).

More generally, if byvar is a list with n members, then the left-hand n columns hold the combinations of the distinct values of each of the n series and the count column holds the number of observations at which each combination is realized. Note that the count column can always be found at the position nelem(byvar) + 1.

Specifying an aggregation function

If the third argument is given, then x must not be null, and the rightmost m columns hold the values of the statistic specified by funcname for each of the variables in x. (Thus, m is equal to 1 if x is a single series and equal to nelem(x) if x is a list.) The given statistic is calculated on the respective sub-samples defined by the combinations in byvar (in ascending order); these combinations are shown in the first n column(s) of the returned matrix.

So, in the special case where x and byvar are both individual series, the return value is a matrix with three columns holding, respectively, the distinct values of byvar, sorted in ascending order; the count of observations at which byvar takes on each of these values; and the values of the statistic specified by funcname calculated on series x, using only those observations at which byvar takes on the value given in the first column.

For s the name of a parameter to a user-defined function, returns the name of the corresponding argument, if the argument had a name at the caller level. If the argument was anonymous, an empty string is returned unless the optional default argument is provided, in which case its value is used as a fallback.

The basic "constructor" function for a new array variable. In using this function you must specify a type (in plural form) for the array: strings, matrices, bundles, lists or arrays. The return value is an array of the specified type with n elements, each of which is initialized as "empty" (e.g. zero-length string, null matrix). Examples of usage:

	  strings S = array(5)
	  matrices M = array(3)

Returns the arc sine of x, that is, the value whose sine is x. The result is in radians; the input should be in the range –1 to 1.

Performs an in-place sort of the elements of a, using a comparator function specified by the caller under the control of the quicksort routine.

The argument a can be of any of the types supported for a gretl array, namely strings, matrices, bundles, lists or arrays. The fname argument must be the name of a function which takes two const arguments, whose type matches that of the elements of a. This function must return an integer value on the following pattern: 0 if the two arguments have the same sort order, negative if the first argument sorts before the second, or positive if the second sorts before the first. (The exact values do not matter.)

For example, suppose one wants to sort an array of bundles, each of which contains a scalar named crit, by increasing value of crit. Then the following function would be suitable for passing to asort:

	  function scalar my_bsort (const bundle b1, const bundle b2)
	     return sgn(b1.crit - b2.crit)
	  end function

If you want to preserve the unsorted array, make a copy of it before passing it to asort. The return value from this function is a nominal 0 on success.

This function is intended for testing or debugging of hansl code. The argument should be an expression which evaluates to a scalar. The return value is 1 if expr evaluates to a non-zero value (boolean "true", or "success") or 0 if it evaluates to zero (boolean "false", or "failure").

Returns the arc tangent of x, that is, the value whose tangent is x. The result is in radians.

Returns the principal value of the arc tangent of y/x, using the signs of the two arguments to determine the quadrant of the result. The return value is in radians, in the range [–π, π].

If the two arguments differ in type, the type of the result is the "higher" of the two, where the ordering is matrix > series > scalar. For example, if y is a scalar and x an n-vector (or vice versa) the result is an n-vector. Note that matrix arguments must be vectors, and if neither argument is a scalar the two arguments must be of the same length.

Closely related to the C library function of the same name. Returns the result of converting the string s (or the leading portion thereof, after discarding any initial white space) to a floating-point number. Unlike atof in C, however, the decimal character is always assumed (for reasons of portability) to be ".". Any characters that follow the portion of s that converts to a floating-point number under this assumption are ignored.

If none of s (following any discarded white space) is convertible under the stated assumption, NA is returned.

	  # examples
	  x = atof("1.234") # gives x = 1.234
	  x = atof("1,234") # gives x = 1
	  x = atof("1.2y")  # gives x = 1.2
	  x = atof("y")     # gives x = NA
	  x = atof(",234")  # gives x = NA

Primarily intended for use by writers of function packages. Here is the context in which bcheck may be useful: you have a function which accepts a bundle argument whereby the caller can make various choices. Some elements of the bundle may have default values—so the caller is not obliged to make an explicit choice—while other elements may be required. You want to determine whether the argument you get is valid. The main text below assumes that an input bundle is supplied by the caller of your function, but see the section headed "No input bundle" for the contrary case.

To use bcheck you construct a template bundle containing all the supported keys, with values that exemplify the type associated with each key, and pass this in pointer form as target. For the second argument, input, pass the bundle you get from the caller. This function then checks the following:

• Does input contain any keys not present in target? If so, bcheck returns a non-zero value, indicating that input is erroneous. (Most likely, the key in question is misspelled.)

• Does input contain under any given key an object whose type does not match that in target? If so, a non-zero value is returned.

• If some elements in target require input from the caller (so the value you supply is not a default value, just a placeholder to indicate the required type), you should supply a third argument to bcheck: an array of strings holding the keys for which input is not optional. Then the return value will be non-zero if any required elements are missing from input.

In addition to the above you may wish to impose lower and/or upper bounds on the value of one or more scalar members of the bundle argument. If so, add a bundle named bounds to your template bundle. Each member of this secondary bundle should have a key that identifies a member of the template bundle; its value should be a 2-vector holding lower and upper limits. Put NA in place of one of the limits if it is unbounded. So, for example, the following code will check that if x1 is given in the caller's input it is between 1 and 5, and if x2 is given it is non-negative:

	  template.bounds = _(x1={1,5}, x2={0,NA})

If no errors are detected on any of these points, values supplied in input are copied to target (defaults being replaced by valid selections on the caller's part). If errors are found a message will be printed indicating what is wrong with input.

To give a simple example, suppose your function's argument bundle supports a matrix X (required), a non-negative scalar z with default value 0, and a string s with default value "display". Then the following code fragment would be suitable for checking a bundle named uservals supplied by the caller:

	  bundle target = _(X={}, z=0, s="display")
	  target.bounds = _(z={0,NA})
	  strings req = defarray("X")
	  err = bcheck(&target, uservals, req)
	  if err
	     # react appropriately
	  else
	     # proceed, using the values in target
	  endif

No input bundle

If the input bundle is not supplied to bcheck, it behaves as follows. If the required-keys argument is not given, it returns zero (since none of the error conditions mentioned above can occur), and target is not modified. Otherwise it returns non-zero since it's clear that one or more specifications must be missing. This means that it's safe to pass a null input to bcheck.

Computes one of the Bessel function variants for order v and argument x. The return value is of the same type as x. The specific function is selected by the first argument, which must be J, Y, I, or K. A good discussion of the Bessel functions can be found on Wikipedia; here we give a brief account.

case J: Bessel function of the first kind. Resembles a damped sine wave. Defined for real v and x, but if x is negative then v must be an integer.

case Y: Bessel function of the second kind. Defined for real v and x but has a singularity at x = 0.

case I: Modified Bessel function of the first kind. An exponentially growing function. Acceptable arguments are as for case J.

case K: Modified Bessel function of the second kind. An exponentially decaying function. Diverges at x = 0 and is not defined for negative x. Symmetric around v = 0.

Numerical maximization via the method of Broyden, Fletcher, Goldfarb and Shanno. On input the vector b should hold the initial values of a set of parameters, and the argument f should specify a call to a function that calculates the (scalar) criterion to be maximized, given the current parameter values and any other relevant data. If the object is in fact minimization, this function should return the negative of the criterion. On successful completion, BFGSmax returns the maximized value of the criterion, and b holds the parameter values which produce the maximum.

The optional third argument provides a means of supplying analytical derivatives (otherwise the gradient is computed numerically). The gradient function call g must have as its first argument a predefined matrix that is of the correct size to contain the gradient, given in pointer form. It also must take the parameter vector as an argument (in pointer form or otherwise). Other arguments are optional.

Given a matrix B containing only zeros and ones, this function interprets each row as the binary representation of a 32-bit unsigned integer, and returns a column vector with the decimal representation of those integers. The argument cannot have more than 32 columns otherwise an error is flagged.

Note that the least significant bit comes in the first column. So column 1 corresponds to 2⁰, column 2 to 2¹, and so on. For example, the expression

	  scalar x = bin2dec({1,0,1})

stores the value 5 into x.

Returns the binomial coefficient, that is the number of ways in which k items can be chosen from n items without repetition, irrespective of ordering. This is also equal to the coefficient of the (k+1)-th term in the polynomial expansion of the binomial power (1+x)^n.

For integer arguments the result is n!/(k!(n-k)!) but the function also accepts noninteger arguments, and the formula above generalizes to Γ(n+1)/(Γ(k+1) × Γ(n-k+1)).

When k > n or k < 0 no valid answer exists and an error is flagged.

If the two arguments differ in type, the type of the result is the "higher" of the two, where the ordering is matrix > series > scalar. For example, if n is a scalar and k an r-vector (or vice versa) the result is an r-vector. Note that matrix arguments must be vectors, and if neither argument is a scalar the two arguments must be of the same length.

Binary permutations: returns a p x n matrix, each of whose rows holds a distinct arrangement of k ones and n – k zeros (in lexicographic order). The maximum supported value of n is 64, n and k must be non-negative, and k must be no greater than n; otherwise an error is flagged. In case n = k = 0 an empty matrix is returned.

For example, with n = 4 and k = 2, the result is

	  0   0   1   1 
	  0   1   0   1 
	  0   1   1   0 
	  1   0   0   1 
	  1   0   1   0 
	  1   1   0   0

Returns the result from application of the Baxter–King bandpass filter to the series y. The optional parameters f1 and f2 represent, respectively, the lower and upper bounds of the range of frequencies to extract, while k is the approximation order to be used.

If these arguments are not supplied then the default values depend on the periodicity of the dataset. For yearly data the defaults for f1, f2 and k are 2, 8 and 3, respectively; for quarterly data, 6, 32 and 12; for monthly data, 18, 96 and 36. These values are chosen to match the most common choice among practitioners, that is to use this filter for extracting the "business cycle" frequency component; this, in turn, is commonly defined as being between 18 months and 8 years. The filter, per default choice, spans 3 years of data.

Returns the Box–Cox transformation with parameter d for the positive series y (or the columns of matrix y).

The result is (y^d - 1)/d for d not equal to zero, or log(y) for d = 0.

Reads a bundle from the file specified by the fname argument. By default the bundle is assumed to be represented in XML, and to be gzip-compressed if fname has extension .gz. But if the extension is .json or .geojson the content is assumed to be JSON.

In the XML case the file must contain a gretl-bundle element, which is used to store zero or more bundled-item elements. For example,

	  
	  
          moo
          3
	  

If the bundle B contains a member under the key oldkey, its key is changed to newkey, otherwise an error is flagged. Returns 0 on successful renaming.

Changing the key of a bundle member is not a common task but it can arise in the context of functions that work with bundles, and brename is an efficient tool for the job. Example:

	  # set up a bundle holding a big matrix
	  bundle b
	  b.X = mnormal(1000, 1000)
	  if 0
	      # change the key manually
	      Xcopy = b.X
	      delete b.X
	      b.Y = Xcopy
	      delete Xcopy
	  else
	      # versus: change it efficiently
	      brename(b, "X", "Y")
	  endif

The first method requires that the big matrix be copied twice, out of the bundle then back into it under a different key; the efficient method changes the key directly.

Returns the result from application of a low-pass Butterworth filter with order n and frequency cutoff omega to the series y. The cutoff is expressed in degrees and must be greater than 0 and less than 180. Smaller cutoff values restrict the pass-band to lower frequencies and hence produce a smoother trend. Higher values of n produce a sharper cutoff, at the cost of possible numerical instability.

Returns an m x n real matrix holding the complex "argument" of each element of the m x n complex matrix C. The argument of the complex number z = x + yi can also be computed as atan2(y, x).

Centers the columns of matrix X around their means. If the optional second argument has a non-zero value then in addition the centered values are divided by the column standard deviations (which are calculated using n – 1 as divisor, where n is the number of rows of X).

If a non-zero value is supplied for skip_na missing values are ignored, otherwise if a column of X contains any missing values the corresponding column in the output is all missing.

This is a legacy function, predating gretl's native support for complex matrices.

This function returns a list in which each series in L that has the "coded" attribute is replaced by a set of dummy variables representing each of its coded values, with the least value omitted. If L contains no coded series the return value will be identical to L.

The generated dummy variables, if any, are named on the pattern Dvarname_vi where vi is the i^th represented value of the coded variable. In case any values are negative, "m" is inserted before the (absolute) value of vi.

For example, suppose L contains a coded series named C1 with values –9, –7, 0, 1 and 2. Then the generated dummies will be DC1_m7 (coding for C1 = –7), DC1_0 (coding for C1 = 0), and so on.

Performs a Cholesky decomposition of A. If A is real it must be symmetric and positive definite; if so, the result is a lower-triangular matrix L which satisfies A = LL'. If A is complex it must be Hermitian and positive definite, and the result is a lower-triangular complex matrix such that A = LL^H. Otherwise, the function will return an error.

Returns an m x n real matrix holding the complex modulus of each element of the m x n complex matrix C. The modulus of the complex number z = x + yi equals the square root of x² + y².

This is a legacy function, predating gretl's native support for complex matrices.

If the col argument is given, retrieves the name for column col of matrix M. If M has no column names attached the value returned is an empty string; if col is out of bounds for the given matrix an error is flagged.

If no second argument is given, retrieves an array of strings holding the column names from M, or an empty array if M does not have column names attached.

Example:

	  matrix A = { 11, 23, 13 ; 54, 15, 46 }
	  cnameset(A, "Col_A Col_B Col_C")
	  string name = cnameget(A, 3)
	  print name

Attaches names to the columns of the T x k matrix M. If S is a named list, the names are taken from the names of the listed series; the list must have k members. If S is an array of strings, it should contain k elements. A single string is also acceptable as the second argument; in that case it should contain k space-separated substrings. As a special case, passing an empty string as the second argument has the effect of removing any existing column names.

Returns the matrix A premultiplied by the commutation matrix K_m,n (using an algorithm that is more efficient than explicit multiplication). Each column of A is assumed to come from a vec operation on a m x n matrix. In particular,

	  commute(vec(B), rows(B), cols(B))

gives vec(B'). In order to compute the commutation matrix proper, just apply the function to an appropriately sized identity matrix. For example:

	  K_32 = commute(I(6), 3, 2)

The optional argument n defaults to m. If the optional argument post is non-zero, then post-multiplication is performed instead of pre-multiplication; the optional Boolean switch add_id will premultiply A by I + K_m,n instead of K_m,n.

Returns an m x n complex matrix holding the complex conjugate of each element of the m x n complex matrix C. The conjugate of the complex number z = x + yi equals x – yi.

Provides a means of determining whether the numerical object x contains any of the elements of S, a matrix which plays the role of a set.

The return value is an object of the same size as x containing 1s in positions where a value of x matches any element of S and zeros elsewhere. For example, the code

	  matrix A = mshape(seq(1,9), 3, 3)
	  matrix C = contains(A, {1, 5, 9})

gives

	  A (3 x 3)

	  1   4   7
	  2   5   8
	  3   6   9

	  C (3 x 3)

	  1   0   0
	  0   1   0
	  0   0   1

This function may be particularly useful when x is a series that contains a fine-grained encoding for a qualitative characteristic, and you wish to reduce this to a smaller number of categories. You can pack into S a set of values to be consolidated, and obtain a dummy variable with value 1 for observations matching this set, 0 otherwise.

Since S serves as a set, for greatest efficiency it should be a vector with no repeated values, however an arbitrary matrix is accepted.

Computes the 2-dimensional convolution of the matrices A and B. If A is r x c and B is m x n then the returned matrix will have r+m-1 rows and c+n-1 columns.

Given an m x n complex matrix Z, returns an m x n real matrix holding the quadrance of the elements of Z. The quadrance of the complex number z = a + bi is a² + b². It therefore equals the squared modulus of z and also equals z multiplied by its complex conjugate, but the direct calculation carried out by cquad is considerably faster than either of the alternative approaches.

On the basis of a cross-tabulation of a and b, returns an integer code indicating the sort of correspondence between the two variables, as follows.

• Code = 2: there’s a 1-to-1 relationship.

• Code = 1: there’s a 1-to-n relationship (a "nests" b, can be interpreted as a function of b in the mathematical sense).

• Code = –1: there’s an n-to-1 relationship (b "nests" a, can be interpreted as a function of a).

• Code = 0: there’s no relationship.

Note that these codes are based solely on the sample values of the two arguments. In case b is the square of a, for example, the result will differ depending on whether a contains some pairs of values that differ only by sign (code = –1), or not (code = 2).

One possible use case is to check whether two discrete series encode the same information. For example, the following:

	  open grunfeld.gdt
	  c = corresp($unit, firm)

gives c = 2, indicating that the series firm is in fact a unique identifier for the cross-sectional units in this panel dataset.

If only the first two arguments are given, computes the correlogram for x for lags 1 to p. Let k represent the number of elements in x (1 if x is a series, the number of columns if x is a matrix, or the number of list-members if x is a list). The return value is a matrix with p rows and 2k columns, the first k columns holding the respective autocorrelations and the remainder the respective partial autocorrelations.

If a third argument is given, this function computes the cross-correlogram for each of the k elements in x and y, from lead p to lag p. The returned matrix has 2p + 1 rows and k columns. If x is series or list and y is a vector, the vector must have just as many rows as there are observations in the current sample range.

Returns the hyperbolic cosine of x.

Critical value calculator. Returns x such that P(X > x) = p, where the distribution X is determined by the character c. Between the arguments c and p, zero or more additional scalar arguments are required to specify the parameters of the distribution, as follows.

• Standard normal (c = z, n, or N): no extra arguments

• Student's t (t): degrees of freedom

• Chi square (c, x, or X): degrees of freedom

• Snedecor's F (f or F): df (num.); df (den.)

• Binomial (b or B): probability; trials

• Poisson (p or P): mean

• Laplace (l or L): mean; scale

• Standardized GED (E): shape

Reinterprets a real matrix as holding complex values or vice versa. The precise action depends on mode (which must have value 1, 2, 3 or 4) as follows:

mode 1: A must be a real matrix with an even number of columns. Returns a complex matrix with half as many columns, the odd-numbered columns of A supplying the real parts and the even-numbered columns the imaginary parts.

mode 2: Performs the inverse operation of mode 1. A must be a complex matrix and the return value is a real matrix with twice as many columns as A.

mode 3: A must be a real matrix with an even number of rows. Returns a complex matrix with half as many rows, the odd-numbered rows of A supplying the real parts and the even-numbered rows the imaginary parts.

mode 4: Performs the inverse operation of mode 3. A must be a complex matrix and the return value is a real matrix with twice as many rows as A.

Cumulates x (that is, creates a running sum). When x is a series, produces a series y each of whose elements is the sum of the values of x to date; the starting point of the summation is the first non-missing observation in the currently selected sample. If any missing values are encountered in x, subsequent values of y will be set to missing. When x is a matrix, its elements are cumulated by columns.

In the case of panel data cumulation is in the time dimension, starting anew for each panel unit.

Provides a somewhat flexible means of obtaining a text buffer containing data from an internet server, using libcurl. On input the bundle b must contain a string named URL which gives the full address of the resource on the target host. Other optional elements are as follows.

• "header": a string specifying an HTTP header to be sent to the host.

• "postdata": a string holding data to be sent to the host.

Returns the number of (relevant) days between the epoch days ed1 and ed2, inclusive. The weeklen, which must equal 5, 6 or 7, gives the number of days in the week that should be counted (a value of 6 omits Sundays, and a value of 5 omits both Saturdays and Sundays).

This function returns the binary representation of the numbers contained in the column vector x, by storing each binary digit into a column of the returned matrix, which always has 32 columns. Each element of x must be an integer between 0 and 2³²-1. Otherwise, an error is flagged.

Note that the least significant bit comes in the first column. So column 1 corresponds to 2⁰, column 2 to 2¹, and so on. For example, the expression

	  matrix B = dec2bin(5)

produces a row vector full of zeros except for positions 1 and 3.

Enables the definition of an array variable in extenso, by providing one or more elements. In using this function you must specify a type (in plural form) for the array: strings, matrices, bundles or lists. Each of the arguments must evaluate to an object of the specified type. On successful completion, the return value is an array of n elements, where n is the number of arguments.

	  strings S = defarray("foo", "bar", "baz")
	  matrices M = defarray(I(3), X'X, A*B, P[1:])

Enables the initialization of a bundle variable in extenso, by providing zero or more pairs of the form key, member. If we count the arguments from 1, every odd-numbered argument must evaluate to a string (key) and every even-numbered argument must evaluate to an object of a type that can be included in a bundle.

A couple of simple examples:

	  bundle b1 = defbundle("s", "Sample string", "m", I(3))
	  bundle b2 = defbundle("yn", normal(), "x", 5)

The first example creates a bundle with members a string and a matrix; the second, a bundle with a series member and a scalar member. Note that you cannot specify a type for each argument when using this function, so you must accept the "natural" type of the argument in question. If you wanted to add a series with constant value 5 to a bundle named b1 it would be necessary to do something like the following (after declaring b1):

	  series b1.s5 = 5

If no arguments are given to this function it is equivalent to creating an empty bundle (or to emptying an existing bundle of its content), as could also be done via

	  bundle b = null

Variant syntax

Two alternative forms of syntax are available for defining bundles. In each case the keyword defbundle is replaced by a single underscore. In the first variant the comma-separated arguments take the form key=value, where the key is taken to be a literal string and does not require quotation. Here is an example:

	  bundle b = _(x=5, strval="some string", m=I(3))

This form is particularly convenient for constructing an anonymous bundle on the fly as a function argument, as in

	  b = regls(ys, LX, _(lfrac=0.35, stdize=0))

where the regls function takes an optional bundle argument holding various parameters.

The second variant is designed for the case where you wish to pack several pre-existing named objects into a bundle: you just give their names, unquoted:

	  bundle b = _(x, y, z)

Here the object x is copied into the bundle under the key "x", and similarly for y and z.

These alternative forms involve less typing than the full defbundle() version and are likely to be more convenient in many cases, but note that they are less flexible. Only the full version can handle keys given as string variables rather than literal strings.

Defines a list (of named series), given one or more suitable arguments. Each argument must be a named series (given by name or integer ID number), an existing named list, or an expression which evaluates to a list (including a vector which can be interpreted as a set of series ID numbers).

One point to note: this function simply concatenates its arguments to produce the list that it returns. If the intent is that the return value does not contain duplicates (does not reference any given series more than once), it is up to the caller to ensure that requirement is satisfied.

The primary purpose of this function is to produce a deseasonalized version of the (quarterly or monthly) input series x, using X-13ARIMA-SEATS; it is available only if X-13ARIMA-SEATS is installed. If the second, optional argument is omitted, seasonal adjustment is carried out with all X-13ARIMA options at their default values (fully automatic procedure). When opts is supplied, it may contain any of the following option specifications.

• verbose: what to print? 0 = nothing (the default); 1 = confirmation of the options selected; 2 = confirmation of options plus the output from X-13ARIMA.

• seats: 1 to use the SEATS algorithm in place of the default X11 algorithm for seasonal adjustment, or 0.

• airline: 1 to use the "airline" ARIMA model specification (0,1,1)(0,1,1) in place of the default automatic model selection, or 0.

• arima: can be used to impose a chosen ARIMA specification, in the form of a 6-vector holding small non-negative integers. These are given the (p,d,q,P,D,Q) interpretation, in traditional time-series notation: the first three terms represent the non-seasonal AR, Integration and MA orders, and the last three the seasonal counterparts. If both airline and arima are given, arima takes precedence.

• outliers: enable detection and correction for outliers (choices 1 through 7), or 0 (the default) to omit this feature. The three available outlier types with their numerical codes are: 1 = additive outlier (ao), 2 = level shift (ls), 4 = temporary change (tc). To combine options you add the codes, for example 1 + 2 + 4 = 7 to activate all three. Note that the choice 3 = 1 + 2 (ao and ls) is the default within X-13ARIMA-SEATS, and is selected via the outlier tickbox in gretl's dialog window for seasonal adjustment via X13.

• critical: a positive scalar, the critical value for defining outliers, the default being automatic, dependent on the sample size. Relevant only when outliers is specified.

• logtrans: should the input series be put in log form? 0 = no, 1 = yes, 2 = automatically selected (the default). Note that it is not recommended to pass the input series in log form; if you want the log to be used, pass the "raw" level but specify logtrans=1.

• trading_days: should trading-day effects be included? 0 = no, 1 = yes, 2 = automatic (the default).

• working_days: a simpler version of trading_days with a single distinction between weekdays and weekends rather than individual day effects. 0 = no (the default), 1 = yes, 2 = automatic. Use only one of trading_days and working_days.

• easter: 1 to allow for an easter effect, as a supplement to either trading_days or working_days, or 0 (the default).

• output: a string to select the type of the output series, "sa" for deseasonalized (the default), "trend" for the estimated trend, or "irreg" for the irregular component.

• save_spc: boolean flag, default 0; see below.

Augmented results

In some cases one may wish to obtain all three of the results available from X-13ARIMA via a single call to deseas. This is supported as follows. Pass the opts bundle in pointer form, and give the string "all" under the output key. The direct return value is then the seasonally adjusted series, but on successful completion opts will contain a matrix named results with three columns: seasonally adjusted, trend and irregular. Here's an illustration (where the direct return value is discarded).

	  bundle b = _(output="all")
	  deseas(y, &b)
	  series y_dseas = b.results[,1]
	  series y_trend = b.results[,2]
	  series y_irreg = b.results[,3]

Saving the X-13ARIMA specification

The save_spc flag can be used to save the content of the X-13ARIMA input file written by gretl. The options bundle should be passed in pointer form and the specification (as a string) can be found under the key x13a_spc. The following code illustrates saving this to file under the name myspec.spc in the user's working directory. (Note that the .spc extension is required by X-13ARIMA.)

	  bundle b = _(save_spc=1)
	  deseas(y, &b)
	  outfile myspec.spc
	     print b.x13a_spc
	  end outfile

Returns the direct sum of A and B, that is a matrix holding A in its north-west corner and B in its south-east corner. If both A and B are square, the resulting matrix is block-diagonal.

Computes first differences. If y is a series, or a list of series, starting values are set to NA. If y is a matrix, differencing is done by columns and starting values are set to 0.

When a list is returned, the individual variables are automatically named according to the template d_ varname where varname is the name of the original series. The name is truncated if necessary, and may be adjusted in case of non-uniqueness in the set of names thus constructed.

Returns the digamma (or Psi) function of x, that is the derivative of the log of the Gamma function.

Computes distances between points on a metric that can be euclidean (the default), manhattan, hamming, chebyshev, cosine or mahalanobis. The string identifying the metric can be given as an unambiguous truncation. The additional metrics correlation, standardized Euclidean are supported via simple transformations of the inputs; see below.

Each row of the m x n matrix X is treated as a point in an n-dimensional space; in an econometric context this is likely to represent a single observation comprising the values of n variables.

Standard cases

This section applies to all metrics except the Mahalanobis distance, for which the syntax is slightly different (see below).

If Y is not given, the return value is a column vector of length m(m – 1)/2 comprising the non-redundant subset of all pairwise distances between the m points (rows of X). Given such a vector named d, the full symmetric matrix of inter-point distances (with zeros on the principal diagonal) can be constructed via

	  D = unvech(d, 0)

Returns the density of the standard normal distribution at x. To get the density for a non-standard normal distribution at x, pass the z-score of x to the dnorm function and multiply the result by the Jacobian of the z transformation, namely 1 over σ, as illustrated below:

	  mu = 100
	  sigma = 5
	  x = 109
	  fx = (1/sigma) * dnorm((x-mu)/sigma)

Returns a list with the same elements as X, but for the collinear series. Therefore, if all the series in X are linearly independent, the output list is just a copy of X.

The algorithm uses the QR decomposition (Householder transformation), so it is subject to finite precision error. In order to gauge the sensitivity of the algorithm, a second optional parameter epsilon may be specified to make the collinearity test more or less strict, as desired. The default value for epsilon is 1.0e-8. Setting epsilon to a larger value increases the probability of a series to be dropped.

Example:

	  nulldata 20
	  set seed 9876
	  series foo = normal()
	  series bar = normal()
	  series foobar = foo + bar
	  list X = foo bar foobar
	  list Y = dropcoll(X)
	  list print X
	  list print Y
	  # set epsilon to a ridiculously small value
	  list Y = dropcoll(X, 1.0e-30)
	  list print Y

produces

	  ? list print X
	  foo bar foobar
	  ? list print Y
	  foo bar
	  ? list Y = dropcoll(X, 1.0e-30)
	  Replaced list Y
	  ? list print Y
	  foo bar foobar

The argument x should be a discrete series. This function creates a set of dummy variables coding for the distinct values in the series. By default the smallest value is taken as the omitted category and is not explicitly represented.

The optional second argument represents the value of x which should be treated as the omitted category. The effect when a single argument is given is equivalent to dummify(x, min(x)). To produce a full set of dummies, with no omitted category, use dummify(x, NA).

The generated variables are automatically named according to the template Dvarname_i where varname is the name of the original series and i is a 1-based index. The original portion of the name is truncated if necessary, and may be adjusted in case of non-uniqueness in the set of names thus constructed.

Given the year in argument y, returns the date of Easter on the Gregorian calendar as month + day/100. For example, in 2014 the date of Easter was April 20, which is represented under this convention as 4.2. (Note that April 2 would be returned as 4.02.) The following code shows how month and day can be extracted from the return value.

	  scalar e = easterday(2014)
	  scalar m = floor(e)
	  scalar d = round(100*(e-m))

Calculates the empirical CDF of y. This is returned in a matrix with two columns: the first holds the sorted unique values of y and the second holds the cumulative relative frequency, that is the count of observations whose value is less than or equal to the value in the first column, divided by the total number of observations.

Solves the generalized eigenvalue problem |A – λB| = 0, where both A and B are symmetric and B is positive definite. The eigenvalues are returned directly, arranged in ascending order. If the optional third argument is given it should be the name of an existing matrix preceded by &; in that case the generalized eigenvectors are written to the named matrix.

Returns the number of the day in the current epoch specified by year, month and day. The epoch day equals 1 for the first of January in the year 1 AD on the proleptic Gregorian calendar; it stood at 733786 on 2010-01-01. If any of the arguments are given as series the value returned is a series, otherwise it is a scalar.

By default the year, month and day values are assumed to be given relative to the Gregorian calendar, but if the year is a negative value the interpretation switches to the Julian calendar.

An alternative call is also supported: if a single argument is given, it is taken to be a date (or series of dates) in ISO 8601 "basic" numeric format, YYYYMMDD. So the following two calls produce the same result, namely 700115.

	  eval epochday(1917, 11, 7)
	  eval epochday(19171107)

Returns non-zero if name, which should be valid as a gretl identifier, names a currently defined object, be it a scalar, a series, a matrix, list, string, bundle or array; otherwise returns 0.

Produces a matrix holding several statistics which serve to evaluate f as a forecast of the observed data y.

If f is a series or vector the output is a column vector; if f is a list with k members or a T x k matrix the output has k columns, each of which holds statistics for the corresponding element (series or column) of the input as a forecast of y.

In all cases the "vertical" dimension of the input (for a series or list the length of the current sample range, for a matrix the number of rows) must match across the two arguments.

The rows of the returned matrix are as follows:

	  1  Mean Error (ME)
	  2  Root Mean Squared Error (RMSE)
	  3  Mean Absolute Error (MAE)
	  4  Mean Percentage Error (MPE)
	  5  Mean Absolute Percentage Error (MAPE)
	  6  Theil's U (U1 or U2)
	  7  Bias proportion, UM
	  8  Regression proportion, UR
	  9  Disturbance proportion, UD

The variant of Theil's U shown by default depends on the nature of the data: if they are known to be time series then U2 is shown, otherwise U1 is produced. But this choice can be forced via the optional trailing argument: give a non-zero value to force U2, or zero to force U1.

Calculates a numerical approximation to the Jacobian associated with the n-vector b and the transformation function specified by the argument fcall. The function call should take b as its first argument (either straight or in pointer form), followed by any additional arguments that may be needed, and it should return an m x 1 matrix. On successful completion fdjac returns an m x n matrix holding the Jacobian.

The optional third argument can be used to set the step size h used in the approximation mechanism (see below); if this argument is omitted the step size is determined automatically.

Here is an example of usage:

	  matrix J = fdjac(theta, myfunc(&theta, X))

The function can use three different methods: simple forward-difference, bilateral difference or 4-nodes Richardson extrapolation. Respectively:

J₀ = (f(x+h) - f(x))/h

J₁ = (f(x+h) - f(x-h))/2h

J₂ = [8(f(x+h) - f(x-h)) - (f(x+2h) - f(x-2h))] /12h

Primarily useful for writers of functions. The first argument should be the name of a function; the remaining arguments will be passed to the specified function. This permits treating the function identified by funcname as itself a variable. The return value is whatever the named function returns given the specified arguments.

The example below illustrates some possible uses.

	  function scalar utility (scalar c, scalar sigma)
	      return (c^(1-sigma)-1)/(1-sigma)
	  end function

	  strings S = defarray("log", "utility")

	  # call a 1-argument built-in function
	  x = feval(S[1], 2.5)
	  # call a user-defined function
	  x = feval(S[2], 5, 0.5)
	  # a 2-argument built-in function
	  func = "zeros"
	  m = feval(func, 5-2, sqrt(4))
	  print m
	  # a 3-argument built-in
	  x = feval("monthlen", 12, 1980, 5)

Discrete Fourier transform. The input matrix X may be real or complex. The output is a complex matrix of the same dimensions as X.

Inverse discrete Fourier transform. It is assumed that X contains n complex column vectors. A matrix with n columns is returned.

Computes an ARMA-like filtering of the argument x. The transformation can be written as

y_t = a₀ x_t + a₁ x_t-1 + ... a_q x_t-q + b₁ y_t-1 + ... b_py_t-p

If argument x is a series, the result will be itself a series. Otherwise, if x is a matrix with T rows and k columns, the result will be a matrix of the same size, in which the filtering is performed column by column.

The two arguments a and b are optional. They may be scalars, vectors or the keyword null.

If a is a scalar, this is used as a₀ and implies q=0; if it is a vector of q+1 elements, they contain the coefficients from a₀ to a_q. If a is null or omitted, this is equivalent to setting a₀ =1 and q=0.

If b is a scalar, this is used as b₁ and implies p=1; if it is a vector of p elements, they contain the coefficients from b₁ to b_p. If b is null or omitted, this is equivalent to setting B(L)=1.

The optional scalar argument y0 is taken to represent all values of y prior to the beginning of sample (used only when p > 0). If omitted, it is understood to be 0. Similarly, the optional argument x0 may be used to specify one or more pre-sample values of x, information that is relevant only when q > 0. Otherwise pre-sample values of x are assumed to be zero.

"Flattens" either an array of matrices into a single matrix or an array of strings into a single string.

Matrices

In the matrix case, the way the matrices in A are joined together depends on the the alt argument, which should have value 0 (horizontal), 1 (vertical) or 2 ("vec-wise"). The best way to explain the difference between the three alternatives is by example: the code

	  X = {1,3,5; 2,4,6}
	  A = defarray(X, X+6)
	  U = flatten(A,0) # = A[1] ~ A[2]
	  V = flatten(A,1) # = A[1] | A[2]
	  W = flatten(A,2) # = vec(A[1]) ~ vec(A[2])

produces the following three matrices:

	  U (2 x 6)

	  1    3    5    7    9   11 
	  2    4    6    8   10   12 

	  V (4 x 3)

	  1    3    5 
	  2    4    6 
	  7    9   11 
	  8   10   12 

	  W (6 x 2)

	  1    7 
	  2    8 
	  3    9 
	  4   10 
	  5   11 
	  6   12 

Returns the fractional difference of order d for the series y.

Note that in theory fractional differentiation is an infinitely long filter. In practice, presample values of y_t are assumed to be zero.

A negative value of d can be given, in which case fractional integration is performed.

Attempts to find a single root of a continuous (typically nonlinear) function f—that is, a value of the scalar variable x such that f(x) = 0. The fcall argument should provide a call to the function in question; fcall may include an arbitrary number of arguments but the first one must be the scalar playing the role of x. On successful completion the value of the root is returned.

Returns the gamma function of x.

Provides the script writer with a convenient means of generating series whose names are not known in advance, and/or creating a series and appending it to a list in a single operation.

The first argument gives the name of the series to create (or modify); this can be a string literal, a string variable, or an expression that evaluates to a string. The second argument, rhs ("right-hand side"), defines the source series: this can be the name of an existing series or an expression that evaluates to a series, as would appear to the right of the equals sign when defining a series in the usual way.

The return value from this function is the ID number of the series in the dataset, a value suitable for inclusion in a list (or –1 on failure).

For example, suppose you want to add n random normal series to the dataset and put them all into a named list. The following will do the job:

	  nulldata 10
	  list Normals = null
	  scalar n = 3
	  loop i = 1 .. n
	      Normals += genseries(sprintf("norm%d", i), normal())
	  endloop

On completion Normals will contain the series norm1, norm2 and norm3 .

Returns an array of strings holding the keys identifying the contents of b. If the bundle is empty an empty array is returned.

This function is used to read successive lines from source, which should be a named string variable. On each call a line from the source is written to target (which must also be a named string variable, given in pointer form), with the newline character stripped off. The valued returned is 1 if there was anything to be read (including blank lines), 0 if the source has been exhausted.

Here is an example in which the content of a text file is broken into lines:

	  string s = readfile("data.txt")
	  string line
	  scalar i = 1
	  loop while getline(s, &line)
	      printf "line %d = '%s'\n", i++, line
	  endloop

In this example we can be sure that the source is exhausted when the loop terminates. If the source might not be exhausted you should follow your regular call(s) to getline with a "clean up" call, in which target is replaced by null (or omitted altogether) as in

	  getline(s, &line) # get a single line
	  getline(s, null) # clean up

Note that although the reading position advances at each call to getline, source is not modified by this function, only target.

Returns Gini's inequality index for the (non-negative) series or vector y. A Gini value of zero indicates perfect equality. The maximum Gini value for a series with n members is (n – 1)/n, occurring when only one member has a positive value; a Gini of 1.0 is therefore the limit approached by a large series with maximal inequality.

Returns A⁺, the Moore–Penrose or generalized inverse of the r x c matrix A, computed via the singular value decomposition.

One-dimensional maximization via the Golden Section Search method. The matrix b should be a 3-vector. On input the first element is ignored while the second and third elements set the lower and upper bounds on the search. The fncall argument should specify a call to a function that returns the value of the maximand; element 1 of b, which will hold the current value of the adjustable parameter when the function is called, should be given as its first argument; any other required arguments may then follow. The function in question should be unimodal (should have no local maxima other than the global maximum) over the stipulated range, or GSS is not sure to find the maximum.

On successful completion GSSmax returns the optimum value of the maximand, while b holds the optimal parameter value along with the limits of its bracket.

The optional third argument may be used to set the tolerance for convergence, that is, the maximum acceptable width of the final bracket for the parameter. If this argument is not given a value of 0.0001 is used.

If the object is in fact minimization, either the function call should return the negative of the criterion or alternatively GSSmax may be called under the alias GSSmin.

Here is a simple example of usage:

	  function scalar trigfunc (scalar theta)
	      return 4 * sin(theta) * (1 + cos(theta))
	  end function

	  matrix m = {0, 0, $pi/2}
	  eval GSSmax(&m, trigfunc(m[1]))
	  printf "\n%10.7f", m

Horizontal direct product. The two arguments must have the same number of rows, r. The return value is a matrix with r rows, in which the i-th row is the Kronecker product of the corresponding rows of X and Y. If Y is omitted, the "shorthand" syntax applies (see below).

If X is an r x k matrix and Y is an r x m matrix, the result will be a matrix with r rows and km columns.

This operation is called "horizontal direct product" in conformity to its implementation in the GAUSS programming language. Its equivalent in standard matrix algebra would be called the row-wise Khatri-Rao product, or "face-splitting" product in the signal processing literature.

Example: the code

	  A = {1,2,3; 4,5,6}
	  B = {0,1; -1,1}
	  C = hdprod(A, B)

produces the following matrix:

          0    1    0    2    0    3
         -4    4   -5    5   -6    6

Shorthand syntax

If X and Y are the same matrix, then each row of the result is the vectorization of a symmetric matrix. In these cases, the second argument may be omitted; however, the returned matrix will only contain the non-redundant columns, and will therefore have k(k+1)/2 columns. For example,

	  A = {1,2,3; 4,5,6}
	  C = hdprod(A)

produces

	  1    2    3    4    6    9
	  16   20   24   25   30   36

Note that the i-th row of C is vech(a_i a_i'), where a_i is the i-th row of A.

When using the shorthand syntax with complex matrices, the implicit second argument will be the conjugate of the first one, so as to make each row of the result the symmetric vectorization of a Hermitian matrix.

Given a MIDAS list, produces a list of the same length holding high-frequency first differences. The second argument is optional and defaults to unity: it can be used to multiply the differences by some constant.

Given a MIDAS list, produces a list of the same length holding high-frequency log-differences. The second argument is optional and defaults to unity: it can be used to multiply the differences by some constant, for example one might give a value of 100 to produce (approximate) percentage changes.

Given a MIDAS list, hfvars, produces a list holding high-frequency lags minlag to maxlag. Use positive values for actual lags, negative for leads. For example, if minlag is –3 and maxlag is 5 then the returned list will hold 9 series: 3 leads, the contemporary value, and 5 lags.

Note that high-frequency lag 0 corresponds to the first high frequency period within a low frequency period, for example the first month of a quarter or the first day of a month.

Produces from the vector x a MIDAS list of m series, where m is the ratio of the frequency of observation for the variable in x to the base frequency of the current dataset. The value of m must be at least 3 and the length of x must be m times the length of the current sample range.

The names of the series in the returned list are constructed from the given prefix (which must be an ASCII string of 24 characters or less, and valid as a gretl identifier), plus one or more digits representing the sub-period of the observation. An error is flagged if any of these names duplicate names of existing objects.

Returns the cycle component from application of the Hodrick–Prescott filter to series y. If the smoothing parameter, lambda, is not supplied then a data-based default is used, namely 100 times the square of the periodicity (100 for annual data, 1600 for quarterly data, and so on).

Returns the Gauss hypergeometric function for real argument x.

If x is a scalar, the return value will be scalar; otherwise, it will be a matrix the same size as x.

If m is omitted, returns an identity matrix of order n. Otherwise returns an n x m matrix with ones on the main diagonal and zeros elsewhere.

Returns the row indices of the maxima of the columns of X. For columns containing NAs the result is also set to NA, unless the optional argument skip_na is nonzero, in which case the index for the maximum valid entry will be returned.

Returns the column indices of the maxima of the columns of X. For rows containing NAs the result is also set to NA, unless the optional argument skip_na is nonzero, in which case the index for the maximum valid entry will be returned.

Returns the row indices of the minima of the columns of X. For columns containing NAs the result is also set to NA, unless the optional argument skip_na is nonzero, in which case the index for the minimum valid entry will be returned.

Returns the column indices of the minima of the rows of X. For rows containing NAs the result is also set to NA, unless the optional argument skip_na is nonzero, in which case the index for the minimum valid entry will be returned.

Returns the infinity-norm of X, that is, the maximum across the rows of X of the sum of absolute values of the row elements.

Returns the (1-based) position of y in list L, or 0 if y is not present in L.

The second argument may be given as the name of a series or alternatively as an integer ID number. If you know that a series of a certain name (say foo) exists, then you can call this function as, for example,

	  pos = inlist(L, foo)

Here you are, in effect, asking "Give me the position of series foo in list L (or 0 if it is not included in L)." However, if you are unsure whether a series of the given name exists, you should place the name in quotes:

	  pos = inlist(L, "foo")

In this case you are asking, "If there's a series named foo in L give me its position, otherwise return 0."

Checks the elements of the strings array S for equality with test. By default, returns a column vector of length equal to the number of matches, holding the positions of the matches within the array—or an empty matrix in case of no matches.

Example:

	  strings S = defarray("A", "B", "C", "B")
	  eval instrings(S, "B")
	  2
	  4

If a non-zero value is given for the optional simple argument, the return value is a scalar: 1 if test is found in S, 0 otherwise. In this case the implementation is able to take a shortcut, so it's more efficient if you just want a boolean answer.

Returns the integer part of x, truncating the fractional part, or NA if the result cannot be represented as a 32-bit signed integer (does not lie in the interval [–2147483648, 2147483647]).

Returns a series in which missing values in x are imputed via linear interpolation, for time series data or in the time dimension of a panel dataset. Extrapolation is not performed; missing values are replaced only if they are both preceded and followed by valid observations.

Returns the inverse of A. If A is singular or not square, an error message is produced and nothing is returned. Note that gretl checks automatically the structure of A and uses the most efficient numerical procedure to perform the inversion.

The matrix types gretl checks for are: identity; diagonal; symmetric and positive definite; symmetric but not positive definite; and triangular.

Inverse cumulative distribution function calculator. For a continuous distribution, returns x such that P(X <= x) = u, for u in the interval 0 to 1. For a discrete distribution (Binomial or Poisson), returns the smallest x such that P(X <= x) ≥ u.

The distribution of X is determined by the string d. Between the arguments d and u, zero or more additional scalar arguments are required to specify the parameters of the distribution, as follows.

• Standard normal (c = z, n, or N): no extra arguments

• Gamma (g or G): shape; scale

• Student's t (t): degrees of freedom

• Chi square (c, x, or X): degrees of freedom

• Snedecor's F (f or F): df (num.); df (den.)

• Binomial (b or B): probability; trials

• Poisson (p or P): mean

• Laplace (l or L): mean; scale

• Standardized GED (E): shape

• Non-central chi square (ncX): df, non-centrality parameter

• Non-central F (ncF): df (num.), df (den.), non-centrality parameter

• Non-central t (nct): df, non-centrality parameter

Returns the inverse Mills ratio at x, that is the ratio between the standard normal density and the complement to the standard normal distribution function, both evaluated at x.

Tests whether name is the identifier for a complex matrix. The return value is one of the following:

NA: name does not identify a matrix.

0: name identifies a real matrix, composed entirely of regular floating-point numbers ("doubles", in C parlance).

1: name identifies a "nominally" complex matrix, composed of numbers with both a real and an imaginary part, but in which all imaginary parts are zero.

2: the matrix in question holds at least one "genuinely" complex value, with a non-zero imaginary part.

Without the optional second argument, returns 1 if y has a constant value over the current sample range (or over its entire length if y is a vector), otherwise 0.

The second argument is accepted only if the current dataset is a panel and y is a series. In that case a panel-code value of 0 calls for a check for time-invariance, while a value of 1 means check for cross-sectional invariance (that is, in each time period the value of y is the same for all groups).

If y is a series, missing values are ignored in checking for constancy.

If name is the identifier for a currently defined series, returns 1 if the series is marked as discrete-valued, otherwise 0. If name does not identify a series, returns NA.

If all the values contained in x are 0 or 1 (or missing), returns the number of ones, otherwise 0.

Given a scalar argument, returns 1 if x is "Not a Number" (NaN), otherwise 0. Given a matrix argument, returns a matrix of the same dimensions with 1s in positions where the corresponding element of the input is NaN and 0s elsewhere.

Given a series date holding dates in ISO 8601 "basic" format (YYYYMMDD), this function writes the year, month and (optionally) day components into the series named by the second and subsequent arguments. An example call, assuming the series dates contains suitable 8-digit values:

	  series y, m, d
	  isoconv(dates, &y, &m, &d)

The nominal return value is 0 on successful completion; in case of failure an error is flagged.

This function maps between the four designations for countries present in ISO 3166, namely

1. Country name

2. Alpha-2 code (two uppercase letters)

3. Alpha-3 code (three uppercase letters)

4. Numeric code (3 digits)

Given a country's designation in one form, the return value is its designation in the form (1 to 4) selected by the optional output argument or, if this argument is omitted, a default conversion as follows: when source is a country name the return value is the country's 2-letter code; otherwise the return value is the country name. Various valid calls are illustrated below in interactive form.

	  ? eval isocountry("Bolivia")
	  BO
	  ? eval isocountry("Bolivia", 3)
	  BOL
	  ? eval isocountry("GB")
	  United Kingdom of Great Britain and Northern Ireland
	  ? eval isocountry("GB", 3)
	  GBR
	  ? strings S = defarray("ES", "DE", "SD")
	  ? strings C = isocountry(S)
	  ? print C
	  Array of strings, length 3
	  [1] "Spain"
	  [2] "Germany"
	  [3] "Sudan"
	  ? matrix m = {4, 840}
	  ? C = isocountry(m)
	  ? print C
	  Array of strings, length 2
	  [1] "Afghanistan"
	  [2] "United States of America"

When source is in form 4 (numeric code) this can be given as a string or array of strings (for example, "032" for Argentina) or in numeric form. In the latter case source may be given as a series or vector, though an error will be flagged if any of the numbers are out of the range 0 to 999.

The argument ed is interpreted as an epoch day, which equals 1 for the first of January in the year 1 AD on the proleptic Gregorian calendar. The default return value (of the same type as ed) is an 8-digit number, or a series of such numbers, on the pattern YYYYMMDD (ISO 8601 "basic" format), giving the Gregorian calendar date corresponding to the epoch day.

Returns the ISO 8601 week number corresponding to the date(s) specified by the three arguments, or NA if the date is invalid. Note that all three arguments must be of the same type, either scalars (integers) or series.

Computes a kernel density estimate (or set of estimates) for the argument x, which may be a single series or vector or a list or matrix with more than column. The returned matrix has k + 1 columns, where k is the number of elements (series or columns) in x. The first column holds a set of evenly spaced abscissae and the rest hold the estimated density or densities at each of these points.

The formula used to compute the estimated density at each reference point, x, is

where n denotes the number of data points, h is a "bandwidth" parameter, and k() is the kernel function. The larger the value of the bandwidth parameter, the smoother the estimated density.

Returns a row vector containing critical values at the 10, 5 and 1 percent levels for the KPSS test for stationarity of a time series. T should give the number of observations and trend should be 1 if the test includes a trend, 0 otherwise.

Sets up a Kalman bundle, that is an object which contains all the information needed to define a linear state space model of the form

where Var(u) = R, and state transition equation

where Var(v) = Q.

Returns the excess kurtosis of the series x, skipping any missing observations.

If the first argument is a scalar, generates lags 1 to p of the series y, or if y is a list, of all series in the list, or if y is a matrix, of all columns in the matrix. If p = 0 and y is a series or list, the maximum lag defaults to the periodicity of the data; otherwise p must be positive.

If a vector is given as the first argument, the lags generated are those specified in the vector. Common usage in this case would be to give p as, for example, seq(3,7), hence omitting the first and second lags. However, it is OK to give a vector with gaps, as in {3,5,7}, although the lags should always be given in ascending order.

In the case of list output, the generated variables are automatically named according to the template varname _ i where varname is the name of the original series and i is the specific lag. The original portion of the name is truncated if necessary, and may be adjusted in case of non-uniqueness in the set of names thus constructed.

When y is a list, or a matrix with more than one column, and the lag order is greater than 1, the default ordering of the terms in the return value is by variable: all lags of the first input series or column followed by all lags of the second, and so on. The optional third argument can be used to change this: if bylag is non-zero then the terms are ordered by lag: lag 1 of all the input series or columns, then lag 2 of all the series or columns, and so on.

Computes log differences; starting values are set to NA.

When a list is returned, the individual variables are automatically named according to the template ld_varname where varname is the name of the original series. The name is truncated if necessary, and may be adjusted in case of non-uniqueness in the set of names thus constructed.

Computes a new series as a linear combination of the series in the list L. The coefficients are given by the vector b, which must have length equal to the number of series in L.

Depends on having TRAMO installed. Returns a "linearized" version of the input series; that is, a series in which any missing values are replaced by interpolated values and outliers are adjusted. TRAMO's fully automatic mechanism is used; consult the TRAMO documentation for details.

Note that if the input series has no missing values and no values that TRAMO regards as outliers, this function will return a copy of the original series.

Computes the Ljung–Box Q' statistic for the series y using lag order p, over the currently defined sample range. The lag order must be greater than or equal to 1 and less than the number of available observations.

Returns the log of the gamma function of x.

Returns the natural logarithm of x; produces NA for non-positive values. Note: ln is an acceptable alias for log.

When a list is returned, the individual variables are automatically named according to the template l_varname where varname is the name of the original series. The name is truncated if necessary, and may be adjusted in case of non-uniqueness in the set of names thus constructed.

Returns the base-10 logarithm of x; produces NA for non-positive values.

Returns the base-2 logarithm of x; produces NA for non-positive values.

Returns the logistic CDF of the argument x, that is, 1/(1 + e^–x). If x is a matrix, the function is applied element by element.

Returns an n x n lower triangular matrix: the elements on and below the diagonal are equal to the corresponding elements of A; the remaining elements are zero.

Returns the long-run variance of y, calculated using a Bartlett kernel with window size k. If the second argument is omitted, or given a negative value, the window size defaults to the integer part of the cube root of the sample size.

For the variance calculation, the series y is centered around the optional parameter mu; if this is omitted or NA, the sample mean is used.

A convenience function for making a list of series using the columns of a suitable matrix as input. The row dimension of X must equal either the length of the current dataset or the number of observations in the current sample range.

This function has two primary modes plus a special case.

The first mode is activated if a single argument of type scalar, series or matrix is given: the return value is a scalar, the maximum valid value "within" the argument: if x is a series, its maximum value within the current sample range, or if x is a matrix, its greatest element, missing values being ignored. The case of a scalar argument is supported for the sake of completeness; you just get its value back.

The second mode is activated if two arguments are given. The arguments x and y must be of the same type, and must be scalars, series or matrices (and if they are matrices, they must be of the same dimensions). The return value is an object of the same type as the arguments, holding the "between" or "cross" maximum or maxima. If the arguments are scalars you get the greater of the two; if they're series you get a series holding the greater of the values of the two series at each observation in the current sample range; if they're matrices you get a matrix holding the greater of their elements in each row and column. For each of the pairwise comparisons if either term is missing the result is also a missing value.

The special case

This arises if a single list argument is given. The return value is a series, containing at each observation in the current sample range the greatest of the values of the series in the list at that observation.

Returns a row vector containing the maxima of the columns of X. For columns containing NAs the result is also set to NA, unless the optional argument skip_na is nonzero, in which case the maximum valid entry will be returned.

Returns a column vector containing the maxima of the rows of X. For rows containing NAs the result is also set to NA, unless the optional argument skip_na is nonzero, in which case the maximum valid entry will be returned.

Computes a covariance matrix treating each column of X as a variable. The divisor is n – 1, where n is the number of rows of X, unless the optional second argument is supplied, in which case n – dfcorr is used.

Returns the matrix covariogram for a T x k matrix X (typically containing regressors), an (optional) T -vector u (typically containing residuals), an (optional) (p+1)-vector of weights w, and a lag order p, which must be greater than or equal to 0.

The returned matrix is the sum for j from -p to p of w(|j|) * X(t)X(t-j)' * u(t)u(t-j), where X(t)' is the t-th row of X.

If u is given as null the u terms are omitted, and if w is given as null all the weights are taken to be 1.0.

For example, the following piece of code

	  set seed 123
	  X = mnormal(6,2)
	  Lag = mlag(X,1)
	  Lead = mlag(X,-1)
	  print X Lag Lead
	  eval X'X
	  eval mcovg(X, , , 0)
	  eval X'(X + Lag + Lead)
	  eval mcovg(X, , , 1)

produces this output:

	  ? print X Lag Lead
	  X (6 x 2)

	    -0.76587      -1.0600
	    -0.43188      0.30687
	    -0.82656      0.40681
	     0.39246      0.75479
	     0.36875       2.5498
	     0.28855     -0.55251

	  Lag (6 x 2)

	      0.0000       0.0000
	    -0.76587      -1.0600
	    -0.43188      0.30687
	    -0.82656      0.40681
	     0.39246      0.75479
	     0.36875       2.5498

	  Lead (6 x 2)

	    -0.43188      0.30687
	    -0.82656      0.40681
	     0.39246      0.75479
	     0.36875       2.5498
	     0.28855     -0.55251
	      0.0000       0.0000

	  ? eval X'X
	      1.8295       1.4201
	      1.4201       8.7596

	  ? eval mcovg(X,,, 0)
	      1.8295       1.4201
	      1.4201       8.7596

	  ? eval X'(X + Lag + Lead)
	      3.0585       2.5603
	      2.5603       10.004

	  ? eval mcovg(X,,, 1)
	      3.0585       2.5603
	      2.5603       10.004

If x is a series, returns the (scalar) sample mean, skipping any missing observations.

If x is a list, returns a series y such that y_t is the mean of the values of the variables in the list at observation t. By default the mean is recorded as NA if there are any missing values at t, but if you pass a non-zero value for partial any non-missing values will be used to form the statistic.

The following example illustrates the working of the function

		open denmark.gdt
		eval mean(LRM)
		list L = dataset
		eval mean(L)

The first call will return the scalar mean value (scalar) of the series LRM, and the second one returns a series.

Returns the means of the columns of X. If a non-zero value is given for the optional second argument missing values are ignored, otherwise the result is NA for any columns that contain missing values.

For example, the following piece of code

		matrix m = mnormal(5, 2)
		m[1,2] = NA
		print m
		eval meanc(m)

produces this output:

		? print m
		m (5 x 2)

	   -0.098299          nan
	      1.1829      -1.2817
	     0.46037     -0.92947
	      1.4896     -0.91970
	     0.91918      0.47748

		? eval meanc(m)
	     0.79075          nan

If x is a series, returns the (scalar) sample median, skipping any missing observations.

If x is a list, returns a series y such that y_t is the median of the values of the variables in the list at observation t, or NA if there are any missing values at t.

The following example illustrates the working of the function

	  set verbose off
	  open denmark.gdt
	  eval median(LRM)
	  list L = dataset
	  series m = median(L)

The first call will return the scalar median value (scalar) of the series LRM, and the second one returns a series.

Returns the minima of the columns of X. For columns containing NAs the result is also set to NA, unless the optional argument skip_na is nonzero, in which case the minimum valid entry will be returned.

Returns the minima of the rows of X. For rows containing NAs the result is also set to NA, unless the optional argument skip_na is nonzero, in which case the minimum valid entry will be returned.