MDL {bimets} | R Documentation

## BIMETS Model Description Language

### 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:

    R> klein1.txt="
    MODEL

    COMMENT> Consumption
    BEHAVIORAL> cn
    TSRANGE 1921 1 1941 1
    EQ> cn =  a1 + a2*p + a3*TSLAG(p,1) + a4*(w1+w2)
    COEFF> a1 a2 a3 a4

    COMMENT> Investment
    BEHAVIORAL> i
    TSRANGE 1921 1 1941 1
    EQ> i = b1 + b2*p + b3*TSLAG(p,1) + b4*TSLAG(k,1)
    COEFF> b1 b2 b3 b4

    COMMENT> Demand for Labor
    BEHAVIORAL> w1
    TSRANGE 1921 1 1941 1
    EQ> w1 = c1 + c2*(y+t-w2) + c3*TSLAG(y+t-w2,1)+c4*time
    COEFF> c1 c2 c3 c4

    COMMENT> Gross National Product
    IDENTITY> y
    EQ> y = cn + i + g - t

    COMMENT> Profits
    IDENTITY> p
    EQ> p = y - (w1+w2)

    COMMENT> Capital Stock
    IDENTITY> k
    EQ> k = TSLAG(k,1) + i

    END
    "

Please note that there are circular dependencies between equations of the model, i.e. `cn <- w1 <- y <- cn`. 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> name = coeff1*f1 + coeff2*f2 + coeff3*f3 + ...`
where `name` is the name 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> name = f1 + f2 + f3 + ...`
where `name` is the name of the identity variable and
`f1, f2, f3, ...` are functions of variables.
The mathematical expression can include the standard arithmetic operators, parentheses and `MDL` functions described later in this section. `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` 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*Y[i], and the new independent variables will be X[i+1]=P*X[i] with the matrix P defined as:

|  | 1 | 0 | 0 | 0 | ... | 0 | 0
|  | -RHO_i[1] | 1 | 0 | 0 | ... | 0 | 0
P | = | -RHO_i[2] | -RHO_i[1] | 1 | 0 | ... | 0 | 0
|  |  |  | ...
|  | 0 | 0 | ... | -RHO_i[n] | ... | -RHO_i[1] | 1

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:

    RESTRICT> linear_combination_of coefficients_1 = value_1
    ...
    linear_combination_of coefficients_n = value_n

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:

    RESTRICT> coeff1 = 0
    coeff2 = 10.5
    coeff3-3*coeff4+1.2*coeff5 = 0

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:

    EQUATION> Y TSRANGE 2010 1 2015 4
    EQ> Y = C1*X1 + C2*X2 + C3*X3
    COEFF> C1 C2 C3
    RESTRICT> 1.1*C1 + 1.3*C3 = 2.1
    1.2*C2 = 0.8

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:

R | = | 1.1 | 0 | 1.3
|  | 0 | 1.2 | 0

and

r | = | 2.1
|  | 0.8

