mvProbitMargEff: Expectations and Marginal Effects from Multivariate Probit...
In mvProbit: Multivariate Probit Models

Description Usage Arguments Details Value Author(s) References See Also Examples

View source: R/mvProbitMargEff.R

mvProbitExp calculates expected outcomes from multivariate probit models.

mvProbitMargEff calculates marginal effects of the explanatory variables on expected outcomes from multivariate probit models.

The margEff method for objects of class "mvProbit" is a wrapper function that (for the convenience of the user) extracts the relevant information from the estimation results and then calls mvProbitMargEff.

mvProbitExp( formula, coef, sigma = NULL, data,
   cond = FALSE, algorithm = "GHK", nGHK = 1000, random.seed = 123, ... )

mvProbitMargEff( formula, coef, sigma = NULL, vcov = NULL, data,
   cond = FALSE, algorithm = "GHK", nGHK = 1000, 
   eps = 1e-06, dummyVars = NA, addMean = FALSE, 
   returnJacobian = FALSE, random.seed = 123,
   ... )

## S3 method for class 'mvProbit'
margEff( object, data = eval( object$call$data ),
   cond = FALSE, othDepVar = NULL, dummyVars = object$dummyVars, 
   atMean = FALSE, calcVCov = FALSE, ... )

`formula`	a one-sided or two-sided `"formula"`: a symbolic description of the model (currently, all binary outcome variables must have the same explanatory variables).
`coef`	a numeric vector of the model coefficients; if argument `sigma` is not specified, this vector must also include the correlation coefficients; the order of elements is explained in the section “details”.
`sigma`	optional argument for specifying the covariance/correlation matrix of the residuals (must be symmetric and have ones on its diagonal); if this argument is not specified, the correlation coefficients must be specified by argument `coef`.
`vcov`	an optional symmetric matrix specifying the variance-covariance matrix of all coefficients (model coefficients and correlation coefficients); if this argument is specified, the approximate variance covariance matrices of the marginal effects are calculated and returned as an attribute (see below).
`data`	a `data.frame` containing the data.
`cond`	logical value indicating whether (marginal effects on) conditional expectations (if `TRUE`) or (marginal effects on) unconditional expectations (if `FALSE`, default) should be returned.
`algorithm`	algorithm for computing integrals of the multivariate normal distribution, either function `GenzBretz()`, `Miwa()`, or `TVPACK()` (see documentation of `pmvnorm`) or character string `"GHK"` (see documentation of `ghkvec`).
`nGHK`	numeric value specifying the number of simulation draws of the GHK algorithm for computing integrals of the multivariate normal distribution.
`eps`	numeric, the difference between the two values of each (numerical) explanatory variable that is used for the numerical differentiation.
`dummyVars`	optional vector containing the names (character strings) of explanatory variables that should be treated as dummy variables (see section ‘Details’). If `NA` (the default), dummy variables are detected automatically, i.e. all explanatory variables which contain only zeros and ones or only `TRUE` and `FALSE` in the data set specified by argument `data` are treated as dummy variables. If `NULL`, no variable is treated as dummy variable.
`addMean`	logical. If `TRUE`, the mean of values of all marginal effects are added in an additional row at the bottom of the returned data.frame. If argument `returnJacobian` is `TRUE`, the Jacobian of the mean marginal effects with respect to the coefficients is included in the returned array of the Jacobians (in an additional slot at the end of the first dimension). If argument `vcov` of `mvProbitMargEff` is specified or argument `calcVCov` of the `margEff` method is `TRUE`, the variance covariance matrix of the mean marginal effects is included in the returned array of the variance covariance matrices (in an additional slot at the end of the first dimension).
`returnJacobian`	logical. If `TRUE`, the Jacobian of the marginal effects with respect to the coefficients is returned.
`random.seed`	an integer used to seed R's random number generator; this is to ensure replicability when computing (cumulative) probabilities of the multivariate normal distribution which is required to calculate the conditional expectations; `set.seed( random.seed )` is called each time before a (cumulative) probability of the multivariate normal distribution is computed; defaults to 123.
`object`	an object of class `"mvProbit"` (returned by `mvProbit`.
`othDepVar`	optional scalar or vector for specifying the values of the (other) dependent variables when calculating the marginal effects on the conditional expectations. If this argument is a scalar (zero or one), it is assumed that all (other) dependent variables have this value at all observations. If this argument is a vector (filled with zeros or ones) with length equal to the number of dependent variables, it is assumed that the vector of dependent variables has these values at all observations. If this argument is `NULL` (the default), the dependent variables are assumed to have the values that these variables have in the data set `data`.
`atMean`	logical. If `TRUE`, the marginal effects are calculated not at each observation but at the mean values across all observations of the variables in the data set specified by argument `data`.
`calcVCov`	logical. If `TRUE`, the approximate variance covariance matrices of the marginal effects are calculated and returned as an attribute (see below).
`...`	additional arguments to `mvProbitExp` are passed to `pmvnorm` when calculating conditional expectations; additional arguments of `mvProbitMargEff` are passed to `mvProbitExp` and possibly further to `pmvnorm`; additional arguments of the `margEff` method are passed to `mvProbitMargEff` and possibly further to `mvProbitMargEff` and `pmvnorm`.

When calculating (marginal effects on) unconditional expectations, the left-hand side of argument formula is ignored. When calculating (marginal effects on) conditional expectations and argument formula is a one-sided formula (i.e. only the right-hand side is specified) or argument othDepOne is TRUE, (the marginal effects on) the conditional expectations are calculated based on the assumption that all other dependent variables are one.

The computation of the marginal effects of dummy variables (i.e. variables specified in argument dummyVars) ignores argument eps and evaluates the effect of increasing these variables from zero to one. The marginal effects of (continuous) variables (i.e. variables not specified in argument dummyVars) are calculated by evaluating the effect of increasing these variables from their actual values minus 0.5 * eps to their actual values plus 0.5 * eps (divided by eps).

If the model has n dependent variables (equations) and k explanatory variables in each equation, the order of the model coefficients in argument coef must be as follows: b_{1,1}, ..., b_{1,k}, b_{2,1}, ..., b_{2,k}, ..., b_{n,1}, ..., b_{n,k}, where b_{i,j} is the coefficient of the jth explanatory variable in the ith equation. If argument sigma is not specified, argument coef must additionally include following elements: R_{1,2}, R_{1,3}, R_{1,4}, ..., R_{1,n}, R_{2,3}, R_{2,4}, ..., R_{2,n}, ..., R_{n-1,n}, where R_{i,j} is the correlation coefficient corresponding to the ith and jth equation.

If argument vcov of function mvProbitMargEff is specified or argument calcVCov of the margEff method is TRUE, the approximate variance covariance matrices of the marginal effects are calculated at each observation by using the ‘delta method’, where the jacobian matrix of the marginal effects with respect to the coefficients is obtained by numerical differentiation.

The ‘state’ (or ‘seed’) of R's random number generator is saved at the beginning of the call to these functions and restored at the end so that these functions do not affect the generation of random numbers outside this function although the random seed is set to argument random.seed and the calculation of the (cumulative) multivariate normal distribution uses random numbers.

mvProbitExp returns a data frame containing the expectations of the dependent variables.

mvProbitMargEff and the margEff method return a data frame containing the marginal effects of the explanatory variables on the expectations of the dependent variables.

If argument vcov of function mvProbitMargEff is specified or argument calcVCov of the margEff method is TRUE, the returned data frame has an attribute vcov, which is a three-dimensional array, where the first dimension corresponds to the observation and the latter two dimensions span the approximate variance covariance matrix of the marginal effects calculated for each observation.

If argument returnJacobian of function mvProbitMargEff or method margEff is set to TRUE, the returned data frame has an attribute jacobian, which is a three-dimensional array that contains the Jacobian matrices of the marginal effects with respect to the coefficients at each observation, where the first dimension corresponds to the observations, the second dimension corresponds to the marginal effects, and the third dimension corresponds to the coefficients.

Arne Henningsen

Greene, W.H. (1996): Marginal Effects in the Bivariate Probit Model, NYU Working Paper No. EC-96-11. Available at http://ssrn.com/abstract=1293106.

mvProbit, mvProbitLogLik, probit, glm

## generate a simulated data set
set.seed( 123 )
# number of observations
nObs <- 10

# generate explanatory variables
xData <- data.frame( 
   const = rep( 1, nObs ),
   x1 = as.numeric( rnorm( nObs ) > 0 ),
   x2 = as.numeric( rnorm( nObs ) > 0 ),
   x3 = rnorm( nObs ),
   x4 = rnorm( nObs ) )

# model coefficients
beta <- c(  0.8,  1.2, -1.0,  1.4, -0.8,
           -0.6,  1.0,  0.6, -1.2, -1.6,
            0.5, -0.6, -0.7,  1.1,  1.2 )

# covariance matrix of error terms
library( miscTools )
sigma <- symMatrix( c( 1, 0.2, 0.4, 1, -0.1, 1 ) )

# unconditional expectations of dependent variables
yExp <- mvProbitExp( ~ x1 + x2 + x3 + x4, coef = c( beta ), 
   sigma = sigma, data = xData )
print( yExp )

# marginal effects on unconditional expectations of dependent variables
margEffUnc <- mvProbitMargEff( ~ x1 + x2 + x3 + x4, coef = c( beta ), 
   sigma = sigma, data = xData )
print( margEffUnc )

# conditional expectations of dependent variables
# (assuming that all other dependent variables are one)
yExpCond <- mvProbitExp( ~ x1 + x2 + x3 + x4, coef = beta,
   sigma = sigma, data = xData, cond = TRUE )
print( yExpCond )

# marginal effects on conditional expectations of dependent variables
# (assuming that all other dependent variables are one)
margEffCond <- mvProbitMargEff( ~ x1 + x2 + x3 + x4, coef = beta,
   sigma = sigma, data = xData, cond = TRUE )
print( margEffCond )

# conditional expectations of dependent variables
# (assuming that all other dependent variables are zero)
xData$y1 <- 0
xData$y2 <- 0
xData$y3 <- 0
yExpCond0 <- mvProbitExp( cbind( y1, y2, y3 ) ~ x1 + x2 + x3 + x4, 
   coef = beta, sigma = sigma, data = xData, cond = TRUE )
print( yExpCond0 )

# marginal effects on conditional expectations of dependent variables
# (assuming that all other dependent variables are zero)
margEffCond0 <- mvProbitMargEff( cbind( y1, y2, y3 ) ~ x1 + x2 + x3 + x4, 
   coef = beta, sigma = sigma, data = xData, cond = TRUE )
print( margEffCond0 )