% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/RSQ.R
\name{RSQ}
\alias{RSQ}
\alias{RSQ.nestedLogit}
\alias{print.RSQ.nestedLogit}
\alias{RSQ.multinom}
\alias{print.RSQ.multinom}
\alias{RSQ.polr}
\alias{print.RSQ.polr}
\title{Pseudo-R² Measures for Nested Logit and Related Models}
\usage{
RSQ(x, ...)

\method{RSQ}{nestedLogit}(
  x,
  which = c("McFadden", "CoxSnell", "Nagelkerke"),
  include = "AIC",
  digits = 3L,
  ...
)

\method{print}{RSQ.nestedLogit}(x, digits = attr(x, "digits"), ...)

\method{RSQ}{multinom}(
  x,
  which = c("McFadden", "CoxSnell", "Nagelkerke"),
  include = "AIC",
  digits = 3L,
  ...
)

\method{print}{RSQ.multinom}(x, digits = attr(x, "digits"), ...)

\method{RSQ}{polr}(
  x,
  which = c("McFadden", "CoxSnell", "Nagelkerke"),
  include = "AIC",
  digits = 3L,
  ...
)

\method{print}{RSQ.polr}(x, digits = attr(x, "digits"), ...)
}
\arguments{
\item{x}{a \code{"nestedLogit"} object.}

\item{...}{currently unused.}

\item{which}{character vector naming the pseudo-R² measures to compute.
Any subset of \code{c("McFadden", "McFaddenAdj", "CoxSnell", "Nagelkerke", "Tjur")},
or \code{"ALL"} to include all of them.
Default: \code{c("McFadden", "CoxSnell", "Nagelkerke")}.}

\item{include}{character vector of additional columns to append to the result.
Any subset of \code{c("AIC", "BIC", "n")}, where \code{"n"} adds the
number of observations used for each row, or \code{"ALL"} to include all of them.
Default: \code{"AIC"}.}

\item{digits}{integer; number of decimal places used when printing
(default \code{3L}).}
}
\value{
An object of class \code{c("RSQ.nestedLogit", "data.frame")} with one
row per dichotomy plus a final \code{"Combined"} row, and columns
\code{response} (the sub-model name), the requested pseudo-R² measures,
and any additional statistics requested via \code{include}.
The \code{formula}, object name, and \code{digits} are stored as attributes
and used by the \code{print} method.
}
\description{
Computes pseudo-R² and related fit measures for a \code{"nestedLogit"} object
and related models for a polytomous response. For the \code{"nestedLogit"} case,
the result shows
one row per binary logit sub-model (dichotomy) and an additional
\code{"Combined"} row for the overall polytomous model.
}
\details{
\code{RSQ} is implemented as an S3 generic with methods for \code{"nestedLogit"}, as well as
\code{nnet::multinom()}, and \code{MASS::polr()} objects, which are other methods for
modeling a polytomous response variable.

In contrast to standard, Gaussian linear models, where \eqn{R^2} has a uniformly simple interpretation as
"variance accounted for" by the model, and with different, yet \emph{equivalent} computational formulas,
there is no single commonly accepted measure for logistic regression models for a binary response or
a dichotomy among outcomes.

The following measures are available via the \code{which} argument:
\describe{
\item{\code{"McFadden"}}{1 - L/L\eqn{_0}, where L is the fitted model
log-likelihood and L\eqn{_0} that of the null (intercept-only) model
(McFadden, 1979).  Values of 0.1--0.3 indicate a reasonable fit in
logistic regression.}
\item{\code{"McFaddenAdj"}}{1 - (L - k)/L\eqn{_0}, where k is the number
of non-intercept parameters; penalises model complexity (Hosmer &
Lemeshow, 2000).}
\item{\code{"CoxSnell"}}{1 - exp(2(L\eqn{_0} - L)/n); bounded strictly
below 1 for discrete outcomes (Cox & Snell, 1989).}
\item{\code{"Nagelkerke"}}{Cox-Snell divided by its theoretical maximum,
rescaling to [0, \1] (Nagelkerke, 1991).}
\item{\code{"Tjur"}}{Mean fitted value for \eqn{y = 1} minus mean fitted
value for \eqn{y = 0}; the coefficient of discrimination (Tjur, 2009).
Per-dichotomy only (\code{NA} in the Combined row).}
}

For the \strong{Combined} row the log-likelihood is the sum of the sub-model
log-likelihoods (exploiting the independence of the nested dichotomies), and
\eqn{n} is \code{nrow(x$data)} --- the full sample size of the polytomous model ---
not the sum of per-dichotomy observation counts, which would double-count
observations that appear in more than one sub-model.

A wider range of pseudo-R² measures for logistic-type models (\code{glm},
\code{polr}, \code{multinom}, \code{vglm}) is available in
\code{\link[DescTools:PseudoR2]{DescTools::PseudoR2()}}, including the Efron (1978) and
McKelvey & Zavoina (1975) measures not implemented here.
For an accessible overview see \url{https://statisticalhorizons.com/r2logistic/}.
}
\examples{
data("Womenlf", package = "carData")
wlf.nested <- nestedLogit(partic ~ hincome + children,
  logits(work = dichotomy("not.work", c("parttime", "fulltime")),
         full = dichotomy("parttime", "fulltime")),
  data = Womenlf)

# Default: McFadden, CoxSnell, Nagelkerke + AIC
RSQ(wlf.nested)

# All measures and all extra columns
RSQ(wlf.nested, which = "ALL", include = "ALL")

# Multinomial logit for comparison
if (requireNamespace("nnet", quietly = TRUE)) {
  wlf.multi <- nnet::multinom(partic ~ hincome + children, data = Womenlf,
                              trace = FALSE)
  RSQ(wlf.multi)
}

# Proportional-odds model for comparison
if (requireNamespace("MASS", quietly = TRUE)) {
  wlf.polr <- MASS::polr(partic ~ hincome + children, data = Womenlf)
  RSQ(wlf.polr)
}

}
\references{
Cox, D. R., & Snell, E. J. (1989). \emph{The Analysis of Binary Data} (2nd ed.).
Chapman and Hall.

Efron, B. (1978). Regression and ANOVA with zero-one data: Measures of
residual variation. \emph{Journal of the American Statistical Association},
\emph{73}(361), 113--121. \doi{10.2307/2286498}

Hosmer, D. W., & Lemeshow, S. (2000). \emph{Applied Logistic Regression}
(2nd ed.). Wiley. \doi{10.1002/0471722146}

McFadden, D. (1979). Quantitative methods for analysing travel behaviour of
individuals: Some recent developments. In D. A. Hensher & P. R. Stopher
(Eds.), \emph{Behavioural Travel Modelling} (pp. 279--318). Croom Helm.

McKelvey, R. D., & Zavoina, W. (1975). A statistical model for the analysis
of ordinal level dependent variables. \emph{Journal of Mathematical Sociology},
\emph{4}(1), 103--120. \doi{10.1080/0022250X.1975.9989847}

Nagelkerke, N. J. D. (1991). A note on a general definition of the
coefficient of determination. \emph{Biometrika}, \emph{78}(3), 691--692.
\doi{10.1093/biomet/78.3.691}

Tjur, T. (2009). Coefficients of determination in logistic regression
models --- a new proposal: The coefficient of discrimination.
\emph{The American Statistician}, \emph{63}(4), 366--372.
\doi{10.1198/tast.2009.08210}
}
\seealso{
\code{\link[=nestedLogit]{nestedLogit()}}, \code{\link[broom:glance]{broom::glance()}},
\code{\link[DescTools:PseudoR2]{DescTools::PseudoR2()}},
\code{\link[nnet:multinom]{nnet::multinom()}}, \code{\link[MASS:polr]{MASS::polr()}}
}
\author{
Michael Friendly
}
