diff --git a/DESCRIPTION b/DESCRIPTION index 71793e916..140445fc0 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Type: Package Package: performance Title: Assessment of Regression Models Performance -Version: 0.12.0.1 +Version: 0.12.0.2 Authors@R: c(person(given = "Daniel", family = "Lüdecke", diff --git a/NEWS.md b/NEWS.md index 8ebbb8b3d..8aecc62b2 100644 --- a/NEWS.md +++ b/NEWS.md @@ -4,7 +4,12 @@ * `icc()` and `r2_nakagawa()` get a `null_model` argument. This can be useful when computing R2 or ICC for mixed models, where the internal computation of - the null model fails. + the null model fails, or when you already have fit the null model and want + to save time. + +* `icc()` and `r2_nakagawa()` get a `approximation` argument indicating the + approximation method for the distribution-specific (residual) variance. See + Nakagawa et al. 2017 for details. # performance 0.12.0 diff --git a/R/icc.R b/R/icc.R index 27b945481..8fc19db13 100644 --- a/R/icc.R +++ b/R/icc.R @@ -34,9 +34,11 @@ #' However, these intervals are rather inaccurate and often too narrow. It is #' recommended to calculate bootstrapped confidence intervals for mixed models. #' @param verbose Toggle warnings and messages. -#' @param null_model Optional, a null model to compute the random effect variances. -#' Should only be used if calculation of r-squared or ICC fails when `null_model` -#' is not specified. +#' @param null_model Optional, a null model to compute the random effect variances, +#' which is passed to [`insight::get_variance()`]. Usually only required if +#' calculation of r-squared or ICC fails when `null_model` is not specified. If +#' calculating the null model takes longer and you already have fit the null +#' model, you can pass it here, too, to speed up the process. #' @param ... Arguments passed down to `lme4::bootMer()` or `boot::boot()` #' for bootstrapped ICC or R2. #' @@ -173,6 +175,7 @@ icc <- function(model, iterations = 100, ci_method = NULL, null_model = NULL, + approximation = "lognormal", verbose = TRUE, ...) { # special handling for smicd::semLme() @@ -201,7 +204,12 @@ icc <- function(model, } # calculate random effect variances - vars <- .compute_random_vars(model, tolerance, null_model = null_model) + vars <- .compute_random_vars( + model, + tolerance = tolerance, + null_model = null_model, + approximation = approximation + ) # return if ICC couldn't be computed if (is.null(vars) || all(is.na(vars))) { @@ -535,6 +543,7 @@ print.icc_decomposed <- function(x, digits = 2, ...) { name_fun = "icc()", name_full = "ICC", null_model = null_model, + approximation = "lognormal", verbose = TRUE) { vars <- tryCatch( insight::get_variance(model, @@ -542,6 +551,7 @@ print.icc_decomposed <- function(x, digits = 2, ...) { name_full = name_full, tolerance = tolerance, null_model = null_model, + approximation = approximation, verbose = verbose ), error = function(e) { diff --git a/R/r2_nakagawa.R b/R/r2_nakagawa.R index cdd884e24..f65c23a5a 100644 --- a/R/r2_nakagawa.R +++ b/R/r2_nakagawa.R @@ -58,6 +58,7 @@ r2_nakagawa <- function(model, iterations = 100, ci_method = NULL, null_model = NULL, + approximation = "lognormal", verbose = TRUE, ...) { # calculate random effect variances @@ -66,6 +67,7 @@ r2_nakagawa <- function(model, tolerance, components = c("var.fixed", "var.residual"), null_model = null_model, + approximation = approximation, name_fun = "r2()", name_full = "r-squared" ) diff --git a/man/icc.Rd b/man/icc.Rd index 5f4110375..89ae6a9d0 100644 --- a/man/icc.Rd +++ b/man/icc.Rd @@ -13,6 +13,7 @@ icc( iterations = 100, ci_method = NULL, null_model = NULL, + approximation = "lognormal", verbose = TRUE, ... ) @@ -49,9 +50,15 @@ to calculate analytical confidence assuming a chi-squared distribution. However, these intervals are rather inaccurate and often too narrow. It is recommended to calculate bootstrapped confidence intervals for mixed models.} -\item{null_model}{Optional, a null model to compute the random effect variances. -Should only be used if calculation of r-squared or ICC fails when \code{null_model} -is not specified.} +\item{null_model}{Optional, a null model to compute the random effect variances, +which is passed to \code{\link[insight:get_variance]{insight::get_variance()}}. Usually only required if +calculation of r-squared or ICC fails when \code{null_model} is not specified. If +calculating the null model takes longer and you already have fit the null +model, you can pass it here, too, to speed up the process.} + +\item{approximation}{Character string, indicating the approximation method +for the distribution-specific (residual) variance. Can be \code{"lognormal"} +(default), \code{"delta"} or \code{"trigamma"}. See \emph{Nakagawa et al. 2017} for details.} \item{verbose}{Toggle warnings and messages.} diff --git a/man/r2_nakagawa.Rd b/man/r2_nakagawa.Rd index da1cbf00e..13d2d1e35 100644 --- a/man/r2_nakagawa.Rd +++ b/man/r2_nakagawa.Rd @@ -12,6 +12,7 @@ r2_nakagawa( iterations = 100, ci_method = NULL, null_model = NULL, + approximation = "lognormal", verbose = TRUE, ... ) @@ -48,9 +49,15 @@ to calculate analytical confidence assuming a chi-squared distribution. However, these intervals are rather inaccurate and often too narrow. It is recommended to calculate bootstrapped confidence intervals for mixed models.} -\item{null_model}{Optional, a null model to compute the random effect variances. -Should only be used if calculation of r-squared or ICC fails when \code{null_model} -is not specified.} +\item{null_model}{Optional, a null model to compute the random effect variances, +which is passed to \code{\link[insight:get_variance]{insight::get_variance()}}. Usually only required if +calculation of r-squared or ICC fails when \code{null_model} is not specified. If +calculating the null model takes longer and you already have fit the null +model, you can pass it here, too, to speed up the process.} + +\item{approximation}{Character string, indicating the approximation method +for the distribution-specific (residual) variance. Can be \code{"lognormal"} +(default), \code{"delta"} or \code{"trigamma"}. See \emph{Nakagawa et al. 2017} for details.} \item{verbose}{Toggle warnings and messages.}