| LOAD_MODEL {bimets} | R Documentation |
Load a BIMETS model description file
Description
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,
quietly=FALSE,
oldStyleModel=FALSE,
...)
Arguments
modelFile |
The path to the text file containing the |
modelText |
The |
quietly |
If |
oldStyleModel |
Backward compatibility. |
... |
Backward compatibility. |
Value
This function returns a BIMETS model object containing all the information gathered the input model definition's parsing.
A BIMETS model created with the LOAD_MODEL function can be viewed as a complex R list() containing the following elements (see example):
- 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; the former is also subsetted into vendogBehaviorals and vendogIdentities
- 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 list containing the names of the endogenous pre-recursive variables to be sequentially computed (once per simulation period, by using their EQ> definition in the MDL) before the simulation iterative algorithm takes place;
2. vsim (the simultaneous block) is the ordered list containing the names of the endogenous variables to be sequentially computed during each iteration of the simulation iterative algorithm;
3. vfeed is the list containing the names of the endogenous feedback variables; generally vfeed are the last variables of the ordered vsim list;
4. vpost is the ordered list containing the names of the endogenous post-recursive variables to be sequentially computed (once per simulation period, by using their EQ> definition in the MDL) after the simulation iterative algorithm has found a solution in the simultaenous block (more details in 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 recursive lagging
(e.g. TSLAG(...TSLAG(...)...)), 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;
- eqComponentsNamesBehaviorals: the names of behavioral endogenous variables that appear in the behavioral equation;
- eqComponentsNamesIdentities: the names of identity endogenous variables that appear in the behavioral equation;
- eqComponentsNamesExogenous: the names of 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 example and MDL).
- pdlRestrictionMatrix: the R Lagrange matrix that is used in PDL restriction analysis (see example and MDL);
- IVComponentsNames: the names of endogenous and exogenous variables that appear in the instrumental variables equations, if any;
- iv: the original definitions of instrumental variables, if any.
For example, given a BIMETS model named myModel, the information on a technical 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 example 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 example), as a character variable;
- eqComponentsNames: the names of endogenous and exogenous variables that appear in the identity equation;
- eqComponentsNamesBehaviorals: the names of behavioral endogenous variables that appear in the identity equation;
- eqComponentsNamesIdentities: the names of identity endogenous 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
STOCHSIMULATE
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