% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fracregmlogit.R
\name{fracregmlogit}
\alias{fracregmlogit}
\title{Estimate Fractional Multinomial Logit Models}
\usage{
fracregmlogit(
  y,
  X,
  beta0 = NULL,
  MLEmethod = "CG",
  maxit = 5e+05,
  abstol = 1e-05,
  cluster = NULL,
  reps = 1000,
  na.action = stats::na.omit,
  ...
)
}
\arguments{
\item{y}{the dependent variable (N*J). Can be a matrix or a named data frame.
The first column of the matrix is automatically treated as the baseline.}

\item{X}{independent variable (N*K). Can be a matrix or a named data frame.
If there is no intercept term in the X, then an intercept term is
automatically added.}

\item{beta0}{Initial value for beta used in optimisation. Uses a 1*K(J-1)
vector. Default to a vector of zeros.}

\item{MLEmethod}{Method of optimisation. Goes into
\code{maxLik(method=MLEmethod))}. Choose from "NR","BFGS","CG","BHHH","SANN",or "NM".  
Default to "CG", the conjugate gradients method. See Details.}

\item{maxit}{Maximum number of iterations.}

\item{abstol}{Tolerance.}

\item{cluster}{A vector of clusters to be used for clustered standard error computation. 
Default to NULL, no cluster computed.}

\item{reps}{Number of bootstrap replications to be computed for clustered standard errors.}

\item{na.action}{A function specifying how to handle missing values, default is \code{stats::na.omit}. If \code{NULL}, no action is taken.}

\item{...}{additional parameters that go into \code{maxLik()}}
}
\value{
The function returns an object of class "fracregmlogit". Use \code{fracregmlogit.pe}, \code{predict}, 
 \code{residuals}, \code{fitted} to extract various useful features of the value returned by 
\code{fracregmlogit}.

An object of class "fracregmlogit" contains the following components:

\code{estimates}   A list of matrices containing parameter estimates,
  standard errors, and hypothesis testing results.

\code{baseline}    The baseline choice

\code{likelihood}  The likelihood value

\code{conv_code}   Convergence diagnostics code.

\code{convergence} Convergence messages.

\code{count}       Provides dataset information

\code{y}           The dependent variable data frame.

\code{X}           The independent variable data frame. Augmented by factor dummy transformation
, constant term added.

\code{rowNo}       A vector of row numbers from the original X and y that is used for estimation.

\code{coefficient} Matrix of estimated coefficients. Augmented with the baseline coefficient
(which is a vector of zeros).

\code{vcov}        A list of matrices containing the robust variance covariance matrix for each choice
variable.

\code{cluster}     The vector of clusters.

\code{reps}        Number of bootstrap replications for clustered standard error
}
\description{
Used to estimate fractional multinomial logit models using quasi-maximum
likelihood estimation following Papke and Wooldridge (1996).
}
\details{
The fractional multinomial logit model is the expansion of the multinomial
logit to fractional responses. Unlike standard multinomial logit models,
which only consider 0-1 responses, the fractional multinomial logit model considers the
case where the response variable is fractions that sum up to one. Examples
of this type of data include percentages of budget spent in education, defence,
public health; fractions of a population that have middle school, high
school, college, or post-college education, etc.

This function follows Papke and Wooldridge (1996)'s paper, in which they
proposed a quasi-maximum likelihood estimator for fractional response data.
The likelihood function used here is a standard multinomial likelihood
function, see Buis (2008) and <http://maartenbuis.nl/software/likelihoodFmlogit.pdf> for
the likelihood used here. Robust standard errors are provided following Papke
and Wooldridge (1996), in which they proposed an asymptotically consistent
estimator of variance.

Maximisation is done by calling \code{\link[maxLik]{maxLik}}. maxLik is a wrapper function 
for different maximisation methods in R. These include most methods provided by \code{\link[maxLik]{maxLik}},  
but also other methods such as BHHH (Berndt-Hall-Hall-Hausman). 

MLE convergence can be a problem in R, especially if the dataset is large with many explanatory variables. 
It is recommended to call CG (Conjugate Gradients) or BHHH (Berndt-Hall-Hall-Hausman).
The conjugate gradients method is usually faster, but could lead to non-convergence under 
certain scenarios. BHHH is slower, but has better convergence properties.
}
\examples{
data("fracreg_spending")
X = fracreg_spending[,2:5]
y = fracreg_spending[,6:11]

# Fit the fractional multinomial logit model
results1 = fracregmlogit(y, X)

# View estimates
summary(results1)

# Compute marginal effects
pe = fracregmlogit.pe(results1, effect="marginal", marg.type="aveacr", se=TRUE, R=50)
summary(pe)

# Plot effects for 'houseval'
plot(pe, varlist="houseval")

}
\references{
Papke, L. E. and Wooldridge, J. M. (1996), Econometric methods
  for fractional response variables with an application to 401(k) plan
  participation rates. J. Appl. Econ., 11: 619-632.

Buis, M. L. (2008), fmlogit: Stata module fitting a fractional 
  multinomial logit model by quasi maximum likelihood. Statistical Software Components, 
  Boston College Department of Economics.

Mullahy, J. (2015), Multivariate fractional regression estimation of 
  econometric share models. Journal of Econometric Methods, 4(1): 71-100.

Murteira, J. M. R., and Ramalho, J. J. S. (2016), Regression analysis of 
  multivariate fractional data. Econometric Reviews, 35(4): 515-552.

Ji, J., and Woodill, A. J., fmlogit: Fractional Multinomial Logit. R package repository. <https://github.com/f1kidd/fmlogit>.
}
\seealso{
\code{\link{fracregmlogit.pe}} for computing partial effects, \code{\link{plot.fracregmlogit.pe}} for plotting effects, \code{\link{fitted.fracregmlogit}} for residuals and predictions.
}
