mnp                   package:MNP                   R Documentation

_F_i_t_t_i_n_g _t_h_e _M_u_l_t_i_n_o_m_i_a_l _P_r_o_b_i_t _M_o_d_e_l _v_i_a _M_a_r_k_o_v _c_h_a_i_n _M_o_n_t_e _C_a_r_l_o

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

     'mnp' is used to fit (Bayesian) multinomial probit model via
     Markov chain Monte Carlo.  'mnp' can also fit the model with
     different choice sets for each observation, and complete or
     partial ordering of all the available alternatives. The
     computation uses the efficient marginal data augmentation
     algorithm that is developed by Imai and van Dyk (2005).

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

     mnp(formula, data = parent.frame(), choiceX = NULL, cXnames = NULL,
         base = NULL, latent = FALSE, n.draws = 5000, p.var = "Inf",
         p.df = n.dim+1, p.scale = 1, coef.start = 0, cov.start = 1,
         burnin = 0, thin = 0, verbose = FALSE) 

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

 formula: A symbolic description of the model to be fit specifying the
          response variable and covariates. The formula should  not
          include the choice-specific covariates. Details and specific
          examples are given below.  

    data: An optional data frame in which to interpret the variables in
          'formula' and 'choiceX'. The default is the environment in
          which 'mnp' is called. 

 choiceX: An optional list containing a matrix of choice-specific
          covariates for each category. Details and examples are
          provided below. 

 cXnames: A vector of the names for the choice-specific covariates
          specified in 'choiceX'. The details and examples are provided
          below. 

    base: The name of the base category. For the standard multinomial
          probit model, the default is the lowest level of the response
          variable. For the multinomial probit model with ordered
          preferences, the default base category is the last column in
          the matrix of response variables. 

  latent: logical. If 'TRUE', then the latent variable W will be
          returned. See Imai and van Dyk (2005) for the notation. The
          default is 'FALSE'. 

 n.draws: A positive integer. The number of MCMC draws. The default is
          '5000'. 

   p.var: A positive definite matrix. The prior variance of the
          coefficients.  A scalar input can set the prior variance to
          the diagonal matrix whose diagonal element is equal to that
          value. The default is '"Inf"', which represents an improper
          noninformative prior distribution on the coefficients. 

    p.df: A positive integer greater than 'n.dim-1'. The prior degrees
          of freedom parameter for the covariance matrix. The default
          is 'n.dim+1', which is equal to the total number of
          alternatives. 

 p.scale: A positive definite matrix whose first diagonal element is
          set to '1'. The prior scale matrix for the covariance matrix.
          The first diagonal element is set to 1 if it is not equal to
          1 already. A scalar input can be used to set the scale matrix
          to a diagonal matrix with diagonal elements equal to the
          scalar input value, except that the first diagonal element is
          set to one. The default is '1'. 

coef.start: A vector. The starting values for the coefficients. A
          scalar input sets the starting values for all the
          coefficients equal to that value.  The default is '0'. 

