% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/beta-postestimation.R,
%   R/gamma-postestimation.R, R/lm-postestimation.R, R/logit-postestimation.R,
%   R/mlmodel-utils.R, R/negbin-postestimation.R, R/poisson-postestimation.R,
%   R/probit-postestimation.R
\name{predict.ml_beta}
\alias{predict.ml_beta}
\alias{predict.ml_gamma}
\alias{predict.ml_lm}
\alias{predict.ml_logit}
\alias{predict.mlmodel}
\alias{predict.ml_negbin}
\alias{predict.ml_poisson}
\alias{predict.ml_probit}
\title{Predictions for mlmodel models}
\usage{
\method{predict}{ml_beta}(
  object,
  newdata = NULL,
  type = "response",
  se.fit = FALSE,
  vcov = NULL,
  vcov.type = "oim",
  cl_var = NULL,
  repetitions = 999,
  seed = NULL,
  progress = FALSE,
  ...
)

\method{predict}{ml_gamma}(
  object,
  newdata = NULL,
  type = "response",
  se.fit = FALSE,
  vcov = NULL,
  vcov.type = "oim",
  cl_var = NULL,
  repetitions = 999,
  seed = NULL,
  progress = FALSE,
  ...
)

\method{predict}{ml_lm}(
  object,
  newdata = NULL,
  type = "response",
  se.fit = FALSE,
  vcov = NULL,
  vcov.type = "oim",
  cl_var = NULL,
  repetitions = 999,
  seed = NULL,
  progress = FALSE,
  ...
)

\method{predict}{ml_logit}(
  object,
  newdata = NULL,
  type = "response",
  se.fit = FALSE,
  vcov = NULL,
  vcov.type = "oim",
  cl_var = NULL,
  repetitions = 999,
  seed = NULL,
  progress = FALSE,
  ...
)

\method{predict}{mlmodel}(object, ...)

\method{predict}{ml_negbin}(
  object,
  newdata = NULL,
  type = "response",
  se.fit = FALSE,
  vcov = NULL,
  vcov.type = "oim",
  cl_var = NULL,
  repetitions = 999,
  seed = NULL,
  progress = FALSE,
  ...
)

\method{predict}{ml_poisson}(
  object,
  newdata = NULL,
  type = "response",
  se.fit = FALSE,
  vcov = NULL,
  vcov.type = "oim",
  cl_var = NULL,
  repetitions = 999,
  seed = NULL,
  progress = FALSE,
  ...
)

\method{predict}{ml_probit}(
  object,
  newdata = NULL,
  type = "response",
  se.fit = FALSE,
  vcov = NULL,
  vcov.type = "oim",
  cl_var = NULL,
  repetitions = 999,
  seed = NULL,
  progress = FALSE,
  ...
)
}
\arguments{
\item{object}{An object from an estimation with one of our models.}

\item{newdata}{Optional data frame for out-of-sample predictions.}

\item{type}{Character string indicating what to predict. See \strong{Details}.}

\item{se.fit}{Logical. If \code{TRUE}, also return standard errors (delta method).}

\item{vcov}{Optional user-supplied variance-covariance matrix.}

\item{vcov.type}{Type of variance-covariance matrix. See \link[=vcov.mlmodel]{vcov}.}

\item{cl_var}{Clustering variable (name or vector).}

\item{repetitions}{Number of bootstrap replications when \code{vcov.type = "boot"}.}

\item{seed}{Random seed for bootstrapping, for reproducibility.}

\item{progress}{Logical. Show bootstrap/jackknife progress bar? Default is
\code{FALSE} in higher-level functions.}

\item{...}{Additional arguments passed to methods.}
}
\value{
An object that inherits from \code{predict.mlmodel} and has two elements:
\describe{
\item{fit}{Vector with the predictions.}
\item{se.fit}{If \code{se.fit} is \code{TRUE} a vector with the delta-method standard
errors, using analytical gradients. If \code{se.fit} is \code{FALSE}, it is set to
\code{NULL}.}
}
}
\description{
Methods for computing predictions from models fitted with the
\code{mlmodels} package.
}
\details{
\subsection{ml_beta prediction types}{

The \code{type} argument controls what quantity is returned.\tabular{lll}{
   Type \tab Description \tab Notes \cr
   \code{"link"} \tab Linear mean predictor ( xb ) \tab logit-mean \cr
   \code{"response"} \tab Expected proportion (outcome) \tab Default \cr
   \code{"mean"} \tab Alias for \code{"response"} \tab - \cr
   \code{"fitted"} \tab Alias for \code{"response"} \tab - \cr
   \code{"odds"} \tab Odds ratio \tab exp(xb) \cr
   \code{"zd"} \tab Linear precision predictor \tab log-phi \cr
   \code{"phi"} \tab Dispersion parameter \tab - \cr
   \code{"shape1"} \tab Shape parameter of the beta distribution \tab mu * phi \cr
   \code{"shape2"} \tab Shape parameter of the beta distribution \tab (1 - mu) * phi \cr
   \code{"mode"} \tab Mode prediction (See below) \tab (shape1 - 1) / (shape1 + shape2 - 2) \cr
   \code{"variance"} \tab Variance of the outcome variable \tab mu * (1 - mu) / (1 + phi) \cr
   \code{"var"} \tab Alias for \code{"variance"} \tab - \cr
   \code{"sigma"} \tab Standard deviation of outcome variable \tab sqrt(\code{"variance"}) \cr
   \code{"sd"} \tab Alias for \code{"sigma"} \tab - \cr
}


When \code{se.fit = TRUE}, standard errors are computed using the delta method
for all supported types.

\strong{Mode Indeterminations}

The mode is only defined if \code{shape1 > 1} \strong{and} \code{shape2 > 1} \strong{and} \code{shape1 + shape2 != 2}. If these conditions are not met the prediction and standard
error will be \code{NA}.
}

\subsection{ml_gamma prediction types}{

The \code{type} argument controls what quantity is returned.\tabular{lll}{
   Type \tab Description \tab Notes \cr
   \code{"link"} \tab Linear mean predictor ( xb ) \tab log-mean \cr
   \code{"response"} \tab Expected outcome \tab Default \cr
   \code{"mean"} \tab Alias for \code{"response"} \tab - \cr
   \code{"fitted"} \tab Alias for \code{"response"} \tab - \cr
   \code{"zd"} \tab Linear shape predictor \tab log-nu \cr
   \code{"nu"} \tab Shape parameter \tab - \cr
   \code{"variance"} \tab Variance of the outcome variable \tab - \cr
   \code{"var"} \tab Alias for \code{"variance"} \tab - \cr
   \code{"sigma"} \tab Standard deviation of outcome variable \tab sqrt(\code{"variance"}) \cr
   \code{"sd"} \tab Alias for \code{"sigma"} \tab - \cr
}


When \code{se.fit = TRUE}, standard errors are computed using the delta method
for all supported types.
}

\subsection{ml_lm prediction types}{

The \code{type} argument controls what quantity is returned. Behavior differs
depending on whether the outcome was modeled in logs (\code{log(y)}).\tabular{llll}{
   Type \tab Normal (linear) case \tab Lognormal case (\code{log(y)}) \tab Notes \cr
   \code{link} \tab Linear predictor for scale (zd) \tab Linear predictor on log scale (mu-log) \tab Scale equation \cr
   \code{fitted} \tab xb (mean predictor) \tab xb (original log-scale predictor) \tab Mean equation \cr
   \code{response}, \code{mean}, \code{mu} \tab xb (E\code{[y]}) \tab E\code{[y]} = exp(mu-log + sigma^2/2) - shift \tab Proper expected value on original scale \cr
   \code{median} \tab xb (same as mean) \tab exp(mu-log) - shift \tab Median of y \cr
   \code{sigma}, \code{sd} \tab sd of y \tab sd of \code{log(y)} \tab On log scale \cr
   \code{sigma_y}, \code{sd_y} \tab same as \code{sigma} \tab sd of y \tab Only meaningful in lognormal case \cr
   \code{variance}, \code{var} \tab sigma^2 \tab sigma^2 (variance of \code{log(y)}) \tab On log scale \cr
   \code{variance_y}, \code{var_y} \tab same as \code{variance} \tab Var(y) = exp(2 mu-log + sigma^2)(exp(sigma^2) - 1) \tab Only meaningful in lognormal case \cr
   \code{zd} \tab Linear predictor for scale (zd) \tab Linear predictor for scale (zd) \tab Alias for \code{link} \cr
}


When the outcome is log-transformed, \code{response} (or \code{mean}) returns the
correct lognormal expected value on the original scale of y. The \code{median}
is the simple exponential back-transform.
}

\subsection{ml_logit prediction types}{

The \code{type} argument controls what quantity is returned. Behavior differs
depending on whether the model is homoskedastic or heteroskedastic.\tabular{llll}{
   Type \tab Homoskedastic case \tab Heteroskedastic case \tab Notes \cr
   \code{"xb"} \tab Linear predictor xb \tab Linear predictor xb \tab Linear predictor for value \cr
   \code{"response"} \tab P(y=1 | x) \tab P(y=1 | x) \tab Prob. of success (default) \cr
   \code{"prob"} \tab Alias for \code{"response"} \tab Alias for \code{"response"} \tab - \cr
   \code{"fitted"} \tab Alias for \code{"response"} \tab Alias for \code{"response"} \tab - \cr
   \code{"prob0"} \tab P(y=0 | x) \tab P(y=0 | x) \tab Prob. of failure \cr
   \code{"link"} \tab Linear predictor xb \tab xb / exp(zd) \tab Log-odds \cr
   \code{"odds"} \tab Odds = exp(xb) \tab Odds = exp(xb / exp(zd)) \tab - \cr
   \code{"sigma"} \tab 1 (constant) \tab Std. Deviation: exp(zd) \tab Only available if heteroskedastic \cr
   \code{"variance"} \tab 1 (constant) \tab Variance: exp(2*zd) \tab Only available if heteroskedastic \cr
   \code{"zd"} \tab 0 (constant) \tab Linear predictor zd \tab Linear predictor for scale \cr
}


In binary logit models, the \strong{overall scale} of the latent error term is
not identified and is normalized to 1. In the homoskedastic case there is
no scale equation, so sigma is fixed at 1. In the heteroskedastic case,
the scale equation has no intercept. Therefore, the predicted \code{"sigma"}
and \code{"variance"} represent \strong{individual-level deviations} from the
normalized overall scale, not the absolute standard deviation or variance.

When \code{se.fit = TRUE}, standard errors are computed using the delta method.
Standard errors are not available (and will return \code{NA}) for \code{"sigma"},
\code{"variance"}, and \code{"zd"} in homoskedastic models.
}

\subsection{ml_negbin prediction types}{

The \code{type} argument controls what quantity is returned. In addition to
standard types, Negative Binomial models support flexible probability requests
using the \code{P(...)} syntax.\tabular{lll}{
   Type \tab Description \tab Notes \cr
   \code{"link"} \tab Linear mean predictor ( xb ) \tab log-mean \cr
   \code{"response"} \tab Expected count ( \code{mu} = \code{exp(xb)} ) \tab Default \cr
   \code{"mean"} \tab Alias for \code{"response"} \tab - \cr
   \code{"fitted"} \tab Alias for \code{"response"} \tab - \cr
   \code{"zd"} \tab Linear dispersion predictor \tab log-alpha \cr
   \code{"alpha"} \tab Dispersion parameter \tab - \cr
   \code{"variance"} \tab Variance of the outcome variable \tab - \cr
   \code{"var"} \tab Alias for \code{"variance"} \tab - \cr
   \code{"sigma"} \tab Standard deviation of outcome variable \tab sqrt(\code{"variance"}) \cr
   \code{"sd"} \tab Alias for \code{"sigma"} \tab - \cr
   \code{P(k)} \tab P(Y = k) \tab Exact probability, k integer >= 0 \cr
   \code{P(,k)} \tab P(Y <= k) \tab Cumulative (lower tail) \cr
   \code{P(k,)} \tab P(Y >= k) \tab Survival (upper tail) \cr
   \code{P(a,b)} \tab P(a <= Y <= b) \tab Interval probability, a <= b, a >= 0 \cr
}


When \code{se.fit = TRUE}, standard errors are computed using the delta method
for all supported types.
}

\subsection{ml_poisson prediction types}{

The \code{type} argument controls what quantity is returned. In addition to
standard types, Poisson models support flexible probability requests
using the \code{P(...)} syntax.\tabular{lll}{
   Type \tab Description \tab Notes \cr
   \code{"link"} \tab Linear predictor ( xb ) \tab log-mean \cr
   \code{"response"} \tab Expected count ( \code{mu} = \code{exp(xb)} ) \tab Default \cr
   \code{"mean"} \tab Alias for \code{"response"} \tab - \cr
   \code{"mu"} \tab Alias for \code{"response"} \tab - \cr
   \code{"fitted"} \tab Alias for \code{"response"} \tab - \cr
   \code{P(k)} \tab P(Y = k) \tab Exact probability, k integer >= 0 \cr
   \code{P(,k)} \tab P(Y <= k) \tab Cumulative (lower tail) \cr
   \code{P(k,)} \tab P(Y >= k) \tab Survival (upper tail) \cr
   \code{P(a,b)} \tab P(a <= Y <= b) \tab Interval probability, a <= b, a >= 0 \cr
}


When \code{se.fit = TRUE}, standard errors are computed using the delta method
for all supported types.
}

\subsection{ml_probit prediction types}{

The \code{type} argument controls what quantity is returned. Behavior differs
depending on whether the model is homoskedastic or heteroskedastic.\tabular{llll}{
   Type \tab Homoskedastic case \tab Heteroskedastic case \tab Notes \cr
   \code{"xb"} \tab Linear predictor xb \tab Linear predictor xb \tab Linear predictor for value \cr
   \code{"response"} \tab P(y=1 | x) \tab P(y=1 | x) \tab Prob. of success (default) \cr
   \code{"prob"} \tab Alias for \code{"response"} \tab Alias for \code{"response"} \tab - \cr
   \code{"fitted"} \tab Alias for \code{"response"} \tab Alias for \code{"response"} \tab - \cr
   \code{"prob0"} \tab P(y=0 | x) \tab P(y=0 | x) \tab Prob. of failure \cr
   \code{"link"} \tab Linear predictor xb \tab xb / exp(zd) \tab Probit index \cr
   \code{"odds"} \tab Odds = prob / prob0 \tab Odds = prob / prob0. \tab - \cr
   \code{"sigma"} \tab 1 (constant) \tab Std. Deviation: exp(zd) \tab Only available if heteroskedastic \cr
   \code{"variance"} \tab 1 (constant) \tab Variance: exp(2*zd) \tab Only available if heteroskedastic \cr
   \code{"zd"} \tab 0 (constant) \tab Linear predictor zd \tab Linear predictor for scale \cr
}


In binary probit models, the \strong{overall scale} of the latent error term is
not identified and is normalized to 1. In the homoskedastic case there is
no scale equation, so sigma is fixed at 1. In the heteroskedastic case,
the scale equation has no intercept. Therefore, the predicted \code{"sigma"}
and \code{"variance"} represent \strong{individual-level deviations} from the
normalized overall scale, not the absolute standard deviation or variance.

The \code{"link"} type returns the value on the \strong{probit scale}, which is the
inverse of the standard normal cumulative distribution function
(p = Phi^(-1)(p)). This is the linear prediction (p = xb) ih homoskedastic models,
and the standardized linear predictor (p = xb / sigma) in heteroskedastic models.

When \code{se.fit = TRUE}, standard errors are computed using the delta method.
Standard errors are not available (and will return \code{NA}) for \code{"sigma"},
\code{"variance"}, and \code{"zd"} in homoskedastic models.
}
}
\examples{

# Basic usage and different predict types
data(docvis)
fit_pois <- ml_poisson(docvis ~ age + educyr + totchr, data = docvis)

head(predict(fit_pois, type = "response")$fit)     # Expected count
head(predict(fit_pois, type = "P(3)")$fit)         # Prob of exactly 3

# Prediction at the mean (typical case)
typical <- data.frame(age = mean(docvis$age), 
                      educyr = mean(docvis$educyr), 
                      totchr = mean(docvis$totchr))
predict(fit_pois, newdata = typical, type = "response")

# In-sample vs full-data prediction with subset / boundary dropping
data(pw401k)
fit_beta <- ml_beta(prate ~ mrate + I(mrate^2) + log(totemp) + 
                    I(log(totemp)^2) + age + I(age^2) + sole,
                    data = pw401k, 
                    subset = prate < 1)

# In-sample prediction (NAs for dropped observations)
head(predict(fit_beta, type = "response")$fit)

# Full-data prediction (predicts for all rows, including dropped ones)
head(predict(fit_beta, newdata = pw401k, type = "response")$fit)

}
\author{
Alfonso Sanchez-Penalver
}
