Description

(Note: this is the html version of the reference manual. Please consider reading the pdf version of this reference manual, wherein there are figures and the mathematical expressions are better formatted than in html.)

BIMETS provides a language to unambiguously specify an econometric model. This page describes how to create a model and its general structure. The specification of an econometric model is translated and identified by keyword statements which are grouped in a model file, i.e. a plain text file or a character variable with a specific syntax. Collectively, these keyword statements constitute the BIMETS Model Description Language (from now on MDL). The model specifications consist of groups of statements. Each statement begins with a keyword. The keyword classifies the component of the model which is beign specified.

Below is an example of a Klein's model with a MDL compliant syntax that can either be stored in a character variable or in a plain text file.

The content of the klein1.txt variable is:

Please note that there are circular dependencies between equations of the model, e.g. p <- w1 <- y <- p as shown in the "BIMETS package" section figure. Circular dependencies imply that the model simulation must be solved with an iterative algorithm.

As shown, the model definition is quite intuitive. The first keyword is MODEL, while at the end of the model definition we can find the END keyword. Available tags in the definition of a generic BIMETS model are:

- EQUATION> or BEHAVIORAL> indicate the beginning of a series of keyword statements describing a behavioral equation. The behavioral statement general form is:
BEHAVIORAL> name [TSRANGE startYear, startPeriod, endYear, endPeriod]
where name is the name of the behavioral equation and the optional TSRANGE specifies that the provided time interval must be used in the coefficients estimation. The optional TSRANGE is defined as a 4-dimensional numerical array built with starting year, starting period, ending year and ending period.

Given Y = b * X + RES, where Y are the historical values of the dependent variable and X are the historical values of the regressors, if the requested estimation method is OLS (Ordinary Least Squares), in the general case (i.e. no restrictions nor error auto-correlation, as described later) the coefficients will be calculated as: b_ols = (X' * X )^(-1) * X' * Y.

If the requested estimation method is IV (Instrumental Variables), given Z the matrix built with instrumental variables as columns Z_i, that should not be correlated to the disturbance terms, i.e. E[ RES' * Z_i ] = 0, the coefficients will be either calculated as
b_iv=(Z' * X)^(-1) * Z' * Y, or more generally as: b_iv=(X_hat' * Omega^(-1) * X_hat)^(-1) * X_hat' * Omega^(-1) * Y where X_hat = Z * (Z' * Z)^(-1) * Z' * X and Omega = sigma^(2) * I, sigma^(2) = E[ RES' * RES ]

- IDENTITY> indicates the beginning of a series of keyword statements describing an identity or technical equation. The identity statement general form is:
IDENTITY> name
where name is the identity name.

- EQ> specifies the mathematical expression for a behavioral or an identity equation.

The equation statement general form for a behavioral equation is:
EQ> LHS = coeff1*f1 + coeff2*f2 + coeff3*f3 + ...
where LHS is a function of the behavioral variable,
coeff1, coeff2, coeff3, ... are the coefficient names of the equation and
f1, f2, f3, ... are functions of variables.

The equation statement general form for an identity equation is:
EQ> LHS = f1 + f2 + f3 + ...
where LHS is a function of the identity variable and
f1, f2, f3, ... are functions of variables.

The following MDL functions can be used in the LHS left-hand side of the equation, with name as the name of the behavioral or the identity variable:

- name - i.e. the identity function;

- TSDELTA(name,i) - i-periods difference of the name time series;

- TSDELTAP(name,i) - i-periods percentage difference of the name time series;

- TSDELTALOG(name,i) - i-periods logarithmic difference of the name time series;

- LOG(name) - log of the name time series;

- EXP(name) - exponential of the name time series.

On the other side the mathematical expression available for using in the RHS right-hand side of the EQ> equation and in the IV> expression described later in this page (i.e. f1, f2, f3, ...) can include the standard arithmetic operators, parentheses and the following MDL functions:

- TSLAG(ts,i) - lag the ts time series by i-periods;

- TSDELTA(ts,i) - i-periods difference of the ts time series;

- TSDELTAP(ts,i) - i-periods percentage difference of the ts time series;

- TSDELTALOG(ts,i) - i-periods logarithmic difference of the ts time series;

- MOVAVG(ts,i) - i-periods moving average of the ts time series;

- MOVSUM(ts,i) - i-periods moving sum of the ts time series;

- LOG(ts) - log of the ts time series;

- EXP(ts) - exponential of the ts time series;

- ABS(ts) - absolute values of the ts time series.

MDL function names are reserved names. They cannot be used as variable or coefficient names. The coefficient names are specified in a subsequent COEFF> keyword statement within a behavioral equation. By definition, identities do not have any coefficient that must be assessed. Any name not specified as a coefficient name or mentioned on the list of the available MDL functions is assumed to be a variable.

- COEFF> specifies the coefficient names used in the EQ> keyword statement of a behavioral equation. The coefficients statement general form is:
COEFF> coeff0 coeff1 coeff2 ... coeffn.
The coefficients order in this statement must be the same as it appears in the behavioral equation.

- ERROR> specifies an autoregressive process of a given order for the regression error. The error statement general form is:
ERROR> AUTO(n)
where n is the order of the autoregressive process for the error.

During an estimation, users must ensure that the required data is available for the specified error structure: n periods of data prior to the time interval specified by TSRANGE are requested in any time series involved in the regression.

The solution requires an iterative algorithm. Given Y_1 = b_1 * X_1 + RES_1, where Y_1 are the historical values of the dependent variable and X_1 are the historical values of the regressors, the iterative algorithm is based on the Cochrane-Orcutt procedure:

1) Make an initial estimation by using the original TSRANGE extended backward n periods (given n as the autocorrelation order).

2) estimate the error autocorrelation coefficients RHO_i=RHO_i[1],...,RHO_i[n] with i=1 by regressing the residuals RES_i on their lagged values by using the auxiliary model:
RES_i=RHO_i[1]*TSLAG(RES_i,1)+...+RHO_i[n]*TSLAG(RES_i,n)

3) transform the data for the dependent and the independent variables by using the estimated RHO_i. The new dependent variable will be: Y_(i+1)=P_i*Y_i, and the new independent variables will be X_(i+1)=P_i*X_i with the matrix P_i defined as:

4) run another estimation on the original model Y_(i+1) = b_(i+1) * X_(i+1) + RES_(i+1) by using the suitable TSRANGE and the transformed data coming out of step 3 and compute the new time series for the residuals.

5) estimate the new autocorrelation coefficients RHO_(i+1)=RHO_(i+1)[1],...,RHO_(i+1)[n], by regressing the new residuals arising from step 4 (similar to step 2)

6) carry out the convergence check through a comparison among the previous RHO_i and the new ones arising from steps 5.
If all(abs(RHO_(i+1)-RHO_i) < d), where RHO_i is the RHO vector at the iteration i and d is a small convergence factor, then exit otherwise repeat from step 3 with i <- i+1.

