From 7d348add902971f5baa1bcea7143cfe12e745dd8 Mon Sep 17 00:00:00 2001 From: Daniel Date: Sun, 6 Oct 2024 21:49:11 +0200 Subject: [PATCH] parameters(): `performance=TRUE` arg as alias for `summary` (#1022) * parameters(): `performance=TRUE` arg as alias for `summary` Fixes #898 * progress * fix * final ones * desc * news * update tests * update snaps * fix * consistent order of arguments * lintr --- DESCRIPTION | 8 +- NEWS.md | 11 +- R/1_model_parameters.R | 39 +++-- R/extract_parameters.R | 8 +- R/format.R | 141 +++++------------- R/methods_aod.R | 9 +- R/methods_averaging.R | 10 +- R/methods_betareg.R | 9 +- R/methods_bfsl.R | 9 +- R/methods_brglm2.R | 18 ++- R/methods_car.R | 2 +- R/methods_cplm.R | 10 +- R/methods_emmeans.R | 10 +- R/methods_fixest.R | 34 +++-- R/methods_glmmTMB.R | 13 +- R/methods_hglm.R | 9 +- R/methods_lme4.R | 17 ++- R/methods_mclogit.R | 9 +- R/methods_mmrm.R | 9 +- R/methods_mvord.R | 10 +- R/methods_nestedLogit.R | 13 +- R/methods_ordinal.R | 9 +- R/methods_selection.R | 10 +- R/methods_survey.R | 9 +- R/methods_svy2lme.R | 2 +- R/methods_systemfit.R | 9 +- R/print.parameters_model.R | 14 +- R/utils.R | 11 ++ R/utils_model_parameters.R | 10 +- man/model_parameters.Rd | 12 +- man/model_parameters.averaging.Rd | 9 +- man/model_parameters.default.Rd | 69 +++++---- man/model_parameters.merMod.Rd | 28 ++-- man/model_parameters.mlm.Rd | 6 +- man/model_parameters.zcpglm.Rd | 13 +- man/print.compare_parameters.Rd | 12 +- man/print.parameters_model.Rd | 12 +- .../_snaps/model_parameters.fixest.md | 5 +- tests/testthat/_snaps/model_parameters.glm.md | 3 +- .../testthat/_snaps/model_parameters.mixed.md | 5 +- tests/testthat/_snaps/printing.md | 3 +- tests/testthat/test-model_parameters.fixest.R | 2 +- tests/testthat/test-model_parameters.glm.R | 4 +- tests/testthat/test-model_parameters.mixed.R | 2 +- tests/testthat/test-p_adjust.R | 4 +- tests/testthat/test-printing.R | 2 +- vignettes/model_parameters.Rmd | 10 +- vignettes/model_parameters_print.Rmd | 12 +- 48 files changed, 423 insertions(+), 262 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 1ad00ca59..98546e117 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Type: Package Package: parameters Title: Processing of Model Parameters -Version: 0.22.2.16 +Version: 0.22.2.17 Authors@R: c(person(given = "Daniel", family = "Lüdecke", @@ -80,8 +80,8 @@ Depends: R (>= 3.6) Imports: bayestestR (>= 0.14.0), - datawizard (>= 0.12.3), - insight (>= 0.20.4), + datawizard (>= 0.13.0), + insight (>= 0.20.5), graphics, methods, stats, @@ -224,4 +224,4 @@ Config/testthat/edition: 3 Config/testthat/parallel: true Config/Needs/website: easystats/easystatstemplate Config/rcmdcheck/ignore-inconsequential-notes: true -Remotes: easystats/bayestestR, easystats/datawizard +Remotes: easystats/bayestestR#678 diff --git a/NEWS.md b/NEWS.md index 5a6d2f037..1605c740e 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,13 @@ -# parameters 0.22.3 +# parameters 0.23.0 + +## Breaking Changes + +* Argument `summary` in `model_parameters()` is now deprecated. Please use + `include_info` instead. + +* Changed output style for the included additional information on model formula, + sigma and R2 when printing model parameters. This information now also includes + the RMSE. ## Changes diff --git a/R/1_model_parameters.R b/R/1_model_parameters.R index ad69ad6e8..ab2c75968 100644 --- a/R/1_model_parameters.R +++ b/R/1_model_parameters.R @@ -398,8 +398,8 @@ model_parameters <- function(model, ...) { # Add new options to the docs in "print.parameters_model" -# getOption("parameters_summary"): show model summary -# getOption("parameters_mixed_summary"): show model summary for mixed models +# getOption("parameters_info"): show model summary +# getOption("parameters_mixed_info"): show model summary for mixed models # getOption("parameters_cimethod"): show message about CI approximation # getOption("parameters_exponentiate"): show warning about exp for log/logit links # getOption("parameters_labels"): use value/variable labels instead pretty names @@ -466,9 +466,10 @@ parameters <- model_parameters #' _Confidence intervals and approximation of degrees of freedom_ in #' [`model_parameters()`] for further details. When `ci_method=NULL`, in most #' cases `"wald"` is used then. -#' @param summary Logical, if `TRUE`, prints summary information about the +#' @param include_info Logical, if `TRUE`, prints summary information about the #' model (model formula, number of observations, residual standard deviation #' and more). +#' @param summary Deprecated, please use `info` instead. #' @param keep Character containing a regular expression pattern that #' describes the parameters that should be included (for `keep`) or excluded #' (for `drop`) in the returned data frame. `keep` may also be a @@ -566,16 +567,23 @@ model_parameters.default <- function(model, standardize = NULL, exponentiate = FALSE, p_adjust = NULL, + vcov = NULL, + vcov_args = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, - vcov = NULL, - vcov_args = NULL, ...) { # validation check for inputs .is_model_valid(model) + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + # validation check, warn if unsupported argument is used. # unsupported arguments will be removed from the argument list. dots <- .check_dots( @@ -597,7 +605,7 @@ model_parameters.default <- function(model, standardize = standardize, exponentiate = exponentiate, p_adjust = p_adjust, - summary = summary, + include_info = include_info, keep_parameters = keep, drop_parameters = drop, vcov = vcov, @@ -654,12 +662,12 @@ model_parameters.default <- function(model, component = "conditional", ci_method = NULL, p_adjust = NULL, - summary = FALSE, + include_info = FALSE, keep_parameters = NULL, drop_parameters = NULL, - verbose = TRUE, vcov = NULL, vcov_args = NULL, + verbose = TRUE, ...) { dots <- list(...) @@ -726,7 +734,7 @@ model_parameters.default <- function(model, iterations, ci_method = ci_method, p_adjust = p_adjust, - summary = summary, + include_info = include_info, verbose = verbose, ... ) @@ -751,15 +759,22 @@ model_parameters.glm <- function(model, standardize = NULL, exponentiate = FALSE, p_adjust = NULL, + vcov = NULL, + vcov_args = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, - vcov = NULL, - vcov_args = NULL, verbose = TRUE, ...) { dots <- list(...) + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + # set default if (is.null(ci_method)) { if (isTRUE(bootstrap)) { @@ -797,7 +812,7 @@ model_parameters.glm <- function(model, standardize = standardize, exponentiate = exponentiate, p_adjust = p_adjust, - summary = summary, + include_info = include_info, keep_parameters = keep, drop_parameters = drop, vcov = vcov, diff --git a/R/extract_parameters.R b/R/extract_parameters.R index 49bc03c0b..6f6653bd4 100644 --- a/R/extract_parameters.R +++ b/R/extract_parameters.R @@ -16,7 +16,7 @@ keep_parameters = NULL, drop_parameters = NULL, include_sigma = TRUE, - summary = FALSE, + include_info = FALSE, vcov = NULL, vcov_args = NULL, ...) { @@ -301,7 +301,7 @@ # ==== add sigma and residual df - if (isTRUE(include_sigma) || isTRUE(summary)) { + if (isTRUE(include_sigma) || isTRUE(include_info)) { parameters <- .add_sigma_residual_df(parameters, model) } @@ -424,7 +424,7 @@ keep_parameters = NULL, drop_parameters = NULL, include_sigma = FALSE, - summary = FALSE, + include_info = FALSE, vcov = NULL, vcov_args = NULL, verbose = TRUE, @@ -639,7 +639,7 @@ # add sigma - if (isTRUE(include_sigma) || isTRUE(summary)) { + if (isTRUE(include_sigma) || isTRUE(include_info)) { parameters <- .add_sigma_residual_df(parameters, model) } diff --git a/R/format.R b/R/format.R index a350ae7a1..857068863 100644 --- a/R/format.R +++ b/R/format.R @@ -542,6 +542,7 @@ format.parameters_sem <- function(x, show_sigma = FALSE, show_formula = FALSE, show_r2 = FALSE, + show_rmse = FALSE, format = "text") { # prepare footer footer <- NULL @@ -549,6 +550,7 @@ format.parameters_sem <- function(x, sigma_value <- attributes(x)$sigma r2 <- attributes(x)$r2 + rmse <- attributes(x)$rmse residual_df <- attributes(x)$residual_df p_adjust <- attributes(x)$p_adjust model_formula <- attributes(x)$model_formula @@ -575,29 +577,35 @@ format.parameters_sem <- function(x, footer <- .add_footer_r2(footer, digits, r2, type) } + # footer: r-squared + if (isTRUE(show_rmse)) { + footer <- .add_footer_values(footer, digits, value = rmse, text = "RMSE ", type) + } + # footer: p-adjustment - if ("p" %in% colnames(x) && isTRUE(verbose)) { - footer <- .add_footer_padjust(footer, p_adjust, type) + if ("p" %in% colnames(x) && isTRUE(verbose) && !is.null(p_adjust) && p_adjust != "none") { + footer <- .add_footer_text(footer, text = paste("p-value adjustment method:", format_p_adjust(p_adjust))) } # footer: anova test if (!is.null(anova_test)) { - footer <- .add_footer_anova_test(footer, anova_test, type) + footer <- .add_footer_text(footer, text = sprintf("%s test statistic", anova_test)) } - # footer: anova test + # footer: anova type if (!is.null(anova_type)) { - footer <- .add_footer_anova_type(footer, anova_type, type) + footer <- .add_footer_text(footer, text = sprintf("Anova Table (Type %s tests)", anova_type)) } + # footer: marginaleffects::comparisons() if (!is.null(prediction_type)) { - footer <- .add_footer_prediction_type(footer, prediction_type, type) + footer <- .add_footer_text(footer, text = sprintf("Prediction type: %s", prediction_type)) } # footer: htest alternative if (!is.null(text_alternative)) { - footer <- .add_footer_alternative(footer, text_alternative, type) + footer <- .add_footer_text(footer, text = text_alternative) } # footer: generic text @@ -627,7 +635,7 @@ format.parameters_sem <- function(x, # footer: generic text .add_footer_text <- function(footer = NULL, text = NULL, type = "text", is_ggeffects = FALSE) { - if (!is.null(text)) { + if (!is.null(text) && length(text)) { if (type == "text" || type == "markdown") { if (is.null(footer)) { fill <- "\n" @@ -644,6 +652,29 @@ format.parameters_sem <- function(x, } +# footer: generic values +.add_footer_values <- function(footer = NULL, + digits = 3, + value = NULL, + text = NULL, + type = "text") { + if (!is.null(value) && !is.null(text)) { + string <- sprintf("%s: %s", text, insight::format_value(value, digits = digits)) + if (type == "text" || type == "markdown") { + if (is.null(footer)) { + fill <- "\n" + } else { + fill <- "" + } + footer <- paste0(footer, fill, string, "\n") + } else if (type == "html") { + footer <- c(footer, string) + } + } + footer +} + + # footer: residual standard deviation .add_footer_sigma <- function(footer = NULL, digits = 3, sigma = NULL, residual_df = NULL, type = "text") { if (!is.null(sigma)) { @@ -660,9 +691,9 @@ format.parameters_sem <- function(x, } else { fill <- "" } - footer <- paste0(footer, sprintf("%sResidual standard deviation: %.*f%s\n", fill, digits, sigma, res_df)) + footer <- paste0(footer, sprintf("%sSigma: %.*f%s\n", fill, digits, sigma, res_df)) } else if (type == "html") { - footer <- c(footer, insight::trim_ws(sprintf("Residual standard deviation: %.*f%s", digits, sigma, res_df))) + footer <- c(footer, insight::trim_ws(sprintf("Sigma: %.*f%s", digits, sigma, res_df))) } } footer @@ -693,96 +724,6 @@ format.parameters_sem <- function(x, } -# footer: anova type -.add_footer_anova_type <- function(footer = NULL, aov_type = NULL, type = "text") { - if (!is.null(aov_type)) { - if (type == "text" || type == "markdown") { - if (is.null(footer)) { - fill <- "\n" - } else { - fill <- "" - } - footer <- paste0(footer, sprintf("%sAnova Table (Type %s tests)\n", fill, aov_type)) - } else if (type == "html") { - footer <- c(footer, sprintf("Anova Table (Type %s tests)", aov_type)) - } - } - footer -} - - -# footer: marginaleffects::comparisions() prediction_type -.add_footer_prediction_type <- function(footer = NULL, prediction_type = NULL, type = "text") { - if (!is.null(prediction_type)) { - if (type == "text" || type == "markdown") { - if (is.null(footer)) { - fill <- "\n" - } else { - fill <- "" - } - footer <- paste0(footer, sprintf("%sPrediction type: %s\n", fill, prediction_type)) - } else if (type == "html") { - footer <- c(footer, sprintf("Prediction type: %s", prediction_type)) - } - } - footer -} - - -# footer: anova test -.add_footer_anova_test <- function(footer = NULL, test = NULL, type = "text") { - if (!is.null(test)) { - if (type == "text" || type == "markdown") { - if (is.null(footer)) { - fill <- "\n" - } else { - fill <- "" - } - footer <- paste0(footer, sprintf("%s%s test statistic\n", fill, test)) - } else if (type == "html") { - footer <- c(footer, sprintf("%s test statistic", test)) - } - } - footer -} - - -# footer: htest alternative -.add_footer_alternative <- function(footer = NULL, text_alternative = NULL, type = "text") { - if (!is.null(text_alternative)) { - if (type == "text" || type == "markdown") { - if (is.null(footer)) { - fill <- "\n" - } else { - fill <- "" - } - footer <- paste0(footer, sprintf("%s%s\n", fill, text_alternative)) - } else if (type == "html") { - footer <- c(footer, text_alternative) - } - } - footer -} - - -# footer: p-adjustment -.add_footer_padjust <- function(footer = NULL, p_adjust = NULL, type = "text") { - if (!is.null(p_adjust) && p_adjust != "none") { - if (type == "text" || type == "markdown") { - if (is.null(footer)) { - fill <- "\n" - } else { - fill <- "" - } - footer <- paste0(footer, fill, "p-value adjustment method: ", format_p_adjust(p_adjust), "\n") - } else if (type == "html") { - footer <- c(footer, paste0("p-value adjustment method: ", format_p_adjust(p_adjust))) - } - } - footer -} - - # footer: model formula .add_footer_formula <- function(footer = NULL, model_formula = NULL, n_obs = NULL, type = "text") { if (!is.null(model_formula)) { diff --git a/R/methods_aod.R b/R/methods_aod.R index fe98716ae..ef067d3e2 100644 --- a/R/methods_aod.R +++ b/R/methods_aod.R @@ -18,6 +18,7 @@ model_parameters.glimML <- function(model, exponentiate = FALSE, p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, @@ -29,6 +30,12 @@ model_parameters.glimML <- function(model, merge_by <- "Parameter" } + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + # dispersion is just an alias... if (component == "dispersion") { component <- "random" @@ -46,7 +53,7 @@ model_parameters.glimML <- function(model, p_adjust = p_adjust, keep_parameters = keep, drop_parameters = drop, - summary = summary, + include_info = include_info, verbose = verbose, ... ) diff --git a/R/methods_averaging.R b/R/methods_averaging.R index 5c3d9f690..f3c7e00a3 100644 --- a/R/methods_averaging.R +++ b/R/methods_averaging.R @@ -41,11 +41,19 @@ model_parameters.averaging <- function(model, exponentiate = FALSE, p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, ...) { component <- match.arg(component) + + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + out <- .model_parameters_generic( model = model, ci = ci, @@ -55,7 +63,7 @@ model_parameters.averaging <- function(model, p_adjust = p_adjust, keep_parameters = keep, drop_parameters = drop, - summary = summary, + include_info = include_info, ... ) diff --git a/R/methods_betareg.R b/R/methods_betareg.R index 4c4ce273b..37fbb8124 100644 --- a/R/methods_betareg.R +++ b/R/methods_betareg.R @@ -11,6 +11,7 @@ model_parameters.betareg <- function(model, exponentiate = FALSE, p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, @@ -23,6 +24,12 @@ model_parameters.betareg <- function(model, verbose = verbose ) + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + component <- match.arg(component) if (component == "all") { merge_by <- c("Parameter", "Component") @@ -44,7 +51,7 @@ model_parameters.betareg <- function(model, p_adjust = p_adjust, keep_parameters = keep, drop_parameters = drop, - summary = summary, + include_info = include_info, vcov = NULL, vcov_args = NULL ) diff --git a/R/methods_bfsl.R b/R/methods_bfsl.R index 078946cd3..69aa7c3f4 100644 --- a/R/methods_bfsl.R +++ b/R/methods_bfsl.R @@ -4,10 +4,17 @@ model_parameters.bfsl <- function(model, ci_method = "residual", p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, ...) { + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + out <- .model_parameters_generic( model = model, ci = ci, @@ -16,7 +23,7 @@ model_parameters.bfsl <- function(model, p_adjust = p_adjust, keep_parameters = keep, drop_parameters = drop, - summary = summary, + include_info = include_info, ... ) diff --git a/R/methods_brglm2.R b/R/methods_brglm2.R index e4f0bc983..acfd9a1c5 100644 --- a/R/methods_brglm2.R +++ b/R/methods_brglm2.R @@ -15,6 +15,7 @@ model_parameters.bracl <- function(model, exponentiate = FALSE, p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, @@ -27,6 +28,12 @@ model_parameters.bracl <- function(model, verbose = verbose ) + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + # detect number of levels of response resp <- insight::get_response(model) @@ -56,7 +63,7 @@ model_parameters.bracl <- function(model, p_adjust = p_adjust, keep_parameters = keep, drop_parameters = drop, - summary = summary, + include_info = include_info, vcov = NULL, vcov_args = NULL ) @@ -153,10 +160,17 @@ model_parameters.multinom <- function(model, exponentiate = FALSE, p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, ...) { + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + model_parameters.bracl( model, ci = ci, @@ -166,7 +180,7 @@ model_parameters.multinom <- function(model, standardize = standardize, exponentiate = exponentiate, p_adjust = p_adjust, - summary = summary, + include_info = include_info, keep = keep, drop = drop, verbose = verbose, diff --git a/R/methods_car.R b/R/methods_car.R index 0284cb283..3d2502cbc 100644 --- a/R/methods_car.R +++ b/R/methods_car.R @@ -46,7 +46,7 @@ model_parameters.deltaMethod <- function(model, p_adjust = NULL, verbose = TRUE, iterations = NULL, ci_method = "residual", p_adjust = p_adjust, - summary = FALSE, + include_info = FALSE, verbose = verbose ) fun_args <- c(fun_args, dots) diff --git a/R/methods_cplm.R b/R/methods_cplm.R index 3ba6bf0ee..ad8efa25f 100644 --- a/R/methods_cplm.R +++ b/R/methods_cplm.R @@ -36,9 +36,10 @@ model_parameters.zcpglm <- function(model, standardize = NULL, exponentiate = FALSE, p_adjust = NULL, + summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, - summary = getOption("parameters_summary", FALSE), verbose = TRUE, ...) { component <- match.arg(component) @@ -48,6 +49,11 @@ model_parameters.zcpglm <- function(model, component <- "conditional" } + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } # Processing if (bootstrap) { @@ -75,7 +81,7 @@ model_parameters.zcpglm <- function(model, ci, exponentiate, p_adjust = p_adjust, - summary = summary, + include_info = include_info, verbose = verbose, ... ) diff --git a/R/methods_emmeans.R b/R/methods_emmeans.R index aac0f08dd..c8ed97188 100644 --- a/R/methods_emmeans.R +++ b/R/methods_emmeans.R @@ -172,7 +172,15 @@ model_parameters.emm_list <- function(model, # exponentiate coefficients and SE/CI, if requested params <- .exponentiate_parameters(params, model, exponentiate) - params <- .add_model_parameters_attributes(params, model, ci, exponentiate, p_adjust = p_adjust, verbose = verbose, ...) + params <- .add_model_parameters_attributes( + params, + model, + ci, + exponentiate, + p_adjust = p_adjust, + verbose = verbose, + ... + ) attr(params, "object_name") <- insight::safe_deparse_symbol(substitute(model)) class(params) <- c("parameters_model", "see_parameters_model", class(params)) diff --git a/R/methods_fixest.R b/R/methods_fixest.R index 9481f0090..7bfc9a945 100644 --- a/R/methods_fixest.R +++ b/R/methods_fixest.R @@ -9,12 +9,13 @@ model_parameters.fixest <- function(model, standardize = NULL, exponentiate = FALSE, p_adjust = NULL, + vcov = NULL, + vcov_args = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, - vcov = NULL, - vcov_args = NULL, ...) { # default ci-method, based on statistic if (is.null(ci_method)) { @@ -25,6 +26,12 @@ model_parameters.fixest <- function(model, } } + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + # extract model parameters table, as data frame out <- tryCatch( { @@ -38,7 +45,7 @@ model_parameters.fixest <- function(model, standardize = standardize, exponentiate = exponentiate, p_adjust = p_adjust, - summary = summary, + include_info = include_info, keep_parameters = keep, drop_parameters = drop, vcov = vcov, @@ -65,14 +72,14 @@ model_parameters.fixest <- function(model, standard_error.fixest <- function(model, vcov = NULL, vcov_args = NULL, ...) { params <- insight::get_parameters(model) - if (!is.null(vcov)) { + if (is.null(vcov)) { + stats <- summary(model) + SE <- as.vector(stats$se) + } else { # we don't want to wrap this in a tryCatch because the `fixest` error is # informative when `vcov` is wrong. V <- insight::get_varcov(model, vcov = vcov, vcov_args = vcov_args) SE <- sqrt(diag(V)) - } else { - stats <- summary(model) - SE <- as.vector(stats$se) } .data_frame( @@ -124,13 +131,20 @@ model_parameters.fixest_multi <- function(model, standardize = NULL, exponentiate = FALSE, p_adjust = NULL, + vcov = NULL, + vcov_args = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, - vcov = NULL, - vcov_args = NULL, ...) { + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + # iterate over responses out <- lapply( model, @@ -142,7 +156,7 @@ model_parameters.fixest_multi <- function(model, standardize = standardize, exponentiate = exponentiate, p_adjust = p_adjust, - summary = summary, + include_info = include_info, keep = keep, drop = drop, verbose = verbose, diff --git a/R/methods_glmmTMB.R b/R/methods_glmmTMB.R index 291a4ca7a..26ad72dd1 100644 --- a/R/methods_glmmTMB.R +++ b/R/methods_glmmTMB.R @@ -21,13 +21,20 @@ model_parameters.glmmTMB <- function(model, p_adjust = NULL, wb_component = TRUE, summary = getOption("parameters_mixed_summary", FALSE), + include_info = getOption("parameters_mixed_info", FALSE), + include_sigma = FALSE, keep = NULL, drop = NULL, verbose = TRUE, - include_sigma = FALSE, ...) { insight::check_if_installed("glmmTMB") + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + # validation check, warn if unsupported argument is used. dot_args <- .check_dots( dots = list(...), @@ -98,7 +105,7 @@ model_parameters.glmmTMB <- function(model, keep_component_column = component != "conditional", include_sigma = include_sigma, wb_component = wb_component, - summary = summary + include_info = include_info ) fun_args <- c(fun_args, dot_args) params <- do.call(".extract_parameters_generic", fun_args) @@ -236,7 +243,7 @@ model_parameters.glmmTMB <- function(model, p_adjust = p_adjust, verbose = verbose, group_level = group_level, - summary = summary, + include_info = include_info, wb_component = wb_component, ... ) diff --git a/R/methods_hglm.R b/R/methods_hglm.R index c324d3d4f..a8f27fea7 100644 --- a/R/methods_hglm.R +++ b/R/methods_hglm.R @@ -23,6 +23,7 @@ model_parameters.hglm <- function(model, component = "all", p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, @@ -31,13 +32,19 @@ model_parameters.hglm <- function(model, effects <- match.arg(effects, choices = c("fixed", "random", "all")) component <- match.arg(component, choices = c("all", "conditional", "dispersion")) + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + # fixed effects mp <- model_parameters.default( model, ci = ci, ci_method = ci_method, bootstrap = bootstrap, effects = "fixed", component = "conditional", iterations = iterations, - exponentiate = exponentiate, p_adjust = p_adjust, summary = summary, + exponentiate = exponentiate, p_adjust = p_adjust, include_info = include_info, keep = keep, drop = drop, verbose = verbose, ... ) diff --git a/R/methods_lme4.R b/R/methods_lme4.R index 230b43832..4d55dac15 100644 --- a/R/methods_lme4.R +++ b/R/methods_lme4.R @@ -159,17 +159,24 @@ model_parameters.merMod <- function(model, group_level = FALSE, exponentiate = FALSE, p_adjust = NULL, + vcov = NULL, + vcov_args = NULL, wb_component = TRUE, summary = getOption("parameters_mixed_summary", FALSE), + include_info = getOption("parameters_mixed_info", FALSE), + include_sigma = FALSE, keep = NULL, drop = NULL, verbose = TRUE, - include_sigma = FALSE, - vcov = NULL, - vcov_args = NULL, ...) { dots <- list(...) + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + # set default if (is.null(ci_method)) { if (isTRUE(bootstrap)) { @@ -248,7 +255,7 @@ model_parameters.merMod <- function(model, drop_parameters = drop, verbose = verbose, include_sigma = include_sigma, - summary = summary, + include_info = include_info, vcov = vcov, vcov_args = vcov_args ) @@ -313,7 +320,7 @@ model_parameters.merMod <- function(model, ci_method = ci_method, p_adjust = p_adjust, verbose = verbose, - summary = summary, + include_info = include_info, group_level = group_level, wb_component = wb_component, ... diff --git a/R/methods_mclogit.R b/R/methods_mclogit.R index 5d01b5a94..802e851a3 100644 --- a/R/methods_mclogit.R +++ b/R/methods_mclogit.R @@ -7,10 +7,17 @@ model_parameters.mblogit <- function(model, exponentiate = FALSE, p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, ...) { + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + out <- .model_parameters_generic( model = model, ci = ci, @@ -22,7 +29,7 @@ model_parameters.mblogit <- function(model, p_adjust = p_adjust, keep_parameters = keep, drop_parameters = drop, - summary = summary, + include_info = include_info, ... ) diff --git a/R/methods_mmrm.R b/R/methods_mmrm.R index 89b68b402..d786dca5d 100644 --- a/R/methods_mmrm.R +++ b/R/methods_mmrm.R @@ -10,6 +10,7 @@ model_parameters.mmrm <- function(model, exponentiate = FALSE, p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, @@ -19,6 +20,12 @@ model_parameters.mmrm <- function(model, "kenward" ) + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + # extract model parameters table, as data frame out <- tryCatch( .model_parameters_generic( @@ -31,7 +38,7 @@ model_parameters.mmrm <- function(model, standardize = standardize, exponentiate = exponentiate, p_adjust = p_adjust, - summary = summary, + include_info = include_info, keep_parameters = keep, drop_parameters = drop, vcov = NULL, diff --git a/R/methods_mvord.R b/R/methods_mvord.R index 563a03e8a..43ec187f1 100644 --- a/R/methods_mvord.R +++ b/R/methods_mvord.R @@ -12,11 +12,19 @@ model_parameters.mvord <- function(model, exponentiate = FALSE, p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, ...) { component <- match.arg(component) + + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + out <- .model_parameters_generic( model = model, ci = ci, @@ -29,7 +37,7 @@ model_parameters.mvord <- function(model, p_adjust = p_adjust, keep_parameters = keep, drop_parameters = drop, - summary = summary, + include_info = include_info, ... ) attr(out, "object_name") <- insight::safe_deparse_symbol(substitute(model)) diff --git a/R/methods_nestedLogit.R b/R/methods_nestedLogit.R index c87df18bd..bec97e33a 100644 --- a/R/methods_nestedLogit.R +++ b/R/methods_nestedLogit.R @@ -8,15 +8,22 @@ model_parameters.nestedLogit <- function(model, standardize = NULL, exponentiate = FALSE, p_adjust = NULL, + vcov = NULL, + vcov_args = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, - vcov = NULL, - vcov_args = NULL, verbose = TRUE, ...) { dots <- list(...) + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + # set default if (is.null(ci_method)) { if (isTRUE(bootstrap)) { @@ -61,7 +68,7 @@ model_parameters.nestedLogit <- function(model, standardize = standardize, exponentiate = exponentiate, p_adjust = p_adjust, - summary = summary, + include_info = include_info, keep_parameters = keep, drop_parameters = drop, vcov = vcov, diff --git a/R/methods_ordinal.R b/R/methods_ordinal.R index aab826e99..09ada5454 100644 --- a/R/methods_ordinal.R +++ b/R/methods_ordinal.R @@ -12,6 +12,7 @@ model_parameters.clm2 <- function(model, exponentiate = FALSE, p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, @@ -23,6 +24,12 @@ model_parameters.clm2 <- function(model, merge_by <- "Parameter" } + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + ## TODO check merge by out <- .model_parameters_generic( @@ -37,7 +44,7 @@ model_parameters.clm2 <- function(model, p_adjust = p_adjust, keep_parameters = keep, drop_parameters = drop, - summary = summary, + include_info = include_info, ... ) diff --git a/R/methods_selection.R b/R/methods_selection.R index 46c227832..728adba85 100644 --- a/R/methods_selection.R +++ b/R/methods_selection.R @@ -9,11 +9,19 @@ model_parameters.selection <- function(model, exponentiate = FALSE, p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, ...) { component <- match.arg(component) + + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + out <- .model_parameters_generic( model = model, ci = ci, @@ -25,7 +33,7 @@ model_parameters.selection <- function(model, exponentiate = exponentiate, keep_parameters = keep, drop_parameters = drop, - summary = summary, + include_info = include_info, p_adjust = p_adjust, ... ) diff --git a/R/methods_survey.R b/R/methods_survey.R index 4af36e799..7112b822b 100644 --- a/R/methods_survey.R +++ b/R/methods_survey.R @@ -8,6 +8,7 @@ model_parameters.svyglm <- function(model, exponentiate = FALSE, p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, @@ -18,6 +19,12 @@ model_parameters.svyglm <- function(model, ) } + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + # validation check, warn if unsupported argument is used. dot_args <- .check_dots( dots = list(...), @@ -35,7 +42,7 @@ model_parameters.svyglm <- function(model, p_adjust = p_adjust, keep_parameters = keep, drop_parameters = drop, - summary = summary, + include_info = include_info, verbose = verbose ) fun_args <- c(fun_args, dot_args) diff --git a/R/methods_svy2lme.R b/R/methods_svy2lme.R index e34e7bb88..cc7e9f83a 100644 --- a/R/methods_svy2lme.R +++ b/R/methods_svy2lme.R @@ -2,10 +2,10 @@ model_parameters.svy2lme <- function(model, ci = 0.95, effects = "all", + include_sigma = FALSE, keep = NULL, drop = NULL, verbose = TRUE, - include_sigma = FALSE, ...) { dots <- list(...) # which component to return? diff --git a/R/methods_systemfit.R b/R/methods_systemfit.R index 9edd008de..4df115737 100644 --- a/R/methods_systemfit.R +++ b/R/methods_systemfit.R @@ -8,10 +8,17 @@ model_parameters.systemfit <- function(model, exponentiate = FALSE, p_adjust = NULL, summary = FALSE, + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, ...) { + ## TODO remove deprecated later + if (!missing(summary)) { + .deprecated_warning("summary", "include_info", verbose) + include_info <- summary + } + out <- .model_parameters_generic( model = model, ci = ci, @@ -24,7 +31,7 @@ model_parameters.systemfit <- function(model, p_adjust = p_adjust, keep_parameters = keep, drop_parameters = drop, - summary = summary, + include_info = include_info, ... ) diff --git a/R/print.parameters_model.R b/R/print.parameters_model.R index 96dfe89ff..e8f6d1206 100644 --- a/R/print.parameters_model.R +++ b/R/print.parameters_model.R @@ -107,13 +107,13 @@ #' some messages providing additional information can be displayed or suppressed #' using `options()`: #' -#' - `parameters_summary`: `options(parameters_summary = TRUE)` will override the -#' `summary` argument in `model_parameters()` and always show the model summary -#' for non-mixed models. +#' - `parameters_info`: `options(parameters_info = TRUE)` will override the +#' `include_info` argument in `model_parameters()` and always show the model +#' summary for non-mixed models. #' -#' - `parameters_mixed_summary`: `options(parameters_mixed_summary = TRUE)` will -#' override the `summary` argument in `model_parameters()` for mixed models, and -#' will then always show the model summary. +#' - `parameters_mixed_info`: `options(parameters_mixed_info = TRUE)` will +#' override the `include_info` argument in `model_parameters()` for mixed +#' models, and will then always show the model summary. #' #' - `parameters_cimethod`: `options(parameters_cimethod = TRUE)` will show the #' additional information about the approximation method used to calculate @@ -430,6 +430,7 @@ print.parameters_random <- function(x, digits = 2, ...) { show_sigma <- ifelse(show_summary, TRUE, show_sigma) show_formula <- ifelse(show_summary, TRUE, show_formula) show_r2 <- .additional_arguments(x, "show_summary", FALSE) + show_rmse <- .additional_arguments(x, "show_summary", FALSE) # set defaults, if necessary if (is.null(model_sigma)) { @@ -443,6 +444,7 @@ print.parameters_random <- function(x, digits = 2, ...) { show_sigma = show_sigma, show_formula = show_formula, show_r2 = show_r2, + show_rmse = show_rmse, format = format ) } diff --git a/R/utils.R b/R/utils.R index 5e093bcaa..7533beb71 100644 --- a/R/utils.R +++ b/R/utils.R @@ -196,3 +196,14 @@ } ifnotfound } + +.deprecated_warning <- function(old, new, verbose = TRUE) { + if (verbose) { + insight::format_warning(paste0( + "Argument `", old, + "` is deprecated and will be removed in the future. Please use `", + new, + "` instead." + )) + } +} diff --git a/R/utils_model_parameters.R b/R/utils_model_parameters.R index 5f22af548..eaa1373ec 100644 --- a/R/utils_model_parameters.R +++ b/R/utils_model_parameters.R @@ -10,7 +10,7 @@ iterations = 1000, ci_method = NULL, p_adjust = NULL, - summary = FALSE, + include_info = FALSE, verbose = TRUE, group_level = FALSE, wb_component = FALSE, @@ -54,7 +54,7 @@ attr(params, "robust_vcov") <- isTRUE(list(...)$robust) || "vcov" %in% names(list(...)) attr(params, "ignore_group") <- isFALSE(group_level) attr(params, "ran_pars") <- isFALSE(group_level) - attr(params, "show_summary") <- isTRUE(summary) + attr(params, "show_summary") <- isTRUE(include_info) attr(params, "log_link") <- isTRUE(grepl("log", info$link_function, fixed = TRUE)) attr(params, "logit_link") <- isTRUE(identical(info$link_function, "logit")) @@ -77,10 +77,12 @@ } - # for summaries, add R2 - if (isTRUE(summary) && requireNamespace("performance", quietly = TRUE)) { + # for additional infos, add R2, RMSE + if (isTRUE(include_info) && requireNamespace("performance", quietly = TRUE)) { rsq <- .safe(suppressWarnings(performance::r2(model))) attr(params, "r2") <- rsq + rmse <- .safe(performance::performance_rmse(model)) + attr(params, "rmse") <- rmse } diff --git a/man/model_parameters.Rd b/man/model_parameters.Rd index c5992cb58..c3e5dc2f1 100644 --- a/man/model_parameters.Rd +++ b/man/model_parameters.Rd @@ -402,12 +402,12 @@ warnings for the different functions in the \strong{parameters} package. However some messages providing additional information can be displayed or suppressed using \code{options()}: \itemize{ -\item \code{parameters_summary}: \code{options(parameters_summary = TRUE)} will override the -\code{summary} argument in \code{model_parameters()} and always show the model summary -for non-mixed models. -\item \code{parameters_mixed_summary}: \code{options(parameters_mixed_summary = TRUE)} will -override the \code{summary} argument in \code{model_parameters()} for mixed models, and -will then always show the model summary. +\item \code{parameters_info}: \code{options(parameters_info = TRUE)} will override the +\code{include_info} argument in \code{model_parameters()} and always show the model +summary for non-mixed models. +\item \code{parameters_mixed_info}: \code{options(parameters_mixed_info = TRUE)} will +override the \code{include_info} argument in \code{model_parameters()} for mixed +models, and will then always show the model summary. \item \code{parameters_cimethod}: \code{options(parameters_cimethod = TRUE)} will show the additional information about the approximation method used to calculate confidence intervals and p-values. Set to \code{FALSE} to hide this message when diff --git a/man/model_parameters.averaging.Rd b/man/model_parameters.averaging.Rd index 5a001d7be..c9c8cbdd1 100644 --- a/man/model_parameters.averaging.Rd +++ b/man/model_parameters.averaging.Rd @@ -30,6 +30,7 @@ exponentiate = FALSE, p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, @@ -43,6 +44,7 @@ exponentiate = FALSE, p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, @@ -59,6 +61,7 @@ exponentiate = FALSE, p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, @@ -174,6 +177,7 @@ exponentiate = FALSE, p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, @@ -190,6 +194,7 @@ exponentiate = FALSE, p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, @@ -250,7 +255,9 @@ possible adjustment methods are \code{"tukey"}, \code{"scheffe"}, \code{"sidak"} and \code{"none"} to explicitly disable adjustment for \code{emmGrid} objects (from \strong{emmeans}).} -\item{summary}{Logical, if \code{TRUE}, prints summary information about the +\item{summary}{Deprecated, please use \code{info} instead.} + +\item{include_info}{Logical, if \code{TRUE}, prints summary information about the model (model formula, number of observations, residual standard deviation and more).} diff --git a/man/model_parameters.default.Rd b/man/model_parameters.default.Rd index 55fde59d6..132dc2d5d 100644 --- a/man/model_parameters.default.Rd +++ b/man/model_parameters.default.Rd @@ -17,12 +17,13 @@ standardize = NULL, exponentiate = FALSE, p_adjust = NULL, + vcov = NULL, + vcov_args = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, - vcov = NULL, - vcov_args = NULL, ... ) @@ -35,11 +36,12 @@ standardize = NULL, exponentiate = FALSE, p_adjust = NULL, + vcov = NULL, + vcov_args = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, - vcov = NULL, - vcov_args = NULL, verbose = TRUE, ... ) @@ -53,12 +55,13 @@ standardize = NULL, exponentiate = FALSE, p_adjust = NULL, + vcov = NULL, + vcov_args = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, - vcov = NULL, - vcov_args = NULL, ... ) @@ -122,7 +125,34 @@ possible adjustment methods are \code{"tukey"}, \code{"scheffe"}, \code{"sidak"} and \code{"none"} to explicitly disable adjustment for \code{emmGrid} objects (from \strong{emmeans}).} -\item{summary}{Logical, if \code{TRUE}, prints summary information about the +\item{vcov}{Variance-covariance matrix used to compute uncertainty estimates +(e.g., for robust standard errors). This argument accepts a covariance matrix, +a function which returns a covariance matrix, or a string which identifies +the function to be used to compute the covariance matrix. +\itemize{ +\item A covariance matrix +\item A function which returns a covariance matrix (e.g., \code{stats::vcov()}) +\item A string which indicates the kind of uncertainty estimates to return. +\itemize{ +\item Heteroskedasticity-consistent: \code{"vcovHC"}, \code{"HC"}, \code{"HC0"}, \code{"HC1"}, +\code{"HC2"}, \code{"HC3"}, \code{"HC4"}, \code{"HC4m"}, \code{"HC5"}. See \code{?sandwich::vcovHC}. +\item Cluster-robust: \code{"vcovCR"}, \code{"CR0"}, \code{"CR1"}, \code{"CR1p"}, \code{"CR1S"}, +\code{"CR2"}, \code{"CR3"}. See \code{?clubSandwich::vcovCR}. +\item Bootstrap: \code{"vcovBS"}, \code{"xy"}, \code{"residual"}, \code{"wild"}, \code{"mammen"}, +\code{"webb"}. See \code{?sandwich::vcovBS}. +\item Other \code{sandwich} package functions: \code{"vcovHAC"}, \code{"vcovPC"}, \code{"vcovCL"}, +\code{"vcovPL"}. +} +}} + +\item{vcov_args}{List of arguments to be passed to the function identified by +the \code{vcov} argument. This function is typically supplied by the \strong{sandwich} +or \strong{clubSandwich} packages. Please refer to their documentation (e.g., +\code{?sandwich::vcovHAC}) to see the list of available arguments.} + +\item{summary}{Deprecated, please use \code{info} instead.} + +\item{include_info}{Logical, if \code{TRUE}, prints summary information about the model (model formula, number of observations, residual standard deviation and more).} @@ -150,31 +180,6 @@ names.} \item{verbose}{Toggle warnings and messages.} -\item{vcov}{Variance-covariance matrix used to compute uncertainty estimates -(e.g., for robust standard errors). This argument accepts a covariance matrix, -a function which returns a covariance matrix, or a string which identifies -the function to be used to compute the covariance matrix. -\itemize{ -\item A covariance matrix -\item A function which returns a covariance matrix (e.g., \code{stats::vcov()}) -\item A string which indicates the kind of uncertainty estimates to return. -\itemize{ -\item Heteroskedasticity-consistent: \code{"vcovHC"}, \code{"HC"}, \code{"HC0"}, \code{"HC1"}, -\code{"HC2"}, \code{"HC3"}, \code{"HC4"}, \code{"HC4m"}, \code{"HC5"}. See \code{?sandwich::vcovHC}. -\item Cluster-robust: \code{"vcovCR"}, \code{"CR0"}, \code{"CR1"}, \code{"CR1p"}, \code{"CR1S"}, -\code{"CR2"}, \code{"CR3"}. See \code{?clubSandwich::vcovCR}. -\item Bootstrap: \code{"vcovBS"}, \code{"xy"}, \code{"residual"}, \code{"wild"}, \code{"mammen"}, -\code{"webb"}. See \code{?sandwich::vcovBS}. -\item Other \code{sandwich} package functions: \code{"vcovHAC"}, \code{"vcovPC"}, \code{"vcovCL"}, -\code{"vcovPL"}. -} -}} - -\item{vcov_args}{List of arguments to be passed to the function identified by -the \code{vcov} argument. This function is typically supplied by the \strong{sandwich} -or \strong{clubSandwich} packages. Please refer to their documentation (e.g., -\code{?sandwich::vcovHAC}) to see the list of available arguments.} - \item{...}{Arguments passed to or from other methods. For instance, when \code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are passed down to \code{bootstrap_model()}. Further non-documented arguments are \code{digits}, diff --git a/man/model_parameters.merMod.Rd b/man/model_parameters.merMod.Rd index 52bb86415..a5c99f91e 100644 --- a/man/model_parameters.merMod.Rd +++ b/man/model_parameters.merMod.Rd @@ -47,10 +47,11 @@ p_adjust = NULL, wb_component = TRUE, summary = getOption("parameters_mixed_summary", FALSE), + include_info = getOption("parameters_mixed_info", FALSE), + include_sigma = FALSE, keep = NULL, drop = NULL, verbose = TRUE, - include_sigma = FALSE, ... ) @@ -66,14 +67,15 @@ group_level = FALSE, exponentiate = FALSE, p_adjust = NULL, + vcov = NULL, + vcov_args = NULL, wb_component = TRUE, summary = getOption("parameters_mixed_summary", FALSE), + include_info = getOption("parameters_mixed_info", FALSE), + include_sigma = FALSE, keep = NULL, drop = NULL, verbose = TRUE, - include_sigma = FALSE, - vcov = NULL, - vcov_args = NULL, ... ) @@ -92,10 +94,11 @@ p_adjust = NULL, wb_component = TRUE, summary = getOption("parameters_mixed_summary", FALSE), + include_info = getOption("parameters_mixed_info", FALSE), + include_sigma = FALSE, keep = NULL, drop = NULL, verbose = TRUE, - include_sigma = FALSE, ... ) @@ -114,10 +117,11 @@ p_adjust = NULL, wb_component = TRUE, summary = getOption("parameters_mixed_summary", FALSE), + include_info = getOption("parameters_mixed_info", FALSE), + include_sigma = FALSE, keep = NULL, drop = NULL, verbose = TRUE, - include_sigma = FALSE, ... ) @@ -133,14 +137,15 @@ group_level = FALSE, exponentiate = FALSE, p_adjust = NULL, + vcov = NULL, + vcov_args = NULL, wb_component = TRUE, summary = getOption("parameters_mixed_summary", FALSE), + include_info = getOption("parameters_mixed_info", FALSE), + include_sigma = FALSE, keep = NULL, drop = NULL, verbose = TRUE, - include_sigma = FALSE, - vcov = NULL, - vcov_args = NULL, ... ) @@ -154,6 +159,7 @@ exponentiate = FALSE, p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, @@ -316,7 +322,9 @@ between-effects, and cross-level interactions. By default, the \code{Component} column indicates, which parameters belong to the conditional or zero-inflation component of the model.} -\item{summary}{Logical, if \code{TRUE}, prints summary information about the +\item{summary}{Deprecated, please use \code{info} instead.} + +\item{include_info}{Logical, if \code{TRUE}, prints summary information about the model (model formula, number of observations, residual standard deviation and more).} diff --git a/man/model_parameters.mlm.Rd b/man/model_parameters.mlm.Rd index 01dfb5acf..54d2ee308 100644 --- a/man/model_parameters.mlm.Rd +++ b/man/model_parameters.mlm.Rd @@ -35,6 +35,7 @@ exponentiate = FALSE, p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, @@ -67,6 +68,7 @@ exponentiate = FALSE, p_adjust = NULL, summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, @@ -166,7 +168,9 @@ interest mainly is to get a "tidy" data frame of model summaries, it is recommended to set \code{pretty_names = FALSE} to speed up computation of the summary table.} -\item{summary}{Logical, if \code{TRUE}, prints summary information about the +\item{summary}{Deprecated, please use \code{info} instead.} + +\item{include_info}{Logical, if \code{TRUE}, prints summary information about the model (model formula, number of observations, residual standard deviation and more).} diff --git a/man/model_parameters.zcpglm.Rd b/man/model_parameters.zcpglm.Rd index bb91a300c..c9d67ae9d 100644 --- a/man/model_parameters.zcpglm.Rd +++ b/man/model_parameters.zcpglm.Rd @@ -14,9 +14,10 @@ standardize = NULL, exponentiate = FALSE, p_adjust = NULL, + summary = getOption("parameters_summary", FALSE), + include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, - summary = getOption("parameters_summary", FALSE), verbose = TRUE, ... ) @@ -88,6 +89,12 @@ possible adjustment methods are \code{"tukey"}, \code{"scheffe"}, \code{"sidak"} and \code{"none"} to explicitly disable adjustment for \code{emmGrid} objects (from \strong{emmeans}).} +\item{summary}{Deprecated, please use \code{info} instead.} + +\item{include_info}{Logical, if \code{TRUE}, prints summary information about the +model (model formula, number of observations, residual standard deviation +and more).} + \item{keep}{Character containing a regular expression pattern that describes the parameters that should be included (for \code{keep}) or excluded (for \code{drop}) in the returned data frame. \code{keep} may also be a @@ -110,10 +117,6 @@ names.} \item{drop}{See \code{keep}.} -\item{summary}{Logical, if \code{TRUE}, prints summary information about the -model (model formula, number of observations, residual standard deviation -and more).} - \item{verbose}{Toggle warnings and messages.} \item{...}{Arguments passed to or from other methods. For instance, when diff --git a/man/print.compare_parameters.Rd b/man/print.compare_parameters.Rd index 7adb416bc..d74c26307 100644 --- a/man/print.compare_parameters.Rd +++ b/man/print.compare_parameters.Rd @@ -212,12 +212,12 @@ warnings for the different functions in the \strong{parameters} package. However some messages providing additional information can be displayed or suppressed using \code{options()}: \itemize{ -\item \code{parameters_summary}: \code{options(parameters_summary = TRUE)} will override the -\code{summary} argument in \code{model_parameters()} and always show the model summary -for non-mixed models. -\item \code{parameters_mixed_summary}: \code{options(parameters_mixed_summary = TRUE)} will -override the \code{summary} argument in \code{model_parameters()} for mixed models, and -will then always show the model summary. +\item \code{parameters_info}: \code{options(parameters_info = TRUE)} will override the +\code{include_info} argument in \code{model_parameters()} and always show the model +summary for non-mixed models. +\item \code{parameters_mixed_info}: \code{options(parameters_mixed_info = TRUE)} will +override the \code{include_info} argument in \code{model_parameters()} for mixed +models, and will then always show the model summary. \item \code{parameters_cimethod}: \code{options(parameters_cimethod = TRUE)} will show the additional information about the approximation method used to calculate confidence intervals and p-values. Set to \code{FALSE} to hide this message when diff --git a/man/print.parameters_model.Rd b/man/print.parameters_model.Rd index e3618d06e..d3038109c 100644 --- a/man/print.parameters_model.Rd +++ b/man/print.parameters_model.Rd @@ -253,12 +253,12 @@ warnings for the different functions in the \strong{parameters} package. However some messages providing additional information can be displayed or suppressed using \code{options()}: \itemize{ -\item \code{parameters_summary}: \code{options(parameters_summary = TRUE)} will override the -\code{summary} argument in \code{model_parameters()} and always show the model summary -for non-mixed models. -\item \code{parameters_mixed_summary}: \code{options(parameters_mixed_summary = TRUE)} will -override the \code{summary} argument in \code{model_parameters()} for mixed models, and -will then always show the model summary. +\item \code{parameters_info}: \code{options(parameters_info = TRUE)} will override the +\code{include_info} argument in \code{model_parameters()} and always show the model +summary for non-mixed models. +\item \code{parameters_mixed_info}: \code{options(parameters_mixed_info = TRUE)} will +override the \code{include_info} argument in \code{model_parameters()} for mixed +models, and will then always show the model summary. \item \code{parameters_cimethod}: \code{options(parameters_cimethod = TRUE)} will show the additional information about the approximation method used to calculate confidence intervals and p-values. Set to \code{FALSE} to hide this message when diff --git a/tests/testthat/_snaps/model_parameters.fixest.md b/tests/testthat/_snaps/model_parameters.fixest.md index 6106b566f..c095a3fe0 100644 --- a/tests/testthat/_snaps/model_parameters.fixest.md +++ b/tests/testthat/_snaps/model_parameters.fixest.md @@ -1,7 +1,7 @@ # model_parameters.fixest Code - model_parameters(m1, summary = TRUE, verbose = FALSE) + model_parameters(m1, include_info = TRUE, verbose = FALSE) Output # Fixed Effects @@ -11,6 +11,7 @@ phq4 | -3.66 | 0.67 | [-4.98, -2.34] | -5.45 | < .001 Model: QoL ~ time + phq4 (564 Observations) - Residual standard deviation: 12.365 (df = 561) + Sigma: 12.365 (df = 561) r2: 0.743; ar2: 0.613; wr2: 0.180; war2: 0.175 + RMSE : 10.069 diff --git a/tests/testthat/_snaps/model_parameters.glm.md b/tests/testthat/_snaps/model_parameters.glm.md index c4b65f584..716d9eeb0 100644 --- a/tests/testthat/_snaps/model_parameters.glm.md +++ b/tests/testthat/_snaps/model_parameters.glm.md @@ -9,8 +9,9 @@ wt | -5.34 | 0.56 | [-6.49, -4.20] | -9.56 | < .001 Model: mpg ~ wt (32 Observations) - Residual standard deviation: 3.046 (df = 30) + Sigma: 3.046 (df = 30) R2: 0.753; adjusted R2: 0.745 + RMSE : 2.949 --- diff --git a/tests/testthat/_snaps/model_parameters.mixed.md b/tests/testthat/_snaps/model_parameters.mixed.md index 9955f33b9..c89fefb71 100644 --- a/tests/testthat/_snaps/model_parameters.mixed.md +++ b/tests/testthat/_snaps/model_parameters.mixed.md @@ -52,7 +52,7 @@ --- Code - model_parameters(m1, effects = "fixed", summary = TRUE) + model_parameters(m1, effects = "fixed", include_info = TRUE) Output # Fixed Effects @@ -62,8 +62,9 @@ cyl | 0.40 | 0.08 | [ 0.25, 0.56] | 5.29 | < .001 Model: wt ~ cyl (32 Observations) - Residual standard deviation: 0.594 (df = 28) + Sigma: 0.594 (df = 28) Conditional R2: 0.628; Marginal R2: 0.550 + RMSE : 0.564 Message Uncertainty intervals (equal-tailed) and p-values (two-tailed) computed diff --git a/tests/testthat/_snaps/printing.md b/tests/testthat/_snaps/printing.md index c3e657e4e..750751645 100644 --- a/tests/testthat/_snaps/printing.md +++ b/tests/testthat/_snaps/printing.md @@ -92,8 +92,9 @@ Species [virginica] * Petal Length | 0.45 | 0.29 | [-0.12, 1.03] | 1.56 | 0.120 Model: Sepal.Length ~ Species * Petal.Length (150 Observations) - Residual standard deviation: 0.336 (df = 144) + Sigma: 0.336 (df = 144) R2: 0.840; adjusted R2: 0.835 + RMSE : 0.330 Message Uncertainty intervals (equal-tailed) and p-values (two-tailed) computed diff --git a/tests/testthat/test-model_parameters.fixest.R b/tests/testthat/test-model_parameters.fixest.R index f34f75866..567ba491f 100644 --- a/tests/testthat/test-model_parameters.fixest.R +++ b/tests/testthat/test-model_parameters.fixest.R @@ -35,7 +35,7 @@ test_that("model_parameters.fixest", { # currently, a bug for fixest 10.4 on R >= 4.3 # skip_if_not(getRversion() < "4.2.0") expect_snapshot( - model_parameters(m1, summary = TRUE, verbose = FALSE) + model_parameters(m1, include_info = TRUE, verbose = FALSE) ) # Poission, df = Inf diff --git a/tests/testthat/test-model_parameters.glm.R b/tests/testthat/test-model_parameters.glm.R index c5cebbb75..969a7a6f3 100644 --- a/tests/testthat/test-model_parameters.glm.R +++ b/tests/testthat/test-model_parameters.glm.R @@ -36,10 +36,10 @@ test_that("print digits model_parameters.lm", { skip_if_not_installed("performance") model <- lm(mpg ~ wt, data = mtcars) - params <- model_parameters(model, summary = TRUE, verbose = FALSE) + params <- model_parameters(model, include_info = TRUE, verbose = FALSE) expect_snapshot(params) - params <- model_parameters(model, summary = FALSE, verbose = FALSE) + params <- model_parameters(model, include_info = FALSE, verbose = FALSE) expect_snapshot(params) }) diff --git a/tests/testthat/test-model_parameters.mixed.R b/tests/testthat/test-model_parameters.mixed.R index 7cebab25e..4f7ddc432 100644 --- a/tests/testthat/test-model_parameters.mixed.R +++ b/tests/testthat/test-model_parameters.mixed.R @@ -129,5 +129,5 @@ test_that("print-model_parameters", { skip_if_not_installed("merDeriv") expect_snapshot(model_parameters(m1, effects = "all")) - expect_snapshot(model_parameters(m1, effects = "fixed", summary = TRUE)) + expect_snapshot(model_parameters(m1, effects = "fixed", include_info = TRUE)) }) diff --git a/tests/testthat/test-p_adjust.R b/tests/testthat/test-p_adjust.R index aada4dacd..95496035b 100644 --- a/tests/testthat/test-p_adjust.R +++ b/tests/testthat/test-p_adjust.R @@ -23,7 +23,7 @@ test_that("model_parameters, p-adjust after keep/drop", { ) expect_message( - mp <- model_parameters(model, summary = TRUE, keep = c("wt", "hp"), p_adjust = "bonferroni"), + mp <- model_parameters(model, include_info = TRUE, keep = c("wt", "hp"), p_adjust = "bonferroni"), "more than 1 element" ) expect_equal( @@ -34,7 +34,7 @@ test_that("model_parameters, p-adjust after keep/drop", { ) expect_message( - mp <- model_parameters(model, summary = TRUE, keep = c("cyl", "gear"), p_adjust = "bonferroni"), + mp <- model_parameters(model, include_info = TRUE, keep = c("cyl", "gear"), p_adjust = "bonferroni"), "more than 1 element" ) expect_equal( diff --git a/tests/testthat/test-printing.R b/tests/testthat/test-printing.R index ceff6e642..462689fa7 100644 --- a/tests/testthat/test-printing.R +++ b/tests/testthat/test-printing.R @@ -25,7 +25,7 @@ withr::with_options( # snapshot breaks between R CMD check "classic" and "strict" skip_if_not_installed("performance") model <- lm(Sepal.Length ~ Species * Petal.Length, data = iris) - out <- model_parameters(model, summary = TRUE) + out <- model_parameters(model, include_info = TRUE) expect_snapshot(print(out)) }) diff --git a/vignettes/model_parameters.Rmd b/vignettes/model_parameters.Rmd index 99946751f..28ba6f093 100644 --- a/vignettes/model_parameters.Rmd +++ b/vignettes/model_parameters.Rmd @@ -1,6 +1,6 @@ --- title: "Summary of Model Parameters" -output: +output: rmarkdown::html_vignette: toc: true fig_width: 10.08 @@ -10,7 +10,7 @@ vignette: > %\VignetteIndexEntry{Summary of Model Parameters} \usepackage[utf8]{inputenc} %\VignetteEngine{knitr::rmarkdown} -editor_options: +editor_options: chunk_output_type: console bibliography: bibliography.bib --- @@ -150,9 +150,9 @@ glm(vs ~ poly(mpg, 2) + cyl, data = mtcars, family = binomial()) |> ``` ```{r} -# show Odds Ratios and include model summary +# show Odds Ratios and include model info glm(vs ~ poly(mpg, 2) + cyl, data = mtcars, family = binomial()) |> - parameters(exponentiate = TRUE, summary = TRUE) + parameters(exponentiate = TRUE, include_info = TRUE) ``` ### Mixed Models @@ -269,7 +269,7 @@ parameters( The **parameters** package extends the support to structural models. -### Principal Component Analysis (PCA) and Exploratory Factor Analysis (EFA) +### Principal Component Analysis (PCA) and Exploratory Factor Analysis (EFA) ```{r eval=all(successfully_loaded[c("psych", "nFactors")])} psych::pca(mtcars, nfactors = 3) |> diff --git a/vignettes/model_parameters_print.Rmd b/vignettes/model_parameters_print.Rmd index c4a94810d..2a80f8f06 100644 --- a/vignettes/model_parameters_print.Rmd +++ b/vignettes/model_parameters_print.Rmd @@ -1,6 +1,6 @@ --- title: "Printing Model Parameters" -output: +output: rmarkdown::html_vignette: toc: true fig_width: 10.08 @@ -10,7 +10,7 @@ vignette: > %\VignetteIndexEntry{Printing Model Parameters} \usepackage[utf8]{inputenc} %\VignetteEngine{knitr::rmarkdown} -editor_options: +editor_options: chunk_output_type: console bibliography: bibliography.bib --- @@ -122,13 +122,13 @@ mp <- model_parameters(model) print(mp, split_component = FALSE) ``` -## Adding model summaries +## Adding model information -A model summary can be added to the table when `summary = TRUE` in the call to `model_parameters()`: +A model summary can be added to the table when `include_info = TRUE` in the call to `model_parameters()`: ```{r} model <- lm(Sepal.Length ~ Species * Petal.Length, data = iris) -model_parameters(model, summary = TRUE) +model_parameters(model, include_info = TRUE) ``` ## Including the reference level of categorical variables @@ -380,6 +380,6 @@ print(tab, table_width = 80) # More advances tables and markdown / HTML formatting -The `print_md()` as well as `print_html()` functions can be used to create markdown (for knitting to PDF or Word) and HTML tables. +The `print_md()` as well as `print_html()` functions can be used to create markdown (for knitting to PDF or Word) and HTML tables. Meanwhile, there are a lot of additional packages that allow users to have even more flexibility regarding table layouts. One package we can recommend is the [*modelsummary* package](https://vincentarelbundock.github.io/modelsummary/).