From 126b7688282bc50e932da7d3b5a8928bcfd2e501 Mon Sep 17 00:00:00 2001 From: Daniel Date: Thu, 13 Jun 2024 09:32:42 +0200 Subject: [PATCH] allow null model --- DESCRIPTION | 2 +- NEWS.md | 8 ++++++++ R/icc.R | 46 ++++++++++++++++++++++++++-------------------- R/r2_nakagawa.R | 6 +++++- man/icc.Rd | 5 +++++ man/r2_nakagawa.Rd | 5 +++++ 6 files changed, 50 insertions(+), 22 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index a5bb5e1ee..71793e916 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Type: Package Package: performance Title: Assessment of Regression Models Performance -Version: 0.12.0 +Version: 0.12.0.1 Authors@R: c(person(given = "Daniel", family = "Lüdecke", diff --git a/NEWS.md b/NEWS.md index 51a13a1f0..8ebbb8b3d 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,11 @@ +# performance 0.12.1 + +## General + +* `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. + # performance 0.12.0 ## Breaking diff --git a/R/icc.R b/R/icc.R index 47fbb9a45..27b945481 100644 --- a/R/icc.R +++ b/R/icc.R @@ -11,31 +11,34 @@ #' #' @param model A (Bayesian) mixed effects model. #' @param re_formula Formula containing group-level effects to be considered in -#' the prediction. If `NULL` (default), include all group-level effects. -#' Else, for instance for nested models, name a specific group-level effect -#' to calculate the variance decomposition for this group-level. See 'Details' -#' and `?brms::posterior_predict`. +#' the prediction. If `NULL` (default), include all group-level effects. +#' Else, for instance for nested models, name a specific group-level effect +#' to calculate the variance decomposition for this group-level. See 'Details' +#' and `?brms::posterior_predict`. #' @param ci Confidence resp. credible interval level. For `icc()` and `r2()`, -#' confidence intervals are based on bootstrapped samples from the ICC resp. -#' R2 value. See `iterations`. +#' confidence intervals are based on bootstrapped samples from the ICC resp. +#' R2 value. See `iterations`. #' @param by_group Logical, if `TRUE`, `icc()` returns the variance -#' components for each random-effects level (if there are multiple levels). -#' See 'Details'. +#' components for each random-effects level (if there are multiple levels). +#' See 'Details'. #' @param iterations Number of bootstrap-replicates when computing confidence -#' intervals for the ICC or R2. +#' intervals for the ICC or R2. #' @param ci_method Character string, indicating the bootstrap-method. Should -#' be `NULL` (default), in which case `lme4::bootMer()` is used for -#' bootstrapped confidence intervals. However, if bootstrapped intervals cannot -#' be calculated this was, try `ci_method = "boot"`, which falls back to -#' `boot::boot()`. This may successfully return bootstrapped confidence intervals, -#' but bootstrapped samples may not be appropriate for the multilevel structure -#' of the model. There is also an option `ci_method = "analytical"`, which tries -#' 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. +#' be `NULL` (default), in which case `lme4::bootMer()` is used for +#' bootstrapped confidence intervals. However, if bootstrapped intervals cannot +#' be calculated this was, try `ci_method = "boot"`, which falls back to +#' `boot::boot()`. This may successfully return bootstrapped confidence intervals, +#' but bootstrapped samples may not be appropriate for the multilevel structure +#' of the model. There is also an option `ci_method = "analytical"`, which tries +#' 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. #' @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 ... Arguments passed down to `lme4::bootMer()` or `boot::boot()` -#' for bootstrapped ICC or R2. +#' for bootstrapped ICC or R2. #' #' @inheritParams r2_bayes #' @inheritParams insight::get_variance @@ -169,6 +172,7 @@ icc <- function(model, ci = NULL, iterations = 100, ci_method = NULL, + null_model = NULL, verbose = TRUE, ...) { # special handling for smicd::semLme() @@ -197,7 +201,7 @@ icc <- function(model, } # calculate random effect variances - vars <- .compute_random_vars(model, tolerance) + vars <- .compute_random_vars(model, tolerance, null_model = null_model) # return if ICC couldn't be computed if (is.null(vars) || all(is.na(vars))) { @@ -530,12 +534,14 @@ print.icc_decomposed <- function(x, digits = 2, ...) { components = c("var.fixed", "var.random", "var.residual"), name_fun = "icc()", name_full = "ICC", + null_model = null_model, verbose = TRUE) { vars <- tryCatch( insight::get_variance(model, name_fun = name_fun, name_full = name_full, tolerance = tolerance, + null_model = null_model, verbose = verbose ), error = function(e) { diff --git a/R/r2_nakagawa.R b/R/r2_nakagawa.R index eca4712fa..cdd884e24 100644 --- a/R/r2_nakagawa.R +++ b/R/r2_nakagawa.R @@ -57,6 +57,7 @@ r2_nakagawa <- function(model, ci = NULL, iterations = 100, ci_method = NULL, + null_model = NULL, verbose = TRUE, ...) { # calculate random effect variances @@ -64,6 +65,7 @@ r2_nakagawa <- function(model, model, tolerance, components = c("var.fixed", "var.residual"), + null_model = null_model, name_fun = "r2()", name_full = "r-squared" ) @@ -85,7 +87,9 @@ r2_nakagawa <- function(model, } # null-model - null_model <- insight::null_model(model) + if (is.null(null_model)) { + null_model <- insight::null_model(model) + } vars_null <- insight::get_variance(null_model, tolerance = tolerance) # names of group levels diff --git a/man/icc.Rd b/man/icc.Rd index d25004e07..5f4110375 100644 --- a/man/icc.Rd +++ b/man/icc.Rd @@ -12,6 +12,7 @@ icc( ci = NULL, iterations = 100, ci_method = NULL, + null_model = NULL, verbose = TRUE, ... ) @@ -48,6 +49,10 @@ 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{verbose}{Toggle warnings and messages.} \item{...}{Arguments passed down to \code{brms::posterior_predict()}.} diff --git a/man/r2_nakagawa.Rd b/man/r2_nakagawa.Rd index 76e41e077..da1cbf00e 100644 --- a/man/r2_nakagawa.Rd +++ b/man/r2_nakagawa.Rd @@ -11,6 +11,7 @@ r2_nakagawa( ci = NULL, iterations = 100, ci_method = NULL, + null_model = NULL, verbose = TRUE, ... ) @@ -47,6 +48,10 @@ 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{verbose}{Toggle warnings and messages.} \item{...}{Arguments passed down to \code{brms::posterior_predict()}.}