% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/logit-fit.R
\name{ml_logit}
\alias{ml_logit}
\title{Fit Binary Logit Model by Maximum Likelihood}
\usage{
ml_logit(
  value,
  scale = NULL,
  weights = NULL,
  data,
  subset = NULL,
  noint_value = FALSE,
  constraints = NULL,
  start = NULL,
  method = "NR",
  control = NULL,
  ...
)
}
\arguments{
\item{value}{Two-sided formula for the probability equation.}

\item{scale}{Optional one-sided formula for heteroskedasticity.}

\item{weights}{Optional weights variable. It can be either the name of the
variable in \code{data}, or a vector with the weights.}

\item{data}{Data frame.}

\item{subset}{Optional subset expression. Only observations for which this
expression evaluates to \code{TRUE} are used in the estimation. This can be
a logical vector or an expression (e.g. \code{subset = age > 30}).}

\item{noint_value}{Logical. Should the value equation omit the intercept?
Default is \code{FALSE}.}

\item{constraints}{Optional constraints on the parameters. Can be a character
vector of string constraints, a named list of string constraints, or a raw
maxLik constraints list. See \strong{Details}.}

\item{start}{Numeric vector of starting values for the coefficients. Required
if constraints are being supplied. If supplied without constraints they
will be ignored. See \strong{Details}.}

\item{method}{A string with the method used for optimization. See
\link[maxLik:maxLik]{maxLik} for options, and see \strong{Details}.}

\item{control}{A list of control parameters passed to \link[maxLik:maxLik]{maxLik}.
If \code{NULL} (default), a sensible set of options is chosen automatically
depending on whether constraints are used. See \link[maxLik:maxControl]{maxControl}.}

\item{...}{Additional arguments passed to \link[maxLik:maxLik]{maxLik}.}
}
\value{
An object of class \code{ml_logit} that extends \code{mlmodel}.
}
\description{
Fit Binary Logit Model by Maximum Likelihood
}
\details{
\strong{Important:} Do not use the usual R syntax to remove the intercept in the
formula (\code{- 1} or \code{+ 0}) for the value equation. Use the dedicated argument
\code{noint_value} instead. For the scale equation (if modeling heteroskedasticity),
the formula must contain only the predictors (right-hand side).

\code{ml_logit()} handles both strictly binary (\code{0/1}), and fractional response
(\code{0 <= y <= 1}) outcomes. When using fractional responses, it is recommended
to use robust standard errors (\code{vcov.type = "robust"}).

Coefficient names in the fitted object use the prefixes \verb{value::} and
\verb{scale::} (when heteroskedasticity is modeled) to clearly identify which
equation each coefficient belongs to.

Either inequality or equality linear constraints are accepted, but not both.
A constraint cannot have a linear combination of more than two coefficients.

\strong{Important}: When \code{constraints} are supplied, \code{start} cannot be \code{NULL}.
You \strong{must} provide initial values that yield a feasible log-likelihood.
If no constraints are used, any supplied \code{start} is ignored.

When constraints are used, \code{ml_logit} automatically chooses \code{method}:
\itemize{
\item Equality constraints => Nelder-Mead (\code{"NM"})
\item Inequality constraints => BFGS (\code{"BFGS"})
}

In these cases your supplied \code{method} argument (if any) is ignored.
}
\examples{

# Homoskedastic binary logit model
data(smoke)
smoke$smokes <- smoke$cigs > 0

fit_logit <- ml_logit(smokes ~ cigpric + income + age, 
                      data = smoke)

summary(fit_logit, vcov.type = "robust")

# Heteroskedastic binary logit model
fit_logit_het <- ml_logit(smokes ~ cigpric + income + age,
                          scale = ~ educ,
                          data = smoke)

summary(fit_logit_het, vcov.type = "robust")

# Different predict types
head(predict(fit_logit, type = "response")$fit)   # Predicted probability
head(predict(fit_logit, type = "link")$fit)       # Linear predictor (log-odds)

# Fitted values and residuals
head(fitted(fit_logit))
head(residuals(fit_logit))
head(residuals(fit_logit, type = "pearson"))

}
\seealso{
\link{ml_probit} \link{ml_beta}
}
\author{
Alfonso Sanchez-Penalver
}
