LOAD_MODEL {bimets} | R Documentation

## Load a BIMETS model description file

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

This function parses a `MDL` model definition and creates an equivalent R data structure that can be estimated and simulated. The input model definition can be either an external plain text file or a `character` variable.

### Usage

    LOAD_MODEL( modelFile=NULL,
                modelText=NULL,
                showWarnings=TRUE,
                quietly=FALSE,
                oldStyleModel=FALSE,
                ...)

### Arguments

`modelFile` | The path to the text file containing the `MDL` model definition.
`modelText` | The `character` variable containing the `MDL` model definition. `modelText` takes precedence over `modelFile` if both are defined.
`showWarnings` | If `TRUE` a warning message will be shown if the model has a null set of endogenous variables or a null set of exogenous variables.
`quietly` | If `TRUE`, information messages will be suppressed.
`oldStyleModel` | Backward compatibility.
`...` | Backward compatibility.

### Value

This function returns a BIMETS model object containing all the information gathered from the parsing of the input model definition.
A BIMETS model created with the `LOAD_MODEL` function can be viewed as a complex R `list()` containing the following elements (see examples):
- rawData and cleanModel: string arrays containing the original model definition. `cleanModel` is a clean version of the model definition, i.e. without comments, blank lines, etc.;
- behaviorals and identities: sub-lists containing all the information gathered from the behavioral and the identity definitions. This sub lists are described later in this page;
- vendog and vexog: string array containing the names of the endogenous and exogenous variables of the model;
- totNumEqs, totNumIds and eqCoeffNum: integer variables containing the behaviorals count, the identities count and the coefficients count of the model;
- incidence_matrix: the incidence matrix built from the model equations; it is a square matrix in which each row and each column represent an endogenous variable. If the `(i,j)` element is equal to `1` than in the model definition the current value of the endogenous variable referred by the `i`-row directly depends on the current value of the endogenous variable referred by the `j`-column. (see example)
- vpre, vsim, vfeed and vpost: the simulation process takes advantage of an appropriate ordering of the equations to increase the performances by iteratively solving only one subset of equations, while the other equations are solved straightforwardly. (Ref: Don Gallo - Solving large sparse systems of equations in econometric models - Journal of Forecasting 1987 and Numerical methods for simulation and optimal control of large-scale macroeconomic models - Nepomiastchy, Rachidi, Ravelli - 1980). The optimal reordering of the model equations is achieved by using an iterative algorithm applied to the incidence matrix, that produces 4 ordered arrays of endogenous variables:
1) `vpre` is the ordered string array containing the names of the endogenous pre-recursive variables that must be computed (by using their `EQ>` definition) before the simulation iterative algorithm takes place;
2) `vsim` is the ordered string array containing the names of the endogenous variables that must be sequentially computed during each iteration of the simulation algorithm;
3) `vfeed` is the ordered string array containing the names of the endogenous feedback variables to be evaluated for convergence during the simulation iterative algorithm;
4) `vpost` is the ordered string array containing the names of the endogenous post-recursive variables that must be computed after the execution and the convergence of the iterative algorithm in step 3 (more details in `BIMETS package` and `SIMULATE` help pages);
- max_lag: the max lag of the model, i.e. the highest number of periods a time series of the model is lagged by in the `MDL` definition. It also accounts for PDLs and for the order of the error autocorrelation, if any;
- modelName: the name of the model, copied from the input file name or from the input `character` variable name containing the model definition;
BEHAVIORALS and IDENTITIES
The elements 'behaviorals' and 'identities' of the BIMETS model are named lists that contain information on behaviorals and identities of the model. In both of this two lists, the name of each element is the name of the behavioral or the identity the data refer to, as specified in the model definition file: e.g. given a BIMETS model named `myModel`, the information on a behavioral named `cn` (i.e there exists a "BEHAVIORAL> cn" in the `MDL` definition of the model) is stored into `myModel$behaviorals$cn`.
Behavioral elements have the following components:
- eq: the equation of the behavioral, as a `character` variable;
- eqCoefficientsNames: the names of the coefficients (the original ones and eventually the ones created by the `PDL>` expansion);
- eqCoefficientsNamesOriginal: the names of the original coefficients;
- eqComponentsNames: the names of endogenous and exogenous variables that appear in the behavioral equation;
- tsrange: the estimation time range as a 4 integer array;
- eqRegressorsNames: a `character` array containing the regressor expressions (the original ones and eventually the ones created by the `PDL>` expansion);
- eqRegressorsNamesOriginal: a `character` array containing the expressions of the original regressors;
- errorRaw: the original definition of the error autocorrelation, if any (see `MDL`);
- errorType: the type of the error structure;
- errorDim: the dimension of the error autocorrelation;
- eqSimExp: the `R` optimized `expression` of the behavioral equation that is used in the simulation algorithm;
- matrixR: the `R` Lagrange matrix that is used in restriction analysis (see `MDL`);
- vectorR: the `r` Lagrange vector that is used in restriction analysis (see `MDL`);
- restrictRaw: the original definition of the coefficient restrictions, if any.
- pdlRaw: the original definition of the PDL restrictions, if any (see examples and `MDL`).
- pdlRestrictionMatrix: the `R` Lagrange matrix that is used in PDL restriction analysis (see examples and `MDL`);
For example, given a BIMETS model named `myModel`, the information on a techincal identity named `y` (i.e there exists an "IDENTITY> y" in the `MDL` definition of the model) is stored in `myModel$identities$y`.
Identity elements have the following components:
- eqRaw: the original equations of the identity (more than one if the identity has multiple equations and has `IF>` conditions), as a `character` variable (see examples and `MDL`);
- ifRaw: the original `IF>` conditions, if any, of the identity, as a `character` variable;
- eqFull: the full expression of the identity, composed with `IF>` conditions and related equations (see examples), as a `character` variable;
- eqComponentsNames: the names of endogenous and exogenous variables that appear in the identity equation;
- eqSimExp: the `R` optimized `expression` of the identity equation that is used in the simulation algorithm;
- hasIF: boolean, `TRUE` if the identity has an `IF>` condition;

