\name{mnp}

\alias{mnp}
\alias{MNP}

\title{Fitting the Multinomial Probit Model via Markov chain Monte Carlo} 

\description{
  \code{mnp} is used to fit (Bayesian) multinomial probit
  model via Markov chain Monte Carlo.  \code{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 (2005a).
}

\usage{
mnp(formula, data = parent.frame(), choiceX = NULL, cXnames = NULL,
    base = NULL, latent = FALSE, invcdf = 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) 
}

\arguments{
  \item{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. 
  }
  \item{data}{An optional data frame in which to interpret the variables
    in \code{formula} and \code{choiceX}. The default is the environment
    in which \code{mnp} is called.
  }
  \item{choiceX}{An optional list containing a matrix of choice-specific
    covariates for each category. Details and examples are provided
    below.
  }
  \item{cXnames}{A vector of the names for the choice-specific covariates
    specified in \code{choiceX}. The details and examples are provided
    below.
  }
  \item{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.
  }
  \item{latent}{logical. If \code{TRUE}, then the latent variable W will
    be returned. See Imai and van Dyk (2005) for the notation. The
    default is \code{FALSE}.
  }
  \item{invcdf}{logical. If \code{TRUE}, then the inverse cdf method is
    used for truncated normal sampling. If \code{FALSE}, then the
    rejection sampling method is used. The default is \code{FALSE}.
  }
  \item{n.draws}{A positive integer. The number of MCMC draws. The
    default is \code{5000}.
  }
  \item{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 \code{"Inf"}, which represents an improper noninformative
    prior distribution on the coefficients.
  }
  \item{p.df}{A positive integer greater than \code{n.dim-1}. The prior
  degrees of freedom parameter for the covariance matrix. The default is
    \code{n.dim+1}, which is equal to the total number of alternatives.
  }
  \item{p.scale}{A positive definite matrix whose first diagonal element
    is set to \code{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 \code{1}.
  }
  \item{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 \code{0}.
  }
  \item{cov.start}{A positive definite matrix whose first diagonal
    element is set to \code{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 \code{1}. 
  }
  \item{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 \code{0}. 
  }
  \item{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 \code{0}. 
  }
  \item{verbose}{logical. If \code{TRUE}, helpful messages along with
    a progress report of the Gibbs sampling are printed
    on the screen. The default is \code{FALSE}.
  }
}

\details{
  To fit the multinomial probit model when only the most
  preferred choice is observed, use the syntax for the formula, \code{y
  ~ x1 + x2}, where \code{y} is a factor variable indicating the most
  preferred choice and \code{x1} and \code{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,
  \code{choiceX=list(A=cbind(z1, z2), B=cbind(z3, z4), C=cbind(z5,
  z6))}, where \code{A}, \code{B}, and \code{C} represent the choice
  names of the response variable, and \code{z1} and \code{z2} are each
  vectors of length \eqn{n} that record the values of the two
  choice-specific covariates for each individual for choice A, likewise
  for \code{z3}, \eqn{\ldots}, \code{z6}. The corresponding variable names via
  \code{cXnames=c("price", "quantity")}
  need to be specified, where \code{price} refers to the coefficient
  name for \code{z1}, \code{z3}, and \code{z5}, and \code{quantity}
  refers to that for \code{z2}, \code{z4}, and \code{z6}.

  If the choice set varies from one observation to another, use the
  syntax, \code{cbind(y1, y2, y3) ~ x1 + x2}, in the case of a
  three choice problem, and indicate unavailable alternatives by
  \code{NA}. If only the most preferred choice is observed, \code{y1},
  \code{y2}, and \code{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, \code{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., \code{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 \code{1 2 2 3}. Ties are allowed. The
  missing values in the response variable should be denoted by
  \code{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.
}

\examples{
###
### NOTE: this example is not fully analyzed. In particular, the
### convergence has not been assessed. A full analysis of these data
### sets appear in Imai and van Dyk (2005b).
###

## 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 quantities of interest for the first 3 observations
pre1 <- predict(res1, newdata = detergent[1:3,])

## load the Japanese election data
data(japan)
## run the multinomial probit model with ordered preferences
res2 <- mnp(cbind(LDP, NFP, SKG, JCP) ~ gender + education + age, data = japan,
            verbose = TRUE)
## summarize the results
summary(res2)
## calculate the predicted probabilities for the 10th observation
## averaging over 100 additional Monte Carlo draws given each of MCMC draw.
pre2 <- predict(res2, newdata = japan[10,], type = "prob", n.draws = 100,
                verbose = TRUE)
}

\value{
  An object of class \code{mnp} containing the following elements:
  \item{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.
  }
  \item{call}{The matched call.}
  \item{x}{The matrix of covariates.}
  \item{y}{The vector or matrix of the response variable.}
  \item{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.}
  \item{alt}{The names of alternatives.}
  \item{n.alt}{The total number of alternatives.}
  \item{base}{The base category used for fitting.}
  \item{invcdf}{The value of \code{invcdf}.}
  \item{p.var}{The prior variance for the coefficients.}
  \item{p.df}{The prior degrees of freedom parameter for the covariance matrix.}
  \item{p.scale}{The prior scale matrix for the covariance matrix.}
  \item{burnin}{The number of initial burnin draws.}
  \item{thin}{The thinning interval.}
}


\references{
  Imai, Kosuke and David A. van Dyk. (2005a) \dQuote{A Bayesian Analysis
    of the Multinomial Probit Model Using the Marginal Data
    Augmentation,} \emph{Journal of Econometrics}, Vol. 124, No. 2
  (February), pp.311-334.

  Imai, Kosuke and David A. van Dyk. (2005b) \dQuote{MNP: R Package for
    Fitting the Multinomial Probit Models,} \emph{Journal of Statistical
  Software}, Vol. 14, No. 3 (May), pp.1-32.
}

\author{
  Kosuke Imai, Department of Politics, Princeton University
  \email{kimai@Princeton.Edu}, \url{http://imai.princeton.edu};
  David A. van Dyk, Department of Statistics, University of California,
Irvine \email{dvd@uci.edu}, \url{http://www.ics.uci.edu/~dvd}.  
}

\seealso{\code{coef.mnp}, \code{cov.mnp}, \code{predict.mnp},
\code{summary.mnp}; MNP home page at
  \url{http://imai.princeton.edu/research/MNP.html}}

\keyword{models}