EquationsModelling         package:fMultivar         R Documentation

_E_q_u_a_t_i_o_n_s _M_o_d_e_l_l_i_n_g

_D_e_s_c_r_i_p_t_i_o_n:

     A collection and description of easy to use  functions to perform
     fits of systems of  regression equations. The underlying functions
      are those from the contributed R-package  systemfit written by
     Jeff D. Hamann and Arne  Henningsen. The package offers functions
     for  fitting linear structural equations using  Ordinary Least
     Squares (OLS), Weighted Least  Squares (WLS), Seemingly Unrelated
     Regression  (SUR), Two-Stage Least Squares (2SLS), Weighted 
     Two-Stage Least Squares (W2SLS) or Three-Stage  Least Squares
     (3SLS).  

     The wrapper fullfills the naming conventions of Rmetrics, returns
     a  S4 object named 'fSYSTEM', and allows for 'timeSeries' objects 
     as input. In addition a S-Plus like FinMetrics function 'SUR'  is
     made available. 

     The Models Based on 'systemfit' Include:

       '"OLS"'    Ordinary Least Square Modelling,
       '"WLS"'    Weighted Least Square Modelling,
       '"SUR"'    Seemingly Unrelated Regression,
       '"2SLS"'   Two-Stage Least Squares,
       '"W2SLS"'  Weighted Two-Stage Least Squares,
       '"3SLS"'   Three-Stage Least Squares.

     Further Functions and Methods are:

       'print'    S3 Print method for objects of class 'fSYSTEM',
       'summary'  S3 Summary method for objects of class 'fSYSTEM',
       'predict'  S3 Predict method for objects of class 'fSYSTEM'.

     S-Plus like Finmetrics Function:

       'SUR'  A S-PLUS like function for '"SUR"' models.

     Note, that the contributed R package 'systemfit' is required! If
     the package 'systemfit' is not installed on your computer or not
     availalble for your operating system, then you can load it  as
     builtin function calling the internal Rmetrics function 
     'systemfitBuiltin()'.

_U_s_a_g_e:

     systemFit(formula, data = list(), method = c("OLS", "WLS", "SUR", "2SLS", 
         "W2SLS", "3SLS", "W3SLS"), title = NULL, description = NULL, ...)
         
     nlsystemFit(formula, data = list(), method = c("OLS", "SUR", "2SLS", "3SLS"), 
         start = NULL, title = NULL, description = NULL, ...)

     ## S3 method for class 'fSYSTEM':
     predict(object, newdata = object@data, se.fit = FALSE, 
         se.pred = FALSE, interval = "none", ci = 0.95, ...)

     ## S3 method for class 'fSYSTEM':
     print(x, ...)
     ## S3 method for class 'fSYSTEM':
     summary(object, ...)

     ## S3 method for class 'fSYSTEM':
     coef(object, ...)
     ## S3 method for class 'fSYSTEM':
     fitted(object, ...)
     ## S3 method for class 'fSYSTEM':
     residuals(object, ...)

     SUR(formula, data = list(), ...)

_A_r_g_u_m_e_n_t_s:

      ci: [predict] - 
           the confidence interval, by default 0.95. 

 formula: [systemFit] - 
           the list of formulas describing the system of equations. 

    data: [systemFit] - 
           the input data set in form of a 'data.frame' or 
          'timeSeries' object. 

description: [systemFit] - 
           a character string which allows for a brief description. 

