% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lm-fit.R
\name{ml_lm}
\alias{ml_lm}
\title{Fit linear model by Maximum Likelihood}
\usage{
ml_lm(
  value,
  scale = NULL,
  weights = NULL,
  data,
  subset = NULL,
  noint_value = FALSE,
  noint_scale = FALSE,
  constraints = NULL,
  start = NULL,
  method = "NR",
  control = NULL,
  ...
)
}
\arguments{
\item{value}{Formula for the conditional mean (value) equation.}

\item{scale}{Formula for log(sigma) (optional). If \code{NULL}, a homoskedastic
model is fitted.}

\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{noint_scale}{Logical. Should the scale 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_lm} that extends \code{mlmodel}.
}
\description{
Fit linear 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 or scale equations. Use the dedicated
arguments \code{noint_value} and \code{noint_scale} instead.

Coefficient names in the fitted object use the prefixes \verb{value::} and
\verb{scale::} to clearly identify to which equation each coefficient belongs to,
and to avoid confusion when the same variable(s) appear(s) in both the value
and scale equations.

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_lm} automatically chooses the optimizer:
\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 linear model
data(mroz)
fit_lin <- ml_lm(faminc ~ age + I(age^2) + huswage + educ + unem, 
                 data = mroz)
summary(fit_lin, vcov.type = "robust")

# Heteroskedastic linear model
fit_het <- ml_lm(faminc ~ age + I(age^2) + huswage + educ + unem,
                 scale = ~ educ + exper,
                 data = mroz)
summary(fit_het, vcov.type = "robust")

# Lognormal (log-linear) model
fit_log <- ml_lm(log(faminc) ~ age + I(age^2) + huswage + educ + unem,
                 data = mroz)
summary(fit_log, vcov.type = "robust")

# Different predict types
head(predict(fit_log, type = "response")$fit)      # Expected value E[y]
head(predict(fit_log, type = "median")$fit)        # Median of y
head(predict(fit_log, type = "variance_y")$fit)    # Variance of y
head(predict(fit_log, type = "var")$fit)           # Variance of log(y)

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

}
\author{
Alfonso Sanchez-Penalver
}