- RESTRICT> is a keyword that can be used to specify linear coefficient restrictions. A deterministic restriction can be applied to any equation coefficient. Any number of RESTRICT> keywords is allowed for each behavioral equation.

A deterministic (exact) coefficient restriction sets a linear expression containing one or more coefficients equal to a constant. The restriction only affects the coefficients of the behavioral equation in which it is specified. The restriction statement general form is:

where linear_combination_of_coefficients_i, i=1..n is a linear combination of the coefficient(s) to be restricted and value_i is the in-place scalar value to which the linear combination of the coefficients is set equal. Each linear combination can be set equal to a different value.

MDL example:

In many econometric packages, linear restrictions have to be coded by hand in the equations. BIMETS allows the users to write down the restriction in a natural way thus applying a constrained minimization. This procedure, although it leads to approximate numerical estimates, allows an easy implementation.

The theory behind this procedure is that of the Lagrange multipliers. Presented here is an example of its implementation.

Suppose that we have an equation defined as:

Coefficients C1, C2, C3 are to be estimated. They are subject to the linear constraints specified by the RESTRICT> keyword statement. In the case of OLS estimation, this is carried out in the following steps:

1) Compute the cross-product matrices X' X and X' Y where X is a matrix with dimension
[NOBS x NREG] containing the values of the independent variables (regressors) historical observations (and a vector of ones for the constant term, if any), and where Y is a NOBS elements vector of the dependent variable (regressand) historical observations; NOBS is the number of observations available on the TSRANGE specified in the behavioral equation and NREG is the number of regressors, or coefficients;

2) Build the restriction matrices. In the example:

and

R is a matrix of [NRES x NREG] size and r is a vector of [NRES] length, where NRES is the number of restrictions;

3) Compute the scaling factors for the augmentation to be performed in the next step:

Rscale[i]=mean(X' X)/max(abs(R[i,]))

where R[i,] is the i-th row of the R matrix.

Assuming mean(X' X) = 5000, in the example above we will have:
Rscale[1]=5000 / 1.3
Rscale[2]=5000 / 1.2

The augmented matrices will then be defined as:

and

4) Compute the so-called "augmented" cross-product matrix (X' X)_aug by adding to the cross-product matrix (X' X) a total of NRES rows and NRES columns:

5) In a similar way, compute the so-called "augmented" cross-product matrix (X' Y)_aug by adding a total of NRES elements to the cross-product matrix (X' Y):

6) Caculate the beta_hat_aug augmented coefficients by regressing the (X' Y)_aug on the (X' X)_aug.