interval: [predict] - 
           Type of interval calculation, one of '"none"', 
          '"confidence"', or '"prediction"'. 

  method: [systemFit] - 
           a character string describing the desired method, one of:
          '"OLS"', '"WLS"', '"SUR"', '"2SLS"',  '"W2SLS"', '"3SLS"', or
          '"W3SLS"'. 

 newdata: [predict] - 
           a new input data set in form of a 'data.frame' or 
          'timeSeries'to be predicted. 

  object: [predict][summary] - 
           [coef][fitted][residuals][vcov] - 
           an object of class 'fSYSTEM'. 

  se.fit: [predict] - 
           a logical, should the standard error of the fitted values 
          be returned? 

 se.pred: [predict] - 
           a logical, should the standard error of the prediction be
          returned? 

   start: start values. 

   title: [systemFit] - 
           a character string which allows for a project title. 

       x: [plot][print] - 
           an object of class 'fSYSTEM'. 

     ...: [systemFit] - 
           additional optional arguments to be passed to the underlying
           function 'systemfit' for the "OLS", "WLS", "SUR", "2SLS", 
          "W2SLS", "3SLS", or "W3SLS" method. 
           These include:  
                'eqnlabels' - 
           an optional list of character vectors of names for the 
          equation labels.  
           'formula3sls' - 
           formula for calculating the 3SLS estimator, one of  '"GLS"',
          '"IV"', '"GMM"', '"Schmidt"'  or '"EViews"', see 'systemfit'
          details.  
           'inst' - 
           one-sided model formula specifying instrumental variables 
          or a list of one-sided model formulas if different
          instruments  should be used for the different equations, only
          needed for  '"2SLS"', '"W2SLS"' and '"3SLS"' estimations.  
           'maxiter' - 
           maximum number of iterations for '"WLS"', '"SUR"', 
          '"W2SLS"' and '"3SLS"' estimations.  
            'probdfsys' - 
           use the degrees of freedom of the whole system (in place of
          the degrees of freedom of the single equation) to calculate 
          prob values for the t-test of individual parameters.  
           'q.restr' - 
           an optional 'j x 1' matrix to impose linear restrictions, 
          see 'R.restr'; default is a 'j x 1' matrix that  contains
          only zeros.  
           'R.restr' - 
           an optional 'j x k' matrix to impose linear restrictions  
          on the parameters by 'R.restr' * b = 'q.restr', 'j' = number
          of restrictions, 'k' = number of all  parameters, b = vector
          of all parameters.  
           'rcovformula' - 
           formula to calculate the estimated residual covariance 
          matrix, see 'systemfit' details.  
           'saveMemory' - 
           save memory by omitting some calculation that are not
          crucial for the basic estimation, e.g. McElroy's  R^2.  
           'single.eq.sigma' - 
           use different sigma^2s for each single equation to calculate
          the covariance matrix and the standard errors of  the
          coefficients, only '"OLS"' and '"2SLS"'.  
           'solvetol' - 
           tolerance level for detecting linear dependencies when
          inverting a matrix or calculating a determinant, see see
          'solve' and 'det'.  
           'tol' - 
           tolerance level indicating when to stop the iteration, only
          '"WLS"', '"SUR"', '"W2SLS"' and  '"3SLS"' estimations.  
           'TX' - 
           an optional matrix to transform the regressor matrix  and,
          hence, also the coefficient vector, see 'systemfit' details.                           