`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:

R_aug | = | 1.1 * Rscale[1] | 0 | 1.3 * Rscale[1]
|  | 0 | 1.2 * Rscale[2] | 0

and

r_aug | = | 2.1 * Rscale[1]
|  | 0.8 * Rscale[2]

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:

(X' X)_aug | = | X' X | R_aug'
|  | R_aug | 0

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

(X' Y)_aug | = | X' Y
|  | r_aug

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:

    1 -2  1
    1 -3  3 -1
    1 -4  6 -4   1
    1 -5 10 -10  5  1
    ... ... ... ...

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:

    EQUATION> Y TSRANGE 2010 1 2015 4
    EQ> Y = C1*X1 + C2*X2 + C3*X3
    COEFF> C1 C2 C3
    PDL> C2 2 5

then

R | = | 0 | 1 | -3 | 3 | 1 | 0 | 0
|  | 0 | 0 | 1 | -3 | 3 | 1 | 0

and

r | = | 0
|  | 0

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(R) / 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 below, 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:

    IDENTITY> myIdentity
    IF> TSDELTA(myEndog*(1-myExog)) > 0
    EQ> myIdentity = TSLAG(myIdentity)+1

    IDENTITY> myIdentity
    IF> TSDELTA(myEndog*(1-myExog)) <= 0
    EQ> myIdentity = TSLAG(myIdentity)

- 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.
The mathematical expression in the `EQ>` and `IF>` definitions can include the standard arithmetic operators, parentheses, and the following MDL time series functions:
- `TSLAG(ts,i)` - lag the `ts` time series by `i`-periods;
- `TSDELTA(ts,i)` - `i`-periods 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.

### See Also

`LOAD_MODEL`
`ESTIMATE`
`SIMULATE`
`MULTMATRIX`
`RENORM`
`TIMESERIES`
`BIMETS indexing`
`BIMETS configuration`
`summary`

### Examples

    #define model
    myModel=
    "MODEL

    COMMENT> Modified Klein Model 1 of the U.S. Economy with PDL,
    COMMENT> autocorrelation on errors, restrictions and conditional evaluations

    COMMENT> Consumption with autocorrelation on errors
    BEHAVIORAL> cn
    TSRANGE 1925 1 1941 1
    EQ> cn =  a1 + a2*p + a3*TSLAG(p,1) + a4*(w1+w2)
    COEFF> a1 a2 a3 a4
    ERROR> AUTO(2)

    COMMENT> Investment with restrictions
    BEHAVIORAL> i
    TSRANGE 1923 1 1941 1
    EQ> i = b1 + b2*p + b3*TSLAG(p,1) + b4*TSLAG(k,1)
    COEFF> b1 b2 b3 b4
    RESTRICT> b2 + b3 = 1

    COMMENT> Demand for Labor with PDL
    BEHAVIORAL> w1
    TSRANGE 1925 1 1941 1
    EQ> w1 = c1 + c2*(y+t-w2) + c3*TSLAG(y+t-w2,1)+c4*time
    COEFF> c1 c2 c3 c4
    PDL> c3 1 2

    COMMENT> Gross National Product
    IDENTITY> y
    EQ> y = cn + i + g - t

    COMMENT> Profits
    IDENTITY> p
    EQ> p = y - (w1+w2)

    COMMENT> Capital Stock with switches
    IDENTITY> k
    EQ> k = TSLAG(k,1) + i
    IF> i > 0
    IDENTITY> k
    EQ> k = TSLAG(k,1)
    IF> i <= 0

    END";

    #define model data
    modelData=list(
      cn    =TIMESERIES(39.8,41.9,45,49.2,50.6,52.6,55.1,56.2,57.3,57.8,55,50.9,
                45.6,46.5,48.7,51.3,57.7,58.7,57.5,61.6,65,69.7,
                START=c(1920,1),FREQ=1),
      g     =TIMESERIES(4.6,6.6,6.1,5.7,6.6,6.5,6.6,7.6,7.9,8.1,9.4,10.7,10.2,9.3,10,
                10.5,10.3,11,13,14.4,15.4,22.3,
                START=c(1920,1),FREQ=1),
      i     =TIMESERIES(2.7,-.2,1.9,5.2,3,5.1,5.6,4.2,3,5.1,1,-3.4,-6.2,-5.1,-3,-1.3,
                2.1,2,-1.9,1.3,3.3,4.9,
                START=c(1920,1),FREQ=1),
      k     =TIMESERIES(182.8,182.6,184.5,189.7,192.7,197.8,203.4,207.6,210.6,215.7,
                216.7,213.3,207.1,202,199,197.7,199.8,201.8,199.9,
                201.2,204.5,209.4,
                START=c(1920,1),FREQ=1),
      p     =TIMESERIES(12.7,12.4,16.9,18.4,19.4,20.1,19.6,19.8,21.1,21.7,15.6,11.4,
                7,11.2,12.3,14,17.6,17.3,15.3,19,21.1,23.5,
                START=c(1920,1),FREQ=1),
      w1    =TIMESERIES(28.8,25.5,29.3,34.1,33.9,35.4,37.4,37.9,39.2,41.3,37.9,34.5,
                29,28.5,30.6,33.2,36.8,41,38.2,41.6,45,53.3,
                START=c(1920,1),FREQ=1),
      y     =TIMESERIES(43.7,40.6,49.1,55.4,56.4,58.7,60.3,61.3,64,67,57.7,50.7,41.3,
                45.3,48.9,53.3,61.8,65,61.2,68.4,74.1,85.3,
                START=c(1920,1),FREQ=1),
      t     =TIMESERIES(3.4,7.7,3.9,4.7,3.8,5.5,7,6.7,4.2,4,7.7,7.5,8.3,5.4,6.8,7.2,
                8.3,6.7,7.4,8.9,9.6,11.6,
                START=c(1920,1),FREQ=1),
      time  =TIMESERIES(NA,-10,-9,-8,-7,-6,-5,-4,-3,-2,-1,0,1,2,3,4,5,6,7,8,9,10,
                START=c(1920,1),FREQ=1),
      w2    =TIMESERIES(2.2,2.7,2.9,2.9,3.1,3.2,3.3,3.6,3.7,4,4.2,4.8,5.3,5.6,6,6.1,
                7.4,6.7,7.7,7.8,8,8.5,
                START=c(1920,1),FREQ=1)
    );

    #load model and model data
    model=LOAD_MODEL(modelText=myModel);
    model=LOAD_MODEL_DATA(model,modelData);

    #estimate model
    model=ESTIMATE(model);

    #simulate model
    model=SIMULATE(model
                   ,TSRANGE=c(1923,1,1941,1)
                   ,simConvergence=0.00001
                   ,simIterLimit=100
    );

[Package bimets version 1.4.0 Index]