cov.start: A positive definite matrix whose first diagonal element is
          set to '1'. The starting values for the covariance matrix.
          The first diagonal element is set to 1 if it is not equal to
          1 already. A scalar input can be used to set the starting
          value to a diagonal matrix with diagonal elements equal to
          the scalar input value, except that the first diagonal
          element is set to one. The default is '1'.  

  burnin: A positive integer. The burnin interval for the Markov chain;
          i.e., the number of initial Gibbs draws that should not be
          stored. The default is '0'.  

    thin: A positive integer. The thinning interval for the Markov
          chain; i.e., the number of Gibbs draws between the recorded
          values that are skipped. The default is '0'.  

 verbose: logical. If 'TRUE', helpful messages along with a progress
          report of the Gibbs sampling are printed on the screen. The
          default is 'FALSE'. 

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

     To fit the multinomial probit model when only the most preferred
     choice is observed, use the syntax for the formula, 'y ~ x1 + x2',
     where 'y' is a factor variable indicating the most preferred
     choice and 'x1' and 'x2' are individual-specific covariates. The
     interactions of individual-specific variables with each of the
     choice indicator variables will be fit.

     To specify choice-specific covariates, use the syntax,
     'choiceX=list(A=cbind(z1, z2), B=cbind(z3, z4), C=cbind(z5, z6))',
     where 'A', 'B', and 'C' represent the choice names of the response
     variable, and 'z1' and 'z2' are each vectors of length n that
     record the values of the two choice-specific covariates for each
     individual for choice A, likewise for 'z3', ..., 'z6'. The
     corresponding variable names via 'cXnames=c("price", "quantity")'
     need to be specified, where 'price' refers to the coefficient name
     for 'z1', 'z3', and 'z5', and 'quantity' refers to that for 'z2',
     'z4', and 'z6'.

     If the choice set varies from one observation to another, use the
     syntax, 'cbind(y1, y2, y3) ~ x1 + x2', in the case of a three
     choice problem, and indicate unavailable alternatives by 'NA'. If
     only the most preferred choice is observed, 'y1', 'y2', and 'y3'
     are indicator variables that take on the value one for individuals
     who prefer that choice and zero otherwise. The last column of the
     response matrix, 'y3' in this particular example syntax, is used
     as the base category.

     To fit the multinomial probit model when the complete or partial
     ordering of the available alternatives is recorded, use the same
     syntax as when the choice set varies (i.e., 'cbind(y1, y2, y3, y4)
     ~ x1 + x2'). For each observation, all the available alternatives
     in the response variables should be numerically ordered in terms
     of preferences such as '1 2 2 3'. Ties are allowed. The missing
     values in the response variable should be denoted by 'NA'. The
     software will impute these missing values using the specified
     covariates. The resulting uncertainty estimates of the parameters
     will properly reflect the amount of missing data. For example, we
     expect the standard errors to be larger when there is more missing
     data.

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

     An object of class 'mnp' containing the following elements: 

   param: A matrix of the Gibbs draws for each parameter; i.e., the
          coefficients and covariance matrix. For the covariance
          matrix, the elements on or above the diagonal are returned. 

    call: The matched call.

       x: The matrix of covariates.

       y: The vector or matrix of the response variable.

       w: The three dimensional array of the latent variable, W. The
          first dimension represents the alternatives, and the second
          dimension indexes the observations. The third dimension
          represents the Gibbs draws. Note that the latent variable for
          the base category is set to 0, and therefore omitted from the
          output.

     alt: The names of alternatives.

   n.alt: The total number of alternatives.

    base: The base category used for fitting.

   p.var: The prior variance for the coefficients.

    p.df: The prior degrees of freedom parameter for the covariance
          matrix.

 p.scale: The prior scale matrix for the covariance matrix.

  burnin: The number of initial burnin draws.

    thin: The thinning interval.

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

     Kosuke Imai, Department of Politics, Princeton University
     kimai@Princeton.Edu, <URL: http://www.princeton.edu/~kimai>;
     Jordan R. Vance, Princeton University; David A. van Dyk,
     Department of Statistics, University of California, Irvine
     dvd@uci.edu, <URL: http://www.ics.uci.edu/~dvd>.

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

     Imai, Kosuke and David A. van Dyk. (2005) "A Bayesian Analysis of
     the Multinomial Probit Model Using the Marginal Data
     Augmentation," _Journal of Econometrics_, Vol. 124, No. 2
     (February), pp.311-334.

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

     'summary.mnp'; MNP home page at <URL:
     http://www.princeton.edu/~kimai/research/MNP.html>

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

     ## load the detergent data
     data(detergent)
     ## run the standard multinomial probit model with intercepts and the price
     res1 <- mnp(choice ~ 1, choiceX = list(Surf=SurfPrice, Tide=TidePrice,
                                            Wisk=WiskPrice, EraPlus=EraPlusPrice,
                                            Solo=SoloPrice, All=AllPrice),
                 cXnames = "price", data = detergent, n.draws = 500, burnin = 100,
                 thin = 3, verbose = TRUE)
     ## summarize the results
     summary(res1)
     ## calculate the predicted probabilities for the first 5 observations
     predict(res1, newdata = detergent[1:3,], type="prob", verbose = TRUE)

     ## load the Japanese election data
     data(japan)
     ## run the multinomial probit model with ordered preferences
     res2 <- mnp(cbind(LDP, NFP, SKG, JCP) ~ sex + education + age, data = japan,
                 verbose = TRUE)
     ## summarize the results
     summary(res2)
     ## calculate the predicted probabilities for the 10th observation
     predict(res2, newdata = japan[10,], type = "prob")