The first NREG values of the augmented coefficients beta_hat_aug array are the estimated coefficients with requested restrictions. The last NRES values are the errors we have on the deterministic restrictions.

In the case of IV estimation the procedure is the same as in the OLS case, but the matrix X has to be replaced with the matrix X_hat, as previously defined in the BEHAVIORAL> keyword.

- PDL> is a keyword that defines an Almon polynomial distributed lag to be used in an estimation. Almon Polynomial distributed lags are specific kind of deterministic restrictions imposed on the coefficients of the distributed lags of a specific regressor. Multiple PDLs on a single behavioral equation can be defined.

The PDL> statement general form is:
PDL> coeffname degree laglength [N] [F]
where coeffname is the name of a coefficient, degree is an integer scalar specifying the degree of the polynomial, laglength is an integer scalar specifying the length of the polynomial (in number of time periods), the optional N (i.e. "nearest") means that the nearest lagged term of the expansion, i.e., the first term, is restricted to zero, and the optional F (i.e. "farthest") means that the farthest lagged term of the expansion, i.e., the last term, is restricted to zero; the PDL> keyword statement thusly defined applies an Almon polynomial distributed lag to the regressor associated with the coeffname coefficient, of laglength length and degree degree, by providing the appropriate expansion and the deterministic restrictions for the degree and length specified. These expansions are not explicitly shown to the user, i.e., the original model is not changed.

laglength must be greater than degree (see example below).

A PDL term can be further referenced in a RESTRICT> keyword statement by using the following syntax: LAG(coefname, pdllag).

Example: RESTRICT> LAG(coeff2,3) = 0 means that, during the estimation, the regressor related to the coefficient coeff2 and lagged by 3 periods in the PDL expansion must have a coefficient equal to zero. This example also implies that a PDL> coeff2 x y with y > 3 has been declared in the same behavioral.

The implementing rules are the following:

1) Read off the laglength of the PDL keyword and expand the column of the regressor related to coeffname in the matrix X (i.e. the original regressors matrix) with the lagged values of the regressor, from the left to the right, starting form the lag 1 to the lag laglength-1. The matrix X will now have a [NOBS x (NREG+laglength-1)] size, with NOBS as the number of observations in the specified TSRANGE and NREG as the number of regressors, or coefficients.

2) Build the restriction matrix R with the following [ Nrow x Ncol ] dimensions:
Nrow = laglength - ( degree + 1 )
Ncol = NREG + laglength - 1

The elements of this matrix will be zero except for the (laglength)-columns related to the section of the expanded columns in the X matrix. For every row we will have to insert degree+2 numbers different from zero.

The degree+2 numbers are taken form the Tartaglia's-like triangle:

where in the i-th row we find the numbers for a PDL of degree=i.

The r vector giving the knows terms for the restrictions is a vector of
NRES = laglength - (degree + 1) elements equal to zero.

An example will clarify:

then

and

The expanded regressors are:
X1, X2, TSLAG(X2,1), TSLAG(X2,2), TSLAG(X2,3), TSLAG(X2,4), X3.

The scaling factor is given, as in the standard restriction case, by: mean(X' X) / max(abs(R[i,]))

- IF> keyword is used to conditionally evaluate an identity during a simulation, depending on the value of a logical expression. Thus, it is possible to have a model alternating between two or more identity specifications for each simulation period, depending upon results from other equations.

The IF> statement general form is:
IF> logical_expression

The IF> keyword must be specified within an identity group; this keyword causes the equation specified in the identity group to be evaluated during the current simulation period only when the logical_expression is TRUE.

Only one IF> keyword is allowed in an identity group. Further occurrences produce an error message and processing stops.

The logical_expression can be composed of constants, endogenous variables, exogenous variables, an expression among variables, combinations of the logical operators; mathematical operators and the MDL functions listed in the EQ> section are allowed.

In the following MDL example, the value of the endogenous myIdentity variable is specified with two complementary conditional identities, depending on the TSDELTA() result:

- IV> specifies the mathematical expression for an instrumental variable used in a behavioral equation.

The general form for an instrumental variable expression is:
IV> f1 + f2 + f3 + ...
f1, f2, f3, ... are functions of variables.

The mathematical expression available for using in the IV> definition are those already described in the EQ> section.

- COMMENT> can be used to insert comments into a model. The general form of this keyword is:
COMMENT> text

The text following the COMMENT> keyword is ignored during all processing, and must lie in the same line. A comment cannot be inserted within another keyword statement. A dollar sign in the first position of a line is equivalent to using the COMMENT> keyword, as in this exmaple:
$This is a comment

No other keywords are currently allowed in the MDL syntax.

See Also

LOAD_MODEL
ESTIMATE
SIMULATE
MULTMATRIX
RENORM
TIMESERIES
BIMETS indexing
BIMETS configuration
summary

Examples