From 83941fe1eeea9748042d9bdc26b5aba734df5f4c Mon Sep 17 00:00:00 2001 From: Daniel Date: Fri, 14 Jun 2024 15:04:29 +0200 Subject: [PATCH] docs --- DESCRIPTION | 2 +- R/icc.R | 4 +++- R/r2_nakagawa.R | 26 ++++++++++++++++++++++++++ man/icc.Rd | 32 +++++++++++++++++++++++++++++++- man/r2_nakagawa.Rd | 30 ++++++++++++++++++++++++++++++ 5 files changed, 91 insertions(+), 3 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index d88d13cbe..b15bdafd1 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -154,4 +154,4 @@ Config/Needs/website: r-lib/pkgdown, easystats/easystatstemplate Config/rcmdcheck/ignore-inconsequential-notes: true -Remotes: easystats/insight \ No newline at end of file +Remotes: easystats/insight diff --git a/R/icc.R b/R/icc.R index cac926505..bb5d228a6 100644 --- a/R/icc.R +++ b/R/icc.R @@ -3,7 +3,7 @@ #' This function calculates the intraclass-correlation coefficient (ICC) - #' sometimes also called *variance partition coefficient* (VPC) or #' *repeatability* - for mixed effects models. The ICC can be calculated for all -#' models supported by `insight::get_variance()`. For models fitted with the +#' models supported by [`insight::get_variance()`]. For models fitted with the #' **brms**-package, `icc()` might fail due to the large variety of #' models and families supported by the **brms**-package. In such cases, an #' alternative to the ICC is the `variance_decomposition()`, which is based @@ -63,6 +63,8 @@ #' applications and data analysis methods (2nd ed). Thousand Oaks: Sage #' Publications. #' +#' @inheritSection r2_nakagawa Supported models and model families +#' #' @details #' ## Interpretation #' The ICC can be interpreted as "the proportion of the variance explained by diff --git a/R/r2_nakagawa.R b/R/r2_nakagawa.R index c15a1639f..ecc04ac04 100644 --- a/R/r2_nakagawa.R +++ b/R/r2_nakagawa.R @@ -18,6 +18,32 @@ #' #' @return A list with the conditional and marginal R2 values. #' +#' @section Supported models and model families: +#' The single variance components that are required to calculate the marginal +#' and conditional r-squared values are calculated using the [`insight::get_variance()`] +#' function. The results are validated against the solutions provided by +#' _Nakagawa et al. (2017)_, in particular examples shown in the Supplement 2 +#' of the paper. Other model families are validated against results from the +#' **MuMIn*+ package. This means that the r-squared values returned by `r2_nakagawa()` +#' should be accurate and reliable for following mixed models or model families: +#' +#' - Bernoulli (logistic) regression +#' - Binomial regression (with other than binary outcomes) +#' - Poisson and Quasi-Poisson regression +#' - Negative binomial regression (including nbinom1 and nbinom2 families) +#' - Gaussian regression (linear models) +#' - Gamma regression +#' - Tweedie regression +#' - Beta regression +#' - Ordered beta regression +#' +#' Following model families are not yet validated, but should work: +#' +#' - Zero-inflated and hurdle models +#' - Beta-binomial regression +#' - Compound Poisson regression +#' - Generalized Poisson regression +#' #' @details #' Marginal and conditional r-squared values for mixed models are calculated #' based on _Nakagawa et al. (2017)_. For more details on the computation of diff --git a/man/icc.Rd b/man/icc.Rd index 70ba589fd..b352e9440 100644 --- a/man/icc.Rd +++ b/man/icc.Rd @@ -85,7 +85,7 @@ ICC as well as the credible intervals for this ICC. This function calculates the intraclass-correlation coefficient (ICC) - sometimes also called \emph{variance partition coefficient} (VPC) or \emph{repeatability} - for mixed effects models. The ICC can be calculated for all -models supported by \code{insight::get_variance()}. For models fitted with the +models supported by \code{\link[insight:get_variance]{insight::get_variance()}}. For models fitted with the \strong{brms}-package, \code{icc()} might fail due to the large variety of models and families supported by the \strong{brms}-package. In such cases, an alternative to the ICC is the \code{variance_decomposition()}, which is based @@ -190,6 +190,36 @@ very large, the variance ratio in the output makes no sense, e.g. because it is negative. In such cases, it might help to use \code{robust = TRUE}. } } +\section{Supported models and model families}{ + +The single variance components that are required to calculate the marginal +and conditional r-squared values are calculated using the \code{\link[insight:get_variance]{insight::get_variance()}} +function. The results are validated against the solutions provided by +\emph{Nakagawa et al. (2017)}, in particular examples shown in the Supplement 2 +of the paper. Other model families are validated against results from the +*\emph{MuMIn}+ package. This means that the r-squared values returned by \code{r2_nakagawa()} +should be accurate and reliable for following mixed models or model families: +\itemize{ +\item Bernoulli (logistic) regression +\item Binomial regression (with other than binary outcomes) +\item Poisson and Quasi-Poisson regression +\item Negative binomial regression (including nbinom1 and nbinom2 families) +\item Gaussian regression (linear models) +\item Gamma regression +\item Tweedie regression +\item Beta regression +\item Ordered beta regression +} + +Following model families are not yet validated, but should work: +\itemize{ +\item Zero-inflated and hurdle models +\item Beta-binomial regression +\item Compound Poisson regression +\item Generalized Poisson regression +} +} + \examples{ \dontshow{if (require("lme4")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} model <- lme4::lmer(Sepal.Length ~ Petal.Length + (1 | Species), data = iris) diff --git a/man/r2_nakagawa.Rd b/man/r2_nakagawa.Rd index 5717fe5f6..cc0f9f500 100644 --- a/man/r2_nakagawa.Rd +++ b/man/r2_nakagawa.Rd @@ -88,6 +88,36 @@ appropriate for mixed models with random slopes or nested random effects The contribution of random effects can be deduced by subtracting the marginal R2 from the conditional R2 or by computing the \code{\link[=icc]{icc()}}. } +\section{Supported models and model families}{ + +The single variance components that are required to calculate the marginal +and conditional r-squared values are calculated using the \code{\link[insight:get_variance]{insight::get_variance()}} +function. The results are validated against the solutions provided by +\emph{Nakagawa et al. (2017)}, in particular examples shown in the Supplement 2 +of the paper. Other model families are validated against results from the +*\emph{MuMIn}+ package. This means that the r-squared values returned by \code{r2_nakagawa()} +should be accurate and reliable for following mixed models or model families: +\itemize{ +\item Bernoulli (logistic) regression +\item Binomial regression (with other than binary outcomes) +\item Poisson and Quasi-Poisson regression +\item Negative binomial regression (including nbinom1 and nbinom2 families) +\item Gaussian regression (linear models) +\item Gamma regression +\item Tweedie regression +\item Beta regression +\item Ordered beta regression +} + +Following model families are not yet validated, but should work: +\itemize{ +\item Zero-inflated and hurdle models +\item Beta-binomial regression +\item Compound Poisson regression +\item Generalized Poisson regression +} +} + \examples{ \dontshow{if (require("lme4")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} model <- lme4::lmer(Sepal.Length ~ Petal.Length + (1 | Species), data = iris)