_D_e_t_a_i_l_s:

     Ordinary Least Squares (OLS) estimates are biased and inconsistent
      when endogenous variables appear as regressors in other equations
      in the system. Furthermore, one observes that the errors of a set
      of related regression equations are often correlated. Then the 
     efficiency of the estimates can in many cases be improved
     including  the correlations into the parameter estimation
     procedure. The  function 'eqnaFit' provides several methods which
     can  produce consistent and asymptotically efficient estimates for
      systems of regression equations. 

     The variables in a system of equations can be characterized by  
     four types. These include _Endogenous Variables_ which are  the
     variables determined by the system, _Exogenous Variables_   which
     are independent variables that do not depend on any of the 
     endogenous variables in the system, _Predetermined Variables_  
     which include both the exogenous variables and lagged endogenous 
     variables, which are past values of endogenous variables
     determined   at previous time periods, and _Instrumental Variables
     _ which  are are predetermined variables used in obtaining
     predicted values  for the current period endogenous variables by a
     first-stage regression.  The use of instrumental variables
     characterizes estimation methods  such as two-stage least squares
     and three-stage least squares.  Instrumental variables estimation
     methods substitute these first-stage  predicted values for
     endogenous variables when they appear as  regressors in model
     equations. 

     _Technical Details: 'systemfit'_

     The matrix 'TX' transforms the regressor matrix (X) by X^{*} = X *
     'TX'. Thus, the vector of coefficients is now b = 'TX' cdot b^{*},
     where b is the original  (stacked) vector of all coefficients and
     b^{*} is the new  coefficient vector that is estimated instead.
     Thus, the elements of  vector b are b_i = sum_j TX_{ij} cdot
     b^{*}_j. 

     The 'TX' matrix can be used to change the order of the
     coefficients and also to restrict coefficients (if 'TX' has  less
     columns than it has rows). However restricting coefficients by the
     'TX' matrix is less powerfull and flexible than the restriction by
     providing the 'R.restr' matrix and the 'q.restr' vector. The
     advantage of restricting the coefficients by the 'TX' matrix is
     that the matrix that is inverted for estimation gets smaller by
     this procedure, while it gets larger if the restrictions are
     imposed by 'R.restr' and 'q.restr'.

     If iterated (WLS, SUR, W2SLS or 3SLS estimation with 'maxit'>1),
     the convergence criterion is 

     sqrt{ sum_i (b_{i,g} - b_{i,g-1})^2 <=ft/  sum_i b_{i,g-1}^2
     right. } < 'tol'.

     Here, b_{i,g} is the ith coefficient of the g-th  iteration step.

     The formula to calculate the estimated covariance matrix of the 
     residuals, hat{Sigma}, can be one of the following, see  Judge et
     al., 1985, p. 469: 

     if 'rcovformula=0:' hat{sigma}_{ij} =  (hat{e}_i' hat{e}_j) / T; 

     if 'rcovformula=1:' hat{sigma}_{ij} =  (hat{e}_i' hat{e}_j) /
     sqrt{(T - k_i)*(T - k_j)}; 

     if 'rcovformula=2:' hat{sigma}_{ij} =  (hat{e}_i' hat{e}_j) / (T -
     k_i - k_j +  tr[(X_i'X_i)^{-1}X_i'X_j(X_j'X_j)^{-1}X_j'X_i]. 

     If k_i = k_j, formula 1 and 2 are equal and yield an unbiased 
     estimator for the residual covariance matrix. If k_i neq k_j, only
     formula 2 yields an unbiased estimator  for the residual
     covariance matrix, but it is not neccessarily positive 
     semidefinit and its inverse is *not* an unbiased estimator for 
     the inverse of the residual covariance matrix. Thus, it is
     doubtful  whether formula 2 is really superior to formula 1, see
     Theil, 1971,  p. 322.

     The formulas to calculate the 3SLS estimator lead to identical 
     results if the same instruments are used in all equations. If 
     different instruments are used in the different equations, only 
     the GMM-3SLS estimator, '"GMM"' and the 3SLS estimator proposed 
     by Schmidt (1990), '"Schmidt"' are consistent, whereas  '"GMM"' is
     efficient relative to '"Schmidt"', see Schmidt, 1990.  

     _Prediction:_

     The variance of the fitted values, used to calculate the standard 
     errors of the fitted values and the confidence interval, is 
     calculated by

     Var[E[y^0]-hat{y}^0]=x^0 ; Var[b] ; {x^0}'

     an the variances of the predicted values, used to calculate the 
     standard errors of the predicted values and the prediction
     intervals,  is calculated by

     Var[y^0-hat{y}^0]=hat{sigma}^2+x^0 ; Var[b] ; {x^0}'

_V_a_l_u_e:

     *Fit: Parameter Estimation* 

     The function 'systemFit' returns an object of class '"fSYSTEM"' 
     with the following slots:

   @call: the matched function call. 

   @data: the input data in form of a 'data.frame' or a  'timeSeries'
          object. 

@description: a character string which allows for a brief project
          description. 

    @fit: a summary of the  results as a list returned from the
          underlying functions from the 'systemfit' package. 

@formulas: the list of formulas describing the system of equations. 

 @method: a character string describing the desired method, one of:
          '"OLS"', '"WLS"', '"SUR"', '"2SLS"',  '"W2SLS"', '"3SLS"', or
          '"W3SLS"'. 

  @title: a character string which allows for a project title. 

    coef: the coefficients from an object of class 'fSYSTEM'. A 
          one-column data frame of all estimated coefficients. 

 confint: the confidence intervals of the coefficients of one equation 
          from an object of class 'fSYSTEM'.  

  fitted: the fitted values of all equations from an object of class 
          'fSYSTEM'.  

residuals: the residuals from an object of class 'fSYSTEM'.  

    vcov: the variance covariance matrix of all coefficients from an 
          object of class 'fSYSTEM'.  

  method: estimation method.  

       g: number of equations.  

       n: total number of observations.  

       k: total number of coefficients.  

      ki: total number of linear independent coefficients.  

      df: degrees of freedom of the whole system.  

    iter: number of iteration steps.  

       b: vector of all estimated coefficients. 

      bt: coefficient vector transformed by 'TX'.  

      se: estimated standard errors of 'b'.  

       t: t values for 'b'.  

       p: p values for 'b'.  

    bcov: estimated covariance matrix of 'b'.  

   btcov: covariance matrix of 'bt'.  

    rcov: estimated residual covariance matrix.  

   drcov: determinant of 'rcov'.  

 rcovest: residual covariance matrix used for estimation,  only "SUR"
          and "3SLS".  

    rcor: estimated residual correlation matrix.  

   olsr2: System OLS R-squared value.  

  mcelr2: McElroys R-squared value for the system, only "SUR" and
          "3SLS".  

       y: vector of all (stacked) endogenous variables. 

       x: matrix of all (diagonally stacked) regressors. 

       h: matrix of all (diagonally stacked) instrumental variables, 
          only "2SLS" and "3SLS".  

    data: data frame of the whole system including instruments.  

 R.restr: the restriction matrix.  

 q.restr: the restriction vector.  

      TX: matrix used to transform the regressor matrix.  

 maxiter: maximum number of iterations.  

     tol: tolerance level indicating when to stop the iteration.  

rcovformula: formula to calculate the estimated residual covariance
          matrix.  

formula3sls: formula for calculating the "3SLS" estimator.  

probdfsys: system degrees of freedom to calculate prob values? 

single.eq.sigma: different sigma^2s for each single equation? 

solvetol: tolerance level when inverting a matrix or calculating  a
          determinant.  

      eq: a list that contains the results that belong to the
          individual  equations.  

eqnlabel*: the equation label of the i-th equation (from the labels
          list).  

formula*: model formula of the i-th equation.  

   inst*: instruments of the i-th equation, only 2SLS and 3SLS.  

      n*: number of observations of the i-th equation.  

      k*: number of coefficients/regressors in the i-th equation
          (including  the constant).  

     ki*: number of linear independent coefficients in the i-th
          equation  (including the constant differs from 'k' only if
          there are  restrictions that are not cross-equation).  

     df*: degrees of freedom of the i-th equation.  

      b*: estimated coefficients of the i-th equation.  

     se*: estimated standard errors of 'b'.  

      t*: t values for 'b'.  

      p*: p values for 'b'.  

   covb*: estimated covariance matrix of 'b'.  

      y*: vector of endogenous variable (response values) of the i-th 
          equation.  

      x*: matrix of regressors (model matrix) of the i-th equation.  

      h*: matrix of instrumental variables of the i-th equation,  only
          "2SLS" and "3SLS".  

   data*: data frame (including instruments) of the i-th equation.  

 fitted*: vector of fitted values of the i-th equation.  

residuals*: vector of residuals of the i-th equation.  

    ssr*: sum of squared residuals of the i-th equation.  

    mse*: estimated variance of the residuals (mean of squared errors) 
           of the i-th equation.  

     s2*: estimated variance of the residuals (hat{sigma}^2) of  the
          i-th equation.  

   rmse*: estimated standard error of the residulas (square root of
          mse)  of the i-th equation.  

      s*: estimated standard error of the residuals (hat{sigma})  of
          the i-th equation.  

     r2*: R-squared (coefficient of determination).  

  adjr2*: adjusted R-squared value.  


     *S3 Methods:* 

     The output from the S3 'summary' method prints the results in form
     of a detailed report together with optional plots.  
      The output from the S3 'print' method prints on object of class
     'fSYSTEM'.  
      The output from the S3 'plot' method returns some diagnostic
     plots. 

     *S-Plus like SUR Function:* 

     The function 'SUR' returns an object of class '"fSYSTEM"'  with
     the same slots returned by the function 'systemFit' for method
     '"SUR"'.

_N_o_t_e:

     It is worth to remark, that there are two more R-packages which
     are  of interest in this context: 

     The contributed R package '"sem"' offers functions for fitting
     general  structural equation models by the method of maximum
     likelihood (SEM)  and for fitting a model by two-stage least
     squares (TSLS). This package  was written by John Fox. 

     The contributed R package '"pls.pcr"' offers also functions for 
     multivariate regression. Principal Component Regression (PCR) and
     two  types of Partial Least Square Regression (PLS), simple-PLS
     and  kernel-PLS, are implemented by Ron Wehrens. 

     These two packages are not discussed here and are available from
     the CRAN server.

     Wrapper for the nonlinear case are not yet available.

_A_u_t_h_o_r(_s):

     Jeff D. Hamann and Arne Henningsen for the 'systemfit' package, 
      Diethelm Wuertz for the Rmetrics R-port.

_R_e_f_e_r_e_n_c_e_s:

     Greene W.H., (1993); _Econometric Analysis_,  Second Edition,
     Macmillan.

     Greene W.H., (2002); _Econometric Analysis_  Fifth Edition,
     Prentice Hall.

     Judge G.G., Griffiths W.E., Hill R.C, Ltkepohl H., Lee T.C.,
     (1985); _The Theory and Practice of Econometrics_, Second Edition,
     Wiley.

     Kmenta J., (1997); _Elements of Econometrics_,  Second Edition,
     University of Michigan Publishing.

     Schmidt P., (1990); _Three-Stage Least Squares with different
     Instruments for  different equations_, Journal of Econometrics 43,
     p. 389-394.

     Theil H., (1971); _Principles of Econometrics_,  Wiley, New York.

_S_e_e _A_l_s_o:

     'lm', 'regFit'.

_E_x_a_m_p_l_e_s:

     ## SOURCE("fMultivar.3A-EquationsModelling")
     ## Not run: 
     ## Note, "systemfit" is required:
        SYSTEMFIT = require(systemfit)
        if (SYSTEMFIT) {
        
     ## Examples from the 'systemfit' Package:
        data(kmenta)
        
     ## OLS Estimations:   
        formulas = list(demand = q ~ p + d, supply = q ~ p + f + a )
        FITOLS = systemFit(formulas, data = kmenta)
        FITOLS
        
     ## OLS Estimation with 2 Restrictions:
        Rrestr <- matrix(0, 2, 7)
        qrestr <- matrix(0, 2, 1)
        Rrestr[1,3] =  1
        Rrestr[1,7] = -1
        Rrestr[2,2] = -1
        Rrestr[2,5] =  1
        qrestr[2,1] =  0.5
        FITOLS2 = systemFit(formulas, data = kmenta, R.restr = Rrestr, 
          q.restr = qrestr)
        FITOLS2
        
     ## Iterated SUR Estimation:
        FITSUR = systemFit(formulas, data = kmenta, method = "SUR", maxit = 100)
        FITSUR
        # Coefficients, Fitted Values, Residuals and Variance-Covariance Matrix:
        # Call by Method:
        coef(FITSUR)
        fitted(FITSUR)
        residuals(FITSUR)

     ## 2SLS Estimation:
        inst = ~ d + f + a
        FIT2SLS = systemFit(formulas, data = kmenta, method = "2SLS", inst = inst)
        FIT2SLS
        # Coefficients, Fitted Values, Residuals and Variance-Covariance Matrix:
        # Call by Slot:
        FIT2SLS@fit$coef
        FIT2SLS@fitted.values
        FIT2SLS@residuals

     ## 2SLS Estimation with Different Instruments in Each Equation:
        insts = list( ~ d + f, ~ d + f + a)
        FIT2SLS2 = systemFit(formulas, data = kmenta, method = "2SLS", inst = insts)
        FIT2SLS2

     ## 3SLS Estimation with GMM-3SLS Formula:
        instruments = ~ d + f + a
        FIT3SLS = systemFit(formulas, data = kmenta, method = "3SLS", 
          inst = instruments, formula3sls = "GMM")
        FIT3SLS
        
        } # if (SYSTEMFIT)
        
     ## SEE ALSO:
        # Demo File: xmpEqnsGrunfeld.R
        # Estimation of Grunfeld's Model Data with OLS and SUR
     ## End(Not run)

