| 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;
- 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;
- max_lead: the max lead of the model, i.e. the highest number of periods a time series of the model is leaded by in the MDL definition. It also accounts for recursive leading
(e.g. TSLEAD(...TSLEAD(...)...));
- modelName: the name of the model, copied from the input file name or from the input character variable name containing the model definition;
- bimets_version: the version of the BIMETS package the current model has been built with.
- 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 then 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, vblocks: 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. More details in "The Optimal Reordering" section in SIMULATE help pages (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 1+3*N ordered arrays of endogenous variables, given N the length of the vblocks list:
1. vpre is the ordered list containing the names of the endogenous pre-recursive variables to be sequentially computed (once per simulation period) before the simulation iterative algorithm takes place;
2. vblocks[[i]]$vsim, i=1..N (the simultaneous subset) is the ordered list containing the names of the endogenous variables to be sequentially computed during each iteration of the simulation iterative algorithm in the current block i;
3. vblocks[[i]]$vfeed, i=1..N is the list containing the names of the endogenous feedback variables in the current block i; generally vfeed are the last variables in the ordered vsim list;
4. vblocks[[i]]$vpost, i=1..N is the ordered list containing the names of the endogenous post-recursive variables to be sequentially computed (once per simulation period) after the simulation iterative algorithm has found a solution in the simultaneous subset in the current block i;
In forward-looking models, the incidence matrix and the equations reordering depend on the simulation periods count, therefore the attributes incidence_matrix, vpre and vblocks will be available only after a simulation has been completed, and will be available to users in the
model$simulation[['__SIM_PARAMETERS__']] lists.
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 current behavioral equation; it is used in the simulation algorithm and is derived by parsing the eqSimExpText text element;
- eqSimExpLeadedText: it is derived by transforming the leaded time series that apper in the current behavioral equation, if any, and it is used, during the simulation of forward-looking models, to build up the leadsEqSimExpText and leadsEqSimExp elements, that contain, per each period in the simulation TSRANGE, the leaded and accordingly transformed equation (see "Rational Expectation Models" section in SIMULATE help page));
- 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.
- lhsFun: the LHS function that appers in the current behavioral equations;
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, ifCondition: the original and the optimized 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 current identity equation; it is used in the simulation algorithm and is derived by parsing the eqSimExpText text element;
- eqSimExpLeadedText: it is derived by transforming the leaded time series that apper in the current identity equation, if any, and it is used, during the simulation of forward-looking models, to build up the leadsEqSimExpText and leadsEqSimExp elements, that contain, per each period in the simulation TSRANGE, the leaded and accordingly transformed equation (see "Rational Expectation Models" section in SIMULATE help page));
- hasIF: boolean, TRUE if the identity has an IF> condition;
- multipleLhsFun: the list of the LHS functions that apper in the equations related to the current identity;
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$vblocks[[1]]$vsim
#[1] "w1" "p" "i" "cn" "y"
myModel$vblocks[[1]]$vfeed
#[1] "y"
myModel$vblocks[[1]]$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