### See Also

`MDL`
`LOAD_MODEL_DATA`
`ESTIMATE`
`SIMULATE`
`MULTMATRIX`
`RENORM`
`TIMESERIES`
`BIMETS indexing`
`BIMETS configuration`

### Examples

    #define model
    myModelDefinition=
    "MODEL
    COMMENT> Modified Klein Model 1 of the U.S. Economy with PDL,
    COMMENT> autocorrelation on errors, restrictions and conditional evaluations
    COMMENT> Consumption
    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
    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
    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 3
    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";

    #load model
    myModel=LOAD_MODEL(modelText=myModelDefinition);

    #retrieve model structure...
    #get definition
    myModel$cleanModel
    # [1] "BEHAVIORAL> cn"
    # [2] "TSRANGE 1925 1 1941 1"
    # [3] "EQ> cn = a1 + a2*p + a3*TSLAG(p,1) + a4*(w1+w2)"
    # [4] "COEFF> a1 a2 a3 a4"
    # [5] "ERROR> AUTO(2)"
    # [6] "BEHAVIORAL> i"
    # [7] "TSRANGE 1923 1 1941 1"
    # [8] "EQ> i = b1 + b2*p + b3*TSLAG(p,1) + b4*TSLAG(k,1)"
    # [9] "COEFF> b1 b2 b3 b4"
    #[10] "RESTRICT> b2 + b3 = 1"
    #[11] "BEHAVIORAL> w1"
    #[12] "TSRANGE 1925 1 1941 1"
    #[13] "EQ> w1 = c1 + c2*(y+t-w2) + c3*TSLAG(y+t-w2,1)+c4*time"
    #[14] "COEFF> c1 c2 c3 c4"
    #[15] "PDL> c3 1 3"
    #[16] "IDENTITY> y"
    #[17] "EQ> y = cn + i + g - t"
    #[18] "IDENTITY> p"
    #[19] "EQ> p = y - (w1+w2)"
    #[20] "IDENTITY> k"
    #[21] "EQ> k = TSLAG(k,1) + i"
    #[22] "IF> i > 0"
    #[23] "IDENTITY> k"
    #[24] "EQ> k = TSLAG(k,1)"
    #[25] "IF> i <= 0"

    #get endogenous and exogenous
    myModel$vendog
    #[1] "cn" "i"  "w1" "y"  "p"  "k"
    myModel$vexog
    #[1] "w2"   "t"    "time" "g"

    #get behaviorals, identities and coefficients count
    myModel$totNumEqs
    #[1] 3
    myModel$totNumIds
    #[1] 3
    myModel$eqCoeffNum
    #[1] 12

    #get the incidence matrix
    myModel$incidence_matrix
    #   cn i w1 y p k
    #cn  0 0  1 0 1 0
    #i   0 0  0 0 1 0
    #w1  0 0  0 1 0 0
    #y   1 1  0 0 0 0
    #p   0 0  1 1 0 0
    #k   0 1  0 0 0 0

    #get the optimal reordering arrays
    myModel$vpre
    #NULL
    myModel$vsim
    #[1] "w1" "p"  "cn" "i"  "y"
    myModel$vfeed
    #[1] "y"
    myModel$vpost
    #[1] "k"

    #get the model max lag and the model name
    myModel$max_lag
    #[1] 3
    myModel$modelName
    #myModelDefinition

    #get infos on behavioral w1

    myModel$behaviorals$w1$eq
    #[1] "w1=c1+c2*(y+t-w2)+c3*TSLAG(y+t-w2,1)+c4*time"

    myModel$behaviorals$w1$eqCoefficientsNames
    #[1] "c1"       "c2"       "c3"       "c3_PDL_1" "c3_PDL_2" "c4"

    myModel$behaviorals$w1$eqCoefficientsNamesOriginal
    #[1] "c1" "c2" "c3" "c4"

    myModel$behaviorals$w1$eqComponentsNames
    #[1] "t"    "time" "w1"   "w2"   "y"

    myModel$behaviorals$w1$tsrange
    #[1] 1925    1 1941    1

    myModel$behaviorals$w1$eqRegressorsNames
    #[1] "1"                       "(y+t-w2)"
    #[3] "TSLAG(y+t-w2,1)"  "TSLAG(TSLAG(y+t-w2,1),1)" "TSLAG(TSLAG(y+t-w2,1),2)" "time"

    myModel$behaviorals$w1$eqRegressorsNamesOriginal
    #[1] "1"                "(y+t-w2)"
    #[3] "TSLAG(y+t-w2,1)" "time"

    myModel$behaviorals$w1$pdlRaw
    #[1] "c3 1 3;"

    myModel$behaviorals$w1$pdlRestrictionMatrix
    #     [,1] [,2] [,3] [,4] [,5] [,6]
    #[1,]    0    0    1   -2    1    0

    #get infos on behavioral cn

    myModel$behaviorals$cn$errorRaw
    #[1] "AUTO(2)"

    myModel$behaviorals$cn$errorType
    #[1] "AUTO"

    myModel$behaviorals$cn$errorDim
    #[1] 2

    myModel$behaviorals$cn$eqSimExp
    #expression(cn[4,]=cn_ADDFACTOR[4,]+cn_a1+cn_a2*p[4,]+cn_a3*(p[3,])+
    #cn_a4*(w1[4,]+w2[4,])+cn_RHO_1*(cn[3,]-(cn_ADDFACTOR[3,]+
    #cn_a1+cn_a2*p[3,]+cn_a3*(p[2,])+cn_a4*(w1[3,]+w2[3,])))+
    #cn_RHO_2*(cn[2,]-(cn_ADDFACTOR[2,]+cn_a1+cn_a2*p[2,]+
    #cn_a3*(p[1,])+cn_a4*(w1[2,]+w2[2,]))))

    #get infos on behavioral i

    myModel$behaviorals$i$matrixR
    #    [,1] [,2] [,3] [,4]
    #[1,]   0    1    1    0

    myModel$behaviorals$i$vectorR
    #[1] 1

    myModel$behaviorals$i$restrictRaw
    #[1] "b2+b3=1;"

    #get infos on identitiy k

    myModel$identities$k$eqRaw
    #[1] "k=TSLAG(k,1)+i;k=TSLAG(k,1);"

    myModel$identities$k$ifRaw
    #[1] "i > 0;i <= 0;"

    myModel$identities$k$eqFull
    #[1] "__IF__ (i > 0) __THEN__ k=TSLAG(k,1)+i;__IF__ (i <= 0) __THEN__ k=TSLAG(k,1);"

    myModel$identities$k$eqComponentsNames
    #[1] "i" "k"

    myModel$identities$k$eqSimExp
    #expression(k[4,]=.MODEL_VIF(k[4,],i[4,] > 0,k_ADDFACTOR[4,]+
    #(k[3,])+i[4,]),k[4,]=.MODEL_VIF(k[4,],i[4,] <= 0,
    #k_ADDFACTOR[4,]+(k[3,])))

    myModel$identities$k$hasIF
    #[1] TRUE

[Package bimets version 1.4.0 Index]