` inserts a line break inside a cell. See #' 'Examples'. #' #' * **A string indicating a pre-defined layout** #' #' `select` can be one of the following string values, to create one of the #' following pre-defined column layouts: #' #' - `"ci"`: Estimates and confidence intervals, no asterisks for p-values. #' This is equivalent to `select = "{estimate} ({ci})"`. #' - `"se"`: Estimates and standard errors, no asterisks for p-values. This is #' equivalent to `select = "{estimate} ({se})"`. #' - `"ci_p"`: Estimates, confidence intervals and asterisks for p-values. This #' is equivalent to `select = "{estimate}{stars} ({ci})"`. #' - `"se_p"`: Estimates, standard errors and asterisks for p-values. This is #' equivalent to `select = "{estimate}{stars} ({se})"`.. #' - `"ci_p2"`: Estimates, confidence intervals and numeric p-values, in two #' columns. This is equivalent to `select = "{estimate} ({ci})|{p}"`. #' - `"se_p2"`: Estimate, standard errors and numeric p-values, in two columns. #' This is equivalent to `select = "{estimate} ({se})|{p}"`. #' #' For `model_parameters()`, glue-like syntax is still experimental in the #' case of more complex models (like mixed models) and may not return expected #' results. #' @param show_sigma Logical, if `TRUE`, adds information about the residual #' standard deviation. #' @param show_formula Logical, if `TRUE`, adds the model formula to the output. #' @param caption Table caption as string. If `NULL`, depending on the model, #' either a default caption or no table caption is printed. Use `caption = ""` #' to suppress the table caption. #' @param footer Can either be `FALSE` or an empty string (i.e. `""`) to #' suppress the footer, `NULL` to print the default footer, or a string. The #' latter will combine the string value with the default footer. #' @param footer_digits Number of decimal places for values in the footer summary. #' @param groups Named list, can be used to group parameters in the printed output. #' List elements may either be character vectors that match the name of those #' parameters that belong to one group, or list elements can be row numbers #' of those parameter rows that should belong to one group. The names of the #' list elements will be used as group names, which will be inserted as "header #' row". A possible use case might be to emphasize focal predictors and control #' variables, see 'Examples'. Parameters will be re-ordered according to the #' order used in `groups`, while all non-matching parameters will be added #' to the end. #' @param column_width Width of table columns. Can be either `NULL`, a named #' numeric vector, or `"fixed"`. If `NULL`, the width for each table column is #' adjusted to the minimum required width. If a named numeric vector, value #' names are matched against column names, and for each match, the specified #' width is used. If `"fixed"`, and table is split into multiple components, #' columns across all table components are adjusted to have the same width. #' @param digits,ci_digits,p_digits Number of digits for rounding or #' significant figures. May also be `"signif"` to return significant #' figures or `"scientific"` to return scientific notation. Control the #' number of digits by adding the value as suffix, e.g. `digits = "scientific4"` #' to have scientific notation with 4 decimal places, or `digits = "signif5"` #' for 5 significant figures (see also [signif()]). #' @param pretty_names Can be `TRUE`, which will return "pretty" (i.e. more human #' readable) parameter names. Or `"labels"`, in which case value and variable #' labels will be used as parameters names. The latter only works for "labelled" #' data, i.e. if the data used to fit the model had `"label"` and `"labels"` #' attributes. See also section _Global Options to Customize Messages when Printing_. #' @param include_reference Logical, if `TRUE`, the reference level of factors will #' be added to the parameters table. This is only relevant for models with #' categorical predictors. The coefficient for the reference level is always #' `0` (except when `exponentiate = TRUE`, then the coefficient will be `1`), #' so this is just for completeness. #' @param ... Arguments passed down to [`format.parameters_model()`], #' [`insight::format_table()`] and [`insight::export_table()`] #' @inheritParams insight::format_table #' @inheritParams compare_parameters #' @inheritParams display.parameters_model #' #' @inheritSection format_parameters Interpretation of Interaction Terms #' @inheritSection model_parameters Labeling the Degrees of Freedom #' #' @section Global Options to Customize Messages and Tables when Printing: #' The `verbose` argument can be used to display or silence messages and #' warnings for the different functions in the **parameters** package. However, #' some messages providing additional information can be displayed or suppressed #' using `options()`: #' #' - `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_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 #' confidence intervals and p-values. Set to `FALSE` to hide this message when #' printing `model_parameters()` objects. #' #' - `parameters_exponentiate`: `options(parameters_exponentiate = TRUE)` will #' show the additional information on how to interpret coefficients of models #' with log-transformed response variables or with log-/logit-links when the #' `exponentiate` argument in `model_parameters()` is not `TRUE`. Set this option #' to `FALSE` to hide this message when printing `model_parameters()` objects. #' #' There are further options that can be used to modify the default behaviour #' for printed outputs: #' #' - `parameters_labels`: `options(parameters_labels = TRUE)` will use variable #' and value labels for pretty names, if data is labelled. If no labels #' available, default pretty names are used. #' #' - `parameters_interaction`: `options(parameters_interaction =
({se})|{p}") #' print_html(result) #' } #' @export print.parameters_model <- function(x, pretty_names = TRUE, split_components = TRUE, select = NULL, caption = NULL, footer = NULL, digits = 2, ci_digits = digits, p_digits = 3, footer_digits = 3, show_sigma = FALSE, show_formula = FALSE, zap_small = FALSE, groups = NULL, column_width = NULL, ci_brackets = c("[", "]"), include_reference = FALSE, ...) { # save original input orig_x <- x # check options --------------- # check if pretty names should be replaced by value labels # (if we have labelled data) if (isTRUE(getOption("parameters_labels", FALSE)) || identical(pretty_names, "labels")) { attr(x, "pretty_names") <- attr(x, "pretty_labels", exact = TRUE) pretty_names <- TRUE } # select which columns to print if (is.null(select)) { select <- getOption("parameters_select") } # check if user supplied digits attributes if (missing(digits)) { digits <- .additional_arguments(x, "digits", digits) } if (missing(ci_digits)) { ci_digits <- .additional_arguments(x, "ci_digits", digits) } if (missing(p_digits)) { p_digits <- .additional_arguments(x, "p_digits", p_digits) } if (missing(footer_digits)) { footer_digits <- .additional_arguments(x, "footer_digits", footer_digits) } # table caption table_caption <- .print_caption(x, caption, format = "text") # main table formatted_table <- .print_core( x = x, pretty_names = pretty_names, split_components = split_components, select = select, digits = digits, ci_digits = ci_digits, p_digits = p_digits, zap_small = zap_small, ci_width = "auto", ci_brackets = ci_brackets, format = "text", groups = groups, include_reference = include_reference, ... ) # if we have multiple components, we can align colum width across components here if (!is.null(column_width) && all(column_width == "fixed") && is.list(formatted_table)) { column_width <- .find_min_colwidth(formatted_table) } # footer footer_stats <- .print_footer( x, digits = footer_digits, show_sigma = show_sigma, show_formula = show_formula ) # check if footer should be printed at all. can be FALSE, or "" to suppress footer if (isFALSE(footer)) { footer <- "" } if (!identical(footer, "")) { if (is.null(footer)) { footer <- footer_stats } else { footer <- paste0("\n", footer, "\n", footer_stats) } } # get attributes verbose <- .additional_arguments(x, "verbose", TRUE) # print main table cat(insight::export_table( formatted_table, format = "text", caption = table_caption, footer = footer, width = column_width, ... )) # inform about CI and df approx. if (isTRUE(verbose)) { .print_footer_cimethod(x) .print_footer_exp(x) } invisible(orig_x) } #' @rdname print.parameters_model #' @export summary.parameters_model <- function(object, ...) { print( x = object, select = "minimal", show_sigma = TRUE, show_formula = TRUE, ... ) } #' @export print.parameters_simulate <- print.parameters_model #' @export print.parameters_brms_meta <- print.parameters_model # Random effects ------------------ #' @export print.parameters_coef <- function(x, ...) { cat(insight::export_table(format(x, ...), ...)) } #' @export print.parameters_random <- function(x, digits = 2, ...) { .print_random_parameters(x, digits = digits) invisible(x) } # helper -------------------- .print_core <- function(x, pretty_names = TRUE, split_components = TRUE, select = NULL, digits = 2, ci_digits = digits, p_digits = 3, zap_small = FALSE, ci_width = "auto", ci_brackets = TRUE, format = "text", groups = NULL, include_reference = FALSE, ...) { format( x, pretty_names = pretty_names, split_components = split_components, select = select, digits = digits, ci_digits = ci_digits, p_digits = p_digits, ci_width = ci_width, ci_brackets = ci_brackets, zap_small = zap_small, format = format, groups = groups, include_reference = include_reference, ... ) } .print_footer <- function(x, digits = 3, show_sigma = FALSE, show_formula = FALSE, format = "text") { # get attributes model_sigma <- attributes(x)$sigma show_summary <- isTRUE(attributes(x)$show_summary) verbose <- .additional_arguments(x, "verbose", TRUE) # override defaults. if argument "summary" is called in "model_parameters()", # this overrides the defaults... 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)) { show_sigma <- FALSE } .format_footer( x, digits = digits, verbose = verbose, show_sigma = show_sigma, show_formula = show_formula, show_r2 = show_r2, show_rmse = show_rmse, format = format ) } .print_caption <- function(x, caption = NULL, format = "text") { no_caption <- attributes(x)$no_caption # no table-title for certain model tables, indicated by the no_caption attribute if (isTRUE(no_caption)) { return(NULL) } title_attribute <- attributes(x)$title[1] # check effects and component parts if (!is.null(x$Effects) && all(x$Effects == "random")) { eff_name <- "Random" } else { eff_name <- "Fixed" } if (!is.null(x$Component) && all(x$Component == "zero_inflated")) { zero_inflated <- " (Zero-Inflation Component)" } else { zero_inflated <- "" } # caption = NULL, set default for HTML tables if (identical(format, "html") && is.null(caption)) { if (isTRUE(attributes(x)$is_ggeffects)) { table_caption <- title_attribute } else { table_caption <- "Model Summary" } } else if (isTRUE(attributes(x)$ordinal_model)) { table_caption <- "" # caption is NULL, set default title, using title-attribute } else if (!is.null(title_attribute) && is.null(caption)) { if (length(title_attribute) == 1 && title_attribute == "") { table_caption <- NULL } else { table_caption <- title_attribute } # if caption is not empty, use it as title } else if (!is.null(caption) && caption != "") { table_caption <- caption # no table-title if caption is empty string } else if (!is.null(caption) && caption == "") { table_caption <- NULL # default title for sub-components of models } else if (identical(format, "text")) { table_caption <- c(paste0("# ", eff_name, " Effects", zero_inflated), "blue") } else { table_caption <- paste0(eff_name, " Effects", zero_inflated) } table_caption } #' @keywords internal .print_random_parameters <- function(random_params, digits = 2) { insight::print_color("# Random Effects\n\n", "blue") # create SD random_params$SD <- NA var_components <- random_params$Description %in% c("Within-Group Variance", "Between-Group Variance") random_params$SD[var_components] <- sqrt(random_params$Value[var_components]) # format values random_params$Value <- format(sprintf("%g", round(random_params$Value, digits = digits)), justify = "right") random_params$SD[var_components] <- format( sprintf("(%g)", round(random_params$SD[var_components], digits = digits)), justify = "right" ) # create summary-information for each component random_params$Line <- "" random_params$Term[is.na(random_params$Term)] <- "" random_params$SD[is.na(random_params$SD)] <- "" non_empty <- random_params$Term != "" & random_params$Type != "" # nolint random_params$Line[non_empty] <- sprintf("%s (%s)", random_params$Type[non_empty], random_params$Term[non_empty]) non_empty <- random_params$Term != "" & random_params$Type == "" # nolint random_params$Line[non_empty] <- sprintf("%s", random_params$Term[non_empty]) # final fix, indentions random_params$Line <- sprintf(" %s", format(random_params$Line)) max_len <- max(nchar(random_params$Line)) + 2 out <- split(random_params, factor(random_params$Description, levels = unique(random_params$Description))) for (i in out) { if ("Within-Group Variance" %in% i$Description) { insight::print_color(format("Within-Group Variance", width = max_len), color = "blue") cat(sprintf("%s %s\n", i$Value, i$SD)) } else if ("Between-Group Variance" %in% i$Description) { insight::print_color("Between-Group Variance\n", "blue") for (j in seq_len(nrow(i))) { cat(sprintf("%s %s %s\n", i$Line[j], i$Value[j], i$SD[j])) } } else if ("Correlations" %in% i$Description) { insight::print_color("Correlations\n", "blue") for (j in seq_len(nrow(i))) { cat(sprintf("%s %s\n", i$Line[j], i$Value[j])) } } else if ("N" %in% i$Description) { insight::print_color("N (groups per factor)\n", "blue") for (j in seq_len(nrow(i))) { cat(sprintf(" %s%s\n", format(i$Term[j], width = max_len - 2), i$Value[j])) } } else if ("Observations" %in% i$Description) { insight::print_color(format("Observations", width = max_len), color = "blue") cat(sprintf("%s\n", i$Value)) } } } .find_min_colwidth <- function(formatted_table) { shared_cols <- unique(unlist(lapply(formatted_table, colnames))) col_width <- rep(NA, length(shared_cols)) for (i in seq_along(shared_cols)) { col_width[i] <- max(unlist(lapply(formatted_table, function(j) { column <- j[[shared_cols[i]]] if (is.null(column)) { NA } else { max(nchar(column)) } }))) } stats::na.omit(stats::setNames(col_width, shared_cols)) } parameters/R/methods_htest.R 0000644 0001762 0000144 00000053315 14736731407 015636 0 ustar ligges users #' Parameters from hypothesis tests #' #' Parameters of h-tests (correlations, t-tests, chi-squared, ...). #' #' @param model Object of class `htest` or `pairwise.htest`. #' @param bootstrap Should estimates be bootstrapped? #' @param ci Level of confidence intervals for effect size statistic. Currently #' only applies to objects from `chisq.test()` or `oneway.test()`. #' @inheritParams model_parameters.default #' @inheritParams model_parameters.aov #' @inherit effectsize::effectsize details #' #' @examples #' #' model <- cor.test(mtcars$mpg, mtcars$cyl, method = "pearson") #' model_parameters(model) #' #' model <- t.test(iris$Sepal.Width, iris$Sepal.Length) #' model_parameters(model, es_type = "hedges_g") #' #' model <- t.test(mtcars$mpg ~ mtcars$vs) #' model_parameters(model, es_type = "hedges_g") #' #' model <- t.test(iris$Sepal.Width, mu = 1) #' model_parameters(model, es_type = "cohens_d") #' #' data(airquality) #' airquality$Month <- factor(airquality$Month, labels = month.abb[5:9]) #' model <- pairwise.t.test(airquality$Ozone, airquality$Month) #' model_parameters(model) #' #' smokers <- c(83, 90, 129, 70) #' patients <- c(86, 93, 136, 82) #' model <- suppressWarnings(pairwise.prop.test(smokers, patients)) #' model_parameters(model) #' #' model <- suppressWarnings(chisq.test(table(mtcars$am, mtcars$cyl))) #' model_parameters(model, es_type = "cramers_v") #' #' @return A data frame of indices related to the model's parameters. #' #' @export model_parameters.htest <- function(model, ci = 0.95, alternative = NULL, bootstrap = FALSE, es_type = NULL, verbose = TRUE, ...) { if (bootstrap) { insight::format_error("Bootstrapped h-tests are not yet implemented.") } else { parameters <- .extract_parameters_htest( model, es_type = es_type, ci = ci, alternative = alternative, verbose = verbose, ... ) } if (!is.null(parameters$Method)) { parameters$Method <- insight::trim_ws(gsub("with continuity correction", "", parameters$Method, fixed = TRUE)) } # save alternative parameters$Alternative <- model$alternative parameters <- .add_htest_parameters_attributes(parameters, model, ci, ...) class(parameters) <- c("parameters_model", "see_parameters_model", class(parameters)) parameters } #' @export standard_error.htest <- function(model, ...) { NULL } #' @export p_value.htest <- function(model, ...) { model$p.value } # .pairwise.htest -------------------- #' @export model_parameters.pairwise.htest <- function(model, verbose = TRUE, ...) { m <- model$p.value parameters <- data.frame( Group1 = rep(rownames(m), each = ncol(m)), Group2 = rep(colnames(m), times = nrow(m)), p = as.numeric(t(m)), stringsAsFactors = FALSE ) parameters <- stats::na.omit(parameters) parameters <- .add_htest_attributes(parameters, model, p_adjust = model$p.adjust.method) class(parameters) <- c("parameters_model", "see_parameters_model", class(parameters)) parameters } # survey-table -------------------- #' @export model_parameters.svytable <- function(model, verbose = TRUE, ...) { model_parameters(summary(model)$statistic, verbose = verbose, ...) } # ==== extract parameters ==== #' @keywords internal .extract_parameters_htest <- function(model, es_type = NULL, ci = 0.95, alternative = NULL, verbose = TRUE, ...) { m_info <- insight::model_info(model, verbose = FALSE) if (!is.null(model$method) && startsWith(model$method, "Box-")) { # Box-Pierce --------- out <- .extract_htest_boxpierce(model) } else if (m_info$is_correlation) { # correlation --------- out <- .extract_htest_correlation(model) } else if (.is_levenetest(model)) { # levene's test --------- out <- .extract_htest_levenetest(model) } else if (m_info$is_ttest) { # t-test ----------- out <- .extract_htest_ttest(model) } else if (m_info$is_ranktest) { # rank-test (kruskal / wilcox / friedman) ----------- out <- .extract_htest_ranktest(model) } else if (m_info$is_onewaytest) { # one-way test ----------- out <- .extract_htest_oneway(model) } else if (m_info$is_chi2test) { # chi2- and mcnemar-test ----------- out <- .extract_htest_chi2(model) } else if (m_info$is_proptest) { # test of proportion -------------- out <- .extract_htest_prop(model) } else if (m_info$is_binomtest) { # exact binomial test -------------- out <- .extract_htest_binom(model) } else if (m_info$is_ftest) { # F test for equal variances -------------- out <- .extract_htest_vartest(model) } else { insight::format_error("`model_parameters()` not implemented for such h-tests yet.") } out <- .add_effectsize_htest(model, out, es_type = es_type, ci = ci, alternative = alternative, verbose = verbose, ... ) row.names(out) <- NULL out } # extract htest Box-Pierce ---------------------- #' @keywords internal .extract_htest_boxpierce <- function(model) { data.frame( Parameter = model$data.name, Chi2 = model$statistic, df_error = model$parameter, p = model$p.value, Method = model$method, stringsAsFactors = FALSE ) } # extract htest correlation ---------------------- #' @keywords internal .extract_htest_correlation <- function(model) { data_names <- unlist(strsplit(model$data.name, " (and|by) ")) out <- data.frame( Parameter1 = data_names[1], Parameter2 = data_names[2], stringsAsFactors = FALSE ) if (model$method == "Pearson's Chi-squared test") { out$Chi2 <- model$statistic out$df_error <- model$parameter out$p <- model$p.value } else if (grepl("Pearson", model$method, fixed = TRUE)) { out$r <- model$estimate out$t <- model$statistic out$df_error <- model$parameter out$p <- model$p.value out$CI_low <- model$conf.int[1] out$CI_high <- model$conf.int[2] } else if (grepl("Spearman", model$method, fixed = TRUE)) { out$rho <- model$estimate out$S <- model$statistic out$df_error <- model$parameter out$p <- model$p.value } else { out$tau <- model$estimate out$z <- model$statistic out$df_error <- model$parameter out$p <- model$p.value } out$Method <- model$method # reorder col_order <- c( "Parameter1", "Parameter2", "Parameter", "r", "rho", "tau", "CI_low", "CI_high", "t", "z", "S", "df_error", "p", "Method", "method" ) out <- out[col_order[col_order %in% names(out)]] out } # extract htest ranktest ---------------------- #' @keywords internal .extract_htest_ranktest <- function(model) { # survey if (grepl("design-based", tolower(model$method), fixed = TRUE)) { data_names <- gsub("~", "", unlist(strsplit(model$data.name, " + ", fixed = TRUE)), fixed = TRUE) out <- data.frame( Parameter1 = data_names[1], Parameter2 = data_names[2], Statistic = model$statistic[[1]], df_error = model$parameter[[1]], Method = model$method, p = model$p.value[[1]], stringsAsFactors = FALSE ) out$Method <- gsub("KruskalWallis", "Kruskal-Wallis", out$Method, fixed = TRUE) colnames(out)[colnames(out) == "Statistic"] <- names(model$statistic)[1] } else { if (grepl(" (and|by) ", model$data.name)) { data_names <- unlist(strsplit(model$data.name, " (and|by) ")) out <- data.frame( Parameter1 = data_names[1], Parameter2 = data_names[2], stringsAsFactors = FALSE ) } else { out <- data.frame( Parameter = model$data.name, stringsAsFactors = FALSE ) } if (grepl("Wilcoxon", model$method, fixed = TRUE)) { out$W <- model$statistic[[1]] out$df_error <- model$parameter[[1]] out$p <- model$p.value[[1]] } else if (grepl("Kruskal-Wallis", model$method, fixed = TRUE) || grepl("Friedman", model$method, fixed = TRUE)) { out$Chi2 <- model$statistic[[1]] out$df_error <- model$parameter[[1]] out$p <- model$p.value[[1]] } out$Method <- model$method } out } # extract htest leveneTest ---------------------- #' @keywords internal .extract_htest_levenetest <- function(model) { data.frame( df = model$Df[1], df_error = model$Df[2], `F` = model$`F value`[1], # nolint p = model$`Pr(>F)`[1], Method = "Levene's Test for Homogeneity of Variance", stringsAsFactors = FALSE ) } # extract htest var.test ---------------------- #' @keywords internal .extract_htest_vartest <- function(model) { data.frame( Parameter = model$data.name, Estimate = model$estimate, df = model$parameter[1], df_error = model$parameter[2], `F` = model$statistic, # nolint CI_low = model$conf.int[1], CI_high = model$conf.int[2], p = model$p.value, Method = "F test to compare two variances", stringsAsFactors = FALSE ) } # extract htest ttest ---------------------- #' @keywords internal .extract_htest_ttest <- function(model, standardized_d = NULL, hedges_g = NULL) { # survey if (grepl("design-based", tolower(model$method), fixed = TRUE)) { data_names <- unlist(strsplit(model$data.name, " ~ ", fixed = TRUE)) out <- data.frame( Parameter1 = data_names[1], Parameter2 = data_names[2], Difference = model$estimate[[1]], t = model$statistic[[1]], df_error = model$parameter[[1]], Method = model$method, p = model$p.value[[1]], stringsAsFactors = FALSE ) out$Method <- gsub("KruskalWallis", "Kruskal-Wallis", out$Method, fixed = TRUE) colnames(out)[colnames(out) == "Statistic"] <- names(model$statistic)[1] } else { paired_test <- startsWith(model$method, "Paired") && length(model$estimate) == 1 if (grepl(" and ", model$data.name, fixed = TRUE) && isFALSE(paired_test)) { data_names <- unlist(strsplit(model$data.name, " and ", fixed = TRUE)) out <- data.frame( Parameter1 = data_names[1], Parameter2 = data_names[2], Mean_Parameter1 = model$estimate[1], Mean_Parameter2 = model$estimate[2], Difference = model$estimate[1] - model$estimate[2], CI_low = model$conf.int[1], CI_high = model$conf.int[2], t = model$statistic, df_error = model$parameter, p = model$p.value, Method = model$method, stringsAsFactors = FALSE ) attr(out, "mean_group_values") <- gsub("mean in group ", "", names(model$estimate), fixed = TRUE) } else if (isTRUE(paired_test)) { data_names <- unlist(strsplit(model$data.name, " (and|by) ")) out <- data.frame( Parameter = data_names[1], Group = data_names[2], Difference = model$estimate, t = model$statistic, df_error = model$parameter, p = model$p.value, CI_low = model$conf.int[1], CI_high = model$conf.int[2], Method = model$method, stringsAsFactors = FALSE ) } else if (grepl(" by ", model$data.name, fixed = TRUE)) { if (length(model$estimate) == 1) { data_names <- unlist(strsplit(model$data.name, " by ", fixed = TRUE)) out <- data.frame( Parameter = data_names[1], Group = data_names[2], Difference = model$estimate, CI = 0.95, CI_low = as.vector(model$conf.int[, 1]), CI_high = as.vector(model$conf.int[, 2]), t = model$statistic, df_error = model$parameter, p = model$p.value, Method = model$method, stringsAsFactors = FALSE ) } else { data_names <- unlist(strsplit(model$data.name, " by ", fixed = TRUE)) out <- data.frame( Parameter = data_names[1], Group = data_names[2], Mean_Group1 = model$estimate[1], Mean_Group2 = model$estimate[2], Difference = model$estimate[1] - model$estimate[2], CI_low = model$conf.int[1], CI_high = model$conf.int[2], t = model$statistic, df_error = model$parameter, p = model$p.value, Method = model$method, stringsAsFactors = FALSE ) attr(out, "mean_group_values") <- gsub("mean in group ", "", names(model$estimate), fixed = TRUE) } } else { out <- data.frame( Parameter = model$data.name, Mean = model$estimate, mu = model$null.value, Difference = model$estimate - model$null.value, CI_low = model$conf.int[1], CI_high = model$conf.int[2], t = model$statistic, df_error = model$parameter, p = model$p.value, Method = model$method, stringsAsFactors = FALSE ) } } attr(out, "htest_type") <- "ttest" out } # extract htest oneway ---------------------- #' @keywords internal .extract_htest_oneway <- function(model) { data.frame( `F` = model$statistic, # nolint df = model$parameter[1], df_error = model$parameter[2], p = model$p.value, Method = model$method, stringsAsFactors = FALSE ) } # extract htest chi2 ---------------------- #' @keywords internal .extract_htest_chi2 <- function(model) { # survey-chisq-test if ((any("observed" %in% names(model)) && inherits(model$observed, "svytable")) || any(startsWith(model$data.name, "svychisq"))) { if (grepl("Pearson's X", model$method, fixed = TRUE)) { model$method <- gsub("(Pearson's X\\^2: )(.*)", "Pearson's Chi2 \\(\\2\\)", model$method) } if (names(model$statistic) == "F") { data.frame( `F` = model$statistic, # nolint df = model$parameter[1], df_error = model$parameter[2], p = model$p.value, Method = model$method, stringsAsFactors = FALSE ) } else { data.frame( Chi2 = model$statistic, df = model$parameter, p = model$p.value, Method = model$method, stringsAsFactors = FALSE ) } } else if (!is.null(model$estimate) && identical(names(model$estimate), "odds ratio")) { data.frame( `Odds Ratio` = model$estimate, # CI = attributes(model$conf.int)$conf.level, CI_low = model$conf.int[1], CI_high = model$conf.int[2], p = model$p.value, Method = model$method, stringsAsFactors = FALSE, check.names = FALSE ) } else { data.frame( Chi2 = model$statistic, df = model$parameter, p = model$p.value, Method = model$method, stringsAsFactors = FALSE ) } } # extract htest prop ---------------------- #' @keywords internal .extract_htest_prop <- function(model) { out <- data.frame( Proportion = paste(insight::format_value(model$estimate, as_percent = TRUE), collapse = " / "), stringsAsFactors = FALSE ) if (length(model$estimate) == 2) { out$Difference <- insight::format_value( abs(model$estimate[1] - model$estimate[2]), as_percent = TRUE ) } if (!is.null(model$conf.int)) { out$CI_low <- model$conf.int[1] out$CI_high <- model$conf.int[2] } out$Chi2 <- model$statistic out$df <- model$parameter[1] out$Null_value <- model$null.value out$p <- model$p.value out$Method <- model$method out } # extract htest binom ---------------------- #' @keywords internal .extract_htest_binom <- function(model) { out <- data.frame( Probability = model$estimate, CI_low = model$conf.int[1], CI_high = model$conf.int[2], Success = model$statistic, Trials = model$parameter, stringsAsFactors = FALSE ) out$Null_value <- model$null.value out$p <- model$p.value out$Method <- model$method out } # ==== effectsizes ===== .add_effectsize_htest <- function(model, out, es_type = NULL, ci = 0.95, alternative = NULL, verbose = TRUE, ...) { # check if effect sizes are requested if (!requireNamespace("effectsize", quietly = TRUE) || is.null(es_type)) { return(out) } # return on invalid options. We may have partial matching with argument # `effects` for `es_type`, and thus all "effects" options should be # ignored. if (es_type %in% c("fixed", "random", "all")) { return(out) } # try to extract effectsize es <- tryCatch( { effectsize::effectsize( model, type = es_type, ci = ci, alternative = alternative, verbose = verbose, ... ) }, error = function(e) { if (verbose) { msg <- c( paste0("Could not compute effectsize ", effectsize::get_effectsize_label(es_type), "."), paste0("Possible reason: ", e$message) ) insight::format_alert(msg) } NULL } ) # return if not successful if (is.null(es)) { return(out) } ## TODO: check if effectsize prefixes are correct @mattansb # Find prefix for CI-columns prefix <- switch(es_type, cohens_g = "Cohens_", cramers_v = "Cramers_", phi = "phi_", cohens_d = "d_", hedges_g = "g_", rank_biserial = "rank_biserial_", rank_epsilon_squared = "rank_epsilon_squared_", kendalls_w = "W_", omega = "Omega2_", eta = "Eta2_", epsilon = "Epsilon2_" ) es$CI <- NULL ci_cols <- startsWith(names(es), "CI") es_ci_cols <- paste0(prefix, names(es)[ci_cols]) names(es)[ci_cols] <- es_ci_cols out <- cbind(out, es) # compose effect size columns es_columns <- unique(c(effectsize::get_effectsize_name(colnames(es)), es_ci_cols)) # reorder col_order <- c( "Parameter1", "Parameter2", "Parameter", "F", "Chi2", "Group", "Mean_Parameter1", "Mean_Parameter2", "Mean_Group1", "Mean_Group2", "mu", "Difference", "W", "CI_low", "CI_high", es_columns, "t", "df", "df_error", "p", "Method", "method" ) out <- out[col_order[col_order %in% names(out)]] out } # ==== add attributes ==== #' @keywords internal .add_htest_parameters_attributes <- function(params, model, ci = 0.95, ...) { attr(params, "title") <- unique(params$Method) attr(params, "model_class") <- class(model) attr(params, "alternative") <- model$alternative if (!is.null(model$alternative)) { h1_text <- "Alternative hypothesis: " if (is.null(model$null.value)) { h1_text <- paste0(h1_text, model$alternative) } else if (length(model$null.value) == 1L) { alt.char <- switch(model$alternative, two.sided = "not equal to", less = "less than", greater = "greater than" ) h1_text <- paste0(h1_text, "true ", names(model$null.value), " is ", alt.char, " ", model$null.value) } else { h1_text <- paste0(h1_text, model$alternative) } attr(params, "text_alternative") <- h1_text } dot.arguments <- lapply(match.call(expand.dots = FALSE)[["..."]], function(x) x) if ("digits" %in% names(dot.arguments)) { attr(params, "digits") <- eval(dot.arguments[["digits"]]) } else { attr(params, "digits") <- 2 } if ("ci_digits" %in% names(dot.arguments)) { attr(params, "ci_digits") <- eval(dot.arguments[["ci_digits"]]) } else { attr(params, "ci_digits") <- NULL } if ("p_digits" %in% names(dot.arguments)) { attr(params, "p_digits") <- eval(dot.arguments[["p_digits"]]) } else { attr(params, "p_digits") <- 3 } attr(params, "ci") <- ci attr(params, "ci_test") <- attributes(model$conf.int)$conf.level # add CI, and reorder if (!"CI" %in% colnames(params) && length(ci) == 1) { ci_pos <- grep("CI_low", colnames(params), fixed = TRUE) if (length(ci_pos)) { if (length(ci_pos) > 1) { ci_pos <- ci_pos[1] } params$CI <- ci a <- attributes(params) params <- params[c(1:(ci_pos - 1), ncol(params), ci_pos:(ncol(params) - 1))] attributes(params) <- utils::modifyList(a, attributes(params)) } } params } #' @keywords internal .add_htest_attributes <- function(params, model, p_adjust = NULL, verbose = TRUE, ...) { dot.arguments <- lapply(match.call(expand.dots = FALSE)[["..."]], function(x) x) attr(params, "p_adjust") <- p_adjust attr(params, "model_class") <- class(model) attr(params, "title") <- params$Method if ("digits" %in% names(dot.arguments)) { attr(params, "digits") <- eval(dot.arguments[["digits"]]) } else { attr(params, "digits") <- 2 } if ("ci_digits" %in% names(dot.arguments)) { attr(params, "ci_digits") <- eval(dot.arguments[["ci_digits"]]) } else { attr(params, "ci_digits") <- NULL } if ("p_digits" %in% names(dot.arguments)) { attr(params, "p_digits") <- eval(dot.arguments[["p_digits"]]) } else { attr(params, "p_digits") <- 3 } if ("s_value" %in% names(dot.arguments)) { attr(params, "s_value") <- eval(dot.arguments[["s_value"]]) } params } parameters/R/utils.R 0000644 0001762 0000144 00000014417 14736731407 014124 0 ustar ligges users # small wrapper around this commonly used try-catch .safe <- function(code, on_error = NULL) { if (isTRUE(getOption("easystats_errors", FALSE)) && is.null(on_error)) { code } else { tryCatch(code, error = function(e) on_error) } } #' help-functions #' @keywords internal .data_frame <- function(...) { x <- data.frame(..., stringsAsFactors = FALSE) rownames(x) <- NULL x } #' Safe transformation from factor/character to numeric #' #' @keywords internal .factor_to_dummy <- function(x) { if (is.numeric(x)) { return(x) } # get unique levels / values values <- if (is.factor(x)) { levels(x) } else { stats::na.omit(unique(x)) } dummy <- as.data.frame(do.call(cbind, lapply(values, function(i) { out <- rep(0, length(x)) out[is.na(x)] <- NA out[x == i] <- 1 out }))) colnames(dummy) <- values dummy } #' @keywords internal .rename_values <- function(x, old, new) { x[x %in% old] <- new x } #' for models with zero-inflation component, return required component of model-summary #' @keywords internal .filter_component <- function(dat, component) { switch(component, conditional = dat[dat$Component == "conditional", ], zi = , zero_inflated = dat[dat$Component == "zero_inflated", ], dat ) } # Find log-terms inside model formula, and return "clean" term names .log_terms <- function(model) { x <- insight::find_terms(model, flatten = TRUE, verbose = FALSE) gsub("^log\\((.*)\\)", "\\1", grep("^log\\((.*)\\)", x, value = TRUE)) } # Execute a function but store warnings (https://stackoverflow.com/a/4947528/4198688) #' @keywords internal .catch_warnings <- function(expr) { myWarnings <- NULL wHandler <- function(w) { myWarnings <<- c(myWarnings, list(w)) invokeRestart("muffleWarning") } val <- withCallingHandlers(expr, warning = wHandler) list(out = val, warnings = myWarnings) } #' @keywords internal .get_object <- function(x, attribute_name = "object_name") { obj_name <- attr(x, attribute_name, exact = TRUE) model <- NULL if (!is.null(obj_name)) { model <- .safe(get(obj_name, envir = parent.frame())) # prevent self reference if (is.null(model) || inherits(model, "parameters_model")) { model <- .safe(get(obj_name, envir = globalenv())) } # prevent self reference if (is.null(model) || inherits(model, "parameters_model")) { model <- .safe(.dynGet(obj_name)) } } model } .is_semLme <- function(x) { all(inherits(x, c("sem", "lme"))) } .insert_row_at <- function(data, row, index, default_value = NA) { # add missing columns new_columns <- setdiff(colnames(data), colnames(row)) if (length(new_columns) > 0) { row[new_columns] <- default_value } # match column order row <- row[match(colnames(data), colnames(row))] # insert row if (index == 1) { rbind(row, data) } else if (index == (nrow(data) + 1)) { rbind(data, row) } else { rbind(data[1:(index - 1), ], row, data[index:nrow(data), ]) } } .insert_element_at <- function(data, element, index) { if (index == 1) { c(element, data) } else if (index == (length(data) + 1)) { c(data, element) } else { c(data[1:(index - 1)], element, data[index:length(data)]) } } .find_factor_levels <- function(model_data, model = NULL, model_call = NULL) { # check whether we have on-the-fly conversion of factors if (!is.null(model)) { model_terms <- insight::find_terms(model, verbose = FALSE) } else if (!is.null(model_call)) { # nolint model_terms <- insight::find_terms(model_call, verbose = FALSE) } else { model_terms <- NULL } # extract all model terms, we now have "as.factor(term)" etc., if any if (!is.null(model_terms$conditional)) { # extract variable names from "as.factor(term)" etc. factor_terms <- grep("(as\\.factor|factor|as\\.character)", model_terms$conditional, value = TRUE) cleaned <- gsub("(as\\.factor|factor|as\\.character)\\((.*)\\)", "\\2", factor_terms) # convert on-the-fly factors into real factors if (length(cleaned)) { for (i in seq_along(cleaned)) { model_data[[factor_terms[i]]] <- as.factor(model_data[[cleaned[i]]]) } } } # extract levels from factors, so we know the reference level out <- lapply(colnames(model_data), function(i) { v <- model_data[[i]] if (is.factor(v)) { paste0(i, levels(v)) } else if (is.character(v)) { paste0(i, unique(v)) } else { NULL } }) names(out) <- names(model_data) insight::compact_list(out) } # This functions finds contrasts for those factors in a model, where including # a reference level makes sense. This is the case when there are contrasts # that are all zeros, which means that the reference level is not included in # the model matrix. .remove_reference_contrasts <- function(model) { cons <- .safe(model$contrasts) if (is.null(cons)) { return(NULL) } out <- vapply(cons, function(mat) { if (is.matrix(mat) && nrow(mat) > 0) { any(rowSums(mat) == 0) } else if (is.character(mat)) { mat %in% c("contr.treatment", "contr.SAS") } else { FALSE } }, logical(1)) # only return those factors that need to be removed names(out)[!out] } # Almost identical to dynGet(). The difference is that we deparse the expression # because get0() allows symbol only since R 4.1.0 .dynGet <- function(x, ifnotfound = stop(gettextf("%s not found", sQuote(x)), domain = NA, call. = FALSE), minframe = 1L, inherits = FALSE) { x <- insight::safe_deparse(x) n <- sys.nframe() myObj <- structure(list(.b = as.raw(7)), foo = 47L) while (n > minframe) { n <- n - 1L env <- sys.frame(n) r <- get0(x, envir = env, inherits = inherits, ifnotfound = myObj) if (!identical(r, myObj)) { return(r) } } 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." )) } } parameters/R/methods_merTools.R 0000644 0001762 0000144 00000002565 14716604200 016300 0 ustar ligges users #' @export model_parameters.merModList <- function(model, ci = 0.95, exponentiate = FALSE, p_adjust = NULL, keep = NULL, drop = NULL, verbose = TRUE, ...) { out <- .model_parameters_generic( model = model, ci = ci, bootstrap = FALSE, iterations = 10, merge_by = "Parameter", standardize = NULL, exponentiate = exponentiate, keep_parameters = keep, drop_parameters = drop, p_adjust = p_adjust, ... ) attr(out, "object_name") <- insight::safe_deparse_symbol(substitute(model)) out } #' @export ci.merModList <- function(x, ci = 0.95, ...) { .ci_generic(model = x, ci = ci, dof = NULL, component = "conditional", ...) } #' @export standard_error.merModList <- function(model, ...) { s <- suppressWarnings(summary(model)) out <- .data_frame( Parameter = s$fe$term, SE = s$fe$std.error ) insight::text_remove_backticks(out, verbose = FALSE) } #' @export format_parameters.merModList <- function(model, brackets = c("[", "]"), ...) { .format_parameter_default(model[[1]], brackets = brackets) } parameters/R/methods_lavaan.R 0000644 0001762 0000144 00000011701 14736731407 015742 0 ustar ligges users # Packages lavaan, blavaan # model parameters --------------------------- #' @rdname model_parameters.principal #' @export model_parameters.lavaan <- function(model, ci = 0.95, standardize = FALSE, component = c("regression", "correlation", "loading", "defined"), keep = NULL, drop = NULL, verbose = TRUE, ...) { params <- .extract_parameters_lavaan(model, ci = ci, standardize = standardize, keep_parameters = keep, drop_parameters = drop, verbose = verbose, ... ) # Filter if (all(component == "all")) { component <- c("regression", "correlation", "loading", "variance", "defined", "mean") } params <- params[tolower(params$Component) %in% component, ] # add class-attribute for printing class(params) <- c("parameters_sem", "see_parameters_sem", class(params)) attr(params, "ci") <- ci attr(params, "model") <- model params } #' @export model_parameters.blavaan <- function(model, centrality = "median", dispersion = FALSE, ci = 0.95, ci_method = "eti", test = "pd", rope_range = "default", rope_ci = 0.95, diagnostic = c("ESS", "Rhat"), component = "all", standardize = NULL, keep = NULL, drop = NULL, verbose = TRUE, ...) { # Processing params <- .extract_parameters_bayesian( model, centrality = centrality, dispersion = dispersion, ci = ci, ci_method = ci_method, test = test, rope_range = rope_range, rope_ci = rope_ci, diagnostic = diagnostic, effects = "all", standardize = standardize, keep_parameters = keep, drop_parameters = drop, verbose = verbose, ... ) # Filter if (!all(component == "all")) { params <- params[tolower(params$Component) %in% component, ] } params <- .add_model_parameters_attributes( params, model, ci, exponentiate = FALSE, ci_method = ci_method, verbose = verbose, ... ) attr(params, "object_name") <- insight::safe_deparse_symbol(substitute(model)) class(params) <- c("parameters_sem", "see_parameters_sem", class(params)) params } # ci --------------------------- #' @export ci.lavaan <- function(x, ci = 0.95, ...) { out <- .extract_parameters_lavaan(model = x, ci = ci, ...) out$CI <- ci out[out$Operator != "~1", c("To", "Operator", "From", "CI", "CI_low", "CI_high")] } # SE --------------------------- #' @export standard_error.lavaan <- function(model, ...) { out <- .extract_parameters_lavaan(model, ...) out[out$Operator != "~1", c("To", "Operator", "From", "SE")] } #' @export standard_error.blavaan <- function(model, ...) { params <- insight::get_parameters(model, ...) .data_frame( Parameter = colnames(params), SE = unname(sapply(params, stats::sd, na.rm = TRUE)) ) } # p-value --------------------------- #' @export p_value.lavaan <- function(model, ...) { out <- .extract_parameters_lavaan(model, ...) out[out$Operator != "~1", c("To", "Operator", "From", "p")] } #' @export p_value.blavaan <- p_value.BFBayesFactor # print --------------------------- #' @export print.parameters_sem <- function(x, digits = 2, ci_digits = digits, p_digits = 3, ...) { # check if user supplied digits attributes if (missing(digits)) { digits <- .additional_arguments(x, "digits", 2) } if (missing(ci_digits)) { ci_digits <- .additional_arguments(x, "ci_digits", digits) } if (missing(p_digits)) { p_digits <- .additional_arguments(x, "p_digits", 3) } verbose <- .additional_arguments(x, "verbose", TRUE) formatted_table <- format( x = x, digits = digits, ci_digits, p_digits = p_digits, format = "text", ci_brackets = TRUE, ci_width = "auto", ... ) cat(insight::export_table(formatted_table, format = "text", ...)) if (isTRUE(verbose)) { .print_footer_cimethod(x) } invisible(x) } #' @export #' @inheritParams stats::predict predict.parameters_sem <- function(object, newdata = NULL, ...) { insight::check_if_installed("lavaan") as.data.frame(lavaan::lavPredict( attributes(object)$model, newdata = newdata, method = "EBM", ... )) } parameters/R/methods_survival.R 0000644 0001762 0000144 00000010667 14737245125 016363 0 ustar ligges users # classes: .coxph, .aareg, .survreg, .riskRegression, .survfit #################### .survfit ------ #' @export model_parameters.survfit <- function(model, keep = NULL, drop = NULL, verbose = TRUE, ...) { s <- summary(model) # extract all elements with same length, which occur most in that list # that is the data we need uniqv <- unique(lengths(s)) tab <- tabulate(match(lengths(s), uniqv)) idx <- which.max(tab) most_len <- uniqv[idx] # convert list into data frame, only for elements of same length params <- as.data.frame(s[lengths(s) == most_len]) # keep specific columns keep_columns <- intersect( c("time", "n.risk", "n.event", "surv", "std.err", "strata", "lower", "upper"), colnames(params) ) params <- params[keep_columns] # rename params <- datawizard::data_rename( params, select = c( Time = "time", `N Risk` = "n.risk", `N Event` = "n.event", Survival = "surv", SE = "std.err", Group = "strata", CI_low = "lower", CI_high = "upper" ) ) # fix labels params$Group <- gsub("x=", "", params$Group, fixed = TRUE) # These are integers, need to be character to display without decimals params$Time <- as.character(params$Time) params[["N Risk"]] <- as.character(params[["N Risk"]]) params[["N Event"]] <- as.character(params[["N Event"]]) attr(params, "ci") <- s$conf.int class(params) <- c("parameters_model", "see_parameters_model", class(params)) params } #################### .coxph ------ #' @export standard_error.coxph <- function(model, method = NULL, ...) { robust <- !is.null(method) && method == "robust" if (isTRUE(robust)) { return(standard_error(model, ...)) } params <- insight::get_parameters(model) cs <- stats::coef(summary(model)) se <- cs[, 3] # check if (length(se) > nrow(params)) { se <- se[match(params$Parameter, .remove_backticks_from_string(rownames(cs)))] } .data_frame( Parameter = params$Parameter, SE = as.vector(se) ) } #' @export p_value.coxph <- function(model, ...) { params <- insight::get_parameters(model) stats <- insight::get_statistic(model) params <- merge(params, stats, sort = FALSE) statistic <- attributes(stats)$statistic # convert in case of z if (identical(statistic, "z-statistic")) { params$Statistic <- params$Statistic^2 } .data_frame( Parameter = params$Parameter, p = as.vector(1 - stats::pchisq(params$Statistic, df = 1)) ) } #################### .aareg ------ #' @export standard_error.aareg <- function(model, ...) { s <- summary(model) se <- s$table[, "se(coef)"] .data_frame( Parameter = .remove_backticks_from_string(names(se)), SE = as.vector(se) ) } #' @export p_value.aareg <- function(model, ...) { s <- summary(model) p <- s$table[, "p"] .data_frame( Parameter = .remove_backticks_from_string(names(p)), p = as.vector(p) ) } #################### .survreg ------ #' @export standard_error.survreg <- function(model, method = NULL, ...) { robust <- !is.null(method) && method == "robust" if (.check_vcov_args(robust, ...)) { return(standard_error.default(model, ...)) } s <- summary(model) se <- s$table[, 2] .data_frame( Parameter = .remove_backticks_from_string(names(se)), SE = as.vector(se) ) } #' @export p_value.survreg <- function(model, method = NULL, ...) { robust <- !is.null(method) && method == "robust" if (.check_vcov_args(robust, ...)) { return(p_value.default(model, ...)) } s <- summary(model) p <- s$table[, "p"] .data_frame( Parameter = .remove_backticks_from_string(names(p)), p = as.vector(p) ) } #################### .riskRegression ------ #' @export standard_error.riskRegression <- function(model, ...) { junk <- utils::capture.output(cs <- stats::coef(model)) .data_frame( Parameter = .remove_backticks_from_string(as.vector(cs[, 1])), SE = as.numeric(cs[, "StandardError"]) ) } #' @export p_value.riskRegression <- function(model, ...) { junk <- utils::capture.output(cs <- stats::coef(model)) .data_frame( Parameter = .remove_backticks_from_string(as.vector(cs[, 1])), p = as.numeric(cs[, "Pvalue"]) ) } parameters/R/reduce_parameters.R 0000644 0001762 0000144 00000017704 14736731407 016460 0 ustar ligges users #' Dimensionality reduction (DR) / Features Reduction #' #' This function performs a reduction in the parameter space (the number of #' variables). It starts by creating a new set of variables, based on the given #' method (the default method is "PCA", but other are available via the #' `method` argument, such as "cMDS", "DRR" or "ICA"). Then, it names this #' new dimensions using the original variables that correlates the most with it. #' For instance, a variable named `'V1_0.97/V4_-0.88'` means that the V1 and the #' V4 variables correlate maximally (with respective coefficients of .97 and #' -.88) with this dimension. Although this function can be useful in #' exploratory data analysis, it's best to perform the dimension reduction step #' in a separate and dedicated stage, as this is a very important process in the #' data analysis workflow. `reduce_data()` is an alias for #' `reduce_parameters.data.frame()`. #' #' @inheritParams principal_components #' @param method The feature reduction method. Can be one of `"PCA"`, `"cMDS"`, #' `"DRR"`, `"ICA"` (see the 'Details' section). #' @param distance The distance measure to be used. Only applies when #' `method = "cMDS"`. This must be one of `"euclidean"`, `"maximum"`, #' `"manhattan"`, `"canberra"`, `"binary"` or `"minkowski"`. Any unambiguous #' substring can be given. #' #' @details #' The different methods available are described below: #' #' ## Supervised Methods #' - **PCA**: See [`principal_components()`]. #' #' - **cMDS / PCoA**: Classical Multidimensional Scaling (cMDS) takes a #' set of dissimilarities (i.e., a distance matrix) and returns a set of points #' such that the distances between the points are approximately equal to the #' dissimilarities. #' #' - **DRR**: Dimensionality Reduction via Regression (DRR) is a very #' recent technique extending PCA (*Laparra et al., 2015*). Starting from a #' rotated PCA, it predicts redundant information from the remaining components #' using non-linear regression. Some of the most notable advantages of #' performing DRR are avoidance of multicollinearity between predictors and #' overfitting mitigation. DRR tends to perform well when the first principal #' component is enough to explain most of the variation in the predictors. #' Requires the **DRR** package to be installed. #' #' - **ICA**: Performs an Independent Component Analysis using the #' FastICA algorithm. Contrary to PCA, which attempts to find uncorrelated #' sources (through least squares minimization), ICA attempts to find #' independent sources, i.e., the source space that maximizes the #' "non-gaussianity" of all sources. Contrary to PCA, ICA does not rank each #' source, which makes it a poor tool for dimensionality reduction. Requires the #' **fastICA** package to be installed. #' #' See also [package vignette](https://easystats.github.io/parameters/articles/parameters_reduction.html). #' #' @references #' - Nguyen, L. H., and Holmes, S. (2019). Ten quick tips for effective #' dimensionality reduction. PLOS Computational Biology, 15(6). #' #' - Laparra, V., Malo, J., and Camps-Valls, G. (2015). Dimensionality #' reduction via regression in hyperspectral imagery. IEEE Journal of Selected #' Topics in Signal Processing, 9(6), 1026-1036. #' #' @examples #' data(iris) #' model <- lm(Sepal.Width ~ Species * Sepal.Length + Petal.Width, data = iris) #' model #' reduce_parameters(model) #' #' out <- reduce_data(iris, method = "PCA", n = "max") #' head(out) #' @export reduce_parameters <- function(x, method = "PCA", n = "max", distance = "euclidean", ...) { UseMethod("reduce_parameters") } #' @rdname reduce_parameters #' @export reduce_data <- function(x, method = "PCA", n = "max", distance = "euclidean", ...) { if (!is.data.frame(x)) { insight::format_error("Only works on data frames.") } reduce_parameters(x, method = method, n = n, distance = distance, ...) } #' @export reduce_parameters.data.frame <- function(x, method = "PCA", n = "max", distance = "euclidean", ...) { x <- datawizard::to_numeric(x, dummy_factors = TRUE) # N factors if (n == "max") { nfac <- ncol(x) - 1 } else { nfac <- .get_n_factors(x, n = n, type = "PCA", rotation = "none") } # compute new features if (tolower(method) %in% c("pca", "principal")) { features <- principal_components(x, n = nfac, ...) features <- as.data.frame(attributes(features)$scores) } else if (tolower(method) %in% c("cmds", "pcoa")) { features <- .cmds(x, n = nfac, distance = distance, ...) } else if (tolower(method) == "drr") { features <- .drr(x, n = nfac, ...) } else if (tolower(method) == "ica") { features <- .ica(x, n = nfac, ...) } else { insight::format_error("`method` must be one of \"PCA\", \"cMDS\", \"DRR\" or \"ICA\".") } # Get weights / pseudo-loadings (correlations) cormat <- as.data.frame(stats::cor(x = x, y = features)) cormat <- cbind(data.frame(Variable = row.names(cormat)), cormat) pca_weights <- as.data.frame(.sort_loadings(cormat, cols = 2:ncol(cormat))) if (n == "max") { pca_weights <- .filter_loadings(pca_weights, threshold = "max", 2:ncol(pca_weights)) non_empty <- vapply(pca_weights[2:ncol(pca_weights)], function(x) !all(is.na(x)), TRUE) pca_weights <- pca_weights[c(TRUE, non_empty)] features <- features[, non_empty] pca_weights[is.na(pca_weights)] <- 0 pca_weights <- .filter_loadings(.sort_loadings(pca_weights, cols = 2:ncol(pca_weights)), threshold = "max", 2:ncol(pca_weights)) } # Create varnames varnames <- vapply(pca_weights[2:ncol(pca_weights)], function(x) { name <- pca_weights$Variable[!is.na(x)] weight <- insight::format_value(x[!is.na(x)]) paste0(paste(name, weight, sep = "_"), collapse = "/") }, character(1)) names(features) <- as.character(varnames) # Attributes attr(features, "loadings") <- pca_weights class(features) <- c("parameters_reduction", class(features)) # Out features } #' @export reduce_parameters.lm <- function(x, method = "PCA", n = "max", distance = "euclidean", ...) { model_data <- reduce_parameters( datawizard::to_numeric(insight::get_predictors(x, ...), ..., dummy_factors = TRUE), method = method, n = n, distance = distance ) y <- data.frame(.row = seq_along(insight::get_response(x))) y[insight::find_response(x)] <- insight::get_response(x) y$.row <- NULL new_formula <- paste(insight::find_response(x), "~", paste(paste0("`", names(model_data), "`"), collapse = " + ")) stats::update(x, formula = new_formula, data = cbind(model_data, y)) } #' @export reduce_parameters.merMod <- reduce_parameters.lm #' @export principal_components.lm <- function(x, ...) { reduce_parameters(x, method = "PCA", ...) } #' @export principal_components.merMod <- principal_components.lm #' @keywords internal .cmds <- function(x, n = "all", distance = "euclidean", ...) { n <- .get_n_factors(x, n = n, type = "PCA", rotation = "none") d <- stats::dist(x, method = distance) cmd <- stats::cmdscale(d, k = n, eig = TRUE) features <- as.data.frame(cmd$points) names(features) <- paste0("CMDS", seq_len(ncol(features))) features } #' @keywords internal .drr <- function(x, n = "all", ...) { n <- .get_n_factors(x, n = n, type = "PCA", rotation = "none") insight::check_if_installed("DRR") junk <- utils::capture.output(suppressMessages({ rez <- DRR::drr(x, n) })) features <- as.data.frame(rez$fitted.data) names(features) <- paste0("DRR", seq_len(ncol(features))) features } #' @keywords internal .ica <- function(x, n = "all", ...) { n <- .get_n_factors(x, n = n, type = "PCA", rotation = "none") insight::check_if_installed("fastICA") rez <- fastICA::fastICA(x, n.comp = ncol(x) - 1) features <- as.data.frame(rez$S) names(features) <- paste0("ICA", seq_len(ncol(features))) features } parameters/R/methods_gam.R 0000644 0001762 0000144 00000005306 14736731407 015250 0 ustar ligges users # classes: .gam, .list #################### .gam ------ #' @export model_parameters.gam <- model_parameters.cgam #' @export ci.gam <- function(x, ci = 0.95, method = NULL, ...) { .ci_generic(model = x, ci = ci, method = "wald", ...) } #' @export standard_error.gam <- function(model, ...) { p.table <- summary(model)$p.table s.table <- summary(model)$s.table d1 <- d2 <- NULL if (!is.null(p.table)) { d1 <- .data_frame( Parameter = rownames(p.table), SE = as.vector(p.table[, 2]), Component = "conditional" ) } if (!is.null(s.table)) { d2 <- .data_frame( Parameter = rownames(s.table), SE = NA, Component = "smooth_terms" ) } insight::text_remove_backticks(rbind(d1, d2), verbose = FALSE) } #' @export p_value.gam <- function(model, ...) { p.table <- summary(model)$p.table s.table <- summary(model)$s.table d1 <- d2 <- NULL if (!is.null(p.table)) { d1 <- .data_frame( Parameter = rownames(p.table), p = as.vector(p.table[, 4]), Component = "conditional" ) } if (!is.null(s.table)) { d2 <- .data_frame( Parameter = rownames(s.table), p = as.vector(s.table[, 4]), Component = "smooth_terms" ) } insight::text_remove_backticks(rbind(d1, d2), verbose = FALSE) } #' @export simulate_model.gam <- function(model, iterations = 1000, ...) { if (is.null(iterations)) iterations <- 1000 beta <- stats::coef(model) varcov <- insight::get_varcov(model, component = "all", ...) out <- as.data.frame(.mvrnorm(n = iterations, mu = beta, Sigma = varcov)) class(out) <- c("parameters_simulate_model", class(out)) attr(out, "object_name") <- insight::safe_deparse_symbol(substitute(model)) out } #################### .list ------ #' @export model_parameters.list <- function(model, ...) { if ("gam" %in% names(model)) { model <- model$gam class(model) <- c("gam", "lm", "glm") model_parameters(model, ...) } else if ("pamobject" %in% names(model)) { model <- model$pamobject model_parameters(model, ...) } else { insight::format_error("We don't recognize this object of class `list`. Please raise an issue.") } } #' @export ci.list <- function(x, ci = 0.95, ...) { if ("gam" %in% names(x)) { x <- x$gam class(x) <- c("gam", "lm", "glm") ci(x, ci = ci, ...) } else { return(NULL) } } #' @export simulate_model.list <- function(model, iterations = 1000, ...) { if ("gam" %in% names(model)) { model <- model$gam class(model) <- c("gam", "lm", "glm") simulate_model(model, iterations = iterations, ...) } } parameters/R/pool_parameters.R 0000644 0001762 0000144 00000032037 14736731407 016156 0 ustar ligges users #' Pool Model Parameters #' #' This function "pools" (i.e. combines) model parameters in a similar fashion #' as `mice::pool()`. However, this function pools parameters from #' `parameters_model` objects, as returned by #' [model_parameters()]. #' #' @param x A list of `parameters_model` objects, as returned by #' [model_parameters()], or a list of model-objects that is supported by #' `model_parameters()`. #' @param ... Arguments passed down to `model_parameters()`, if `x` is a list #' of model-objects. Can be used, for instance, to specify arguments like #' `ci` or `ci_method` etc. #' @inheritParams model_parameters.default #' @inheritParams bootstrap_model #' @inheritParams model_parameters.glmmTMB #' #' @note #' Models with multiple components, (for instance, models with zero-inflation, #' where predictors appear in the count and zero-inflation part, or models with #' dispersion component) may fail in rare situations. In this case, compute #' the pooled parameters for components separately, using the `component` #' argument. #' #' Some model objects do not return standard errors (e.g. objects of class #' `htest`). For these models, no pooled confidence intervals nor p-values #' are returned. #' #' @details Averaging of parameters follows Rubin's rules (_Rubin, 1987, p. 76_). #' The pooled degrees of freedom is based on the Barnard-Rubin adjustment for #' small samples (_Barnard and Rubin, 1999_). #' #' @references #' Barnard, J. and Rubin, D.B. (1999). Small sample degrees of freedom with #' multiple imputation. Biometrika, 86, 948-955. Rubin, D.B. (1987). Multiple #' Imputation for Nonresponse in Surveys. New York: John Wiley and Sons. #' #' @examplesIf require("mice") && require("datawizard") #' # example for multiple imputed datasets #' data("nhanes2", package = "mice") #' imp <- mice::mice(nhanes2, printFlag = FALSE) #' models <- lapply(1:5, function(i) { #' lm(bmi ~ age + hyp + chl, data = mice::complete(imp, action = i)) #' }) #' pool_parameters(models) #' #' # should be identical to: #' m <- with(data = imp, exp = lm(bmi ~ age + hyp + chl)) #' summary(mice::pool(m)) #' #' # For glm, mice used residual df, while `pool_parameters()` uses `Inf` #' nhanes2$hyp <- datawizard::slide(as.numeric(nhanes2$hyp)) #' imp <- mice::mice(nhanes2, printFlag = FALSE) #' models <- lapply(1:5, function(i) { #' glm(hyp ~ age + chl, family = binomial, data = mice::complete(imp, action = i)) #' }) #' m <- with(data = imp, exp = glm(hyp ~ age + chl, family = binomial)) #' # residual df #' summary(mice::pool(m))$df #' # df = Inf #' pool_parameters(models)$df_error #' # use residual df instead #' pool_parameters(models, ci_method = "residual")$df_error #' @return A data frame of indices related to the model's parameters. #' @export pool_parameters <- function(x, exponentiate = FALSE, effects = "fixed", component = "all", verbose = TRUE, ...) { # check input, save original model ----- original_model <- random_params <- NULL obj_name <- insight::safe_deparse_symbol(substitute(x)) if (all(vapply(x, insight::is_model, TRUE)) && all(vapply(x, insight::is_model_supported, TRUE))) { original_model <- x[[1]] # Add exceptions for models with uncommon components here --------------- exception_model_class <- "polr" # exceptions for "component" argument. Eg, MASS::polr has components # "alpha" and "beta", and "component" needs to be set to all by default if (identical(component, "conditional") && inherits(original_model, exception_model_class)) { component <- "all" } x <- lapply(x, model_parameters, effects = effects, component = component, ...) } if (!all(vapply(x, inherits, TRUE, "parameters_model"))) { insight::format_error( "First argument `x` must be a list of `parameters_model` objects, as returned by the `model_parameters()` function." ) } if (is.null(original_model)) { original_model <- .get_object(x[[1]]) } if (isTRUE(attributes(x[[1]])$exponentiate) && verbose) { insight::format_alert( "Pooling on exponentiated parameters is not recommended. Please call `model_parameters()` with 'exponentiate = FALSE', and then call `pool_parameters(..., exponentiate = TRUE)`." ) } # only pool for specific component ----- original_x <- x if ("Component" %in% colnames(x[[1]]) && !insight::is_empty_object(component) && component != "all") { x <- lapply(x, function(i) { i <- i[i$Component == component, ] i$Component <- NULL i }) if (verbose) { insight::format_alert(paste0("Pooling applied to the ", component, " model component.")) } } # preparation ---- params <- do.call(rbind, x) len <- length(x) ci <- attributes(original_x[[1]])$ci if (is.null(ci)) ci <- 0.95 parameter_values <- x[[1]]$Parameter # exceptions ---- # check for special models, like "htest", which have no "Parameter" columns if (!"Parameter" %in% colnames(params)) { # check for possible column names if (all(c("Parameter1", "Parameter2") %in% colnames(params))) { # create combined Parameter column params$Parameter <- paste0(params$Parameter1, " and ", params$Parameter2) # remove old columns params$Parameter1 <- NULL params$Parameter2 <- NULL # update values parameter_values <- paste0(x[[1]]$Parameter1, " and ", x[[1]]$Parameter2) # } # fix coefficient column colnames(params)[colnames(params) == "r"] <- "Coefficient" colnames(params)[colnames(params) == "rho"] <- "Coefficient" colnames(params)[colnames(params) == "tau"] <- "Coefficient" colnames(params)[colnames(params) == "Estimate"] <- "Coefficient" colnames(params)[colnames(params) == "Difference"] <- "Coefficient" } # split multiply (imputed) datasets by parameters, # but only for fixed effects. Filter random effects, # and save parameter names from fixed effects for later use... if (effects == "all" && "Effects" %in% colnames(params) && "random" %in% params$Effects) { random_params <- params[params$Effects == "random", ] params <- params[params$Effects != "random", ] parameter_values <- x[[1]]$Parameter[x[[1]]$Effects != "random"] } # split by component if (!is.null(params$Component) && insight::n_unique(params$Component) > 1) { component_values <- x[[1]]$Component estimates <- split( params, list( factor(params$Parameter, levels = unique(parameter_values)), factor(params$Component, levels = unique(component_values)) ) ) } else { component_values <- NULL estimates <- split( params, factor(params$Parameter, levels = unique(parameter_values)) ) } # pool estimates etc. ----- pooled_params <- do.call(rbind, lapply(estimates, function(i) { # if we split by "component", some of the data frames might be empty # in this case, just skip... if (nrow(i) > 0) { # pooled estimate pooled_estimate <- mean(i$Coefficient) # special models that have no standard errors (like "htest" objects) if (is.null(i$SE) || all(is.na(i$SE))) { out <- data.frame( Coefficient = pooled_estimate, SE = NA, CI_low = NA, CI_high = NA, Statistic = NA, df_error = NA, p = NA, stringsAsFactors = FALSE ) if (verbose) { insight::format_alert("Model objects had no standard errors. Cannot compute pooled confidence intervals and p-values.") } # regular models that have coefficients and standard errors } else { # pooled standard error ubar <- mean(i$SE^2) tmp <- ubar + (1 + 1 / len) * stats::var(i$Coefficient) pooled_se <- sqrt(tmp) # pooled degrees of freedom, Barnard-Rubin adjustment for small samples df_column <- grep("(\\bdf\\b|\\bdf_error\\b)", colnames(i), value = TRUE)[1] if (length(df_column)) { pooled_df <- .barnad_rubin(m = nrow(i), b = stats::var(i$Coefficient), t = tmp, dfcom = unique(i[[df_column]])) # validation check length if (length(pooled_df) > 1 && length(pooled_se) == 1) { pooled_df <- round(mean(pooled_df, na.rm = TRUE)) } } else { pooled_df <- Inf } # pooled statistic pooled_statistic <- pooled_estimate / pooled_se # confidence intervals alpha <- (1 + ci) / 2 fac <- suppressWarnings(stats::qt(alpha, df = pooled_df)) out <- data.frame( Coefficient = pooled_estimate, SE = pooled_se, CI_low = pooled_estimate - pooled_se * fac, CI_high = pooled_estimate + pooled_se * fac, Statistic = pooled_statistic, df_error = pooled_df, p = 2 * stats::pt(abs(pooled_statistic), df = pooled_df, lower.tail = FALSE), stringsAsFactors = FALSE ) } out } else { NULL } })) # pool random effect variances ----- pooled_random <- NULL if (!is.null(random_params)) { estimates <- split(random_params, factor(random_params$Parameter, levels = unique(random_params$Parameter))) pooled_random <- do.call(rbind, lapply(estimates, function(i) { pooled_estimate <- mean(i$Coefficient, na.rm = TRUE) data.frame( Parameter = unique(i$Parameter), Coefficient = pooled_estimate, Effects = "random", stringsAsFactors = FALSE ) })) pooled_params$Effects <- "fixed" } # reorder ------ pooled_params$Parameter <- parameter_values columns <- c("Parameter", "Coefficient", "SE", "CI_low", "CI_high", "Statistic", "df_error", "p", "Effects", "Component") pooled_params <- pooled_params[intersect(columns, colnames(pooled_params))] # final attributes ----- # exponentiate coefficients and SE/CI, if requested pooled_params <- .exponentiate_parameters(pooled_params, NULL, exponentiate) if (!is.null(pooled_random)) { pooled_params <- merge(pooled_params, pooled_random, all = TRUE, sort = FALSE) } # add back component column if (!is.null(component_values)) { pooled_params$Component <- component_values } # this needs to be done extra here, cannot call ".add_model_parameters_attributes()" pooled_params <- .add_pooled_params_attributes( pooled_params, model_params = original_x[[1]], model = original_model, ci, exponentiate, verbose = verbose ) attr(pooled_params, "object_name") <- obj_name # pool sigma ---- sig <- unlist(insight::compact_list(lapply(original_x, function(i) { attributes(i)$sigma }))) if (!insight::is_empty_object(sig)) { attr(pooled_params, "sigma") <- mean(sig, na.rm = TRUE) } class(pooled_params) <- c("parameters_model", "see_parameters_model", class(pooled_params)) pooled_params } # helper ------ .barnad_rubin <- function(m, b, t, dfcom = 999999) { # fix for z-statistic if (is.null(dfcom) || all(is.na(dfcom)) || all(is.infinite(dfcom))) { return(Inf) } lambda <- (1 + 1 / m) * b / t lambda[lambda < 1e-04] <- 1e-04 dfold <- (m - 1) / lambda^2 dfobs <- (dfcom + 1) / (dfcom + 3) * dfcom * (1 - lambda) dfold * dfobs / (dfold + dfobs) } .add_pooled_params_attributes <- function(pooled_params, model_params, model, ci, exponentiate, verbose = TRUE) { info <- insight::model_info(model, verbose = FALSE) pretty_names <- attributes(model_params)$pretty_names if (length(pretty_names) < nrow(model_params)) { pretty_names <- c(pretty_names, model_params$Parameter[(length(pretty_names) + 1):nrow(model_params)]) } attr(pooled_params, "ci") <- ci attr(pooled_params, "exponentiate") <- exponentiate attr(pooled_params, "pretty_names") <- pretty_names attr(pooled_params, "verbose") <- verbose attr(pooled_params, "ordinal_model") <- attributes(model_params)$ordinal_model attr(pooled_params, "model_class") <- attributes(model_params)$model_class attr(pooled_params, "bootstrap") <- attributes(model_params)$bootstrap attr(pooled_params, "iterations") <- attributes(model_params)$iterations attr(pooled_params, "ci_method") <- attributes(model_params)$ci_method attr(pooled_params, "digits") <- attributes(model_params)$digits attr(pooled_params, "ci_digits") <- attributes(model_params)$ci_digits attr(pooled_params, "p_digits") <- attributes(model_params)$p_digits # column name for coefficients coef_col <- .find_coefficient_type(info, exponentiate) attr(pooled_params, "coefficient_name") <- coef_col attr(pooled_params, "zi_coefficient_name") <- if (isTRUE(exponentiate)) { "Odds Ratio" } else { "Log-Odds" } # formula attr(pooled_params, "model_formula") <- insight::find_formula(model, verbose = FALSE) pooled_params } parameters/R/methods_metafor.R 0000644 0001762 0000144 00000015457 14717111737 016146 0 ustar ligges users # package metafor ####### .rma ----------------- #' Parameters from Meta-Analysis #' #' Extract and compute indices and measures to describe parameters of meta-analysis models. #' #' @param include_studies Logical, if `TRUE` (default), includes parameters for #' all studies. Else, only parameters for overall-effects are shown. #' @inheritParams model_parameters.default #' @inheritParams model_parameters.glimML #' #' @examples #' library(parameters) #' mydat <<- data.frame( #' effectsize = c(-0.393, 0.675, 0.282, -1.398), #' stderr = c(0.317, 0.317, 0.13, 0.36) #' ) #' if (require("metafor", quietly = TRUE)) { #' model <- rma(yi = effectsize, sei = stderr, method = "REML", data = mydat) #' model_parameters(model) #' } #' \donttest{ #' # with subgroups #' if (require("metafor", quietly = TRUE)) { #' data(dat.bcg) #' dat <- escalc( #' measure = "RR", #' ai = tpos, #' bi = tneg, #' ci = cpos, #' di = cneg, #' data = dat.bcg #' ) #' dat$alloc <- ifelse(dat$alloc == "random", "random", "other") #' d <<- dat #' model <- rma(yi, vi, mods = ~alloc, data = d, digits = 3, slab = author) #' model_parameters(model) #' } #' #' if (require("metaBMA", quietly = TRUE)) { #' data(towels) #' m <- suppressWarnings(meta_random(logOR, SE, study, data = towels)) #' model_parameters(m) #' } #' } #' #' @return A data frame of indices related to the model's parameters. #' @export model_parameters.rma <- function(model, ci = 0.95, bootstrap = FALSE, iterations = 1000, standardize = NULL, exponentiate = FALSE, include_studies = TRUE, keep = NULL, drop = NULL, verbose = TRUE, ...) { # handle ci-level that was defined in function call... ci_level <- parse(text = insight::safe_deparse(model$call))[[1]]$level if (!is.null(ci_level) && missing(ci)) { ci <- ci_level / 100 } # validation check, warn if unsupported argument is used. .check_dots( dots = list(...), not_allowed = c("vcov", "vcov_args"), class(model)[1], verbose = verbose ) meta_analysis_overall <- .model_parameters_generic( model = model, ci = ci, bootstrap = bootstrap, iterations = iterations, merge_by = "Parameter", standardize = standardize, exponentiate = exponentiate, keep_parameters = keep, drop_parameters = drop, verbose = verbose, ... ) subgroups <- NULL group_variable <- NULL # subgroup analyses? if (!is.null(model$formula.mods)) { group_variable <- deparse(model$formula.mods[[2]])[1] model_data <- insight::get_data(model, verbose = FALSE) if (group_variable %in% colnames(model_data)) { subgroups <- sort(unique(model_data[[group_variable]])) } } if (nrow(meta_analysis_overall) > 1 && !is.null(subgroups)) { meta_analysis_overall$Subgroup <- subgroups meta_analysis_overall$Parameter <- "(Intercept)" } alpha <- (1 + ci) / 2 rma_parameters <- if (!is.null(model$slab) && !is.numeric(model$slab)) { sprintf("%s", model$slab) } else { sprintf("Study %i", 1:model[["k"]]) } # find missing if (!is.null(model$yi.f) && anyNA(model$yi.f)) { rma_parameters <- rma_parameters[match(model$yi, model$yi.f)] } rma_coeffients <- as.vector(model$yi) rma_se <- as.vector(sqrt(model$vi)) rma_ci_low <- rma_coeffients - rma_se * stats::qt(alpha, df = Inf) rma_ci_high <- rma_coeffients + rma_se * stats::qt(alpha, df = Inf) rma_statistic <- rma_coeffients / rma_se rma_ci_p <- 2 * stats::pt(abs(rma_statistic), df = Inf, lower.tail = FALSE) meta_analysis_studies <- data.frame( Parameter = rma_parameters, Coefficient = rma_coeffients, SE = rma_se, CI = ci, CI_low = rma_ci_low, CI_high = rma_ci_high, z = rma_statistic, df_error = NA, p = rma_ci_p, Weight = 1 / as.vector(model$vi), stringsAsFactors = FALSE ) # subgroup analyses? if (!is.null(subgroups)) { meta_analysis_studies$Subgroup <- insight::get_data(model, verbose = FALSE)[[group_variable]] } original_attributes <- attributes(meta_analysis_overall) out <- merge(meta_analysis_studies, meta_analysis_overall, all = TRUE, sort = FALSE) # fix intercept name out$Parameter[out$Parameter == "(Intercept)"] <- "Overall" # filter studies? if (isFALSE(include_studies)) { out <- out[out$Parameter == "Overall", ] } original_attributes$names <- names(out) original_attributes$row.names <- seq_len(nrow(out)) original_attributes$pretty_names <- stats::setNames(out$Parameter, out$Parameter) attributes(out) <- original_attributes # no df out$df_error <- NULL attr(out, "object_name") <- insight::safe_deparse_symbol(substitute(model)) attr(out, "measure") <- model$measure if (!"Method" %in% names(out)) { out$Method <- "Meta-analysis using 'metafor'" } attr(out, "title") <- unique(out$Method) out } #' @export p_value.rma <- function(model, ...) { params <- insight::get_parameters(model) .data_frame( Parameter = .remove_backticks_from_string(params$Parameter), p = model$pval ) } #' @export ci.rma <- function(x, ci = 0.95, ...) { params <- insight::get_parameters(x) out <- tryCatch( { tmp <- lapply(ci, function(i) { model <- stats::update(x, level = i) .data_frame( Parameter = params$Parameter, CI = i, CI_low = as.vector(model$ci.lb), CI_high = as.vector(model$ci.ub) ) }) insight::text_remove_backticks(do.call(rbind, tmp), verbose = FALSE) }, error = function(e) { NULL } ) if (is.null(out)) { se <- standard_error(x) out <- lapply(ci, function(i) { alpha <- (1 + i) / 2 fac <- stats::qnorm(alpha) .data_frame( Parameter = params$Parameter, CI = i, CI_low = params$Estimate - as.vector(se$SE) * fac, CI_high = params$Estimate + as.vector(se$SE) * fac ) }) out <- insight::text_remove_backticks(do.call(rbind, out), verbose = FALSE) } out } #' @export standard_error.rma <- function(model, ...) { params <- insight::get_parameters(model) .data_frame( Parameter = .remove_backticks_from_string(params$Parameter), SE = model[["se"]] ) } #' @export format_parameters.rma <- function(model, ...) { params <- insight::find_parameters(model, flatten = TRUE) names(params) <- params params } parameters/R/methods_BayesFactor.R 0000644 0001762 0000144 00000021751 14736731407 016710 0 ustar ligges users # classes: .BFBayesFactor #' Parameters from BayesFactor objects #' #' Parameters from `BFBayesFactor` objects from `{BayesFactor}` package. #' #' @param model Object of class `BFBayesFactor`. #' @param include_proportions Logical that decides whether to include posterior #' cell proportions/counts for Bayesian contingency table analysis (from #' `BayesFactor::contingencyTableBF()`). Defaults to `FALSE`, as this #' information is often redundant. #' @inheritParams bayestestR::describe_posterior #' @inheritParams p_value #' @inheritParams model_parameters.htest #' #' @details #' The meaning of the extracted parameters: #' #' - For [BayesFactor::ttestBF()]: `Difference` is the raw difference between #' the means. #' - For [BayesFactor::correlationBF()]: `rho` is the linear correlation #' estimate (equivalent to Pearson's *r*). #' - For [BayesFactor::lmBF()] / [BayesFactor::generalTestBF()] #' / [BayesFactor::regressionBF()] / [BayesFactor::anovaBF()]: in addition to #' parameters of the fixed and random effects, there are: `mu` is the #' (mean-centered) intercept; `sig2` is the model's sigma; `g` / `g_*` are #' the *g* parameters; See the *Bayes Factors for ANOVAs* paper #' (\doi{10.1016/j.jmp.2012.08.001}). #' #' @examplesIf require("BayesFactor") #' \donttest{ #' # Bayesian t-test #' model <- BayesFactor::ttestBF(x = rnorm(100, 1, 1)) #' model_parameters(model) #' model_parameters(model, es_type = "cohens_d", ci = 0.9) #' #' # Bayesian contingency table analysis #' data(raceDolls) #' bf <- BayesFactor::contingencyTableBF( #' raceDolls, #' sampleType = "indepMulti", #' fixedMargin = "cols" #' ) #' model_parameters(bf, #' centrality = "mean", #' dispersion = TRUE, #' verbose = FALSE, #' es_type = "cramers_v" #' ) #' } #' @return A data frame of indices related to the model's parameters. #' @export model_parameters.BFBayesFactor <- function(model, centrality = "median", dispersion = FALSE, ci = 0.95, ci_method = "eti", test = "pd", rope_range = "default", rope_ci = 0.95, priors = TRUE, es_type = NULL, include_proportions = FALSE, verbose = TRUE, ...) { insight::check_if_installed("BayesFactor") if (any(startsWith(names(model@numerator), "Null"))) { if (isTRUE(verbose)) { insight::format_alert( "Nothing to compute for point-null models.", "See github.com/easystats/parameters/issues/226" ) } return(NULL) } if (is.null(insight::get_parameters(model, verbose = FALSE))) { if (isTRUE(verbose)) { insight::format_warning("Can't extract model parameters.") } return(NULL) } out <- bayestestR::describe_posterior( model, centrality = centrality, dispersion = dispersion, ci = ci, ci_method = ci_method, test = test, rope_range = rope_range, rope_ci = rope_ci, priors = priors, verbose = verbose, ... ) bf_type <- .classify_BFBayesFactor(model) # Add components and effects columns cleaned_params <- NULL out <- tryCatch( { cleaned_params <- insight::clean_parameters(model) merge(out, cleaned_params[, c("Parameter", "Effects", "Component")], sort = FALSE) }, error = function(e) { out } ) # Extract BF tryCatch( { bfm <- as.data.frame(bayestestR::bayesfactor_models(model)[-1, ]) if (is.null(bfm$log_BF)) { out$BF <- bfm$BF } else { out$BF <- exp(bfm$log_BF) } }, error = function(e) { NULL } ) # leave out redundant posterior cell proportions/counts if (bf_type == "xtable" && isFALSE(include_proportions)) { out <- out[which(!startsWith(out$Parameter, "cell[")), , drop = FALSE] } # Effect size? if (!is.null(es_type)) { # needs {effectsize} to be installed insight::check_if_installed("effectsize") tryCatch( { effsize <- effectsize::effectsize(model, centrality = centrality, dispersion = dispersion, ci = ci, ci_method = ci_method, rope_ci = rope_ci, type = es_type, ... ) if (bf_type == "xtable" && isTRUE(include_proportions)) { out <- merge(out, effsize, sort = FALSE, all = TRUE) } else { if (bf_type == "xtable") { prefix <- "Cramers_" } else { prefix <- "d_" } ci_cols <- startsWith(colnames(effsize), "CI_") colnames(effsize)[ci_cols] <- paste0(prefix, colnames(effsize)[ci_cols]) out$CI <- NULL out <- cbind(out, effsize) } }, error = function(e) { NULL } ) } # # Remove unnecessary columns # if ("CI" %in% names(out) && length(stats::na.omit(unique(out$CI))) == 1) { # out$CI <- NULL # } if ("ROPE_CI" %in% names(out) && length(stats::na.omit(unique(out$ROPE_CI))) == 1) { out$ROPE_CI <- NULL } if ("ROPE_low" %in% names(out)) { out$ROPE_low <- NULL out$ROPE_high <- NULL } # ==== remove Component column if not needed if (!is.null(out$Component) && insight::n_unique(out$Component) == 1) out$Component <- NULL if (!is.null(out$Effects) && insight::n_unique(out$Effects) == 1) out$Effects <- NULL # ==== remove rows and columns with complete `NA`s out <- datawizard::remove_empty(out) # validation check: make sure BF column still exists, # see https://github.com/easystats/correlation/issues/269 if (is.null(out$BF)) { out$BF <- NA } # ==== pretty parameter names cp <- out$Parameter if (!is.null(cleaned_params) && length(cleaned_params$Cleaned_Parameter) == length(cp) && bf_type == "linear") { match_params <- stats::na.omit(match(cp, cleaned_params$Parameter)) cp <- cleaned_params$Cleaned_Parameter[match_params] } pretty_names <- stats::setNames( gsub("Cohens_d", "Cohen's D", gsub("Cramers_v", "Cramer's V", cp, fixed = TRUE), fixed = TRUE), out$Parameter ) if (!"Method" %in% names(out)) { out$Method <- .method_BFBayesFactor(model) } # reorder col_order <- c( "Parameter", "Mean", "Median", "MAD", "CI", "CI_low", "CI_high", "SD", "Cohens_d", "Cramers_v", "Cramers_v_adjusted", "d_CI_low", "d_CI_high", "Cramers_CI_low", "Cramers_CI_high", "pd", "ROPE_Percentage", "Prior_Distribution", "Prior_Location", "Prior_Scale", "Effects", "Component", "BF", "Method" ) out <- out[col_order[col_order %in% names(out)]] attr(out, "title") <- unique(out$Method) attr(out, "object_name") <- insight::safe_deparse_symbol(substitute(model)) attr(out, "pretty_names") <- pretty_names attr(out, "ci_test") <- ci out <- .add_model_parameters_attributes( params = out, model = model, ci = ci, ci_method = ci_method, verbose = verbose ) class(out) <- c("parameters_model", "see_parameters_model", class(out)) out } #' @export p_value.BFBayesFactor <- function(model, ...) { p <- bayestestR::p_direction(model) .data_frame( Parameter = .remove_backticks_from_string(p$Parameter), p = sapply(p$pd, bayestestR::convert_pd_to_p, simplify = TRUE) ) } # helper ------- .classify_BFBayesFactor <- function(x) { insight::check_if_installed("BayesFactor") if (inherits(x@denominator, "BFcorrelation")) { "correlation" } else if (inherits(x@denominator, "BFoneSample")) { "ttest1" } else if (inherits(x@denominator, "BFindepSample")) { "ttest2" } else if (inherits(x@denominator, "BFmetat")) { "meta" } else if (inherits(x@denominator, "BFlinearModel")) { "linear" } else if (inherits(x@denominator, "BFcontingencyTable")) { "xtable" } else if (inherits(x@denominator, "BFproportion")) { "proptest" } else { class(x@denominator) } } .method_BFBayesFactor <- function(x) { if (inherits(x@denominator, "BFcorrelation")) { "Bayesian correlation analysis" } else if (inherits(x@denominator, c("BFoneSample", "BFindepSample"))) { "Bayesian t-test" } else if (inherits(x@denominator, "BFmetat")) { "Meta-analytic Bayes factors" } else if (inherits(x@denominator, "BFlinearModel")) { "Bayes factors for linear models" } else if (inherits(x@denominator, "BFcontingencyTable")) { "Bayesian contingency table analysis" } else if (inherits(x@denominator, "BFproportion")) { "Bayesian proportion test" } else { NA_character_ } } parameters/R/utils_clustering.R 0000644 0001762 0000144 00000002432 14362231726 016347 0 ustar ligges users # Utils ------------------------------------------------------------------- #' @keywords internal .prepare_data_clustering <- function(x, include_factors = FALSE, standardize = FALSE, preprocess = TRUE, ...) { if (isFALSE(preprocess)) { return(x) } # include factors? if (include_factors) { # ordered factors to numeric factors <- vapply(x, is.ordered, TRUE) if (any(factors)) { x[factors] <- sapply( x[factors], datawizard::to_numeric, dummy_factors = FALSE, preserve_levels = TRUE ) } # character and factors to dummies factors <- sapply(x, function(i) is.character(i) | is.factor(i)) if (any(factors)) { dummies <- lapply(x[factors], .factor_to_dummy) x <- cbind(x[!factors], dummies) } } else { # remove factors x <- x[vapply(x, is.numeric, TRUE)] } # Remove all missing values from data, only use numerics x <- stats::na.omit(x) if (isTRUE(standardize)) { x <- datawizard::standardize(x, ...) # remove "dw_transformer" attribute x[] <- lapply(x, as.numeric) } x } parameters/R/cluster_discrimination.R 0000644 0001762 0000144 00000006025 14736731407 017535 0 ustar ligges users #' Compute a linear discriminant analysis on classified cluster groups #' #' Computes linear discriminant analysis (LDA) on classified cluster groups, and #' determines the goodness of classification for each cluster group. See `MASS::lda()` #' for details. #' #' @param x A data frame #' @param cluster_groups Group classification of the cluster analysis, which can #' be retrieved from the [cluster_analysis()] function. #' @param ... Other arguments to be passed to or from. #' #' @seealso [`n_clusters()`] to determine the number of clusters to extract, #' [`cluster_analysis()`] to compute a cluster analysis and #' [`performance::check_clusterstructure()`] to check suitability of data for #' clustering. #' #' @examplesIf requireNamespace("MASS", quietly = TRUE) #' # Retrieve group classification from hierarchical cluster analysis #' clustering <- cluster_analysis(iris[, 1:4], n = 3) #' #' # Goodness of group classification #' cluster_discrimination(clustering) #' @export cluster_discrimination <- function(x, cluster_groups = NULL, ...) { UseMethod("cluster_discrimination") } #' @export cluster_discrimination.cluster_analysis <- function(x, cluster_groups = NULL, ...) { if (is.null(cluster_groups)) { cluster_groups <- stats::predict(x) } cluster_discrimination(attributes(x)$data, cluster_groups, ...) } #' @export cluster_discrimination.default <- function(x, cluster_groups = NULL, ...) { if (is.null(cluster_groups)) { insight::format_error("Please provide cluster assignments via `cluster_groups`.") } x <- stats::na.omit(x) cluster_groups <- stats::na.omit(cluster_groups) # compute discriminant analysis of groups on original data frame insight::check_if_installed("MASS") disc <- MASS::lda(cluster_groups ~ ., data = x, na.action = "na.omit", CV = TRUE) # Assess the accuracy of the prediction # percent correct for each category of groups classification_table <- table(cluster_groups, disc$class) correct <- diag(prop.table(classification_table, 1)) # total correct percentage total_correct <- sum(diag(prop.table(classification_table))) out <- data.frame( Group = unique(cluster_groups), Accuracy = correct, stringsAsFactors = FALSE ) # Sort according to accuracy out <- out[order(out$Group), ] attr(out, "Overall_Accuracy") <- total_correct class(out) <- c("cluster_discrimination", class(out)) out } # Utils ------------------------------------------------------------------- #' @export print.cluster_discrimination <- function(x, ...) { orig_x <- x insight::print_color("# Accuracy of Cluster Group Classification via Linear Discriminant Analysis (LDA)\n\n", "blue") total_accuracy <- attributes(x)$Overall_Accuracy x$Accuracy <- sprintf("%.2f%%", 100 * x$Accuracy) total <- sprintf("%.2f%%", 100 * total_accuracy) print.data.frame(x, row.names = FALSE, ...) insight::print_color(sprintf("\nOverall accuracy of classification: %s\n", total), "yellow") invisible(orig_x) } parameters/R/methods_bayesQR.R 0000644 0001762 0000144 00000002750 14507235543 016046 0 ustar ligges users #' @export model_parameters.bayesQR <- function(model, centrality = "median", dispersion = FALSE, ci = 0.95, ci_method = "eti", test = "pd", rope_range = "default", rope_ci = 0.95, bf_prior = NULL, diagnostic = c("ESS", "Rhat"), priors = TRUE, keep = NULL, drop = NULL, verbose = TRUE, ...) { # Processing params <- .extract_parameters_bayesian( model, centrality = centrality, dispersion = dispersion, ci = ci, ci_method = ci_method, test = test, rope_range = rope_range, rope_ci = rope_ci, bf_prior = bf_prior, diagnostic = diagnostic, priors = priors, keep_parameters = keep, drop_parameters = drop, verbose = verbose, ... ) attr(params, "ci") <- ci attr(params, "object_name") <- insight::safe_deparse_symbol(substitute(model)) class(params) <- c("parameters_model", "see_parameters_model", class(params)) params } #' @export p_value.bayesQR <- p_value.BFBayesFactor parameters/R/methods_glmm.R 0000644 0001762 0000144 00000004355 14507235543 015437 0 ustar ligges users #' @export model_parameters.glmm <- function(model, ci = 0.95, effects = c("all", "fixed", "random"), bootstrap = FALSE, iterations = 1000, standardize = NULL, exponentiate = FALSE, keep = NULL, drop = NULL, verbose = TRUE, ...) { effects <- match.arg(effects) out <- .model_parameters_generic( model = model, ci = ci, bootstrap = bootstrap, iterations = iterations, merge_by = c("Parameter", "Effects"), standardize = standardize, exponentiate = exponentiate, keep_parameters = keep, drop_parameters = drop, effects = effects, ... ) attr(out, "object_name") <- insight::safe_deparse_symbol(substitute(model)) out } #' @export ci.glmm <- function(x, ci = 0.95, effects = c("all", "fixed", "random"), ...) { effects <- match.arg(effects) .ci_generic(model = x, ci = ci, dof = Inf, effects = effects, ...) } #' @export standard_error.glmm <- function(model, effects = c("all", "fixed", "random"), ...) { effects <- match.arg(effects) out <- insight::get_parameters(model, effects = "all") out$SE <- sqrt(diag(insight::get_varcov(model, effects = "all"))) out <- out[, c("Parameter", "SE", "Effects")] if (effects != "all") { out <- out[out$Effects == effects, , drop = FALSE] out$Effects <- NULL } out } #' @export p_value.glmm <- function(model, effects = c("all", "fixed", "random"), ...) { effects <- match.arg(effects) s <- summary(model) out <- insight::get_parameters(model, effects = "all") out$p <- c(s$coefmat[, 4], s$nucoefmat[, 4]) out <- out[, c("Parameter", "p", "Effects")] if (effects != "all") { out <- out[out$Effects == effects, , drop = FALSE] out$Effects <- NULL } out } #' @export format_parameters.glmm <- function(model, brackets = c("[", "]"), ...) { .format_parameter_default(model, effects = "all", brackets = brackets) } parameters/R/display.R 0000644 0001762 0000144 00000022616 14736731407 014431 0 ustar ligges users #' @title Print tables in different output formats #' @name display.parameters_model #' #' @description Prints tables (i.e. data frame) in different output formats. #' `print_md()` is an alias for `display(format = "markdown")`, `print_html()` #' is an alias for `display(format = "html")`. `print_table()` is for specific #' use cases only, and currently only works for `compare_parameters()` objects. #' #' @param x An object returned by [`model_parameters()`]. #' @param object An object returned by [`model_parameters()`],[`simulate_parameters()`], #' [`equivalence_test()`] or [`principal_components()`]. #' @param format String, indicating the output format. Can be `"markdown"` #' or `"html"`. #' @param align Only applies to HTML tables. May be one of `"left"`, #' `"right"` or `"center"`. #' @param digits,ci_digits,p_digits Number of digits for rounding or #' significant figures. May also be `"signif"` to return significant #' figures or `"scientific"` to return scientific notation. Control the #' number of digits by adding the value as suffix, e.g. `digits = "scientific4"` #' to have scientific notation with 4 decimal places, or `digits = "signif5"` #' for 5 significant figures (see also [signif()]). #' @param subtitle Table title (same as caption) and subtitle, as strings. If `NULL`, #' no title or subtitle is printed, unless it is stored as attributes (`table_title`, #' or its alias `table_caption`, and `table_subtitle`). If `x` is a list of #' data frames, `caption` may be a list of table captions, one for each table. #' @param font_size For HTML tables, the font size. #' @param line_padding For HTML tables, the distance (in pixel) between lines. #' @param column_labels Labels of columns for HTML tables. If `NULL`, automatic #' column names are generated. See 'Examples'. #' @param theme String, indicating the table theme. Can be one of `"default"`, #' `"grid"`, `"striped"`, `"bootstrap"` or `"darklines"`. #' @inheritParams print.parameters_model #' @inheritParams insight::format_table #' @inheritParams insight::export_table #' @inheritParams compare_parameters #' #' @return If `format = "markdown"`, the return value will be a character #' vector in markdown-table format. If `format = "html"`, an object of #' class `gt_tbl`. For `print_table()`, an object of class `tinytable` is #' returned. #' #' @details `display()` is useful when the table-output from functions, #' which is usually printed as formatted text-table to console, should #' be formatted for pretty table-rendering in markdown documents, or if #' knitted from rmarkdown to PDF or Word files. See #' [vignette](https://easystats.github.io/parameters/articles/model_parameters_formatting.html) #' for examples. #' #' `print_table()` is a special function for `compare_parameters()` objects, #' which prints the output as a formatted HTML table. It is still somewhat #' experimental, thus, only a fixed layout-style is available at the moment #' (columns for estimates, confidence intervals and p-values). However, it #' is possible to include other model components, like zero-inflation, or random #' effects in the table. See 'Examples'. An alternative is to set `engine = "tt"` #' in `print_html()` to use the _tinytable_ package for creating HTML tables. #' #' @seealso [print.parameters_model()] and [print.compare_parameters()] #' #' @examplesIf require("gt", quietly = TRUE) #' model <- lm(mpg ~ wt + cyl, data = mtcars) #' mp <- model_parameters(model) #' display(mp) #' #' \donttest{ #' data(iris) #' lm1 <- lm(Sepal.Length ~ Species, data = iris) #' lm2 <- lm(Sepal.Length ~ Species + Petal.Length, data = iris) #' lm3 <- lm(Sepal.Length ~ Species * Petal.Length, data = iris) #' out <- compare_parameters(lm1, lm2, lm3) #' #' print_html( #' out, #' select = "{coef}{stars}|({ci})", #' column_labels = c("Estimate", "95% CI") #' ) #' #' # line break, unicode minus-sign #' print_html( #' out, #' select = "{estimate}{stars}
({ci_low} \u2212 {ci_high})", #' column_labels = c("Est. (95% CI)") #' ) #' } #' @export display.parameters_model <- function(object, format = "markdown", pretty_names = TRUE, split_components = TRUE, select = NULL, caption = NULL, subtitle = NULL, footer = NULL, align = NULL, digits = 2, ci_digits = digits, p_digits = 3, footer_digits = 3, ci_brackets = c("(", ")"), show_sigma = FALSE, show_formula = FALSE, zap_small = FALSE, font_size = "100%", line_padding = 4, column_labels = NULL, include_reference = FALSE, verbose = TRUE, ...) { if (identical(format, "html")) { print_html( x = object, pretty_names = pretty_names, split_components = split_components, select = select, digits = digits, caption = caption, subtitle = subtitle, footer = footer, ci_digits = ci_digits, p_digits = p_digits, footer_digits = footer_digits, align = align, ci_brackets = ci_brackets, show_sigma = show_sigma, show_formula = show_formula, zap_small = zap_small, font_size = font_size, line_padding = line_padding, column_labels = column_labels, include_reference = include_reference, verbose = verbose, ... ) } else { print_md( x = object, pretty_names = pretty_names, split_components = split_components, select = select, digits = digits, caption = caption, subtitle = subtitle, footer = footer, ci_digits = ci_digits, p_digits = p_digits, footer_digits = footer_digits, ci_brackets = ci_brackets, show_sigma = show_sigma, show_formula = show_formula, zap_small = zap_small, include_reference = include_reference, verbose = verbose, ... ) } } #' @export display.parameters_simulate <- display.parameters_model #' @export display.parameters_brms_meta <- display.parameters_model # Compare Parameters ------------------------ #' @export display.compare_parameters <- function(object, format = "markdown", digits = 2, ci_digits = digits, p_digits = 3, select = NULL, column_labels = NULL, ci_brackets = c("(", ")"), font_size = "100%", line_padding = 4, zap_small = FALSE, ...) { if (identical(format, "html")) { print_html( x = object, digits = digits, ci_digits = ci_digits, p_digits = p_digits, select = select, column_labels = column_labels, font_size = font_size, line_padding = line_padding, ci_brackets = ci_brackets, zap_small = zap_small, ... ) } else { print_md(x = object, digits = digits, ci_digits = ci_digits, p_digits = p_digits, select = select, ...) } } # SEM models ------------------------ #' @rdname display.parameters_model #' @export display.parameters_sem <- function(object, format = "markdown", digits = 2, ci_digits = digits, p_digits = 3, ci_brackets = c("(", ")"), ...) { print_md(x = object, digits = digits, ci_digits = ci_digits, p_digits = p_digits, ci_brackets = ci_brackets, ...) } # PCA /EFA models ------------------------ #' @rdname display.parameters_model #' @export display.parameters_efa_summary <- function(object, format = "markdown", digits = 3, ...) { print_md(x = object, digits = digits, ...) } #' @export display.parameters_pca_summary <- display.parameters_efa_summary #' @inheritParams model_parameters.principal #' @rdname display.parameters_model #' @export display.parameters_efa <- function(object, format = "markdown", digits = 2, sort = FALSE, threshold = NULL, labels = NULL, ...) { print_md(x = object, digits = digits, sort = sort, threshold = threshold, labels = labels, ...) } #' @export display.parameters_pca <- display.parameters_efa # Equivalence tests ------------------------ #' @rdname display.parameters_model #' @export display.equivalence_test_lm <- function(object, format = "markdown", digits = 2, ...) { print_md(x = object, digits = digits, ...) } # Other functions ------------------------ #' @export display.parameters_distribution <- function(object, format = "markdown", digits = 2, ...) { print_md(x = object, digits = digits, ...) } parameters/R/methods_BBMM.R 0000644 0001762 0000144 00000002616 14716604200 015206 0 ustar ligges users #' @export ci.BBmm <- ci.default #' @export ci.BBreg <- ci.default #' @export standard_error.BBmm <- function(model, ...) { .data_frame( Parameter = insight::find_parameters(model, effects = "fixed", component = "conditional", flatten = TRUE ), SE = as.data.frame(summary(model)$fixed.coefficients)$StdErr ) } #' @export standard_error.BBreg <- function(model, ...) { .data_frame( Parameter = insight::find_parameters(model, effects = "fixed", component = "conditional", flatten = TRUE ), SE = as.data.frame(summary(model)$coefficients)$StdErr ) } ## TODO add ci_method later? ## TODO BBmm only has p based on normal distribution assumptions? #' @export p_value.BBmm <- function(model, ...) { .data_frame( Parameter = insight::find_parameters(model, effects = "fixed", component = "conditional", flatten = TRUE ), p = as.data.frame(summary(model)$fixed.coefficients)$p.value ) } ## TODO add ci_method later? ## TODO BBreg only has p based on normal distribution assumptions? #' @export p_value.BBreg <- function(model, ...) { .data_frame( Parameter = insight::find_parameters(model, effects = "fixed", component = "conditional", flatten = TRUE ), p = as.data.frame(summary(model)$coefficients)$p.value ) } parameters/R/methods_base.R 0000644 0001762 0000144 00000007670 14736731407 015424 0 ustar ligges users #' @rdname model_parameters.brmsfit #' @export model_parameters.data.frame <- function(model, as_draws = FALSE, exponentiate = FALSE, verbose = TRUE, ...) { # treat data frame as bootstraps/posteriors? if (isTRUE(as_draws)) { return(model_parameters.draws(model, exponentiate = exponentiate, verbose = verbose, ...)) } if (isTRUE(verbose)) { insight::format_warning( "A `data.frame` object is no valid regression model object and cannot be used with `model_parameters()`." ) } NULL } # Standard Errors from standard classes --------------------------------------------- #' @rdname standard_error #' @export standard_error.factor <- function(model, force = FALSE, verbose = TRUE, ...) { if (!force) { if (verbose) { insight::format_warning("Can't compute standard error of non-numeric variables.") } return(NA) } standard_error(as.numeric(model), ...) } #' @export standard_error.character <- standard_error.factor #' @export standard_error.numeric <- function(model, ...) { sqrt(stats::var(model, na.rm = TRUE) / length(stats::na.omit(model))) } #' @export standard_error.data.frame <- function(model, verbose = TRUE, ...) { unlist(sapply(model, standard_error, verbose = verbose)) } #' @export standard_error.list <- function(model, verbose = TRUE, ...) { if ("gam" %in% names(model)) { model <- model$gam class(model) <- c("gam", "lm", "glm") standard_error(model) } else if (isTRUE(verbose)) { insight::print_color("\nCould not extract standard errors from model object.\n", "red") } } #' @export standard_error.table <- function(model, ...) { # compute standard error of proportions if (length(dim(model)) == 1) { total.n <- as.vector(sum(model)) rel.frq <- as.vector(model) / total.n out <- .data_frame( Value = names(model), Proportion = rel.frq, SE = suppressWarnings(sqrt(rel.frq * (1 - rel.frq) / total.n)) ) } else { out <- NA } out } #' @export standard_error.xtabs <- standard_error.table #' @export standard_error.parameters_standardized <- function(model, verbose = TRUE, ...) { se <- attr(model, "standard_error") if (is.null(se)) { if (isTRUE(verbose)) { insight::print_color("\nCould not extract standard errors of standardized coefficients.\n", "red") } return(NULL) } # for "refit" method if (is.data.frame(se) && "SE" %in% colnames(se)) { se <- se$SE } out <- .data_frame( Parameter = model$Parameter, SE = as.vector(se) ) insight::text_remove_backticks(out, verbose = FALSE) } # p-Values from standard classes --------------------------------------------- #' @export p_value.numeric <- function(model, null = 0, ...) { # k_lt0 <- sum(model <= 0) # k_gt0 <- sum(model >= 0) # k <- 2 * min(k_lt0, k_gt0) # N <- length(model) # https://blogs.sas.com/content/iml/2011/11/02/how-to-compute-p-values-for-a-bootstrap-distribution.html # https://stats.stackexchange.com/a/28725/293056 x <- stats::na.omit(model) xM <- mean(x) x0 <- x - xM k <- sum(abs(x0) > abs(xM - null)) # two tailed p-value N <- length(x) (k + 1) / (N + 1) } #' @export p_value.data.frame <- function(model, ...) { model_data <- model[vapply(model, is.numeric, TRUE)] .data_frame( Parameter = names(model_data), p = vapply(model_data, p_value, 1) ) } #' @export p_value.list <- function(model, method = NULL, verbose = TRUE, ...) { if ("gam" %in% names(model)) { model <- model$gam class(model) <- c("gam", "lm", "glm") p_value(model, method = method) } else if (isTRUE(verbose)) { insight::format_warning("Could not extract p-values from model object.") } } parameters/R/datasets.R 0000644 0001762 0000144 00000001631 14077467603 014570 0 ustar ligges users #' @docType data #' @title Sample data set #' @name fish #' @keywords data #' #' @description A sample data set, used in tests and some examples. NULL #' @docType data #' @title Sample data set #' @name qol_cancer #' @keywords data #' #' @description A sample data set with longitudinal data, used in the vignette describing the `datawizard::demean()` function. Health-related quality of life from cancer-patients was measured at three time points (pre-surgery, 6 and 12 months after surgery). #' #' @format A data frame with 564 rows and 7 variables: #' \describe{ #' \item{ID}{Patient ID} #' \item{QoL}{Quality of Life Score} #' \item{time}{Timepoint of measurement} #' \item{age}{Age in years} #' \item{phq4}{Patients' Health Questionnaire, 4-item version} #' \item{hospital}{Hospital ID, where patient was treated} #' \item{education}{Patients' educational level} #' } NULL parameters/R/print_table.R 0000644 0001762 0000144 00000013346 14716604200 015253 0 ustar ligges users #' @examplesIf require("tinytable") && require("lme4") && require("glmmTMB") #' \donttest{ #' data(iris) #' data(Salamanders, package = "glmmTMB") #' m1 <- lm(Sepal.Length ~ Species * Petal.Length, data = iris) #' m2 <- lme4::lmer( #' Sepal.Length ~ Petal.Length + Petal.Width + (1 | Species), #' data = iris #' ) #' m3 <- glmmTMB::glmmTMB( #' count ~ spp + mined + (1 | site), #' ziformula = ~mined, #' family = poisson(), #' data = Salamanders #' ) #' out <- compare_parameters(m1, m2, m3, effects = "all", component = "all") #' print_table(out) #' } #' @rdname display.parameters_model #' @export print_table <- function(x, digits = 2, p_digits = 3, theme = "default", ...) { insight::check_if_installed(c("datawizard", "tinytable")) if (!inherits(x, "compare_parameters")) { insight::format_error("`print_table` can only be used with `compare_parameters` objects.") } # random parameters? random_variances <- any(unlist(lapply(attributes(x)$all_attributes, function(i) { i$ran_pars }))) # remember attributes ci_lvl <- attributes(x)$all_attributes[[1]]$ci model_names <- attributes(x)$model_names # check if we have mixed models with random variance parameters. in such # cases, we don't need the group-column, but we rather merge it with the # parameter column if (isTRUE(random_variances)) { # if (any(c("brmsfit", "stanreg", "stanmvreg") %in% m_class)) { # # rename random effect parameters names for stan models # x <- .format_stan_parameters(x) # } else { # x <- .format_ranef_parameters(x) # } x <- .format_ranef_parameters(x) x$Group <- NULL } # check if we have only have fixed effects, and if so, remove column if (!is.null(x$Effects) && all(x$Effects == "fixed")) { x$Effects <- NULL } # check if we have only have conditional component, and if so, remove column if (!is.null(x$Component) && all(x$Component == "conditional")) { x$Component <- NULL } # check if we have models with extra components (e.g., zero-inflated models) # if so, we need to create a group variable, so we can include subheaders in # the table, and we want to re-arrange rows if (!is.null(x$Component) || !is.null(x$Effects)) { # create group variable, so we can include subheaders in table x$groups <- paste0(x$Component, ".", x$Effects) x <- datawizard::data_arrange(x, c("Effects", "Component")) # remove further unused columns x$Component <- NULL x$Effects <- NULL } # we now iterate all model columns, remove non-used columns per model, # and create the formated CI columns etc. for (i in model_names) { x[paste0("SE.", i)] <- NULL x[paste0("df_error.", i)] <- NULL x[paste0("z.", i)] <- NULL x[paste0("t.", i)] <- NULL ci_pos <- which(colnames(x) == paste0("CI.", i)) x[paste0("CI.", i)] <- NULL # format estimate columns estimate_col <- min(which(endsWith(colnames(x), paste0(".", i)))) x[[estimate_col]] <- insight::format_value( x[[estimate_col]], digits = digits, zap_small = TRUE ) # format CI columns x$CI <- insight::format_ci( x[[paste0("CI_low.", i)]], x[[paste0("CI_high.", i)]], digits = digits, ci = NULL, brackets = FALSE, zap_small = TRUE ) colnames(x)[colnames(x) == "CI"] <- paste0(sprintf("%g", 100 * ci_lvl), "% CI.", i) x[paste0("CI_low.", i)] <- NULL x[paste0("CI_high.", i)] <- NULL # format p-values x[[paste0("p.", i)]] <- insight::format_p( x[[paste0("p.", i)]], digits = p_digits, name = NULL ) # relocate CI columns to right position x <- x[c(1:(ci_pos - 1), ncol(x), ci_pos:(ncol(x) - 1))] } # used for subgroup headers, if available row_header_pos <- row_header_labels <- NULL if (!is.null(x$groups)) { # find start row of each subgroup row_header_pos <- which(!duplicated(x$groups)) group_headers <- as.vector(x$groups[row_header_pos]) for (i in seq_along(group_headers)) { gh <- .format_model_component_header( x = NULL, type = group_headers[i], split_column = "", is_zero_inflated = FALSE, is_ordinal_model = FALSE, is_multivariate = FALSE, ran_pars = random_variances, formatted_table = NULL ) group_headers[i] <- gh$name } # create named list, required for tinytables row_header_labels <- as.list(stats::setNames(row_header_pos, group_headers)) # since we have the group names in "row_header_labels" now , we can remove the column x$groups <- NULL # make sure that the row header positions are correct - each header # must be shifted by the number of rows above for (i in 2:length(row_header_pos)) { row_header_pos[i] <- row_header_pos[i] + (i - 1) } } # find out position of column groups col_groups <- lapply(model_names, function(i) { which(endsWith(colnames(x), paste0(".", i))) }) names(col_groups) <- model_names # fix column names for (i in model_names) { colnames(x) <- gsub(paste0("\\.", i, "$"), "", colnames(x)) } # base table out <- tinytable::tt(as.data.frame(x), caption = NULL, notes = NULL, ...) # add subheaders, if any if (is.null(row_header_labels)) { out <- tinytable::group_tt(out, j = col_groups) } else { out <- tinytable::group_tt(out, i = row_header_labels, j = col_groups) out <- tinytable::style_tt(out, i = row_header_pos, italic = TRUE) } # style table out <- insight::apply_table_theme(out, x, theme = theme, sub_header_positions = row_header_pos) # make sure HTML is default output out@output <- "html" out } parameters/R/dof_kenward.R 0000644 0001762 0000144 00000021460 14761570351 015240 0 ustar ligges users #' @rdname p_value_kenward #' @export dof_kenward <- function(model) { parameters <- insight::find_parameters(model, effects = "fixed", flatten = TRUE) L <- as.data.frame(diag(rep(1, n_parameters(model, effects = "fixed")))) krvcov <- .vcov_kenward_ajusted(model) dof <- stats::setNames(sapply(L, .kenward_adjusted_ddf, model = model, adjusted_vcov = krvcov), parameters) attr(dof, "vcov") <- krvcov attr(dof, "se") <- abs(as.vector(sqrt(diag(as.matrix(krvcov))))) dof } # The following code was taken from the "pbkrtest" package and slightly modified #' @author Søren Højsgaard, \email{sorenh@@math.aau.dk} .kenward_adjusted_ddf <- function(model, linear_coef, adjusted_vcov) { .adjusted_ddf(adjusted_vcov, linear_coef, stats::vcov(model)) } .adjusted_ddf <- function(adjusted_vcov, linear_coef, unadjusted_vcov = adjusted_vcov) { insight::check_if_installed("Matrix") if (!is.matrix(linear_coef)) { linear_coef <- matrix(linear_coef, ncol = 1) } vlb <- sum(linear_coef * (unadjusted_vcov %*% linear_coef)) theta <- Matrix::Matrix(as.numeric(outer(linear_coef, linear_coef) / vlb), nrow = length(linear_coef)) P <- attr(adjusted_vcov, "P") W <- attr(adjusted_vcov, "W") A1 <- A2 <- 0 theta_unadjusted_vcov <- theta %*% unadjusted_vcov n.ggamma <- length(P) for (ii in 1:n.ggamma) { for (jj in ii:n.ggamma) { if (ii == jj) { e <- 1 } else { e <- 2 } ui <- as.matrix(theta_unadjusted_vcov %*% P[[ii]] %*% unadjusted_vcov) uj <- as.matrix(theta_unadjusted_vcov %*% P[[jj]] %*% unadjusted_vcov) A1 <- A1 + e * W[ii, jj] * (sum(diag(ui)) * sum(diag(uj))) A2 <- A2 + e * W[ii, jj] * sum(ui * t(uj)) } } B <- (A1 + 6 * A2) / 2 g <- (2 * A1 - 5 * A2) / (3 * A2) c1 <- g / (3 + 2 * (1 - g)) c2 <- (1 - g) / (3 + 2 * (1 - g)) c3 <- (3 - g) / (3 + 2 * (1 - g)) EE <- 1 + A2 VV <- 2 * (1 + B) EEstar <- 1 / (1 - A2) VVstar <- 2 * ((1 + c1 * B) / ((1 - c2 * B)^2 * (1 - c3 * B))) V0 <- 1 + c1 * B V1 <- 1 - c2 * B V2 <- 1 - c3 * B V0 <- ifelse(abs(V0) < 1e-10, 0, V0) rho <- (.divZero(1 - A2, V1))^2 * V0 / V2 df2 <- 4 + 3 / (rho - 1) df2 } .divZero <- function(x, y, tol = 1e-14) { ## ratio x/y is set to 1 if both |x| and |y| are below tol if (abs(x) < tol && abs(y) < tol) { 1 } else { x / y } } .vcov_kenward_ajusted <- function(model) { insight::check_if_installed("lme4") if (!(lme4::getME(model, "is_REML"))) { model <- stats::update(model, . ~ ., REML = TRUE) } .vcovAdj16_internal(stats::vcov(model), .get_SigmaG(model), lme4::getME(model, "X")) } .get_SigmaG <- function(model) { insight::check_if_installed("lme4") insight::check_if_installed("Matrix") GGamma <- lme4::VarCorr(model) SS <- .shgetME(model) ## Put covariance parameters for the random effects into a vector: ## TODO: It is a bit ugly to throw everything into one long vector here; a list would be more elegant ggamma <- NULL for (ii in 1:(SS$n.RT)) { Lii <- GGamma[[ii]] ggamma <- c(ggamma, Lii[lower.tri(Lii, diag = TRUE)]) } ggamma <- c(ggamma, stats::sigma(model)^2) ## Extend ggamma by the residuals variance n.ggamma <- length(ggamma) ## Find G_r: G <- NULL Zt <- lme4::getME(model, "Zt") for (ss in 1:SS$n.RT) { ZZ <- .shget_Zt_group(ss, Zt, SS$Gp) n.lev <- SS$n.lev.by.RT2[ss] ## ; cat(sprintf("n.lev=%i\n", n.lev)) Ig <- Matrix::sparseMatrix(1:n.lev, 1:n.lev, x = 1) for (rr in 1:SS$n.parm.by.RT[ss]) { ## This is takes care of the case where there is random regression and several matrices have to be constructed. ## FIXME: I am not sure this is correct if there is a random quadratic term. The '2' below looks suspicious. ii.jj <- .index2UpperTriEntry(rr, SS$n.comp.by.RT[ss]) ## ; cat("ii.jj:"); print(ii.jj) ii.jj <- unique(ii.jj) if (length(ii.jj) == 1) { EE <- Matrix::sparseMatrix( ii.jj, ii.jj, x = 1, dims = rep(SS$n.comp.by.RT[ss], 2) ) } else { EE <- Matrix::sparseMatrix(ii.jj, ii.jj[2:1], dims = rep(SS$n.comp.by.RT[ss], 2)) } EE <- Ig %x% EE ## Kronecker product G <- c(G, list(t(ZZ) %*% EE %*% ZZ)) } } ## Extend by the indentity for the residual n.obs <- insight::n_obs(model) G <- c(G, list(Matrix::sparseMatrix(1:n.obs, 1:n.obs, x = 1))) Sigma <- ggamma[1] * G[[1]] for (ii in 2:n.ggamma) { Sigma <- Sigma + ggamma[ii] * G[[ii]] } list(Sigma = Sigma, G = G, n.ggamma = n.ggamma) } .index2UpperTriEntry <- function(k, N) { ## inverse of indexSymmat2vec ## result: index pair (i,j) with i>=j ## k: element in the vector of upper triangular elements ## example: N=3: k=1 -> (1,1), k=2 -> (1,2), k=3 -> (1,3), k=4 -> (2,2) aa <- cumsum(N:1) aaLow <- c(0, aa[-length(aa)]) i <- which(aaLow < k & k <= aa) j <- k - N * i + N - i * (3 - i) / 2 + i c(i, j) } .vcovAdj16_internal <- function(Phi, SigmaG, X) { insight::check_if_installed("MASS") insight::check_if_installed("Matrix") SigmaInv <- chol2inv(chol(Matrix::forceSymmetric(as.matrix(SigmaG$Sigma)))) n.ggamma <- SigmaG$n.ggamma TT <- as.matrix(SigmaInv %*% X) HH <- OO <- vector("list", n.ggamma) for (ii in 1:n.ggamma) { HH[[ii]] <- as.matrix(SigmaG$G[[ii]] %*% SigmaInv) OO[[ii]] <- as.matrix(HH[[ii]] %*% X) } ## Finding PP, QQ PP <- QQ <- NULL for (rr in 1:n.ggamma) { OrTrans <- t(OO[[rr]]) PP <- c(PP, list(Matrix::forceSymmetric(-1 * OrTrans %*% TT))) for (ss in rr:n.ggamma) { QQ <- c(QQ, list(OrTrans %*% SigmaInv %*% OO[[ss]])) } } PP <- as.matrix(PP) QQ <- as.matrix(QQ) Ktrace <- matrix(NA, nrow = n.ggamma, ncol = n.ggamma) for (rr in 1:n.ggamma) { HrTrans <- t(HH[[rr]]) for (ss in rr:n.ggamma) { Ktrace[rr, ss] <- Ktrace[ss, rr] <- sum(HrTrans * HH[[ss]]) } } ## Finding information matrix IE2 <- matrix(NA, nrow = n.ggamma, ncol = n.ggamma) for (ii in 1:n.ggamma) { Phi.P.ii <- Phi %*% PP[[ii]] for (jj in ii:n.ggamma) { www <- .indexSymmat2vec(ii, jj, n.ggamma) IE2[ii, jj] <- IE2[jj, ii] <- Ktrace[ii, jj] - 2 * sum(Phi * QQ[[www]]) + sum(Phi.P.ii * (PP[[jj]] %*% Phi)) } } eigenIE2 <- eigen(IE2, only.values = TRUE)$values condi <- min(abs(eigenIE2)) WW <- if (condi > 1e-10) { as.matrix(Matrix::forceSymmetric(2 * solve(IE2))) } else { as.matrix(Matrix::forceSymmetric(2 * MASS::ginv(IE2))) } UU <- matrix(0, nrow = ncol(X), ncol = ncol(X)) for (ii in 1:(n.ggamma - 1)) { for (jj in (ii + 1):n.ggamma) { www <- .indexSymmat2vec(ii, jj, n.ggamma) UU <- UU + WW[ii, jj] * (QQ[[www]] - PP[[ii]] %*% Phi %*% PP[[jj]]) } } UU <- as.matrix(UU) UU <- UU + t(UU) for (ii in 1:n.ggamma) { www <- .indexSymmat2vec(ii, ii, n.ggamma) UU <- UU + WW[ii, ii] * (QQ[[www]] - PP[[ii]] %*% Phi %*% PP[[ii]]) } GGAMMA <- Phi %*% UU %*% Phi PhiA <- Phi + 2 * GGAMMA attr(PhiA, "P") <- PP attr(PhiA, "W") <- WW attr(PhiA, "condi") <- condi PhiA } .indexSymmat2vec <- function(i, j, N) { ## S[i,j] symetric N times N matrix ## r the vector of upper triangular element in row major order: ## r= c(S[1,1],S[1,2]...,S[1,j], S[1,N], S[2,2],...S[N,N] ## Result: k: index of k-th element of r k <- if (i <= j) { (i - 1) * (N - i / 2) + j } else { (j - 1) * (N - j / 2) + i } } .shgetME <- function(model) { insight::check_if_installed("lme4") Gp <- lme4::getME(model, "Gp") n.RT <- length(Gp) - 1 ## Number of random terms (i.e. of (|)'s) n.lev.by.RT <- sapply(lme4::getME(model, "flist"), nlevels) n.comp.by.RT <- .get.RT.dim.by.RT(model) n.parm.by.RT <- (n.comp.by.RT + 1) * n.comp.by.RT / 2 n.RE.by.RT <- diff(Gp) n.lev.by.RT2 <- n.RE.by.RT / n.comp.by.RT ## Same as n.lev.by.RT2 ??? list( Gp = Gp, ## group.index n.RT = n.RT, ## n.groupFac n.lev.by.RT = n.lev.by.RT, ## nn.groupFacLevelsNew n.comp.by.RT = n.comp.by.RT, ## nn.GGamma n.parm.by.RT = n.parm.by.RT, ## mm.GGamma n.RE.by.RT = n.RE.by.RT, ## ... Not returned before n.lev.by.RT2 = n.lev.by.RT2, ## nn.groupFacLevels n_rtrms = lme4::getME(model, "n_rtrms") ) } ## Alternative to .get_Zt_group .shget_Zt_group <- function(ii.group, Zt, Gp, ...) { zIndex.sub <- (Gp[ii.group] + 1):Gp[ii.group + 1] as.matrix(Zt[zIndex.sub, ]) } .get.RT.dim.by.RT <- function(model) { insight::check_if_installed("lme4") ## output: dimension (no of columns) of covariance matrix for random term ii if (inherits(model, "mer")) { vapply(model@ST, nrow, numeric(1)) } else { lengths(lme4::getME(model, "cnms")) } } parameters/R/methods_mmrm.R 0000644 0001762 0000144 00000005304 14761570351 015447 0 ustar ligges users # model_parameters -------------------- #' @export model_parameters.mmrm <- function(model, ci = 0.95, ci_method = NULL, bootstrap = FALSE, iterations = 1000, standardize = NULL, exponentiate = FALSE, p_adjust = NULL, include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, ...) { ci_method <- switch(model$method, Satterthwaite = "satterthwaite", "kenward" ) # extract model parameters table, as data frame out <- .model_parameters_generic( model = model, ci = ci, ci_method = ci_method, bootstrap = bootstrap, iterations = iterations, merge_by = "Parameter", standardize = standardize, exponentiate = exponentiate, p_adjust = p_adjust, include_info = include_info, keep_parameters = keep, drop_parameters = drop, vcov = NULL, vcov_args = NULL, verbose = verbose, ... ) attr(out, "object_name") <- insight::safe_deparse_symbol(substitute(model)) out } #' @export model_parameters.mmrm_fit <- model_parameters.mmrm #' @export model_parameters.mmrm_tmb <- model_parameters.mmrm # ci -------------------- #' @export ci.mmrm <- function(x, ci = 0.95, method = "residual", ...) { .ci_generic(model = x, ci = ci, method = "residual", ...) } #' @export ci.mmrm_fit <- ci.mmrm #' @export ci.mmrm_tmb <- ci.mmrm # p -------------------- #' @export p_value.mmrm <- function(model, dof = NULL, method = NULL, component = "all", vcov = NULL, vcov_args = NULL, verbose = TRUE, ...) { p_value.default( model, dof = NULL, method = NULL, component = "all", vcov = NULL, vcov_args = NULL, verbose = verbose, ... ) } #' @export p_value.mmrm_fit <- p_value.mmrm #' @export p_value.mmrm_tmb <- p_value.mmrm # SE -------------------- #' @export standard_error.mmrm <- function(model, ...) { se <- .get_se_from_summary(model) .data_frame(Parameter = names(se), SE = as.vector(se)) } #' @export standard_error.mmrm_fit <- standard_error.mmrm #' @export standard_error.mmrm_tmb <- standard_error.mmrm parameters/R/methods_gamlss.R 0000644 0001762 0000144 00000001240 14507235543 015757 0 ustar ligges users #################### .gamlss ------ #' @export model_parameters.gamlss <- model_parameters.gam #' @export standard_error.gamlss <- function(model, ...) { parms <- insight::get_parameters(model) utils::capture.output({ cs <- summary(model) }) .data_frame( Parameter = parms$Parameter, SE = as.vector(cs[, 2]), Component = parms$Component ) } #' @export p_value.gamlss <- function(model, ...) { parms <- insight::get_parameters(model) utils::capture.output({ cs <- summary(model) }) .data_frame( Parameter = parms$Parameter, p = as.vector(cs[, 4]), Component = parms$Component ) } parameters/R/methods_phylolm.R 0000644 0001762 0000144 00000001623 14411001335 016142 0 ustar ligges users # ci ----------------- #' @export ci.phylolm <- function(x, ci = 0.95, dof = NULL, method = "wald", verbose = TRUE, ...) { method <- match.arg(method, choices = c("wald", "residual", "normal", "boot")) if (method == "boot" && (is.null(x$boot) || x$boot <= 0)) { insight::format_warning( "Bootstrapped confidence intervals are not available", "Try re-fitting your model, using `boot =
({se})|{p}") #' print_html(result) #' } #' #' data(mtcars) #' m1 <- lm(mpg ~ wt, data = mtcars) #' m2 <- glm(vs ~ wt + cyl, data = mtcars, family = "binomial") #' compare_parameters(m1, m2) #' \donttest{ #' # exponentiate coefficients, but not for lm #' compare_parameters(m1, m2, exponentiate = "nongaussian") #' #' # change column names #' compare_parameters("linear model" = m1, "logistic reg." = m2) #' compare_parameters(m1, m2, column_names = c("linear model", "logistic reg.")) #' #' # or as list #' compare_parameters(list(m1, m2)) #' compare_parameters(list("linear model" = m1, "logistic reg." = m2)) #' } #' @export compare_parameters <- function(..., ci = 0.95, effects = "fixed", component = "conditional", standardize = NULL, exponentiate = FALSE, ci_method = "wald", p_adjust = NULL, select = NULL, column_names = NULL, pretty_names = TRUE, coefficient_names = NULL, keep = NULL, drop = NULL, include_reference = FALSE, groups = NULL, verbose = TRUE) { models <- list(...) if (length(models) == 1) { if (insight::is_model(models[[1]]) || inherits(models[[1]], "parameters_model")) { modellist <- FALSE } else { models <- models[[1]] modellist <- TRUE } } else { modellist <- FALSE } if (isTRUE(modellist)) { model_names <- names(models) if (length(model_names) == 0) { model_names <- paste("Model", seq_along(models), sep = " ") names(models) <- model_names } } else { model_names <- match.call(expand.dots = FALSE)[["..."]] if (length(names(model_names)) > 0) { model_names <- names(model_names) } else if (any(vapply(model_names, is.call, TRUE))) { model_names <- paste("Model", seq_along(models), sep = " ") } else { model_names <- vapply(model_names, as.character, character(1)) names(models) <- model_names } } supported_models <- vapply(models, function(i) { insight::is_model_supported(i) || inherits(i, "lavaan") || inherits(i, "parameters_model") }, TRUE) if (!all(supported_models)) { if (verbose) { insight::format_alert( sprintf("Following objects are not supported: %s", toString(model_names[!supported_models])), "Dropping unsupported models now." ) } models <- models[supported_models] model_names <- model_names[supported_models] } # set default if (is.null(select)) { if (is.null(ci) || is.na(ci)) { # if user set CI to NULL, show only estimates by default select <- "{estimate}" } else { # if we have CI, include them select <- "ci" } } # provide own names if (!is.null(column_names)) { if (length(column_names) != length(model_names)) { if (isTRUE(verbose)) { insight::format_alert("Number of column names does not match number of models.") } } else { model_names <- column_names } } # make sure we have enough coefficient names - else, repeat first value if (!is.null(coefficient_names) && length(coefficient_names) < length(models)) { coefficient_names <- rep(coefficient_names[1], length(models)) } # iterate all models and create list of model parameters m <- lapply(seq_along(models), function(i) { model <- models[[i]] model_name <- model_names[[i]] if (inherits(model, "parameters_model")) { # we already have model parameters object... dat <- model } else { # set default-ci_type for Bayesian models if (.is_bayesian_model(model, exclude = c("bmerMod", "bayesx", "blmerMod", "bglmerMod")) && !ci_method %in% c("hdi", "quantile", "ci", "eti", "si", "bci", "bcai")) { # nolint ci_method_tmp <- "eti" } else { ci_method_tmp <- ci_method } # here we have a model object that needs to be passed to model_parameters dat <- model_parameters( model, ci = ci, effects = effects, component = component, standardize = standardize, exponentiate = exponentiate, ci_method = ci_method_tmp, p_adjust = p_adjust, keep = keep, drop = drop, wb_component = FALSE, include_reference = include_reference, verbose = verbose ) } # set specific names for coefficient column coef_name <- attributes(dat)$coefficient_name if (!is.null(coef_name) && is.null(coefficient_names)) { colnames(dat)[colnames(dat) == "Coefficient"] <- coef_name } else if (!is.null(coefficient_names)) { colnames(dat)[colnames(dat) == "Coefficient"] <- coefficient_names[i] } # set pretty parameter names dat <- .set_pretty_names(dat, pretty_names) # make sure we have a component- and effects column, for merging if (!"Component" %in% colnames(dat)) { dat$Component <- "conditional" } if (!"Effects" %in% colnames(dat)) { dat$Effects <- "fixed" } if (!"Group" %in% colnames(dat)) { dat$Group <- "" } # add zi-suffix to parameter names if (any(dat$Component == "zero_inflated")) { dat$Parameter[dat$Component == "zero_inflated"] <- paste0(dat$Parameter[dat$Component == "zero_inflated"], " (zi)") } # add suffix ignore <- colnames(dat) %in% c("Parameter", "Component", "Effects", "Group") colnames(dat)[!ignore] <- paste0(colnames(dat)[!ignore], ".", model_name) # save model number, for sorting dat$model <- i dat$model[.in_intercepts(dat$Parameter)] <- 0 dat }) object_attributes <- lapply(m, attributes) names(object_attributes) <- model_names # merge all data frames all_models <- suppressWarnings(Reduce(function(x, y) { merge(x, y, all = TRUE, sort = FALSE, by = c("Parameter", "Component", "Effects", "Group")) }, m)) # find columns with model numbers and create new variable "params_order", # which is pasted together of all model-column indices. Take lowest index of # all model-column indices, which then indicates order of parameters/rows. model_cols <- which(startsWith(colnames(all_models), "model")) params_order <- as.numeric(substr(gsub("NA", "", do.call(paste0, all_models[model_cols]), fixed = TRUE), 0, 1)) all_models <- all_models[order(params_order), ] all_models[model_cols] <- NULL # remove empty group-column if (!any(nzchar(as.character(all_models$Group), keepNA = TRUE))) { all_models$Group <- NULL } attr(all_models, "model_names") <- gsub("\"", "", unlist(lapply(model_names, insight::safe_deparse)), fixed = TRUE) attr(all_models, "output_style") <- select attr(all_models, "all_attributes") <- object_attributes attr(all_models, "parameter_groups") <- groups class(all_models) <- c("compare_parameters", "see_compare_parameters", unique(class(all_models))) all_models } #' @rdname compare_parameters #' @export compare_models <- compare_parameters # helper ---------------------------- .set_pretty_names <- function(x, pretty_names) { # check if pretty names should be replaced by value labels # (if we have labelled data) if (isTRUE(getOption("parameters_labels", FALSE)) || identical(pretty_names, "labels")) { attr(x, "pretty_names") <- attr(x, "pretty_labels", exact = TRUE) pretty_names <- TRUE } att <- attributes(x) if (!is.null(att$pretty_names)) { # remove strings with NA names att$pretty_names <- att$pretty_names[!is.na(names(att$pretty_names))] if (length(att$pretty_names) != length(x$Parameter)) { match_pretty_names <- match(names(att$pretty_names), x$Parameter) match_pretty_names <- match_pretty_names[!is.na(match_pretty_names)] if (length(match_pretty_names)) { x$Parameter[match_pretty_names] <- att$pretty_names[x$Parameter[match_pretty_names]] } } else { match_pretty_names <- att$pretty_names[x$Parameter] if (anyNA(match_pretty_names)) { match_pretty_names <- match(names(att$pretty_names), x$Parameter) match_pretty_names <- match_pretty_names[!is.na(match_pretty_names)] if (length(match_pretty_names)) { x$Parameter[match_pretty_names] <- att$pretty_names[x$Parameter[match_pretty_names]] } } else { x$Parameter <- att$pretty_names[x$Parameter] } } } x } .is_bayesian_model <- function(x, exclude = NULL) { bayes_classes <- c( "brmsfit", "stanfit", "MCMCglmm", "stanreg", "stanmvreg", "bmerMod", "BFBayesFactor", "bamlss", "bayesx", "mcmc", "bcplm", "bayesQR", "BGGM", "meta_random", "meta_fixed", "meta_bma", "blavaan", "blrm", "blmerMod" ) # if exclude is not NULL, remove elements in exclude from bayes_class if (!is.null(exclude)) { bayes_classes <- bayes_classes[!bayes_classes %in% exclude] } inherits(x, bayes_classes) } parameters/R/methods_MCMCglmm.R 0000644 0001762 0000144 00000004125 14717111737 016073 0 ustar ligges users #' @export standard_error.MCMCglmm <- function(model, ...) { nF <- model$Fixed$nfl parms <- as.data.frame(model$Sol[, 1:nF, drop = FALSE]) .data_frame( Parameter = .remove_backticks_from_string(colnames(parms)), SE = unname(sapply(parms, stats::sd)) ) } #' @export p_value.MCMCglmm <- function(model, ...) { nF <- model$Fixed$nfl p <- 1 - colSums(model$Sol[, 1:nF, drop = FALSE] > 0) / dim(model$Sol)[1] .data_frame( Parameter = insight::find_parameters(model, effects = "fixed", flatten = TRUE), p = p ) } #' @export model_parameters.MCMCglmm <- function(model, centrality = "median", dispersion = FALSE, ci = 0.95, ci_method = "eti", test = "pd", rope_range = "default", rope_ci = 0.95, bf_prior = NULL, diagnostic = c("ESS", "Rhat"), priors = TRUE, keep = NULL, drop = NULL, verbose = TRUE, ...) { # Processing params <- .extract_parameters_bayesian( model, centrality = centrality, dispersion = dispersion, ci = ci, ci_method = ci_method, test = test, rope_range = rope_range, rope_ci = rope_ci, bf_prior = bf_prior, diagnostic = diagnostic, priors = priors, keep_parameters = keep, drop_parameters = drop, verbose = verbose, ... ) attr(params, "pretty_names") <- format_parameters(model) attr(params, "ci") <- ci attr(params, "object_name") <- insight::safe_deparse_symbol(substitute(model)) class(params) <- c("parameters_model", "see_parameters_model", class(params)) params } parameters/R/methods_crch.R 0000644 0001762 0000144 00000001006 14355245205 015405 0 ustar ligges users #' @export standard_error.crch <- function(model, ...) { cs <- do.call(rbind, stats::coef(summary(model), model = "full")) params <- insight::get_parameters(model) .data_frame( Parameter = params$Parameter, SE = as.vector(cs[, 2]) ) } #' @export p_value.crch <- function(model, ...) { cs <- do.call(rbind, stats::coef(summary(model), model = "full")) params <- insight::get_parameters(model) .data_frame( Parameter = params$Parameter, p = as.vector(cs[, 4]) ) } parameters/R/p_function.R 0000644 0001762 0000144 00000052731 14737236746 015140 0 ustar ligges users #' @title p-value or consonance function #' @name p_function #' #' @description Compute p-values and compatibility (confidence) intervals for #' statistical models, at different levels. This function is also called #' consonance function. It allows to see which estimates are compatible with #' the model at various compatibility levels. Use `plot()` to generate plots #' of the _p_ resp. _consonance_ function and compatibility intervals at #' different levels. #' #' @param ci_levels Vector of scalars, indicating the different levels at which #' compatibility intervals should be printed or plotted. In plots, these levels #' are highlighted by vertical lines. It is possible to increase thickness for #' one or more of these lines by providing a names vector, where the to be #' highlighted values should be named `"emph"`, e.g #' `ci_levels = c(0.25, 0.5, emph = 0.95)`. #' #' @inheritParams model_parameters #' @inheritParams model_parameters.default #' @inheritParams model_parameters.glmmTMB #' @inheritParams standard_error #' #' @note #' Curently, `p_function()` computes intervals based on Wald t- or z-statistic. #' For certain models (like mixed models), profiled intervals may be more #' accurate, however, this is currently not supported. #' #' @seealso See also [`equivalence_test()`] and [`p_significance()`] for #' functions related to checking effect existence and significance. #' #' @details #' ## Compatibility intervals and continuous _p_-values for different estimate values #' #' `p_function()` only returns the compatibility interval estimates, not the #' related _p_-values. The reason for this is because the _p_-value for a #' given estimate value is just `1 - CI_level`. The values indicating the lower #' and upper limits of the intervals are the related estimates associated with #' the _p_-value. E.g., if a parameter `x` has a 75% compatibility interval #' of `(0.81, 1.05)`, then the _p_-value for the estimate value of `0.81` #' would be `1 - 0.75`, which is `0.25`. This relationship is more intuitive and #' better to understand when looking at the plots (using `plot()`). #' #' ## Conditional versus unconditional interpretation of _p_-values and intervals #' #' `p_function()`, and in particular its `plot()` method, aims at re-interpreting #' _p_-values and confidence intervals (better named: _compatibility_ intervals) #' in _unconditional_ terms. Instead of referring to the long-term property and #' repeated trials when interpreting interval estimates (so-called "aleatory #' probability", _Schweder 2018_), and assuming that all underlying assumptions #' are correct and met, `p_function()` interprets _p_-values in a Fisherian way #' as "_continuous_ measure of evidence against the very test hypothesis _and_ #' entire model (all assumptions) used to compute it" #' (*P-Values Are Tough and S-Values Can Help*, lesslikely.com/statistics/s-values; #' see also _Amrhein and Greenland 2022_). #' #' The common definition of p-values can be considered as "conditional" #' interpretation: #' #' _The p-value is the probability of obtaining test results at least as #' extreme as the result actually observed, under the assumption that the #' null hypothesis is correct (Wikipedia)._ #' #' However, this definition or interpretation is inadequate because it only #' refers to the test hypothesis (often the null hypothesis), which is only #' one component of the entire model that is being tested. Thus, #' _Greenland et al. 2022_ suggest an "unconditional" interpretation. #' #' This interpretation as a continuous measure of evidence against the test #' hypothesis and the entire model used to compute it can be seen in the #' figure below (taken from *P-Values Are Tough and S-Values Can Help*, #' lesslikely.com/statistics/s-values). The "conditional" interpretation of #' _p_-values and interval estimates (A) implicitly assumes certain assumptions #' to be true, thus the interpretation is "conditioned" on these assumptions #' (i.e. assumptions are taken as given, only the hypothesis is tested). The #' unconditional interpretation (B), however, questions _all_ these assumptions. #' #' A non-significant p-value could occur because the test hypothesis is false, #' but could also be the result of any of the model assumptions being incorrect. #' #' \if{html}{\cr \figure{unconditional_interpretation.png}{options: alt="Conditional versus unconditional interpretations of P-values"} \cr} #' #' "Emphasizing unconditional interpretations helps avoid overconfident and #' misleading inferences in light of uncertainties about the assumptions used #' to arrive at the statistical results." (_Greenland et al. 2022_). #' #' **Note:** The term "conditional" as used by Rafi and Greenland probably has #' a slightly different meaning than normally. "Conditional" in this notion #' means that all model assumptions are taken as given - it should not be #' confused with terms like "conditional probability". See also _Greenland et al. 2022_ #' for a detailed elaboration on this issue. #' #' In other words, the term compatibility interval emphasizes "the dependence #' of the _p_-value on the assumptions as well as on the data, recognizing that #' _p_<0.05 can arise from assumption violations even if the effect under #' study is null" (_Gelman/Greenland 2019_). #' #' ## Probabilistic interpretation of p-values and compatibility intervals #' #' Schweder (2018) resp. Schweder and Hjort (2016) (and others) argue that #' confidence curves (as produced by `p_function()`) have a valid probabilistic #' interpretation. They distinguish between _aleatory probability_, which #' describes the aleatory stochastic element of a distribution _ex ante_, i.e. #' before the data are obtained. This is the classical interpretation of #' confidence intervals following the Neyman-Pearson school of statistics. #' However, there is also an _ex post_ probability, called _epistemic_ probability, #' for confidence curves. The shift in terminology from _confidence_ intervals #' to _compatibility_ intervals may help emphasizing this interpretation. #' #' In this sense, the probabilistic interpretation of _p_-values and #' compatibility intervals is "conditional" - on the data _and_ model assumptions #' (which is in line with the _"unconditional"_ interpretation in the sense of #' Rafi and Greenland). #' #' Ascribing a probabilistic interpretation to one realized confidence interval #' is possible without repeated sampling of the specific experiment. Important #' is the assumption that a _sampling distribution_ is a good description of the #' variability of the parameter (_Vos and Holbert 2022_). At the core, the #' interpretation of a confidence interval is "I assume that this sampling #' distribution is a good description of the uncertainty of the parameter. If #' that's a good assumption, then the values in this interval are the most #' plausible or compatible with the data". The source of confidence in #' probability statements is the assumption that the selected sampling #' distribution is appropriate. #' #' "The realized confidence distribution is clearly an epistemic probability #' distribution" (_Schweder 2018_). In Bayesian words, compatibility intervals #' (or confidence distributons, or consonance curves) are "posteriors without #' priors" (_Schweder, Hjort, 2003_). #' #' The _p_-value indicates the degree of compatibility of the endpoints of the #' interval at a given confidence level with (1) the observed data and (2) model #' assumptions. The observed point estimate (_p_-value = 1) is the value #' estimated to be _most compatible_ with the data and model assumptions, #' whereas values values far from the observed point estimate (where _p_ #' approaches 0) are least compatible with the data and model assumptions #' (_Schweder and Hjort 2016, pp. 60-61; Amrhein and Greenland 2022_). In this #' regards, _p_-values are statements about _confidence_ or _compatibility_: #' The p-value is not an absolute measure of evidence for a model (such as the #' null/alternative model), it is a continuous measure of the compatibility of #' the observed data with the model used to compute it (_Greenland et al. 2016_, #' _Greenland 2023_). Going one step further, and following _Schweder_, p-values #' can be considered as _epistemic probability_ - "not necessarily of the #' hypothesis being true, but of it _possibly_ being true" (_Schweder 2018_). #' Hence, the interpretation of _p_-values might be guided using #' [`bayestestR::p_to_pd()`]. #' #' ## Probability or compatibility? #' #' We here presented the discussion of p-values and confidence intervals from the #' perspective of two paradigms, one saying that probability statements can be #' made, one saying that interpretation is guided in terms of "compatibility". #' Cox and Hinkley say, "interval estimates cannot be taken as probability #' statements" (_Cox and Hinkley 1979: 208_), which conflicts with the Schweder #' and Hjort confidence distribution school. However, if you view interval #' estimates as being intervals of values being consistent with the data, #' this comes close to the idea of (epistemic) probability. We do not believe that #' these two paradigms contradict or exclude each other. Rather, the aim is to #' emphasize the one point of view or the other, i.e. to place the linguistic #' nuances either on 'compatibility' or 'probability'. #' #' The main take-away is *not* to interpret p-values as dichotomous decisions #' that distinguish between "we found an effect" (statistically significant)" vs. #' "we found no effect" (statistically not significant) (_Altman and Bland 1995_). #' #' ## Compatibility intervals - is their interpretation "conditional" or not? #' #' The fact that the term "conditional" is used in different meanings in #' statistics, is confusing. Thus, we would summarize the (probabilistic) #' interpretation of compatibility intervals as follows: The intervals are built #' from the data _and_ our modeling assumptions. The accuracy of the intervals #' depends on our model assumptions. If a value is outside the interval, that #' might be because (1) that parameter value isn't supported by the data, or (2) #' the modeling assumptions are a poor fit for the situation. When we make bad #' assumptions, the compatibility interval might be too wide or (more commonly #' and seriously) too narrow, making us think we know more about the parameter #' than is warranted. #' #' When we say "there is a 95% chance the true value is in the interval", that is #' a statement of _epistemic probability_ (i.e. description of uncertainty related #' to our knowledge or belief). When we talk about repeated samples or sampling #' distributions, that is referring to _aleatoric_ (physical properties) probability. #' Frequentist inference is built on defining estimators with known _aleatoric_ #' probability properties, from which we can draw _epistemic_ probabilistic #' statements of uncertainty (_Schweder and Hjort 2016_). #' #' ## Functions in the parameters package to check for effect existence and significance #' #' The **parameters** package provides several options or functions to aid #' statistical inference. Beyond `p_function()`, there are, for example: #' - [`equivalence_test()`][equivalence_test.lm], to compute the (conditional) #' equivalence test for frequentist models #' - [`p_significance()`][p_significance.lm], to compute the probability of #' *practical significance*, which can be conceptualized as a unidirectional #' equivalence test #' - the `pd` argument (setting `pd = TRUE`) in `model_parameters()` includes #' a column with the *probability of direction*, i.e. the probability that a #' parameter is strictly positive or negative. See [`bayestestR::p_direction()`] #' for details. If plotting is desired, the [`p_direction()`][p_direction.lm] #' function can be used, together with `plot()`. #' - the `s_value` argument (setting `s_value = TRUE`) in `model_parameters()` #' replaces the p-values with their related _S_-values (*Rafi and Greenland 2020*) #' - finally, it is possible to generate distributions of model coefficients by #' generating bootstrap-samples (setting `bootstrap = TRUE`) or simulating #' draws from model coefficients using [`simulate_model()`]. These samples #' can then be treated as "posterior samples" and used in many functions from #' the **bayestestR** package. #' #' @return A data frame with p-values and compatibility intervals. #' #' @references #' - Altman DG, Bland JM. Absence of evidence is not evidence of absence. BMJ. #' 1995;311(7003):485. \doi{10.1136/bmj.311.7003.485} #' #' - Amrhein V, Greenland S. Discuss practical importance of results based on #' interval estimates and p-value functions, not only on point estimates and #' null p-values. Journal of Information Technology 2022;37:316–20. #' \doi{10.1177/02683962221105904} #' #' - Cox DR, Hinkley DV. 1979. Theoretical Statistics. 6th edition. #' Chapman and Hall/CRC #' #' - Fraser DAS. The P-value function and statistical inference. The American #' Statistician. 2019;73(sup1):135-147. \doi{10.1080/00031305.2018.1556735} #' #' - Gelman A, Greenland S. Are confidence intervals better termed "uncertainty #' intervals"? BMJ (2019)l5381. \doi{10.1136/bmj.l5381} #' #' - Greenland S, Rafi Z, Matthews R, Higgs M. To Aid Scientific Inference, #' Emphasize Unconditional Compatibility Descriptions of Statistics. (2022) #' https://arxiv.org/abs/1909.08583v7 (Accessed November 10, 2022) #' #' - Greenland S, Senn SJ, Rothman KJ, Carlin JB, Poole C, Goodman SN, et al. #' (2016). Statistical tests, P values, confidence intervals, and power: A #' guide to misinterpretations. European Journal of Epidemiology. 31:337-350. #' \doi{10.1007/s10654-016-0149-3} #' #' - Greenland S (2023). Divergence versus decision P-values: A distinction #' worth making in theory and keeping in practice: Or, how divergence P-values #' measure evidence even when decision P-values do not. Scand J Statist, 50(1), #' 54-88. #' #' - Rafi Z, Greenland S. Semantic and cognitive tools to aid statistical #' science: Replace confidence and significance by compatibility and surprise. #' BMC Medical Research Methodology. 2020;20(1):244. \doi{10.1186/s12874-020-01105-9} #' #' - Schweder T. Confidence is epistemic probability for empirical science. #' Journal of Statistical Planning and Inference (2018) 195:116–125. #' \doi{10.1016/j.jspi.2017.09.016} #' #' - Schweder T, Hjort NL. Confidence and Likelihood. Scandinavian Journal of #' Statistics. 2002;29(2):309-332. \doi{10.1111/1467-9469.00285} #' #' - Schweder T, Hjort NL. Frequentist analogues of priors and posteriors. #' In Stigum, B. (ed.), Econometrics and the Philosophy of Economics: Theory #' Data Confrontation in Economics, pp. 285-217. Princeton University Press, #' Princeton, NJ, 2003 #' #' - Schweder T, Hjort NL. Confidence, Likelihood, Probability: Statistical #' inference with confidence distributions. Cambridge University Press, 2016. #' #' - Vos P, Holbert D. Frequentist statistical inference without repeated sampling. #' Synthese 200, 89 (2022). \doi{10.1007/s11229-022-03560-x} #' #' @examplesIf requireNamespace("see") #' model <- lm(Sepal.Length ~ Species, data = iris) #' p_function(model) #' #' model <- lm(mpg ~ wt + as.factor(gear) + am, data = mtcars) #' result <- p_function(model) #' #' # single panels #' plot(result, n_columns = 2) #' #' # integrated plot, the default #' plot(result) #' @export p_function <- function(model, ci_levels = c(0.25, 0.5, 0.75, emph = 0.95), exponentiate = FALSE, effects = "fixed", component = "all", vcov = NULL, vcov_args = NULL, keep = NULL, drop = NULL, verbose = TRUE, ...) { # degrees of freedom dof <- insight::get_df(model, type = "wald") # standard errors se <- standard_error( model, effects = effects, component = component, vcov = vcov, vcov_args = vcov_args )$SE if (is.null(dof) || length(dof) == 0 || .is_chi2_model(model, dof)) { dof <- Inf } x <- do.call(rbind, lapply(seq(0, 1, 0.01), function(i) { suppressMessages(.ci_dof( model, ci = i, dof, effects, component, method = "wald", se = se, vcov = NULL, vcov_args = NULL, verbose = TRUE )) })) # data for plotting out <- x[!is.infinite(x$CI_low) & !is.infinite(x$CI_high), ] out$CI <- round(out$CI, 2) # most plausible value (point estimate) point_estimate <- out$CI_low[which.min(out$CI)] if (!is.null(keep) || !is.null(drop)) { out <- .filter_parameters(out, keep = keep, drop = drop, verbose = verbose ) } # transform non-Gaussian if (isTRUE(exponentiate)) { out$CI_low <- exp(out$CI_low) out$CI_high <- exp(out$CI_high) } # data for p_function ribbon data_ribbon <- datawizard::data_to_long( out, select = c("CI_low", "CI_high"), values_to = "x" ) # data for vertical CI level lines out <- out[out$CI %in% ci_levels, ] out$group <- 1 # emphasize focal hypothesis line emphasize <- which(names(ci_levels) == "emph") if (length(emphasize)) { out$group[out$CI == ci_levels[emphasize]] <- 2 } attr(out, "data") <- data_ribbon attr(out, "point_estimate") <- point_estimate attr(out, "pretty_names") <- suppressWarnings(format_parameters(model, ...)) class(out) <- c("parameters_p_function", "see_p_function", "data.frame") out } #' @rdname p_function #' @export consonance_function <- p_function #' @rdname p_function #' @export confidence_curve <- p_function # methods ---------------------- #' @export plot.parameters_p_function <- function(x, ...) { insight::check_if_installed("see") NextMethod() } #' @export format.parameters_p_function <- function(x, digits = 2, format = NULL, ci_width = NULL, ci_brackets = TRUE, pretty_names = TRUE, ...) { # print dat <- lapply(split(x, x$CI), function(i) { ci <- as.character(i$CI)[1] out <- datawizard::data_rename( i, select = c("CI_low", "CI_high"), replacement = c(sprintf("CI_low_%s", ci), sprintf("CI_high_%s", ci)) ) out$CI <- NULL out$group <- NULL out }) out <- do.call(datawizard::data_merge, list(dat, by = "Parameter")) attr(out, "pretty_names") <- attributes(x)$pretty_names insight::format_table( out, digits = digits, ci_width = ci_width, ci_brackets = ci_brackets, format = format, pretty_names = pretty_names ) } #' @export print.parameters_p_function <- function(x, digits = 2, ci_width = "auto", ci_brackets = TRUE, pretty_names = TRUE, ...) { cat(.print_p_function( x, digits, ci_width, ci_brackets, pretty_names = pretty_names, format = "text", ... )) } #' @export print_md.parameters_p_function <- function(x, digits = 2, ci_width = "auto", ci_brackets = c("(", ")"), pretty_names = TRUE, ...) { .print_p_function(x, digits, ci_width, ci_brackets, pretty_names, format = "markdown", ...) } #' @export print_html.parameters_p_function <- function(x, digits = 2, ci_width = "auto", ci_brackets = c("(", ")"), pretty_names = TRUE, ...) { .print_p_function(x, digits, ci_width, ci_brackets, pretty_names, format = "html", ...) } # helper ---------- .print_p_function <- function(x, digits = 2, ci_width = "auto", ci_brackets = c("(", ")"), pretty_names = TRUE, format = "html", ...) { formatted_table <- format( x, digits = digits, format = format, ci_width = ci_width, ci_brackets = ci_brackets, pretty_names = pretty_names, ... ) insight::export_table( formatted_table, format = format, caption = "Consonance Function", ... ) } # model <- lm(Sepal.Length ~ Species, data = iris) # for later use: highlight p-value for secific parameter estimate values # stat <- insight::get_statistic(model) # se <- parameters::standard_error(model) # estimate to test against - compute p-value for specific estimate # null_estimate <- 1.5 # p <- 2 * stats::pt(abs(stat$Statistic[3]) - (null_estimate / se$SE[3]), df = 147, lower.tail = FALSE) # bayestestR::p_to_pd(p) parameters/R/methods_mclust.R 0000644 0001762 0000144 00000000667 14717111737 016015 0 ustar ligges users #' @export model_parameters.Mclust <- function(model, data = NULL, clusters = NULL, ...) { if (is.null(data)) data <- as.data.frame(model$data) if (is.null(clusters)) clusters <- model$classification params <- .cluster_centers_params(data, clusters, ...) attr(params, "model") <- model attr(params, "type") <- "mixture" attr(params, "title") <- "Gaussian finite mixture model fitted by EM algorithm" params } parameters/R/methods_lm.R 0000644 0001762 0000144 00000001621 14736731407 015110 0 ustar ligges users # lm: .lm, .summary.lm # .lm --------------------- #' @export p_value.lm <- p_value.default #' @export ci.lm <- function(x, ci = 0.95, method = "residual", ...) { .ci_generic(model = x, ci = ci, method = method, ...) } # .summary.lm --------------------- #' @export standard_error.summary.lm <- function(model, ...) { cs <- stats::coef(model) data.frame( Parameter = rownames(cs), SE = as.vector(cs[, 2]), stringsAsFactors = FALSE, row.names = NULL ) } #' @export p_value.summary.lm <- function(model, ...) { cs <- stats::coef(model) data.frame( Parameter = rownames(cs), p = as.vector(cs[, 4]), stringsAsFactors = FALSE, row.names = NULL ) } #' @export ci.summary.lm <- function(x, ci = 0.95, method = "residual", ...) { .ci_generic(model = x, ci = ci, method = method, dof = insight::get_df(x), ...) } parameters/R/methods_gjrm.R 0000644 0001762 0000144 00000004043 14507235543 015434 0 ustar ligges users #' @export model_parameters.SemiParBIV <- function(model, ci = 0.95, bootstrap = FALSE, iterations = 1000, standardize = NULL, exponentiate = FALSE, p_adjust = NULL, keep = NULL, drop = NULL, verbose = TRUE, ...) { out <- .model_parameters_generic( model = model, ci = ci, bootstrap = bootstrap, iterations = iterations, component = "all", merge_by = c("Parameter", "Component"), standardize = standardize, exponentiate = exponentiate, keep_parameters = keep, drop_parameters = drop, p_adjust = p_adjust, ... ) attr(out, "object_name") <- insight::safe_deparse_symbol(substitute(model)) out } #' @export p_value.SemiParBIV <- function(model, ...) { s <- summary(model) s <- insight::compact_list(s[startsWith(names(s), "tableP")]) params <- do.call(rbind, lapply(seq_along(s), function(i) { out <- as.data.frame(s[[i]]) out$Parameter <- rownames(out) out$Component <- paste0("Equation", i) out })) colnames(params)[4] <- "p" rownames(params) <- NULL insight::text_remove_backticks(params[c("Parameter", "p", "Component")], verbose = FALSE) } #' @export standard_error.SemiParBIV <- function(model, ...) { s <- summary(model) s <- insight::compact_list(s[startsWith(names(s), "tableP")]) params <- do.call(rbind, lapply(seq_along(s), function(i) { out <- as.data.frame(s[[i]]) out$Parameter <- rownames(out) out$Component <- paste0("Equation", i) out })) colnames(params)[2] <- "SE" rownames(params) <- NULL insight::text_remove_backticks(params[c("Parameter", "SE", "Component")], verbose = FALSE) } parameters/R/ci_generic.R 0000644 0001762 0000144 00000013273 14716604211 015040 0 ustar ligges users # generic function for CI calculation .ci_generic <- function(model, ci = 0.95, method = "wald", dof = NULL, effects = "fixed", component = "all", vcov = NULL, vcov_args = NULL, verbose = TRUE, ...) { # check method if (is.null(method)) { method <- "wald" } method <- tolower(method) method <- insight::validate_argument( method, c( "wald", "ml1", "betwithin", "kr", "satterthwaite", "kenward", "boot", "profile", "residual", "normal" ) ) effects <- insight::validate_argument(effects, c("fixed", "random", "all")) component <- insight::validate_argument( component, c( "all", "conditional", "zi", "zero_inflated", "dispersion", "precision", "scale", "smooth_terms", "full", "marginal" ) ) if (method == "ml1") { # nolint return(ci_ml1(model, ci = ci)) } else if (method == "betwithin") { return(ci_betwithin(model, ci = ci)) } else if (method == "satterthwaite") { return(ci_satterthwaite(model, ci = ci)) } else if (method %in% c("kenward", "kr")) { return(ci_kenward(model, ci = ci)) } # default CIs follow here (methods wald, boot, profile, residual, normal) out <- lapply(ci, function(i) { .ci_dof( model = model, ci = i, dof = dof, effects = effects, component = component, method = method, vcov = vcov, vcov_args = vcov_args, verbose = verbose, ... ) }) out <- do.call(rbind, out) row.names(out) <- NULL out } #' @keywords internal .ci_dof <- function(model, ci, dof, effects, component, method = "wald", se = NULL, vcov = NULL, vcov_args = NULL, verbose = TRUE, ...) { # need parameters to calculate the CIs if (inherits(model, "emmGrid")) { params <- insight::get_parameters( model, effects = effects, component = component, merge_parameters = TRUE ) } else { params <- insight::get_parameters(model, effects = effects, component = component, verbose = FALSE ) } # check if all estimates are non-NA params <- .check_rank_deficiency(model, params, verbose = FALSE) # for polr, we need to fix parameter names params$Parameter <- gsub("Intercept: ", "", params$Parameter, fixed = TRUE) # validation check... if (is.null(method)) { method <- "wald" } method <- tolower(method) # Fist, we want standard errors for parameters # -------------------------------------------- # if we have adjusted SE, e.g. from kenward-roger, don't recompute # standard errors to save time... if (is.null(se)) { if (!is.null(vcov) || isTRUE(list(...)[["robust"]])) { # robust (HC) standard errors? stderror <- standard_error(model, component = component, vcov = vcov, vcov_args = vcov_args, verbose = verbose, ... ) } else { # normal standard errors, including small-sample approximations stderror <- switch(method, kenward = se_kenward(model), kr = se_kenward(model), satterthwaite = se_satterthwaite(model), standard_error(model, component = component) ) } # if we have a non-empty stderror, use it if (insight::is_empty_object(stderror)) { return(NULL) } # filter non-matching parameters, resp. sort stderror and parameters, # so both have the identical order of values if (nrow(stderror) != nrow(params) || !all(stderror$Parameter %in% params$Parameter) || !all(order(stderror$Parameter) == order(params$Parameter))) { params <- stderror <- merge(stderror, params, sort = FALSE) } se <- stderror$SE } # Next, we need degrees of freedom # -------------------------------- # check if we have a valid dof vector if (is.null(dof)) { # residual df dof <- insight::get_df(x = model, type = method, verbose = FALSE) # make sure we have a value for degrees of freedom if (is.null(dof) || length(dof) == 0 || .is_chi2_model(model, dof)) { dof <- Inf } else if (length(dof) > nrow(params)) { # filter non-matching parameters dof <- dof[seq_len(nrow(params))] } } # Now we can calculate CIs # ------------------------ alpha <- (1 + ci) / 2 fac <- suppressWarnings(stats::qt(alpha, df = dof)) out <- cbind( CI_low = params$Estimate - se * fac, CI_high = params$Estimate + se * fac ) out <- as.data.frame(out) out$CI <- ci out$Parameter <- params$Parameter out <- out[c("Parameter", "CI", "CI_low", "CI_high")] if ("Component" %in% names(params)) out$Component <- params$Component if ("Effects" %in% names(params) && effects != "fixed") out$Effects <- params$Effects if ("Response" %in% names(params)) out$Response <- params$Response # for cox-panel models, we have non-linear parameters with NA coefficient, # but test statistic and p-value - don't check for NA estimates in this case if (anyNA(params$Estimate) && !inherits(model, "coxph.penal")) { out[stats::complete.cases(out), ] } else { out } } .is_chi2_model <- function(model, dof) { statistic <- insight::find_statistic(model) (all(dof == 1) && identical(statistic, "chi-squared statistic")) } parameters/R/methods_hglm.R 0000644 0001762 0000144 00000015341 14761570351 015430 0 ustar ligges users # #' @export # p_value.hglm <- function(model, ...) { # stat <- insight::get_statistic(model) # .data_frame( # Parameter = stat$Parameter, # p = 2 * stats::pnorm(abs(stat$Statistic), lower.tail = FALSE) # ) # } # #' @export # ci.hglm <- function(x, ci = 0.95, ...) { # .ci_generic(model = x, ci = ci, ...) # } #' @export model_parameters.hglm <- function(model, ci = 0.95, ci_method = NULL, bootstrap = FALSE, iterations = 1000, exponentiate = FALSE, effects = "all", component = "all", p_adjust = NULL, include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, ...) { # which components to return? effects <- match.arg(effects, choices = c("fixed", "random", "all")) component <- match.arg(component, choices = c("all", "conditional", "dispersion")) # 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, include_info = include_info, keep = keep, drop = drop, verbose = verbose, ... ) # hglm has a special structure, so we add random effects and dispersion # manually here... if (effects %in% c("all", "random")) { re_params <- insight::get_parameters(model, effects = "random", component = "conditional") re_se <- standard_error(model, effects = "random", component = "conditional") re_ci <- ci(model, effects = "random", component = "conditional") # bind all results re_params <- cbind( re_params[c("Parameter", "Estimate")], re_se["SE"], re_ci[c("CI", "CI_low", "CI_high")] ) # no values for statistic, df and p re_params$t <- re_params$df_error <- re_params$p <- NA # add effects-columns mp$Effects <- "fixed" re_params$Effects <- "random" # renaming colnames(re_params)[colnames(re_params) == "Estimate"] <- "Coefficient" # bind together mp <- rbind(mp, re_params) } # add dispersion model has_dispersion <- !is.null(insight::find_formula(model, verbose = FALSE)$dispersion) if (has_dispersion && component %in% c("all", "dispersion")) { disp_params <- insight::get_parameters(model, effects = "fixed", component = "dispersion") disp_se <- standard_error(model, effects = "fixed", component = "dispersion") disp_ci <- ci(model, effects = "fixed", component = "dispersion") # bind all results disp_params <- cbind( disp_params[c("Parameter", "Estimate")], disp_se["SE"], disp_ci[c("CI", "CI_low", "CI_high")] ) # no values for statistic, df and p disp_params$t <- disp_params$df_error <- disp_params$p <- NA # add effects-columns if (is.null(mp$Effects)) { mp$Effects <- "fixed" } disp_params$Effects <- "fixed" # add component-columns mp$Component <- "conditional" disp_params$Component <- "dispersion" # renaming colnames(disp_params)[colnames(disp_params) == "Estimate"] <- "Coefficient" # bind together mp <- rbind(mp, disp_params) } mp } #' @export standard_error.hglm <- function(model, effects = "fixed", component = "conditional", verbose = TRUE, ...) { effects <- match.arg(effects, choices = c("all", "fixed", "random")) component <- match.arg(component, choices = c("all", "conditional", "dispersion")) f <- insight::find_formula(model, verbose = FALSE) if (component == "dispersion" && is.null(f$dispersion)) { if (verbose) { insight::format_alert("No standard errors found for model's dispersion parameters.") } return(NULL) } # validation check, make sure we have a dispersion component if (component == "all" && is.null(f$dispersion)) { compomnent <- "conditional" } s <- summary(model) if (effects == "fixed") { se <- s$FixCoefMat } else if (effects == "random") { se <- s$RandCoefMat } else { se <- c(s$FixCoefMat, s$RandCoefMat) } out <- .data_frame( Parameter = row.names(se), SE = as.vector(se[, 2]) ) # dispersion component? if (effects != "random" && component %in% c("dispersion", "all")) { se <- s$SummVC1 disp <- .data_frame( Parameter = row.names(se), SE = as.vector(se[, 2]), Component = "dispersion" ) if (component == "dispersion") { out <- disp } else { out$Component <- "conditional" out <- rbind(out, disp) } } out } #' @export ci.hglm <- function(x, ci = 0.95, method = "wald", dof = NULL, effects = "fixed", component = "conditional", verbose = TRUE, ...) { effects <- match.arg(effects, choices = c("all", "fixed", "random")) component <- match.arg(component, choices = c("all", "conditional", "dispersion")) # fixed effects ----------------- if (effects %in% c("fixed", "all")) { out <- .ci_generic( x, ci = ci, method = method, dof = dof, effects = "fixed", component = component, verbose = verbose, ... ) } # add random effects ----------------- if (effects %in% c("random", "all")) { se <- standard_error(x, effects = "random", component = "conditional")$SE .ci_re <- .ci_dof( x, ci = ci, method = method, dof = dof, effects = "random", component = "conditional", se = se, verbose = verbose, ... ) if (effects == "all") { out <- rbind(out, .ci_re) } else { out <- .ci_re } } out } #' @export p_value.hglm <- function(model, dof = NULL, method = NULL, verbose = TRUE, ...) { dots <- list(...) dots$component <- NULL fun_args <- list( model, dof = dof, component = "conditional", method = method, verbose = verbose ) fun_args <- c(fun_args, dots) do.call("p_value.default", fun_args) } parameters/R/n_clusters.R 0000644 0001762 0000144 00000024322 14736731407 015141 0 ustar ligges users #' @title Find number of clusters in your data #' @name n_clusters #' #' @description #' Similarly to [`n_factors()`] for factor / principal component analysis, #' `n_clusters()` is the main function to find out the optimal numbers of clusters #' present in the data based on the maximum consensus of a large number of #' methods. #' #' Essentially, there exist many methods to determine the optimal number of #' clusters, each with pros and cons, benefits and limitations. The main #' `n_clusters` function proposes to run all of them, and find out the number of #' clusters that is suggested by the majority of methods (in case of ties, it #' will select the most parsimonious solution with fewer clusters). #' #' Note that we also implement some specific, commonly used methods, like the #' Elbow or the Gap method, with their own visualization functionalities. See #' the examples below for more details. #' #' @param x A data frame. #' @param standardize Standardize the dataframe before clustering (default). #' @param include_factors Logical, if `TRUE`, factors are converted to numerical #' values in order to be included in the data for determining the number of #' clusters. By default, factors are removed, because most methods that #' determine the number of clusters need numeric input only. #' @param package Package from which methods are to be called to determine the #' number of clusters. Can be `"all"` or a vector containing #' `"easystats"`, `"NbClust"`, `"mclust"`, and `"M3C"`. #' @param fast If `FALSE`, will compute 4 more indices (sets `index = "allong"` #' in `NbClust`). This has been deactivated by default as it is #' computationally heavy. #' @param n_max Maximal number of clusters to test. #' @param clustering_function,gap_method Other arguments passed to other #' functions. `clustering_function` is used by `fviz_nbclust()` and #' can be `kmeans`, `cluster::pam`, `cluster::clara`, `cluster::fanny`, and #' more. `gap_method` is used by `cluster::maxSE` to extract the optimal #' numbers of clusters (see its `method` argument). #' @param method,min_size,eps_n,eps_range Arguments for DBSCAN algorithm. #' @param distance_method The distance method (passed to [`dist()`]). Used by #' algorithms relying on the distance matrix, such as `hclust` or `dbscan`. #' @param hclust_method The hierarchical clustering method (passed to [`hclust()`]). #' @param nbclust_method The clustering method (passed to `NbClust::NbClust()` #' as `method`). #' @inheritParams model_parameters.default #' #' #' #' @note There is also a [`plot()`-method](https://easystats.github.io/see/articles/parameters.html) implemented in the [**see**-package](https://easystats.github.io/see/). #' #' @examples #' \donttest{ #' library(parameters) #' #' # The main 'n_clusters' function =============================== #' if (require("mclust", quietly = TRUE) && require("NbClust", quietly = TRUE) && #' require("cluster", quietly = TRUE) && require("see", quietly = TRUE)) { #' n <- n_clusters(iris[, 1:4], package = c("NbClust", "mclust")) # package can be "all" #' n #' summary(n) #' as.data.frame(n) # Duration is the time elapsed for each method in seconds #' plot(n) #' #' # The following runs all the method but it significantly slower #' # n_clusters(iris[1:4], standardize = FALSE, package = "all", fast = FALSE) #' } #' } #' @export n_clusters <- function(x, standardize = TRUE, include_factors = FALSE, package = c("easystats", "NbClust", "mclust"), fast = TRUE, nbclust_method = "kmeans", n_max = 10, ...) { if (all(package == "all")) { package <- c("easystats", "NbClust", "mclust", "M3C") } x <- .prepare_data_clustering(x, include_factors = include_factors, standardize = standardize, ...) out <- data.frame() if ("easystats" %in% tolower(package)) { out <- rbind(out, .n_clusters_easystats(x, n_max = n_max, ...)) } if ("nbclust" %in% tolower(package)) { out <- rbind(out, .n_clusters_NbClust(x, fast = fast, nbclust_method = nbclust_method, n_max = n_max, ...)) } if ("mclust" %in% tolower(package)) { out <- rbind(out, .n_clusters_mclust(x, n_max = n_max, ...)) } if ("M3C" %in% tolower(package)) { out <- rbind(out, .n_clusters_M3C(x, n_max = n_max, fast = fast)) } # Drop Nans out <- out[!is.na(out$n_Clusters), ] # Error if no solution if (nrow(out) == 0) { insight::format_error("No complete solution was found. Please try again with more methods.") } # Clean out <- out[order(out$n_Clusters), ] # Arrange by n clusters row.names(out) <- NULL # Reset row index out$Method <- as.character(out$Method) # Remove duplicate methods starting with the smallest dupli <- NULL for (i in seq_len(nrow(out))) { if (i > 1 && out[i, "Method"] %in% out$Method[1:i - 1]) { dupli <- c(dupli, i) } } if (!is.null(dupli)) { out <- out[-dupli, ] } # Add summary by_clusters <- .data_frame( n_Clusters = as.numeric(unique(out$n_Clusters)), n_Methods = as.numeric(by(out, as.factor(out$n_Clusters), function(out) n <- nrow(out))) ) attr(out, "summary") <- by_clusters attr(out, "n") <- min(as.numeric(as.character( by_clusters[by_clusters$n_Methods == max(by_clusters$n_Methods), "n_Clusters"] ))) class(out) <- c("n_clusters", "see_n_clusters", class(out)) out } #' @keywords internal .n_clusters_mclust <- function(x, n_max = 10, ...) { insight::check_if_installed("mclust") t0 <- Sys.time() mclustBIC <- mclust::mclustBIC # this is needed as it is internally required by the following function BIC <- mclust::mclustBIC(x, G = 1:n_max, verbose = FALSE) # Extract the best solutions as shown in summary(BIC) out <- strsplit(names(unclass(summary(BIC))), split = ",", fixed = TRUE) # Get separated vectors models <- as.character(sapply(out, function(x) x[[1]])) n <- as.numeric(sapply(out, function(x) x[[2]])) .data_frame( n_Clusters = n, Method = paste0("Mixture (", models, ")"), Package = "mclust", Duration = as.numeric(difftime(Sys.time(), t0, units = "secs")) ) } # Methods ----------------------------------------------------------------- #' @keywords internal .n_clusters_easystats <- function(x, n_max = 10, ...) { elb <- n_clusters_elbow(x, preprocess = FALSE, n_max = n_max, ...) sil <- n_clusters_silhouette(x, preprocess = FALSE, n_max = n_max, ...) gap1 <- n_clusters_gap(x, preprocess = FALSE, gap_method = "firstSEmax", n_max = n_max, ...) gap2 <- n_clusters_gap(x, preprocess = FALSE, gap_method = "globalSEmax", n_max = n_max, ...) .data_frame( n_Clusters = c( attributes(elb)$n, attributes(sil)$n, attributes(gap1)$n, attributes(gap2)$n ), Method = c("Elbow", "Silhouette", "Gap_Maechler2012", "Gap_Dudoit2002"), Package = "easystats", Duration = c( attributes(elb)$duration, attributes(sil)$duration, attributes(gap1)$duration, attributes(gap2)$duration ) ) } #' @keywords internal .n_clusters_NbClust <- function(x, fast = TRUE, nbclust_method = "kmeans", n_max = 10, indices = "all", ...) { insight::check_if_installed("NbClust") if (all(indices == "all")) { indices <- c( "kl", "Ch", "Hartigan", "CCC", "Scott", "Marriot", "trcovw", "Tracew", "Friedman", "Rubin", "Cindex", "DB", "Silhouette", "Duda", "Pseudot2", "Beale", "Ratkowsky", "Ball", "PtBiserial", "Frey", "Mcclain", "Dunn", "SDindex", "SDbw", "gap", "gamma", "gplus", "tau" ) # c("hubert", "dindex") are graphical methods } if (fast) { indices <- indices[!indices %in% c("gap", "gamma", "gplus", "tau")] } out <- data.frame() for (idx in indices) { t0 <- Sys.time() n <- tryCatch( expr = { .catch_warnings(NbClust::NbClust( x, index = tolower(idx), method = nbclust_method, max.nc = n_max, ... )) }, error = function(e) { NULL } ) if (!is.null(n)) { # Catch and print potential warnings w <- "" if (!is.null(n$warnings)) { w <- paste0("\n - ", unlist(n$warnings), collapse = "") insight::format_warning(paste0("For ", idx, " index (NbClust):", w)) } # Don't merge results if convergence issue if (!grepl("did not converge in", w, fixed = TRUE)) { out <- rbind(out, .data_frame( n_Clusters = n$out$Best.nc[["Number_clusters"]], Method = idx, Package = "NbClust", Duration = as.numeric(difftime(Sys.time(), t0, units = "secs")) )) } } } out } #' @keywords internal .n_clusters_M3C <- function(x, n_max = 10, fast = TRUE, ...) { if (!requireNamespace("M3C", quietly = TRUE)) { # nolint insight::format_error( "Package `M3C` required for this function to work. Please install it by first running `remotes::install_github('https://github.com/crj32/M3C')` (the package is not on CRAN)." ) # Not on CRAN (but on github and bioconductor) } data <- data.frame(t(x)) colnames(data) <- paste0("x", seq(1, ncol(data))) # Add columns names as required by the package t0 <- Sys.time() out <- M3C::M3C(data, method = 2, maxK = n_max, removeplots = TRUE, silent = TRUE) out <- .data_frame( n_Clusters = out$scores[which.min(out$scores$PCSI), "K"], Method = "Consensus clustering algorithm (penalty term)", Package = "M3C", Duration = as.numeric(difftime(Sys.time(), t0, units = "secs")) ) # Monte Carlo Version (Super slow) if (isFALSE(fast)) { t0 <- Sys.time() out2 <- M3C::M3C(data, method = 1, maxK = n_max, removeplots = TRUE, silent = TRUE) out <- rbind( out, .data_frame( n_Clusters = out2$scores[which.max(out2$scores$RCSI), "K"], Method = "Consensus clustering algorithm (Monte Carlo)", Package = "M3C", Duration = as.numeric(difftime(Sys.time(), t0, units = "secs")) ) ) } out } parameters/R/methods_sem.R 0000644 0001762 0000144 00000001377 14507235543 015270 0 ustar ligges users #' @export model_parameters.sem <- model_parameters.default #' @export standard_error.sem <- function(model, ...) { if (!.is_semLme(model)) { return(NULL) } if (is.null(model$se)) { insight::format_alert( "Model has no standard errors. Please fit model again with bootstrapped standard errors." ) return(NULL) } .data_frame( Parameter = names(model$se), SE = unname(model$se) ) } #' @export p_value.sem <- function(model, ...) { if (!.is_semLme(model)) { return(NULL) } stat <- insight::get_statistic(model) if (is.null(stat)) { return(NULL) } .data_frame( Parameter = stat$Parameter, p = 2 * stats::pnorm(abs(stat$Statistic), lower.tail = FALSE) ) } parameters/R/methods_averaging.R 0000644 0001762 0000144 00000005267 14761570351 016452 0 ustar ligges users # classes: .averaging #################### .averaging #' @export model_parameters.averaging <- function(model, ci = 0.95, component = "conditional", exponentiate = FALSE, p_adjust = NULL, include_info = getOption("parameters_info", FALSE), keep = NULL, drop = NULL, verbose = TRUE, ...) { component <- insight::validate_argument(component, c("conditional", "full")) out <- .model_parameters_generic( model = model, ci = ci, merge_by = "Parameter", exponentiate = exponentiate, component = component, p_adjust = p_adjust, keep_parameters = keep, drop_parameters = drop, include_info = include_info, ... ) attr(out, "object_name") <- insight::safe_deparse_symbol(substitute(model)) out } #' @export standard_error.averaging <- function(model, component = "conditional", ...) { component <- insight::validate_argument(component, c("conditional", "full")) params <- insight::get_parameters(model, component = component) if (component == "full") { s <- summary(model)$coefmat.full } else { s <- summary(model)$coefmat.subset } .data_frame( Parameter = .remove_backticks_from_string(params$Parameter), SE = as.vector(s[, 3]) ) } #' @export p_value.averaging <- function(model, component = "conditional", ...) { component <- insight::validate_argument(component, c("conditional", "full")) params <- insight::get_parameters(model, component = component) if (component == "full") { s <- summary(model)$coefmat.full } else { s <- summary(model)$coefmat.subset } # to data frame s <- as.data.frame(s) # do we have a p-value column based on t? pvcn <- which(colnames(s) == "Pr(>|t|)") # if not, do we have a p-value column based on z? if (length(pvcn) == 0) { pvcn <- which(colnames(s) == "Pr(>|z|)") } # if not, default to ncol if (length(pvcn) == 0) { if (ncol(s) > 4) { pvcn <- 5 } else { pvcn <- 4 } } .data_frame( Parameter = .remove_backticks_from_string(params$Parameter), p = as.vector(s[, pvcn]) ) } #' @export ci.averaging <- function(x, ci = 0.95, component = "conditional", ...) { component <- insight::validate_argument(component, c("conditional", "full")) .ci_generic(model = x, ci = ci, dof = Inf, component = component) } parameters/R/format_order.R 0000644 0001762 0000144 00000003035 14477616760 015447 0 ustar ligges users #' Order (first, second, ...) formatting #' #' Format order. #' #' @param order value or vector of orders. #' @param textual Return number as words. If `FALSE`, will run [insight::format_value()]. #' @param ... Arguments to be passed to [insight::format_value()] if `textual` is `FALSE`. #' #' @return A formatted string. #' @examples #' format_order(2) #' format_order(8) #' format_order(25, textual = FALSE) #' @export format_order <- function(order, textual = TRUE, ...) { if (textual) { order <- insight::format_number(order) parts <- unlist(strsplit(order, " ", fixed = TRUE)) parts[length(parts)] <- switch(utils::tail(parts, 1), one = "first", two = "second", three = "third", four = "fourth", five = "fifth", six = "sixth", seven = "seventh", eight = "eigth", nine = "ninth" ) out <- paste(parts, collapse = " ") } else { number <- insight::format_value(order, digits = 0, ...) last <- substr(number, nchar(number), nchar(number)) last_two <- substr(number, nchar(number) - 1, nchar(number)) # exceptions if (last_two %in% c(11, 12, 13)) { out <- paste0(number, "th") } else { out <- paste0( number, switch(last, `1` = "st", `2` = "nd", `3` = "rd", `4` = "th", `5` = "th", `6` = "th", `7` = "th", `8` = "th", `9` = "th", `0` = "th" ) ) } } out } parameters/R/ci_satterthwaite.R 0000644 0001762 0000144 00000000653 14317274256 016323 0 ustar ligges users #' @rdname p_value_satterthwaite #' @export ci_satterthwaite <- function(model, ci = 0.95, ...) { df_satter <- dof_satterthwaite(model) out <- lapply(ci, function(i) { .ci_dof( model = model, ci = i, dof = df_satter, effects = "fixed", component = "all", method = "satterthwaite", ... ) }) out <- do.call(rbind, out) row.names(out) <- NULL out } parameters/R/methods_lrm.R 0000644 0001762 0000144 00000002751 14736731407 015277 0 ustar ligges users ## from rms / rmsb package # model parameters ------------- #' @export model_parameters.blrm <- model_parameters.bayesQR # standard error ------------- #' @export standard_error.lrm <- function(model, ...) { se <- sqrt(diag(stats::vcov(model))) # psm-models returns vcov-matrix w/o dimnames if (is.null(names(se))) names(se) <- names(stats::coef(model)) .data_frame( Parameter = .remove_backticks_from_string(names(se)), SE = as.vector(se) ) } #' @export standard_error.ols <- standard_error.lrm #' @export standard_error.rms <- standard_error.lrm #' @export standard_error.psm <- standard_error.lrm # p-values ----------------------- #' @export p_value.lrm <- function(model, ...) { stat <- insight::get_statistic(model) # Issue: 697: typically the degrees of freedom are the same for every # observation, but the value is repeated. This poses problems in multiple # imputation models with Hmisc when we get more df values than parameters. dof <- insight::get_df(model, type = "wald") dfu <- unique(dof) if (length(dfu) == 1) { dof <- dfu } p <- 2 * stats::pt(abs(stat$Statistic), df = dof, lower.tail = FALSE) .data_frame( Parameter = .remove_backticks_from_string(stat$Parameter), p = as.vector(p) ) } #' @export p_value.ols <- p_value.lrm #' @export p_value.rms <- p_value.lrm #' @export p_value.psm <- p_value.lrm #' @export p_value.blrm <- p_value.BFBayesFactor parameters/R/format_df_adjust.R 0000644 0001762 0000144 00000001757 14477616760 016310 0 ustar ligges users #' Format the name of the degrees-of-freedom adjustment methods #' #' Format the name of the degrees-of-freedom adjustment methods. #' #' @param method Name of the method. #' @param approx_string,dof_string Suffix added to the name of the method in #' the returned string. #' #' @examples #' library(parameters) #' #' format_df_adjust("kenward") #' format_df_adjust("kenward", approx_string = "", dof_string = " DoF") #' @return A formatted string. #' @export format_df_adjust <- function(method, approx_string = "-approximated", dof_string = " degrees of freedom") { method <- tolower(method) out <- switch(method, kr = , `kenward-rogers` = , `kenward-roger` = , kenward = "Kenward-Roger", ml1 = "m-l-1", betwithin = , bw = "Between-within", fit = "Residual", boot = "Bootstrapped", insight::format_capitalize(method) ) paste0(out, approx_string, dof_string) } parameters/R/methods_hclust.R 0000644 0001762 0000144 00000012276 14736731407 016012 0 ustar ligges users #' Parameters from Cluster Models (k-means, ...) #' #' Format cluster models obtained for example by [kmeans()]. #' #' @param model Cluster model. #' @param data A data frame. #' @param clusters A vector with clusters assignments (must be same length as #' rows in data). #' @param ... Arguments passed to or from other methods. #' #' @examplesIf require("factoextra", quietly = TRUE) && require("dbscan", quietly = TRUE) && require("cluster", quietly = TRUE) && require("fpc", quietly = TRUE) #' \donttest{ #' # #' # K-means ------------------------------- #' model <- kmeans(iris[1:4], centers = 3) #' rez <- model_parameters(model) #' rez #' #' # Get clusters #' predict(rez) #' #' # Clusters centers in long form #' attributes(rez)$means #' #' # Between and Total Sum of Squares #' attributes(rez)$Sum_Squares_Total #' attributes(rez)$Sum_Squares_Between #' #' # #' # Hierarchical clustering (hclust) --------------------------- #' data <- iris[1:4] #' model <- hclust(dist(data)) #' clusters <- cutree(model, 3) #' #' rez <- model_parameters(model, data, clusters) #' rez #' #' # Get clusters #' predict(rez) #' #' # Clusters centers in long form #' attributes(rez)$means #' #' # Between and Total Sum of Squares #' attributes(rez)$Total_Sum_Squares #' attributes(rez)$Between_Sum_Squares #' #' # #' # Hierarchical K-means (factoextra::hkclust) ---------------------- #' data <- iris[1:4] #' model <- factoextra::hkmeans(data, k = 3) #' #' rez <- model_parameters(model) #' rez #' #' # Get clusters #' predict(rez) #' #' # Clusters centers in long form #' attributes(rez)$means #' #' # Between and Total Sum of Squares #' attributes(rez)$Sum_Squares_Total #' attributes(rez)$Sum_Squares_Between #' #' # K-Medoids (PAM and HPAM) ============== #' model <- cluster::pam(iris[1:4], k = 3) #' model_parameters(model) #' #' model <- fpc::pamk(iris[1:4], criterion = "ch") #' model_parameters(model) #' #' # DBSCAN --------------------------- #' model <- dbscan::dbscan(iris[1:4], eps = 1.45, minPts = 10) #' #' rez <- model_parameters(model, iris[1:4]) #' rez #' #' # Get clusters #' predict(rez) #' #' # Clusters centers in long form #' attributes(rez)$means #' #' # Between and Total Sum of Squares #' attributes(rez)$Sum_Squares_Total #' attributes(rez)$Sum_Squares_Between #' #' # HDBSCAN #' model <- dbscan::hdbscan(iris[1:4], minPts = 10) #' model_parameters(model, iris[1:4]) #' } #' @export model_parameters.hclust <- function(model, data = NULL, clusters = NULL, ...) { if (is.null(data)) { insight::format_error( "This function requires the data used to compute the clustering to be provided via `data` as it is not accessible from the clustering object itself." ) } if (is.null(clusters)) { insight::format_error( "This function requires a vector of clusters assignments of same length as data to be passed, as it is not contained in the clustering object itself." ) } params <- cluster_centers(data, clusters, ...) # Long means means <- datawizard::reshape_longer(params, select = 4:ncol(params), values_to = "Mean", names_to = "Variable" ) attr(params, "variance") <- attributes(params)$variance attr(params, "Sum_Squares_Between") <- attributes(params)$Sum_Squares_Between attr(params, "Sum_Squares_Total") <- attributes(params)$Sum_Squares_Total attr(params, "means") <- means attr(params, "model") <- model attr(params, "scores") <- clusters attr(params, "type") <- "hclust" class(params) <- c("parameters_clusters", class(params)) params } #' @export model_parameters.pvclust <- function(model, data = NULL, clusters = NULL, ci = 0.95, ...) { if (is.null(data)) { insight::format_error( "This function requires the data used to compute the clustering to be provided via `data` as it is not accessible from the clustering object itself." ) } if (is.null(clusters)) { clusters <- .model_parameters_pvclust_clusters(model, data, ci)$Cluster } params <- .cluster_centers_params(data, clusters, ...) attr(params, "model") <- model attr(params, "type") <- "pvclust" attr(params, "title") <- "Bootstrapped Hierarchical Clustering (PVCLUST)" params } # Utils ------------------------------------------------------------------- #' @keywords internal .model_parameters_pvclust_clusters <- function(model, data, ci = 0.95) { insight::check_if_installed("pvclust") rez <- pvclust::pvpick(model, alpha = ci, pv = "si") # Assign clusters out <- data.frame() for (cluster in seq_along(rez$clusters)) { out <- rbind(out, data.frame(Cluster = cluster, Row = rez$clusters[[cluster]], stringsAsFactors = FALSE), make.row.names = FALSE, stringsAsFactors = FALSE) } # Add points not in significant clusters remaining_rows <- row.names(data)[!row.names(data) %in% out$Row] if (length(remaining_rows) > 0) { out <- rbind(out, data.frame(Cluster = 0, Row = remaining_rows, stringsAsFactors = FALSE), make.row.names = FALSE, stringsAsFactors = FALSE) } # Reorder according to original order of rows out <- out[order(match(out$Row, row.names(data))), ] row.names(out) <- NULL out } parameters/R/extract_random_parameters.R 0000644 0001762 0000144 00000007402 14736731407 020215 0 ustar ligges users .extract_random_parameters <- function(model, ...) { UseMethod(".extract_random_parameters") } .extract_random_parameters.merMod <- function(model, ci = 0.95, effects = "random", ...) { insight::check_if_installed("lme4") out <- as.data.frame(lme4::ranef(model, condVar = TRUE), stringsAsFactors = FALSE) colnames(out) <- c("Group", "Parameter", "Level", "Coefficient", "SE") # coerce to character out$Parameter <- as.character(out$Parameter) out$Level <- as.character(out$Level) out$Group <- as.character(out$Group) out$Effects <- "random" if (length(ci) == 1) { fac <- stats::qnorm((1 + ci) / 2) out$CI_low <- out$Coefficient - fac * out$SE out$CI_high <- out$Coefficient + fac * out$SE ci_cols <- c("CI_low", "CI_high") } else { ci_cols <- NULL for (i in ci) { fac <- stats::qnorm((1 + i) / 2) ci_low <- paste0("CI_low_", i) ci_high <- paste0("CI_high_", i) out[[ci_low]] <- out$Coefficient - fac * out$SE out[[ci_high]] <- out$Coefficient + fac * out$SE ci_cols <- c(ci_cols, ci_low, ci_high) } } stat_column <- gsub("-statistic", "", insight::find_statistic(model), fixed = TRUE) # to match rbind out[[stat_column]] <- NA out$df_error <- NA out$p <- NA out <- out[c("Parameter", "Level", "Coefficient", "SE", ci_cols, stat_column, "df_error", "p", "Effects", "Group")] if (effects == "random") { out[c(stat_column, "df_error", "p")] <- NULL } out } .extract_random_parameters.glmmTMB <- function(model, ci = 0.95, effects = "random", component = "conditional", ...) { insight::check_if_installed("lme4") out <- as.data.frame(lme4::ranef(model, condVar = TRUE)) colnames(out) <- c("Component", "Group", "Parameter", "Level", "Coefficient", "SE") # filter component out <- switch(component, zi = , zero_inflated = out[out$Component == "zi", ], cond = , conditional = out[out$Component == "cond", ], disp = , dispersion = out[out$Component == "disp", ], out ) # coerce to character out$Parameter <- as.character(out$Parameter) out$Level <- as.character(out$Level) out$Group <- as.character(out$Group) out$Effects <- "random" # rename out$Component[out$Component == "zi"] <- "zero_inflated" out$Component[out$Component == "cond"] <- "conditional" out$Component[out$Component == "disp"] <- "dispersion" if (length(ci) == 1) { fac <- stats::qnorm((1 + ci) / 2) out$CI_low <- out$Coefficient - fac * out$SE out$CI_high <- out$Coefficient + fac * out$SE ci_cols <- c("CI_low", "CI_high") } else { ci_cols <- NULL for (i in ci) { fac <- stats::qnorm((1 + i) / 2) ci_low <- paste0("CI_low_", i) ci_high <- paste0("CI_high_", i) out[[ci_low]] <- out$Coefficient - fac * out$SE out[[ci_high]] <- out$Coefficient + fac * out$SE ci_cols <- c(ci_cols, ci_low, ci_high) } } stat_column <- gsub("-statistic", "", insight::find_statistic(model), fixed = TRUE) # to match rbind out[[stat_column]] <- NA out$df_error <- NA out$p <- NA out <- out[c( "Parameter", "Level", "Coefficient", "SE", ci_cols, stat_column, "df_error", "p", "Component", "Effects", "Group" )] if (effects == "random") { out[c(stat_column, "df_error", "p")] <- NULL } out } .extract_random_parameters.MixMod <- function(model, ...) { NULL } parameters/vignettes/ 0000755 0001762 0000144 00000000000 14761600757 014442 5 ustar ligges users parameters/vignettes/overview_of_vignettes.Rmd 0000644 0001762 0000144 00000004267 14444564001 021526 0 ustar ligges users --- title: "Overview of Vignettes" output: rmarkdown::html_vignette: vignette: > %\VignetteIndexEntry{Overview of Vignettes} \usepackage[utf8]{inputenc} %\VignetteEngine{knitr::rmarkdown} editor_options: chunk_output_type: console --- ```{r message=FALSE, warning=FALSE, include=FALSE} library(knitr) knitr::opts_chunk$set( echo = TRUE, collapse = TRUE, warning = FALSE, message = FALSE, comment = "#>", eval = TRUE ) ``` All package vignettes are available at [https://easystats.github.io/parameters/](https://easystats.github.io/parameters/). ## Function Overview * [Function Reference](https://easystats.github.io/parameters/reference/index.html) ## Description of Parameters * [Summary of Model Parameters](https://easystats.github.io/parameters/articles/model_parameters.html) * [Parameter and Model Standardization](https://easystats.github.io/parameters/articles/standardize_parameters_effsize.html) * [Robust Estimation of Standard Errors, Confidence Intervals, and p-values](https://easystats.github.io/parameters/articles/model_parameters_robust.html) * [Model Parameters for Multiply Imputed Repeated Analyses](https://easystats.github.io/parameters/articles/model_parameters_mice.html) * [Analysing Longitudinal or Panel Data](https://easystats.github.io/parameters/articles/demean.html) ## Formatting and Printing * [Formatting Model Parameters](https://easystats.github.io/parameters/articles/model_parameters_formatting.html) * [Printing Model Parameters](https://easystats.github.io/parameters/articles/model_parameters_print.html) ## Dimension Reduction and Clustering * [Feature Reduction (PCA, cMDS, ICA, ...)](https://easystats.github.io/parameters/articles/parameters_reduction.html) * [Structural Models (EFA, CFA, SEM, ...)](https://easystats.github.io/parameters/articles/efa_cfa.html) * [Selection of Model Parameters](https://easystats.github.io/parameters/articles/parameters_selection.html) * [Clustering with easystats](https://easystats.github.io/parameters/articles/clustering.html) ## Plotting Functions * [Plotting functions in the **see** package](https://easystats.github.io/see/articles/parameters.html) parameters/data/ 0000755 0001762 0000144 00000000000 13641625623 013336 5 ustar ligges users parameters/data/qol_cancer.RData 0000644 0001762 0000144 00000006464 13641625623 016373 0 ustar ligges users ]iW~LL j6%T2OE4рF H\p]q7-%wKLY,*e[,5_uyHYU v9sν=E۴~k4uP(/7} rpFl_(_|2)/l۽ ^-qpk ^p p #otaaN]corxøn={ 9w8pN 98mowxG .w;{ pÇ >: sÅ w' >i8<:pswx % tCB9|txao9|a#q :?qx?sb ~a2g8\a3 .qae V;\YvpxW:\p5uxyk ur(:D%ءPq8ߡPs;</tXpðCaË ^/ux78lprW8p+ ^pFMi'G o
y,dF@%BܦdĵxftO9 ׀SF[ _<
Ec,Q1yԥ,ԍOZ:\~ŝ:{q>o3#!!N ~Ua5.
vByB71}9pM }Q?qĭ]]ٞOO>׆wk9b[9%?U"9?+| Ik! :zYr/=^yW}Q=/wu@Ƴ
}U3Ghk8p z,ԥ_tcxB<
s5zy;^^>=-{&
Yct@YOx&!FmcgO%˒z<[s]Kg+-Ek;hR^48ܵGb|w}(VwX.oys+ ⬧Pd%qLmU~Ͱ;rm3+< ?HtH'~[
*E ?
)z|.o jЖ_Z
;I?)eOމ8؋Cz|~mQ%]o>uuget%\錼XfGlm@{uUѵfJA7!^WTx$ _&oY.-&*jWB6]#zy3Nt )1oF[3V[ ?
vO*ր=-
v~Ɉ[?=.| ;t[g=w}n}'+;?c
|EיIhV" All package vignettes are available at https://easystats.github.io/parameters/. Sv͛@2mڴ'Oi>v옾QF-YDgŠJٟ{ kk5k4lذe˖gVŕV,H, . x0m~? >k:7IÕZE(Mo"B"ogi>.N4m4 ν7BGgHUӘsfGG67гec+n%_U%3uܮTvFT ]`z8 y3ϓ4'y&}r~o9EM~g["ʰ 2rK.-UԄ
\ U]gٳ8(oh&,Po]v3
ND8jժ
>ŋIHNNvqqîD{.tN:PY>""bժUt4O4fܹCվfp =z4,,,rSRR >|aA@g7n2vŊ? 硔?Nyf*UjԨw^ LAQ(%T}N9FR+J+55X5gF,`iO>ݹco,6G/
|]L&z8O(BaL:Z[O><8Wqȗ7 ~]mBBB6m ߠL
} }z @
[qqq YD D DI9s3ز24c ە.m \IP$S5lvF5 ԙj( x|4DDDlݺ OOOCiذ!|1 Mmׯoccs@MSlYHR܆O
*Um@Zti2릲F3bwqY3܊wd4=DVlEr { l-K $̉Q4ͼU-cM% ?
41ђw K. 5gΜ5ɅO]hYj{*T +W|}.! Sl&_<"}[xN7Qۭ.H2CC)w 3 Gg
O"k7liii6mILLx"+Grr!Cݻsθs璎WeeeEtBBLdd9s>3 JYтBȤ`4)?8iGn#^Efgp++~ \?clSW-&%+,פL ٜ՟~U}. 威?z1ev)
HǏhٲ%]q%ʻ|Znݺ]\\^e^hŊBWeee-\?:\]]!됊+H !hRZu? ?(}Z:_U>g@s{O+G QU^"Fpvae]Ne} ڈP.#MzH.}_2j֬٥Kc+ kk :>Å0|tuP}bqxx84lIӦM!ԩSnݺ
Lo>.Ys10111^RTTTzzz~H !ɨ5)
Ԝ˞n.9cN>w7_X=xEm a~~u=.E&m+alͨNuNP'jCS zŊxU:82sKTMm>/7ܭK &W+Ph ;3
& өk?me%]x[)ڵkW^(
VAAAH@%;;͛4M U
ݺu[zJP^=h{acc05߿?? ?~M6͚5PuStt4#]]][jޝGx >}`037o~/.}0/B |Y[[q,X y),88xȐ!gΜ)
y%66 hބ%K\~TJZzu:u+ww;wh^Մ 9r
{waş~)߂BȤ`4Ao_MLL /]5k֬J٥jG =eʔ'رB>y!LFBB!B& B!LFB&!2'~` IENDB` parameters/man/dot-data_frame.Rd 0000644 0001762 0000144 00000000355 13641634603 016337 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/utils.R
\name{.data_frame}
\alias{.data_frame}
\title{help-functions}
\usage{
.data_frame(...)
}
\description{
help-functions
}
\keyword{internal}
parameters/man/model_parameters.mira.Rd 0000644 0001762 0000144 00000011241 14717115420 017732 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/methods_mice.R
\name{model_parameters.mira}
\alias{model_parameters.mira}
\title{Parameters from multiply imputed repeated analyses}
\usage{
\method{model_parameters}{mira}(
model,
ci = 0.95,
exponentiate = FALSE,
p_adjust = NULL,
keep = NULL,
drop = NULL,
verbose = TRUE,
...
)
}
\arguments{
\item{model}{An object of class \code{mira} or \code{mipo}.}
\item{ci}{Confidence Interval (CI) level. Default to \code{0.95} (\verb{95\%}).}
\item{exponentiate}{Logical, indicating whether or not to exponentiate the
coefficients (and related confidence intervals). This is typical for
logistic regression, or more generally speaking, for models with log or
logit links. It is also recommended to use \code{exponentiate = TRUE} for models
with log-transformed response values. For models with a log-transformed
response variable, when \code{exponentiate = TRUE}, a one-unit increase in the
predictor is associated with multiplying the outcome by that predictor's
coefficient. \strong{Note:} Delta-method standard errors are also computed (by
multiplying the standard errors by the transformed coefficients). This is
to mimic behaviour of other software packages, such as Stata, but these
standard errors poorly estimate uncertainty for the transformed
coefficient. The transformed confidence interval more clearly captures this
uncertainty. For \code{compare_parameters()}, \code{exponentiate = "nongaussian"}
will only exponentiate coefficients from non-Gaussian families.}
\item{p_adjust}{Character vector, if not \code{NULL}, indicates the method to
adjust p-values. See \code{\link[stats:p.adjust]{stats::p.adjust()}} for details. Further
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{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
named list of regular expressions. All non-matching parameters will be
removed from the output. If \code{keep} is a character vector, every parameter
name in the \emph{"Parameter"} column that matches the regular expression in
\code{keep} will be selected from the returned data frame (and vice versa,
all parameter names matching \code{drop} will be excluded). Furthermore, if
\code{keep} has more than one element, these will be merged with an \code{OR}
operator into a regular expression pattern like this: \code{"(one|two|three)"}.
If \code{keep} is a named list of regular expression patterns, the names of the
list-element should equal the column name where selection should be
applied. This is useful for model objects where \code{model_parameters()}
returns multiple columns with parameter components, like in
\code{\link[=model_parameters.lavaan]{model_parameters.lavaan()}}. Note that the regular expression pattern
should match the parameter names as they are stored in the returned data
frame, which can be different from how they are printed. Inspect the
\verb{$Parameter} column of the parameters table to get the exact parameter
names.}
\item{drop}{See \code{keep}.}
\item{verbose}{Toggle warnings and messages.}
\item{...}{Arguments passed to or from other methods.}
}
\description{
Format models of class \code{mira}, obtained from \code{mice::width.mids()}, or of
class \code{mipo}.
}
\details{
\code{model_parameters()} for objects of class \code{mira} works
similar to \code{summary(mice::pool())}, i.e. it generates the pooled summary
of multiple imputed repeated regression analyses.
}
\examples{
\dontshow{if (require("mice", quietly = TRUE) && require("gee", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
library(parameters)
data(nhanes2, package = "mice")
imp <- mice::mice(nhanes2)
fit <- with(data = imp, exp = lm(bmi ~ age + hyp + chl))
model_parameters(fit)
\donttest{
# model_parameters() also works for models that have no "tidy"-method in mice
data(warpbreaks)
set.seed(1234)
warpbreaks$tension[sample(1:nrow(warpbreaks), size = 10)] <- NA
imp <- mice::mice(warpbreaks)
fit <- with(data = imp, expr = gee::gee(breaks ~ tension, id = wool))
# does not work:
# summary(mice::pool(fit))
model_parameters(fit)
}
# and it works with pooled results
data("nhanes2", package = "mice")
imp <- mice::mice(nhanes2)
fit <- with(data = imp, exp = lm(bmi ~ age + hyp + chl))
pooled <- mice::pool(fit)
model_parameters(pooled)
\dontshow{\}) # examplesIf}
}
parameters/man/display.parameters_model.Rd 0000644 0001762 0000144 00000027274 14751367303 020473 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/display.R, R/print_table.R
\name{display.parameters_model}
\alias{display.parameters_model}
\alias{display.parameters_sem}
\alias{display.parameters_efa_summary}
\alias{display.parameters_efa}
\alias{display.equivalence_test_lm}
\alias{print_table}
\title{Print tables in different output formats}
\usage{
\method{display}{parameters_model}(
object,
format = "markdown",
pretty_names = TRUE,
split_components = TRUE,
select = NULL,
caption = NULL,
subtitle = NULL,
footer = NULL,
align = NULL,
digits = 2,
ci_digits = digits,
p_digits = 3,
footer_digits = 3,
ci_brackets = c("(", ")"),
show_sigma = FALSE,
show_formula = FALSE,
zap_small = FALSE,
font_size = "100\%",
line_padding = 4,
column_labels = NULL,
include_reference = FALSE,
verbose = TRUE,
...
)
\method{display}{parameters_sem}(
object,
format = "markdown",
digits = 2,
ci_digits = digits,
p_digits = 3,
ci_brackets = c("(", ")"),
...
)
\method{display}{parameters_efa_summary}(object, format = "markdown", digits = 3, ...)
\method{display}{parameters_efa}(
object,
format = "markdown",
digits = 2,
sort = FALSE,
threshold = NULL,
labels = NULL,
...
)
\method{display}{equivalence_test_lm}(object, format = "markdown", digits = 2, ...)
print_table(x, digits = 2, p_digits = 3, theme = "default", ...)
}
\arguments{
\item{object}{An object returned by \code{\link[=model_parameters]{model_parameters()}},\code{\link[=simulate_parameters]{simulate_parameters()}},
\code{\link[=equivalence_test]{equivalence_test()}} or \code{\link[=principal_components]{principal_components()}}.}
\item{format}{String, indicating the output format. Can be \code{"markdown"}
or \code{"html"}.}
\item{pretty_names}{Can be \code{TRUE}, which will return "pretty" (i.e. more human
readable) parameter names. Or \code{"labels"}, in which case value and variable
labels will be used as parameters names. The latter only works for "labelled"
data, i.e. if the data used to fit the model had \code{"label"} and \code{"labels"}
attributes. See also section \emph{Global Options to Customize Messages when Printing}.}
\item{split_components}{Logical, if \code{TRUE} (default), For models with
multiple components (zero-inflation, smooth terms, ...), each component is
printed in a separate table. If \code{FALSE}, model parameters are printed
in a single table and a \code{Component} column is added to the output.}
\item{select}{Determines which columns and and which layout columns are
printed. There are three options for this argument:
\itemize{
\item \strong{Selecting columns by name or index}
\code{select} can be a character vector (or numeric index) of column names that
should be printed, where columns are extracted from the data frame returned
by \code{model_parameters()} and related functions.
There are two pre-defined options for selecting columns:
\code{select = "minimal"} prints coefficients, confidence intervals and
p-values, while \code{select = "short"} prints coefficients, standard errors and
p-values.
\item \strong{A string expression with layout pattern}
\code{select} is a string with "tokens" enclosed in braces. These tokens will be
replaced by their associated columns, where the selected columns will be
collapsed into one column. Following tokens are replaced by the related
coefficients or statistics: \code{{estimate}}, \code{{se}}, \code{{ci}} (or \code{{ci_low}} and
\code{{ci_high}}), \code{{p}} and \code{{stars}}. The token \code{{ci}} will be replaced by
\verb{\{ci_low\}, \{ci_high\}}. Example: \code{select = "{estimate}{stars} ({ci})"}
It is possible to create multiple columns as well. A \code{|} separates values
into new cells/columns. Example: \code{select = "{estimate} ({ci})|{p}"}.
If \code{format = "html"}, a \verb{Overview of Vignettes
Function Overview
Description of Parameters
Formatting and Printing
Dimension Reduction and Clustering
Plotting Functions
[](https://doi.org/10.21105/joss.02445)
[](https://cran.r-project.org/package=parameters)
[](https://cranlogs.r-pkg.org/)
***Describe and understand your model’s parameters!***
**parameters**’ primary goal is to provide utilities for processing the
parameters of various statistical models (see
[here](https://easystats.github.io/insight/) for a list of supported
models). Beyond computing *p-values*, *CIs*, *Bayesian indices* and
other measures for a wide variety of models, this package implements
features like *bootstrapping* of parameters and models, *feature
reduction* (feature extraction and variable selection), or tools for
data reduction like functions to perform cluster, factor or principal
component analysis.
Another important goal of the **parameters** package is to facilitate
and streamline the process of reporting results of statistical models,
which includes the easy and intuitive calculation of standardized
estimates or robust standard errors and p-values. **parameters**
therefor offers a simple and unified syntax to process a large variety
of (model) objects from many different packages.
## Installation
[](https://cran.r-project.org/package=parameters)
[](https://easystats.r-universe.dev)
[](https://app.codecov.io/gh/easystats/parameters)
| Type | Source | Command |
|----|----|----|
| Release | CRAN | `install.packages("parameters")` |
| Development | r - universe | `install.packages("parameters", repos = "https://easystats.r-universe.dev")` |
| Development | GitHub | `remotes::install_github("easystats/parameters")` |
> **Tip**
>
> Instead of `library(parameters)`, use `library(easystats)`. This will
> make all features of the easystats-ecosystem available.
>
> To stay updated, use `easystats::install_latest()`.
## Documentation
[](https://easystats.github.io/parameters/)
[](https://easystats.github.io/blog/posts/)
[](https://easystats.github.io/parameters/reference/index.html)
Click on the buttons above to access the package
[documentation](https://easystats.github.io/parameters/) and the
[easystats blog](https://easystats.github.io/blog/posts/), and check-out
these vignettes:
- [Summary of Model
Parameters](https://easystats.github.io/parameters/articles/model_parameters.html)
- [Parameter and Model
Standardization](https://easystats.github.io/parameters/articles/standardize_parameters_effsize.html)
- [Robust Estimation of Standard Errors, Confidence Intervals and
p-values](https://easystats.github.io/parameters/articles/model_parameters_robust.html)
- [Model Parameters and Missing
Data](https://easystats.github.io/parameters/articles/model_parameters_mice.html)
- [Feature reduction (PCA, cMDS,
ICA…)](https://easystats.github.io/parameters/articles/parameters_reduction.html)
- [Structural models (EFA, CFA,
SEM…)](https://easystats.github.io/parameters/articles/efa_cfa.html)
- [Parameters
selection](https://easystats.github.io/parameters/articles/parameters_selection.html)
- [A Practical Guide for Panel Data
Analysis](https://easystats.github.io/parameters/articles/demean.html)
- [Plotting
functions](https://easystats.github.io/see/articles/parameters.html)
## Contributing and Support
In case you want to file an issue or contribute in another way to the
package, please follow [this
guide](https://github.com/easystats/parameters/blob/main/.github/CONTRIBUTING.md).
For questions about the functionality, you may either contact us via
email or also file an issue.
# Features
## Model’s parameters description
The
[`model_parameters()`](https://easystats.github.io/parameters/articles/model_parameters.html)
function (that can be accessed via the `parameters()` shortcut) allows
you to extract the parameters and their characteristics from various
models in a consistent way. It can be considered as a lightweight
alternative to [`broom::tidy()`](https://github.com/tidymodels/broom),
with some notable differences:
- The column names of the returned data frame are *specific* to their
content. For instance, the column containing the statistic is named
following the statistic name, i.e., *t*, *z*, etc., instead of a
generic name such as *statistic* (however, you can get standardized
(generic) column names using
[`standardize_names()`](https://easystats.github.io/insight/reference/standardize_names.html)).
- It is able to compute or extract indices not available by default,
such as *p-values*, *CIs*, etc.
- It includes *feature engineering* capabilities, including parameters
[bootstrapping](https://easystats.github.io/parameters/reference/bootstrap_parameters.html).
### Classical Regression Models
``` r
model <- lm(Sepal.Width ~ Petal.Length * Species + Petal.Width, data = iris)
# regular model parameters
model_parameters(model)
#> Parameter | Coefficient | SE | 95% CI | t(143) | p
#> -------------------------------------------------------------------------------------------
#> (Intercept) | 2.89 | 0.36 | [ 2.18, 3.60] | 8.01 | < .001
#> Petal Length | 0.26 | 0.25 | [-0.22, 0.75] | 1.07 | 0.287
#> Species [versicolor] | -1.66 | 0.53 | [-2.71, -0.62] | -3.14 | 0.002
#> Species [virginica] | -1.92 | 0.59 | [-3.08, -0.76] | -3.28 | 0.001
#> Petal Width | 0.62 | 0.14 | [ 0.34, 0.89] | 4.41 | < .001
#> Petal Length × Species [versicolor] | -0.09 | 0.26 | [-0.61, 0.42] | -0.36 | 0.721
#> Petal Length × Species [virginica] | -0.13 | 0.26 | [-0.64, 0.38] | -0.50 | 0.618
# standardized parameters
model_parameters(model, standardize = "refit")
#> Parameter | Coefficient | SE | 95% CI | t(143) | p
#> -------------------------------------------------------------------------------------------
#> (Intercept) | 3.59 | 1.30 | [ 1.01, 6.17] | 2.75 | 0.007
#> Petal Length | 1.07 | 1.00 | [-0.91, 3.04] | 1.07 | 0.287
#> Species [versicolor] | -4.62 | 1.31 | [-7.21, -2.03] | -3.53 | < .001
#> Species [virginica] | -5.51 | 1.38 | [-8.23, -2.79] | -4.00 | < .001
#> Petal Width | 1.08 | 0.24 | [ 0.59, 1.56] | 4.41 | < .001
#> Petal Length × Species [versicolor] | -0.38 | 1.06 | [-2.48, 1.72] | -0.36 | 0.721
#> Petal Length × Species [virginica] | -0.52 | 1.04 | [-2.58, 1.54] | -0.50 | 0.618
# heteroscedasticity-consitent SE and CI
model_parameters(model, vcov = "HC3")
#> Parameter | Coefficient | SE | 95% CI | t(143) | p
#> -------------------------------------------------------------------------------------------
#> (Intercept) | 2.89 | 0.43 | [ 2.03, 3.75] | 6.66 | < .001
#> Petal Length | 0.26 | 0.29 | [-0.30, 0.83] | 0.92 | 0.357
#> Species [versicolor] | -1.66 | 0.53 | [-2.70, -0.62] | -3.16 | 0.002
#> Species [virginica] | -1.92 | 0.77 | [-3.43, -0.41] | -2.51 | 0.013
#> Petal Width | 0.62 | 0.12 | [ 0.38, 0.85] | 5.23 | < .001
#> Petal Length × Species [versicolor] | -0.09 | 0.29 | [-0.67, 0.48] | -0.32 | 0.748
#> Petal Length × Species [virginica] | -0.13 | 0.31 | [-0.73, 0.48] | -0.42 | 0.675
```
### Mixed Models
``` r
library(lme4)
model <- lmer(Sepal.Width ~ Petal.Length + (1 | Species), data = iris)
# model parameters with CI, df and p-values based on Wald approximation
model_parameters(model)
#> # Fixed Effects
#>
#> Parameter | Coefficient | SE | 95% CI | t(146) | p
#> ------------------------------------------------------------------
#> (Intercept) | 2.00 | 0.56 | [0.89, 3.11] | 3.56 | < .001
#> Petal Length | 0.28 | 0.06 | [0.16, 0.40] | 4.75 | < .001
#>
#> # Random Effects
#>
#> Parameter | Coefficient | SE | 95% CI
#> -----------------------------------------------------------
#> SD (Intercept: Species) | 0.89 | 0.46 | [0.33, 2.43]
#> SD (Residual) | 0.32 | 0.02 | [0.28, 0.35]
# model parameters with CI, df and p-values based on Kenward-Roger approximation
model_parameters(model, ci_method = "kenward", effects = "fixed")
#> # Fixed Effects
#>
#> Parameter | Coefficient | SE | 95% CI | t | df | p
#> -------------------------------------------------------------------------
#> (Intercept) | 2.00 | 0.57 | [0.07, 3.93] | 3.53 | 2.67 | 0.046
#> Petal Length | 0.28 | 0.06 | [0.16, 0.40] | 4.58 | 140.98 | < .001
```
### Structural Models
Besides many types of regression models and packages, it also works for
other types of models, such as [**structural
models**](https://easystats.github.io/parameters/articles/efa_cfa.html)
(EFA, CFA, SEM…).
``` r
library(psych)
model <- psych::fa(attitude, nfactors = 3)
model_parameters(model)
#> # Rotated loadings from Factor Analysis (oblimin-rotation)
#>
#> Variable | MR1 | MR2 | MR3 | Complexity | Uniqueness
#> ------------------------------------------------------------
#> rating | 0.90 | -0.07 | -0.05 | 1.02 | 0.23
#> complaints | 0.97 | -0.06 | 0.04 | 1.01 | 0.10
#> privileges | 0.44 | 0.25 | -0.05 | 1.64 | 0.65
#> learning | 0.47 | 0.54 | -0.28 | 2.51 | 0.24
#> raises | 0.55 | 0.43 | 0.25 | 2.35 | 0.23
#> critical | 0.16 | 0.17 | 0.48 | 1.46 | 0.67
#> advance | -0.11 | 0.91 | 0.07 | 1.04 | 0.22
#>
#> The 3 latent factors (oblimin rotation) accounted for 66.60% of the total variance of the original data (MR1 = 38.19%, MR2 = 22.69%, MR3 = 5.72%).
```
## Variable and parameters selection
[`select_parameters()`](https://easystats.github.io/parameters/articles/parameters_selection.html)
can help you quickly select and retain the most relevant predictors
using methods tailored for the model type.
``` r
lm(disp ~ ., data = mtcars) |>
select_parameters() |>
model_parameters()
#> Parameter | Coefficient | SE | 95% CI | t(26) | p
#> -----------------------------------------------------------------------
#> (Intercept) | 141.70 | 125.67 | [-116.62, 400.02] | 1.13 | 0.270
#> cyl | 13.14 | 7.90 | [ -3.10, 29.38] | 1.66 | 0.108
#> hp | 0.63 | 0.20 | [ 0.22, 1.03] | 3.18 | 0.004
#> wt | 80.45 | 12.22 | [ 55.33, 105.57] | 6.58 | < .001
#> qsec | -14.68 | 6.14 | [ -27.31, -2.05] | -2.39 | 0.024
#> carb | -28.75 | 5.60 | [ -40.28, -17.23] | -5.13 | < .001
```
## Statistical inference - how to quantify evidence
There is no standardized approach to drawing conclusions based on the
available data and statistical models. A frequently chosen but also much
criticized approach is to evaluate results based on their statistical
significance (Amrhein, Korner-Nievergelt, & Roth, 2017).
A more sophisticated way would be to test whether estimated effects
exceed the “smallest effect size of interest”, to avoid even the
smallest effects being considered relevant simply because they are
statistically significant, but clinically or practically irrelevant
(Lakens, 2024; Lakens, Scheel, & Isager, 2018). A rather unconventional
approach, which is nevertheless advocated by various authors, is to
interpret results from classical regression models in terms of
probabilities, similar to the usual approach in Bayesian statistics
(Greenland, Rafi, Matthews, & Higgs, 2022; Rafi & Greenland, 2020;
Schweder, 2018; Schweder & Hjort, 2003; Vos & Holbert, 2022).
The *parameters* package provides several options or functions to aid
statistical inference. These are, for example:
- [`equivalence_test()`](https://easystats.github.io/parameters/reference/equivalence_test.lm.html),
to compute the (conditional) equivalence test for frequentist models
- [`p_significance()`](https://easystats.github.io/parameters/reference/p_significance.lm.html),
to compute the probability of *practical significance*, which can be
conceptualized as a unidirectional equivalence test
- [`p_function()`](https://easystats.github.io/parameters/reference/p_function.html),
or *consonance function*, to compute p-values and compatibility
(confidence) intervals for statistical models
- the `pd` argument (setting `pd = TRUE`) in `model_parameters()`
includes a column with the *probability of direction*, i.e. the
probability that a parameter is strictly positive or negative. See
[`bayestestR::p_direction()`](https://easystats.github.io/bayestestR/reference/p_direction.html)
for details.
- the `s_value` argument (setting `s_value = TRUE`) in
`model_parameters()` replaces the p-values with their related
*S*-values (@ Rafi & Greenland, 2020)
- finally, it is possible to generate distributions of model
coefficients by generating bootstrap-samples (setting
`bootstrap = TRUE`) or simulating draws from model coefficients using
[`simulate_model()`](https://easystats.github.io/parameters/reference/simulate_model.html).
These samples can then be treated as “posterior samples” and used in
many functions from the **bayestestR** package.
Most of the above shown options or functions derive from methods
originally implemented for Bayesian models (Makowski, Ben-Shachar, Chen,
& Lüdecke, 2019). However, assuming that model assumptions are met
(which means, the model fits well to the data, the correct model is
chosen that reflects the data generating process (distributional model
family) etc.), it seems appropriate to interpret results from classical
frequentist models in a “Bayesian way” (more details: documentation in
[`p_function()`](https://easystats.github.io/parameters/reference/p_function.html)).
## Citation
In order to cite this package, please use the following command:
``` r
citation("parameters")
To cite package 'parameters' in publications use:
Lüdecke D, Ben-Shachar M, Patil I, Makowski D (2020). "Extracting,
Computing and Exploring the Parameters of Statistical Models using
R." _Journal of Open Source Software_, *5*(53), 2445.
doi:10.21105/joss.02445
} inserts a line break inside a cell. See
'Examples'.
\item \strong{A string indicating a pre-defined layout}
\code{select} can be one of the following string values, to create one of the
following pre-defined column layouts:
\itemize{
\item \code{"ci"}: Estimates and confidence intervals, no asterisks for p-values.
This is equivalent to \code{select = "{estimate} ({ci})"}.
\item \code{"se"}: Estimates and standard errors, no asterisks for p-values. This is
equivalent to \code{select = "{estimate} ({se})"}.
\item \code{"ci_p"}: Estimates, confidence intervals and asterisks for p-values. This
is equivalent to \code{select = "{estimate}{stars} ({ci})"}.
\item \code{"se_p"}: Estimates, standard errors and asterisks for p-values. This is
equivalent to \code{select = "{estimate}{stars} ({se})"}..
\item \code{"ci_p2"}: Estimates, confidence intervals and numeric p-values, in two
columns. This is equivalent to \code{select = "{estimate} ({ci})|{p}"}.
\item \code{"se_p2"}: Estimate, standard errors and numeric p-values, in two columns.
This is equivalent to \code{select = "{estimate} ({se})|{p}"}.
}
}
For \code{model_parameters()}, glue-like syntax is still experimental in the
case of more complex models (like mixed models) and may not return expected
results.}
\item{digits, ci_digits, p_digits}{Number of digits for rounding or
significant figures. May also be \code{"signif"} to return significant
figures or \code{"scientific"} to return scientific notation. Control the
number of digits by adding the value as suffix, e.g. \code{digits = "scientific4"}
to have scientific notation with 4 decimal places, or \code{digits = "signif5"}
for 5 significant figures (see also \code{\link[=signif]{signif()}}).}
\item{ci_width}{Minimum width of the returned string for confidence
intervals. If not \code{NULL} and width is larger than the string's length,
leading whitespaces are added to the string. If \code{width="auto"}, width
will be set to the length of the longest string.}
\item{ci_brackets}{Logical, if \code{TRUE} (default), CI-values are
encompassed in square brackets (else in parentheses).}
\item{zap_small}{Logical, if \code{TRUE}, small values are rounded after
\code{digits} decimal places. If \code{FALSE}, values with more decimal
places than \code{digits} are printed in scientific notation.}
\item{format}{String, indicating the output format. Can be \code{"markdown"}
or \code{"html"}.}
\item{groups}{Named list, can be used to group parameters in the printed output.
List elements may either be character vectors that match the name of those
parameters that belong to one group, or list elements can be row numbers
of those parameter rows that should belong to one group. The names of the
list elements will be used as group names, which will be inserted as "header
row". A possible use case might be to emphasize focal predictors and control
variables, see 'Examples'. Parameters will be re-ordered according to the
order used in \code{groups}, while all non-matching parameters will be added
to the end.}
\item{include_reference}{Logical, if \code{TRUE}, the reference level of factors will
be added to the parameters table. This is only relevant for models with
categorical predictors. The coefficient for the reference level is always
\code{0} (except when \code{exponentiate = TRUE}, then the coefficient will be \code{1}),
so this is just for completeness.}
\item{...}{Arguments passed down to \code{\link[=format.parameters_model]{format.parameters_model()}},
\code{\link[insight:format_table]{insight::format_table()}} and \code{\link[insight:export_table]{insight::export_table()}}}
\item{caption}{Table caption as string. If \code{NULL}, depending on the model,
either a default caption or no table caption is printed. Use \code{caption = ""}
to suppress the table caption.}
\item{footer}{Can either be \code{FALSE} or an empty string (i.e. \code{""}) to
suppress the footer, \code{NULL} to print the default footer, or a string. The
latter will combine the string value with the default footer.}
\item{footer_digits}{Number of decimal places for values in the footer summary.}
\item{show_sigma}{Logical, if \code{TRUE}, adds information about the residual
standard deviation.}
\item{show_formula}{Logical, if \code{TRUE}, adds the model formula to the output.}
\item{column_width}{Width of table columns. Can be either \code{NULL}, a named
numeric vector, or \code{"fixed"}. If \code{NULL}, the width for each table column is
adjusted to the minimum required width. If a named numeric vector, value
names are matched against column names, and for each match, the specified
width is used. If \code{"fixed"}, and table is split into multiple components,
columns across all table components are adjusted to have the same width.}
\item{subtitle}{Table title (same as caption) and subtitle, as strings. If \code{NULL},
no title or subtitle is printed, unless it is stored as attributes (\code{table_title},
or its alias \code{table_caption}, and \code{table_subtitle}). If \code{x} is a list of
data frames, \code{caption} may be a list of table captions, one for each table.}
\item{align}{Only applies to HTML tables. May be one of \code{"left"},
\code{"right"} or \code{"center"}.}
\item{font_size}{For HTML tables, the font size.}
\item{line_padding}{For HTML tables, the distance (in pixel) between lines.}
\item{column_labels}{Labels of columns for HTML tables. If \code{NULL}, automatic
column names are generated. See 'Examples'.}
\item{verbose}{Toggle messages and warnings.}
}
\value{
Invisibly returns the original input object.
}
\description{
A \code{print()}-method for objects from \code{\link[=model_parameters]{model_parameters()}}.
}
\details{
\code{summary()} is a convenient shortcut for
\code{print(object, select = "minimal", show_sigma = TRUE, show_formula = TRUE)}.
}
\section{Global Options to Customize Messages and Tables when Printing}{
The \code{verbose} argument can be used to display or silence messages and
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_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
printing \code{model_parameters()} objects.
\item \code{parameters_exponentiate}: \code{options(parameters_exponentiate = TRUE)} will
show the additional information on how to interpret coefficients of models
with log-transformed response variables or with log-/logit-links when the
\code{exponentiate} argument in \code{model_parameters()} is not \code{TRUE}. Set this option
to \code{FALSE} to hide this message when printing \code{model_parameters()} objects.
}
There are further options that can be used to modify the default behaviour
for printed outputs:
\itemize{
\item \code{parameters_labels}: \code{options(parameters_labels = TRUE)} will use variable
and value labels for pretty names, if data is labelled. If no labels
available, default pretty names are used.
\item \code{parameters_interaction}: \verb{options(parameters_interaction =
({se})|{p}")
print_html(result)
}
\dontshow{\}) # examplesIf}
}
\seealso{
See also \code{\link[=display.parameters_model]{display()}}.
}
parameters/man/p_function.Rd 0000644 0001762 0000144 00000055557 14761600443 015651 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/p_function.R
\name{p_function}
\alias{p_function}
\alias{consonance_function}
\alias{confidence_curve}
\title{p-value or consonance function}
\usage{
p_function(
model,
ci_levels = c(0.25, 0.5, 0.75, emph = 0.95),
exponentiate = FALSE,
effects = "fixed",
component = "all",
vcov = NULL,
vcov_args = NULL,
keep = NULL,
drop = NULL,
verbose = TRUE,
...
)
consonance_function(
model,
ci_levels = c(0.25, 0.5, 0.75, emph = 0.95),
exponentiate = FALSE,
effects = "fixed",
component = "all",
vcov = NULL,
vcov_args = NULL,
keep = NULL,
drop = NULL,
verbose = TRUE,
...
)
confidence_curve(
model,
ci_levels = c(0.25, 0.5, 0.75, emph = 0.95),
exponentiate = FALSE,
effects = "fixed",
component = "all",
vcov = NULL,
vcov_args = NULL,
keep = NULL,
drop = NULL,
verbose = TRUE,
...
)
}
\arguments{
\item{model}{Statistical Model.}
\item{ci_levels}{Vector of scalars, indicating the different levels at which
compatibility intervals should be printed or plotted. In plots, these levels
are highlighted by vertical lines. It is possible to increase thickness for
one or more of these lines by providing a names vector, where the to be
highlighted values should be named \code{"emph"}, e.g
\code{ci_levels = c(0.25, 0.5, emph = 0.95)}.}
\item{exponentiate}{Logical, indicating whether or not to exponentiate the
coefficients (and related confidence intervals). This is typical for
logistic regression, or more generally speaking, for models with log or
logit links. It is also recommended to use \code{exponentiate = TRUE} for models
with log-transformed response values. For models with a log-transformed
response variable, when \code{exponentiate = TRUE}, a one-unit increase in the
predictor is associated with multiplying the outcome by that predictor's
coefficient. \strong{Note:} Delta-method standard errors are also computed (by
multiplying the standard errors by the transformed coefficients). This is
to mimic behaviour of other software packages, such as Stata, but these
standard errors poorly estimate uncertainty for the transformed
coefficient. The transformed confidence interval more clearly captures this
uncertainty. For \code{compare_parameters()}, \code{exponentiate = "nongaussian"}
will only exponentiate coefficients from non-Gaussian families.}
\item{effects}{Should parameters for fixed effects (\code{"fixed"}), random
effects (\code{"random"}), both fixed and random effects (\code{"all"}), or the
overall (sum of fixed and random) effects (\code{"random_total"}) be returned?
Only applies to mixed models. May be abbreviated. If the calculation of
random effects parameters takes too long, you may use \code{effects = "fixed"}.}
\item{component}{Which type of parameters to return, such as parameters for the
conditional model, the zero-inflation part of the model, the dispersion
term, or other auxiliary parameters be returned? Applies to models with
zero-inflation and/or dispersion formula, or if parameters such as \code{sigma}
should be included. May be abbreviated. Note that the \emph{conditional}
component is also called \emph{count} or \emph{mean} component, depending on the
model. There are three convenient shortcuts: \code{component = "all"} returns
all possible parameters. If \code{component = "location"}, location parameters
such as \code{conditional}, \code{zero_inflated}, or \code{smooth_terms}, are returned
(everything that are fixed or random effects - depending on the \code{effects}
argument - but no auxiliary parameters). For \code{component = "distributional"}
(or \code{"auxiliary"}), components like \code{sigma}, \code{dispersion}, or \code{beta}
(and other auxiliary parameters) are returned.}
\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{"HC"}, \code{"HC0"}, \code{"HC1"}, \code{"HC2"},
\code{"HC3"}, \code{"HC4"}, \code{"HC4m"}, \code{"HC5"}. See \code{?sandwich::vcovHC}
\item Cluster-robust: \code{"CR"}, \code{"CR0"}, \code{"CR1"}, \code{"CR1p"}, \code{"CR1S"},
\code{"CR2"}, \code{"CR3"}. See \code{?clubSandwich::vcovCR}
\item Bootstrap: \code{"BS"}, \code{"xy"}, \code{"residual"}, \code{"wild"}, \code{"mammen"},
\code{"fractional"}, \code{"jackknife"}, \code{"norm"}, \code{"webb"}. See
\code{?sandwich::vcovBS}
\item Other \code{sandwich} package functions: \code{"HAC"}, \code{"PC"}, \code{"CL"}, \code{"OPG"},
\code{"PL"}.
}
}}
\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. If no estimation type (argument \code{type}) is given, the default
type for \code{"HC"} equals the default from the \strong{sandwich} package; for type
\code{"CR"}, the default is set to \code{"CR3"}.}
\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
named list of regular expressions. All non-matching parameters will be
removed from the output. If \code{keep} is a character vector, every parameter
name in the \emph{"Parameter"} column that matches the regular expression in
\code{keep} will be selected from the returned data frame (and vice versa,
all parameter names matching \code{drop} will be excluded). Furthermore, if
\code{keep} has more than one element, these will be merged with an \code{OR}
operator into a regular expression pattern like this: \code{"(one|two|three)"}.
If \code{keep} is a named list of regular expression patterns, the names of the
list-element should equal the column name where selection should be
applied. This is useful for model objects where \code{model_parameters()}
returns multiple columns with parameter components, like in
\code{\link[=model_parameters.lavaan]{model_parameters.lavaan()}}. Note that the regular expression pattern
should match the parameter names as they are stored in the returned data
frame, which can be different from how they are printed. Inspect the
\verb{$Parameter} column of the parameters table to get the exact parameter
names.}
\item{drop}{See \code{keep}.}
\item{verbose}{Toggle warnings and messages.}
\item{...}{Arguments passed to or from other methods. Non-documented
arguments are
\itemize{
\item \code{digits}, \code{p_digits}, \code{ci_digits} and \code{footer_digits} to set the number of
digits for the output. \code{groups} can be used to group coefficients. These
arguments will be passed to the print-method, or can directly be used in
\code{print()}, see documentation in \code{\link[=print.parameters_model]{print.parameters_model()}}.
\item If \code{s_value = TRUE}, the p-value will be replaced by the S-value in the
output (cf. \emph{Rafi and Greenland 2020}).
\item \code{pd} adds an additional column with the \emph{probability of direction} (see
\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}} for details). Furthermore, see 'Examples' in
\code{\link[=model_parameters.default]{model_parameters.default()}}.
\item For developers, whose 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.
}}
}
\value{
A data frame with p-values and compatibility intervals.
}
\description{
Compute p-values and compatibility (confidence) intervals for
statistical models, at different levels. This function is also called
consonance function. It allows to see which estimates are compatible with
the model at various compatibility levels. Use \code{plot()} to generate plots
of the \emph{p} resp. \emph{consonance} function and compatibility intervals at
different levels.
}
\details{
\subsection{Compatibility intervals and continuous \emph{p}-values for different estimate values}{
\code{p_function()} only returns the compatibility interval estimates, not the
related \emph{p}-values. The reason for this is because the \emph{p}-value for a
given estimate value is just \code{1 - CI_level}. The values indicating the lower
and upper limits of the intervals are the related estimates associated with
the \emph{p}-value. E.g., if a parameter \code{x} has a 75\% compatibility interval
of \verb{(0.81, 1.05)}, then the \emph{p}-value for the estimate value of \code{0.81}
would be \code{1 - 0.75}, which is \code{0.25}. This relationship is more intuitive and
better to understand when looking at the plots (using \code{plot()}).
}
\subsection{Conditional versus unconditional interpretation of \emph{p}-values and intervals}{
\code{p_function()}, and in particular its \code{plot()} method, aims at re-interpreting
\emph{p}-values and confidence intervals (better named: \emph{compatibility} intervals)
in \emph{unconditional} terms. Instead of referring to the long-term property and
repeated trials when interpreting interval estimates (so-called "aleatory
probability", \emph{Schweder 2018}), and assuming that all underlying assumptions
are correct and met, \code{p_function()} interprets \emph{p}-values in a Fisherian way
as "\emph{continuous} measure of evidence against the very test hypothesis \emph{and}
entire model (all assumptions) used to compute it"
(\emph{P-Values Are Tough and S-Values Can Help}, lesslikely.com/statistics/s-values;
see also \emph{Amrhein and Greenland 2022}).
The common definition of p-values can be considered as "conditional"
interpretation:
\emph{The p-value is the probability of obtaining test results at least as
extreme as the result actually observed, under the assumption that the
null hypothesis is correct (Wikipedia).}
However, this definition or interpretation is inadequate because it only
refers to the test hypothesis (often the null hypothesis), which is only
one component of the entire model that is being tested. Thus,
\emph{Greenland et al. 2022} suggest an "unconditional" interpretation.
This interpretation as a continuous measure of evidence against the test
hypothesis and the entire model used to compute it can be seen in the
figure below (taken from \emph{P-Values Are Tough and S-Values Can Help},
lesslikely.com/statistics/s-values). The "conditional" interpretation of
\emph{p}-values and interval estimates (A) implicitly assumes certain assumptions
to be true, thus the interpretation is "conditioned" on these assumptions
(i.e. assumptions are taken as given, only the hypothesis is tested). The
unconditional interpretation (B), however, questions \emph{all} these assumptions.
A non-significant p-value could occur because the test hypothesis is false,
but could also be the result of any of the model assumptions being incorrect.
\if{html}{\cr \figure{unconditional_interpretation.png}{options: alt="Conditional versus unconditional interpretations of P-values"} \cr}
"Emphasizing unconditional interpretations helps avoid overconfident and
misleading inferences in light of uncertainties about the assumptions used
to arrive at the statistical results." (\emph{Greenland et al. 2022}).
\strong{Note:} The term "conditional" as used by Rafi and Greenland probably has
a slightly different meaning than normally. "Conditional" in this notion
means that all model assumptions are taken as given - it should not be
confused with terms like "conditional probability". See also \emph{Greenland et al. 2022}
for a detailed elaboration on this issue.
In other words, the term compatibility interval emphasizes "the dependence
of the \emph{p}-value on the assumptions as well as on the data, recognizing that
\emph{p}<0.05 can arise from assumption violations even if the effect under
study is null" (\emph{Gelman/Greenland 2019}).
}
\subsection{Probabilistic interpretation of p-values and compatibility intervals}{
Schweder (2018) resp. Schweder and Hjort (2016) (and others) argue that
confidence curves (as produced by \code{p_function()}) have a valid probabilistic
interpretation. They distinguish between \emph{aleatory probability}, which
describes the aleatory stochastic element of a distribution \emph{ex ante}, i.e.
before the data are obtained. This is the classical interpretation of
confidence intervals following the Neyman-Pearson school of statistics.
However, there is also an \emph{ex post} probability, called \emph{epistemic} probability,
for confidence curves. The shift in terminology from \emph{confidence} intervals
to \emph{compatibility} intervals may help emphasizing this interpretation.
In this sense, the probabilistic interpretation of \emph{p}-values and
compatibility intervals is "conditional" - on the data \emph{and} model assumptions
(which is in line with the \emph{"unconditional"} interpretation in the sense of
Rafi and Greenland).
Ascribing a probabilistic interpretation to one realized confidence interval
is possible without repeated sampling of the specific experiment. Important
is the assumption that a \emph{sampling distribution} is a good description of the
variability of the parameter (\emph{Vos and Holbert 2022}). At the core, the
interpretation of a confidence interval is "I assume that this sampling
distribution is a good description of the uncertainty of the parameter. If
that's a good assumption, then the values in this interval are the most
plausible or compatible with the data". The source of confidence in
probability statements is the assumption that the selected sampling
distribution is appropriate.
"The realized confidence distribution is clearly an epistemic probability
distribution" (\emph{Schweder 2018}). In Bayesian words, compatibility intervals
(or confidence distributons, or consonance curves) are "posteriors without
priors" (\emph{Schweder, Hjort, 2003}).
The \emph{p}-value indicates the degree of compatibility of the endpoints of the
interval at a given confidence level with (1) the observed data and (2) model
assumptions. The observed point estimate (\emph{p}-value = 1) is the value
estimated to be \emph{most compatible} with the data and model assumptions,
whereas values values far from the observed point estimate (where \emph{p}
approaches 0) are least compatible with the data and model assumptions
(\emph{Schweder and Hjort 2016, pp. 60-61; Amrhein and Greenland 2022}). In this
regards, \emph{p}-values are statements about \emph{confidence} or \emph{compatibility}:
The p-value is not an absolute measure of evidence for a model (such as the
null/alternative model), it is a continuous measure of the compatibility of
the observed data with the model used to compute it (\emph{Greenland et al. 2016},
\emph{Greenland 2023}). Going one step further, and following \emph{Schweder}, p-values
can be considered as \emph{epistemic probability} - "not necessarily of the
hypothesis being true, but of it \emph{possibly} being true" (\emph{Schweder 2018}).
Hence, the interpretation of \emph{p}-values might be guided using
\code{\link[bayestestR:pd_to_p]{bayestestR::p_to_pd()}}.
}
\subsection{Probability or compatibility?}{
We here presented the discussion of p-values and confidence intervals from the
perspective of two paradigms, one saying that probability statements can be
made, one saying that interpretation is guided in terms of "compatibility".
Cox and Hinkley say, "interval estimates cannot be taken as probability
statements" (\emph{Cox and Hinkley 1979: 208}), which conflicts with the Schweder
and Hjort confidence distribution school. However, if you view interval
estimates as being intervals of values being consistent with the data,
this comes close to the idea of (epistemic) probability. We do not believe that
these two paradigms contradict or exclude each other. Rather, the aim is to
emphasize the one point of view or the other, i.e. to place the linguistic
nuances either on 'compatibility' or 'probability'.
The main take-away is \emph{not} to interpret p-values as dichotomous decisions
that distinguish between "we found an effect" (statistically significant)" vs.
"we found no effect" (statistically not significant) (\emph{Altman and Bland 1995}).
}
\subsection{Compatibility intervals - is their interpretation "conditional" or not?}{
The fact that the term "conditional" is used in different meanings in
statistics, is confusing. Thus, we would summarize the (probabilistic)
interpretation of compatibility intervals as follows: The intervals are built
from the data \emph{and} our modeling assumptions. The accuracy of the intervals
depends on our model assumptions. If a value is outside the interval, that
might be because (1) that parameter value isn't supported by the data, or (2)
the modeling assumptions are a poor fit for the situation. When we make bad
assumptions, the compatibility interval might be too wide or (more commonly
and seriously) too narrow, making us think we know more about the parameter
than is warranted.
When we say "there is a 95\% chance the true value is in the interval", that is
a statement of \emph{epistemic probability} (i.e. description of uncertainty related
to our knowledge or belief). When we talk about repeated samples or sampling
distributions, that is referring to \emph{aleatoric} (physical properties) probability.
Frequentist inference is built on defining estimators with known \emph{aleatoric}
probability properties, from which we can draw \emph{epistemic} probabilistic
statements of uncertainty (\emph{Schweder and Hjort 2016}).
}
\subsection{Functions in the parameters package to check for effect existence and significance}{
The \strong{parameters} package provides several options or functions to aid
statistical inference. Beyond \code{p_function()}, there are, for example:
\itemize{
\item \code{\link[=equivalence_test.lm]{equivalence_test()}}, to compute the (conditional)
equivalence test for frequentist models
\item \code{\link[=p_significance.lm]{p_significance()}}, to compute the probability of
\emph{practical significance}, which can be conceptualized as a unidirectional
equivalence test
\item the \code{pd} argument (setting \code{pd = TRUE}) in \code{model_parameters()} includes
a column with the \emph{probability of direction}, i.e. the probability that a
parameter is strictly positive or negative. See \code{\link[bayestestR:p_direction]{bayestestR::p_direction()}}
for details. If plotting is desired, the \code{\link[=p_direction.lm]{p_direction()}}
function can be used, together with \code{plot()}.
\item the \code{s_value} argument (setting \code{s_value = TRUE}) in \code{model_parameters()}
replaces the p-values with their related \emph{S}-values (\emph{Rafi and Greenland 2020})
\item finally, it is possible to generate distributions of model coefficients by
generating bootstrap-samples (setting \code{bootstrap = TRUE}) or simulating
draws from model coefficients using \code{\link[=simulate_model]{simulate_model()}}. These samples
can then be treated as "posterior samples" and used in many functions from
the \strong{bayestestR} package.
}
}
}
\note{
Curently, \code{p_function()} computes intervals based on Wald t- or z-statistic.
For certain models (like mixed models), profiled intervals may be more
accurate, however, this is currently not supported.
}
\examples{
\dontshow{if (requireNamespace("see")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
model <- lm(Sepal.Length ~ Species, data = iris)
p_function(model)
model <- lm(mpg ~ wt + as.factor(gear) + am, data = mtcars)
result <- p_function(model)
# single panels
plot(result, n_columns = 2)
# integrated plot, the default
plot(result)
\dontshow{\}) # examplesIf}
}
\references{
\itemize{
\item Altman DG, Bland JM. Absence of evidence is not evidence of absence. BMJ.
1995;311(7003):485. \doi{10.1136/bmj.311.7003.485}
\item Amrhein V, Greenland S. Discuss practical importance of results based on
interval estimates and p-value functions, not only on point estimates and
null p-values. Journal of Information Technology 2022;37:316–20.
\doi{10.1177/02683962221105904}
\item Cox DR, Hinkley DV. 1979. Theoretical Statistics. 6th edition.
Chapman and Hall/CRC
\item Fraser DAS. The P-value function and statistical inference. The American
Statistician. 2019;73(sup1):135-147. \doi{10.1080/00031305.2018.1556735}
\item Gelman A, Greenland S. Are confidence intervals better termed "uncertainty
intervals"? BMJ (2019)l5381. \doi{10.1136/bmj.l5381}
\item Greenland S, Rafi Z, Matthews R, Higgs M. To Aid Scientific Inference,
Emphasize Unconditional Compatibility Descriptions of Statistics. (2022)
https://arxiv.org/abs/1909.08583v7 (Accessed November 10, 2022)
\item Greenland S, Senn SJ, Rothman KJ, Carlin JB, Poole C, Goodman SN, et al.
(2016). Statistical tests, P values, confidence intervals, and power: A
guide to misinterpretations. European Journal of Epidemiology. 31:337-350.
\doi{10.1007/s10654-016-0149-3}
\item Greenland S (2023). Divergence versus decision P-values: A distinction
worth making in theory and keeping in practice: Or, how divergence P-values
measure evidence even when decision P-values do not. Scand J Statist, 50(1),
54-88.
\item Rafi Z, Greenland S. Semantic and cognitive tools to aid statistical
science: Replace confidence and significance by compatibility and surprise.
BMC Medical Research Methodology. 2020;20(1):244. \doi{10.1186/s12874-020-01105-9}
\item Schweder T. Confidence is epistemic probability for empirical science.
Journal of Statistical Planning and Inference (2018) 195:116–125.
\doi{10.1016/j.jspi.2017.09.016}
\item Schweder T, Hjort NL. Confidence and Likelihood. Scandinavian Journal of
Statistics. 2002;29(2):309-332. \doi{10.1111/1467-9469.00285}
\item Schweder T, Hjort NL. Frequentist analogues of priors and posteriors.
In Stigum, B. (ed.), Econometrics and the Philosophy of Economics: Theory
Data Confrontation in Economics, pp. 285-217. Princeton University Press,
Princeton, NJ, 2003
\item Schweder T, Hjort NL. Confidence, Likelihood, Probability: Statistical
inference with confidence distributions. Cambridge University Press, 2016.
\item Vos P, Holbert D. Frequentist statistical inference without repeated sampling.
Synthese 200, 89 (2022). \doi{10.1007/s11229-022-03560-x}
}
}
\seealso{
See also \code{\link[=equivalence_test]{equivalence_test()}} and \code{\link[=p_significance]{p_significance()}} for
functions related to checking effect existence and significance.
}
parameters/man/cluster_meta.Rd 0000644 0001762 0000144 00000005136 14502257471 016162 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cluster_meta.R
\name{cluster_meta}
\alias{cluster_meta}
\title{Metaclustering}
\usage{
cluster_meta(list_of_clusters, rownames = NULL, ...)
}
\arguments{
\item{list_of_clusters}{A list of vectors with the clustering assignments from various methods.}
\item{rownames}{An optional vector of row.names for the matrix.}
\item{...}{Currently not used.}
}
\value{
A matrix containing all the pairwise (between each observation)
probabilities of being clustered together by the methods.
}
\description{
One of the core "issue" of statistical clustering is that, in many cases,
different methods will give different results. The \strong{metaclustering} approach
proposed by \emph{easystats} (that finds echoes in \emph{consensus clustering}; see Monti
et al., 2003) consists of treating the unique clustering solutions as a ensemble,
from which we can derive a probability matrix. This matrix contains, for each
pair of observations, the probability of being in the same cluster. For instance,
if the 6th and the 9th row of a dataframe has been assigned to a similar cluster
by 5 our of 10 clustering methods, then its probability of being grouped together
is 0.5.
}
\details{
Metaclustering is based on the hypothesis that, as each clustering algorithm
embodies a different prism by which it sees the data, running an infinite
amount of algorithms would result in the emergence of the "true" clusters.
As the number of algorithms and parameters is finite, the probabilistic
perspective is a useful proxy. This method is interesting where there is no
obvious reasons to prefer one over another clustering method, as well as to
investigate how robust some clusters are under different algorithms.
This metaclustering probability matrix can be transformed into a dissimilarity
matrix (such as the one produced by \code{dist()}) and submitted for instance to
hierarchical clustering (\code{hclust()}). See the example below.
}
\examples{
\donttest{
data <- iris[1:4]
rez1 <- cluster_analysis(data, n = 2, method = "kmeans")
rez2 <- cluster_analysis(data, n = 3, method = "kmeans")
rez3 <- cluster_analysis(data, n = 6, method = "kmeans")
list_of_clusters <- list(rez1, rez2, rez3)
m <- cluster_meta(list_of_clusters)
# Visualize matrix without reordering
heatmap(m, Rowv = NA, Colv = NA, scale = "none") # Without reordering
# Reordered heatmap
heatmap(m, scale = "none")
# Extract 3 clusters
predict(m, n = 3)
# Convert to dissimilarity
d <- as.dist(abs(m - 1))
model <- hclust(d)
plot(model, hang = -1)
}
}
parameters/man/get_scores.Rd 0000644 0001762 0000144 00000003327 14331167101 015616 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/utils_pca_efa.R
\name{get_scores}
\alias{get_scores}
\title{Get Scores from Principal Component Analysis (PCA)}
\usage{
get_scores(x, n_items = NULL)
}
\arguments{
\item{x}{An object returned by \code{\link[=principal_components]{principal_components()}}.}
\item{n_items}{Number of required (i.e. non-missing) items to build the sum
score. If \code{NULL}, the value is chosen to match half of the number of
columns in a data frame.}
}
\value{
A data frame with subscales, which are average sum scores for all
items from each component.
}
\description{
\code{get_scores()} takes \code{n_items} amount of items that load the most
(either by loading cutoff or number) on a component, and then computes their
average.
}
\details{
\code{get_scores()} takes the results from \code{\link[=principal_components]{principal_components()}} and
extracts the variables for each component found by the PCA. Then, for each
of these "subscales", row means are calculated (which equals adding up the
single items and dividing by the number of items). This results in a sum
score for each component from the PCA, which is on the same scale as the
original, single items that were used to compute the PCA.
}
\examples{
if (require("psych")) {
pca <- principal_components(mtcars[, 1:7], n = 2, rotation = "varimax")
# PCA extracted two components
pca
# assignment of items to each component
closest_component(pca)
# now we want to have sum scores for each component
get_scores(pca)
# compare to manually computed sum score for 2nd component, which
# consists of items "hp" and "qsec"
(mtcars$hp + mtcars$qsec) / 2
}
}
parameters/man/dot-n_factors_bentler.Rd 0000644 0001762 0000144 00000000522 13641634603 017741 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/n_factors.R
\name{.n_factors_bentler}
\alias{.n_factors_bentler}
\title{Bentler and Yuan's Procedure}
\usage{
.n_factors_bentler(eigen_values = NULL, model = "factors", nobs = NULL)
}
\description{
Bentler and Yuan's Procedure
}
\keyword{internal}
parameters/man/n_factors.Rd 0000644 0001762 0000144 00000014136 14716604200 015442 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/n_factors.R
\name{n_factors}
\alias{n_factors}
\alias{n_components}
\title{Number of components/factors to retain in PCA/FA}
\usage{
n_factors(
x,
type = "FA",
rotation = "varimax",
algorithm = "default",
package = c("nFactors", "psych"),
cor = NULL,
safe = TRUE,
n_max = NULL,
...
)
n_components(
x,
type = "PCA",
rotation = "varimax",
algorithm = "default",
package = c("nFactors", "psych"),
cor = NULL,
safe = TRUE,
...
)
}
\arguments{
\item{x}{A data frame.}
\item{type}{Can be \code{"FA"} or \code{"PCA"}, depending on what you want to do.}
\item{rotation}{Only used for VSS (Very Simple Structure criterion, see
\code{\link[psych:VSS]{psych::VSS()}}). The rotation to apply. Can be \code{"none"}, \code{"varimax"},
\code{"quartimax"}, \code{"bentlerT"}, \code{"equamax"}, \code{"varimin"}, \code{"geominT"} and
\code{"bifactor"} for orthogonal rotations, and \code{"promax"}, \code{"oblimin"},
\code{"simplimax"}, \code{"bentlerQ"}, \code{"geominQ"}, \code{"biquartimin"} and \code{"cluster"}
for oblique transformations.}
\item{algorithm}{Factoring method used by VSS. Can be \code{"pa"} for Principal
Axis Factor Analysis, \code{"minres"} for minimum residual (OLS) factoring,
\code{"mle"} for Maximum Likelihood FA and \code{"pc"} for Principal Components.
\code{"default"} will select \code{"minres"} if \code{type = "FA"} and \code{"pc"} if
\code{type = "PCA"}.}
\item{package}{Package from which respective methods are used. Can be
\code{"all"} or a vector containing \code{"nFactors"}, \code{"psych"}, \code{"PCDimension"},
\code{"fit"} or \code{"EGAnet"}. Note that \code{"fit"} (which actually also relies on the
\code{psych} package) and \code{"EGAnet"} can be very slow for bigger datasets. Thus,
the default is \code{c("nFactors", "psych")}. You must have the respective
packages installed for the methods to be used.}
\item{cor}{An optional correlation matrix that can be used (note that the
data must still be passed as the first argument). If \code{NULL}, will
compute it by running \code{cor()} on the passed data.}
\item{safe}{If \code{TRUE}, the function will run all the procedures in try
blocks, and will only return those that work and silently skip the ones
that may fail.}
\item{n_max}{If set to a value (e.g., \code{10}), will drop from the results all
methods that suggest a higher number of components. The interpretation becomes
'from all the methods that suggested a number lower than n_max, the results
are ...'.}
\item{...}{Arguments passed to or from other methods.}
}
\value{
A data frame.
}
\description{
This function runs many existing procedures for determining how many factors
to retain/extract from factor analysis (FA) or dimension reduction (PCA). It
returns the number of factors based on the maximum consensus between methods.
In case of ties, it will keep the simplest model and select the solution
with the fewer factors.
}
\details{
\code{n_components()} is actually an alias for \code{n_factors()}, with
different defaults for the function arguments.
}
\note{
There is also a
\href{https://easystats.github.io/see/articles/parameters.html}{\code{plot()}-method}
implemented in the \href{https://easystats.github.io/see/}{\strong{see}-package}.
\code{n_components()} is a convenient short-cut for \code{n_factors(type = "PCA")}.
}
\examples{
\dontshow{if (require("PCDimension", quietly = TRUE) && require("nFactors", quietly = TRUE) && require("EGAnet", quietly = TRUE) && require("psych", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
library(parameters)
n_factors(mtcars, type = "PCA")
result <- n_factors(mtcars[1:5], type = "FA")
as.data.frame(result)
summary(result)
\donttest{
# Setting package = 'all' will increase the number of methods (but is slow)
n_factors(mtcars, type = "PCA", package = "all")
n_factors(mtcars, type = "FA", algorithm = "mle", package = "all")
}
\dontshow{\}) # examplesIf}
}
\references{
\itemize{
\item Bartlett, M. S. (1950). Tests of significance in factor analysis.
British Journal of statistical psychology, 3(2), 77-85.
\item Bentler, P. M., & Yuan, K. H. (1996). Test of linear trend in
eigenvalues of a covariance matrix with application to data analysis.
British Journal of Mathematical and Statistical Psychology, 49(2), 299-312.
\item Cattell, R. B. (1966). The scree test for the number of factors.
Multivariate behavioral research, 1(2), 245-276.
\item Finch, W. H. (2019). Using Fit Statistic Differences to Determine the
Optimal Number of Factors to Retain in an Exploratory Factor Analysis.
Educational and Psychological Measurement.
\item Zoski, K. W., & Jurs, S. (1996). An objective counterpart to the
visual scree test for factor analysis: The standard error scree.
Educational and Psychological Measurement, 56(3), 443-451.
\item Zoski, K., & Jurs, S. (1993). Using multiple regression to determine
the number of factors to retain in factor analysis. Multiple Linear
Regression Viewpoints, 20(1), 5-9.
\item Nasser, F., Benson, J., & Wisenbaker, J. (2002). The performance of
regression-based variations of the visual scree for determining the number
of common factors. Educational and psychological measurement, 62(3),
397-419.
\item Golino, H., Shi, D., Garrido, L. E., Christensen, A. P., Nieto, M.
D., Sadana, R., & Thiyagarajan, J. A. (2018). Investigating the performance
of Exploratory Graph Analysis and traditional techniques to identify the
number of latent factors: A simulation and tutorial.
\item Golino, H. F., & Epskamp, S. (2017). Exploratory graph analysis: A
new approach for estimating the number of dimensions in psychological
research. PloS one, 12(6), e0174035.
\item Revelle, W., & Rocklin, T. (1979). Very simple structure: An
alternative procedure for estimating the optimal number of interpretable
factors. Multivariate Behavioral Research, 14(4), 403-414.
\item Velicer, W. F. (1976). Determining the number of components from the
matrix of partial correlations. Psychometrika, 41(3), 321-327.
}
}
parameters/man/format_p_adjust.Rd 0000644 0001762 0000144 00000001106 13774144072 016647 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/format_p_adjust.R
\name{format_p_adjust}
\alias{format_p_adjust}
\title{Format the name of the p-value adjustment methods}
\usage{
format_p_adjust(method)
}
\arguments{
\item{method}{Name of the method.}
}
\value{
A string with the full surname(s) of the author(s), including year of publication, for the adjustment-method.
}
\description{
Format the name of the p-value adjustment methods.
}
\examples{
library(parameters)
format_p_adjust("holm")
format_p_adjust("bonferroni")
}
parameters/man/p_value_satterthwaite.Rd 0000644 0001762 0000144 00000004654 14716604200 020073 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ci_satterthwaite.R, R/dof_satterthwaite.R,
% R/p_value_satterthwaite.R, R/standard_error_satterthwaite.R
\name{ci_satterthwaite}
\alias{ci_satterthwaite}
\alias{dof_satterthwaite}
\alias{p_value_satterthwaite}
\alias{se_satterthwaite}
\title{Satterthwaite approximation for SEs, CIs and p-values}
\usage{
ci_satterthwaite(model, ci = 0.95, ...)
dof_satterthwaite(model)
p_value_satterthwaite(model, dof = NULL, ...)
se_satterthwaite(model)
}
\arguments{
\item{model}{A statistical model.}
\item{ci}{Confidence Interval (CI) level. Default to \code{0.95} (\verb{95\%}).}
\item{...}{Additional arguments passed down to the underlying functions.
E.g., arguments like \code{vcov} or \code{vcov_args} can be used to compute confidence
intervals using a specific variance-covariance matrix for the standard
errors.}
\item{dof}{Degrees of Freedom.}
}
\value{
A data frame.
}
\description{
An approximate F-test based on the Satterthwaite (1946) approach.
}
\details{
Inferential statistics (like p-values, confidence intervals and
standard errors) may be biased in mixed models when the number of clusters
is small (even if the sample size of level-1 units is high). In such cases
it is recommended to approximate a more accurate number of degrees of freedom
for such inferential statistics. Unlike simpler approximation heuristics
like the "m-l-1" rule (\code{dof_ml1}), the Satterthwaite approximation is
also applicable in more complex multilevel designs. However, the "m-l-1"
heuristic also applies to generalized mixed models, while approaches like
Kenward-Roger or Satterthwaite are limited to linear mixed models only.
}
\examples{
\donttest{
if (require("lme4", quietly = TRUE)) {
model <- lmer(Petal.Length ~ Sepal.Length + (1 | Species), data = iris)
p_value_satterthwaite(model)
}
}
}
\references{
Satterthwaite FE (1946) An approximate distribution of estimates of variance components. Biometrics Bulletin 2 (6):110–4.
}
\seealso{
\code{dof_satterthwaite()} and \code{se_satterthwaite()} are small helper-functions
to calculate approximated degrees of freedom and standard errors for model
parameters, based on the Satterthwaite (1946) approach.
\code{\link[=dof_kenward]{dof_kenward()}} and \code{\link[=dof_ml1]{dof_ml1()}} approximate degrees of freedom based on
Kenward-Roger's method or the "m-l-1" rule.
}
parameters/man/model_parameters.brmsfit.Rd 0000644 0001762 0000144 00000052164 14761570351 020470 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/methods_base.R, R/methods_brms.R
\name{model_parameters.data.frame}
\alias{model_parameters.data.frame}
\alias{model_parameters.brmsfit}
\title{Parameters from Bayesian Models}
\usage{
\method{model_parameters}{data.frame}(
model,
as_draws = FALSE,
exponentiate = FALSE,
verbose = TRUE,
...
)
\method{model_parameters}{brmsfit}(
model,
centrality = "median",
dispersion = FALSE,
ci = 0.95,
ci_method = "eti",
test = "pd",
rope_range = "default",
rope_ci = 0.95,
bf_prior = NULL,
diagnostic = c("ESS", "Rhat"),
priors = FALSE,
effects = "fixed",
component = "all",
exponentiate = FALSE,
standardize = NULL,
group_level = FALSE,
keep = NULL,
drop = NULL,
verbose = TRUE,
...
)
}
\arguments{
\item{model}{Bayesian model (including SEM from \strong{blavaan}. May also be
a data frame with posterior samples, however, \code{as_draws} must be set to
\code{TRUE} (else, for data frames \code{NULL} is returned).}
\item{as_draws}{Logical, if \code{TRUE} and \code{model} is of class \code{data.frame},
the data frame is treated as posterior samples and handled similar to
Bayesian models. All arguments in \code{...} are passed to
\code{model_parameters.draws()}.}
\item{exponentiate}{Logical, indicating whether or not to exponentiate the
coefficients (and related confidence intervals). This is typical for
logistic regression, or more generally speaking, for models with log or
logit links. It is also recommended to use \code{exponentiate = TRUE} for models
with log-transformed response values. For models with a log-transformed
response variable, when \code{exponentiate = TRUE}, a one-unit increase in the
predictor is associated with multiplying the outcome by that predictor's
coefficient. \strong{Note:} Delta-method standard errors are also computed (by
multiplying the standard errors by the transformed coefficients). This is
to mimic behaviour of other software packages, such as Stata, but these
standard errors poorly estimate uncertainty for the transformed
coefficient. The transformed confidence interval more clearly captures this
uncertainty. For \code{compare_parameters()}, \code{exponentiate = "nongaussian"}
will only exponentiate coefficients from non-Gaussian families.}
\item{verbose}{Toggle warnings and messages.}
\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:
\itemize{
\item \code{digits}, \code{p_digits}, \code{ci_digits} and \code{footer_digits} to set the number of
digits for the output. \code{groups} can be used to group coefficients. These
arguments will be passed to the print-method, or can directly be used in
\code{print()}, see documentation in \code{\link[=print.parameters_model]{print.parameters_model()}}.
\item If \code{s_value = TRUE}, the p-value will be replaced by the S-value in the
output (cf. \emph{Rafi and Greenland 2020}).
\item \code{pd} adds an additional column with the \emph{probability of direction} (see
\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}} for details). Furthermore, see 'Examples' for
this function.
\item For developers, whose 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{centrality}{The point-estimates (centrality indices) to compute. Character
(vector) or list with one or more of these options: \code{"median"}, \code{"mean"}, \code{"MAP"}
(see \code{\link[bayestestR:map_estimate]{map_estimate()}}), \code{"trimmed"} (which is just \code{mean(x, trim = threshold)}),
\code{"mode"} or \code{"all"}.}
\item{dispersion}{Logical, if \code{TRUE}, computes indices of dispersion related
to the estimate(s) (\code{SD} and \code{MAD} for \code{mean} and \code{median}, respectively).
Dispersion is not available for \code{"MAP"} or \code{"mode"} centrality indices.}
\item{ci}{Credible Interval (CI) level. Default to \code{0.95} (\verb{95\%}). See
\code{\link[bayestestR:ci]{bayestestR::ci()}} for further details.}
\item{ci_method}{Method for computing degrees of freedom for
confidence intervals (CI) and the related p-values. Allowed are following
options (which vary depending on the model class): \code{"residual"},
\code{"normal"}, \code{"likelihood"}, \code{"satterthwaite"}, \code{"kenward"}, \code{"wald"},
\code{"profile"}, \code{"boot"}, \code{"uniroot"}, \code{"ml1"}, \code{"betwithin"}, \code{"hdi"},
\code{"quantile"}, \code{"ci"}, \code{"eti"}, \code{"si"}, \code{"bci"}, or \code{"bcai"}. See section
\emph{Confidence intervals and approximation of degrees of freedom} in
\code{\link[=model_parameters]{model_parameters()}} for further details. When \code{ci_method=NULL}, in most
cases \code{"wald"} is used then.}
\item{test}{The indices of effect existence to compute. Character (vector) or
list with one or more of these options: \code{"p_direction"} (or \code{"pd"}),
\code{"rope"}, \code{"p_map"}, \code{"p_significance"} (or \code{"ps"}), \code{"p_rope"},
\code{"equivalence_test"} (or \code{"equitest"}), \code{"bayesfactor"} (or \code{"bf"}) or
\code{"all"} to compute all tests. For each "test", the corresponding
\pkg{bayestestR} function is called (e.g. \code{\link[bayestestR:rope]{rope()}} or \code{\link[bayestestR:p_direction]{p_direction()}})
and its results included in the summary output.}
\item{rope_range}{ROPE's lower and higher bounds. Should be a vector of two
values (e.g., \code{c(-0.1, 0.1)}), \code{"default"} or a list of numeric vectors of
the same length as numbers of parameters. If \code{"default"}, the bounds are
set to \code{x +- 0.1*SD(response)}.}
\item{rope_ci}{The Credible Interval (CI) probability, corresponding to the
proportion of HDI, to use for the percentage in ROPE.}
\item{bf_prior}{Distribution representing a prior for the computation of
Bayes factors / SI. Used if the input is a posterior, otherwise (in the
case of models) ignored.}
\item{diagnostic}{Diagnostic metrics to compute. Character (vector) or list
with one or more of these options: \code{"ESS"}, \code{"Rhat"}, \code{"MCSE"} or \code{"all"}.}
\item{priors}{Add the prior used for each parameter.}
\item{effects}{Should results for fixed effects, random effects or both be
returned? Only applies to mixed models. May be abbreviated.}
\item{component}{Which type of parameters to return, such as parameters for the
conditional model, the zero-inflation part of the model, the dispersion
term, or other auxiliary parameters be returned? Applies to models with
zero-inflation and/or dispersion formula, or if parameters such as \code{sigma}
should be included. May be abbreviated. Note that the \emph{conditional}
component is also called \emph{count} or \emph{mean} component, depending on the
model. There are three convenient shortcuts: \code{component = "all"} returns
all possible parameters. If \code{component = "location"}, location parameters
such as \code{conditional}, \code{zero_inflated}, or \code{smooth_terms}, are returned
(everything that are fixed or random effects - depending on the \code{effects}
argument - but no auxiliary parameters). For \code{component = "distributional"}
(or \code{"auxiliary"}), components like \code{sigma}, \code{dispersion}, or \code{beta}
(and other auxiliary parameters) are returned.}
\item{standardize}{The method used for standardizing the parameters. Can be
\code{NULL} (default; no standardization), \code{"refit"} (for re-fitting the model
on standardized data) or one of \code{"basic"}, \code{"posthoc"}, \code{"smart"},
\code{"pseudo"}. See 'Details' in \code{\link[=standardize_parameters]{standardize_parameters()}}.
\strong{Importantly}:
\itemize{
\item The \code{"refit"} method does \emph{not} standardize categorical predictors (i.e.
factors), which may be a different behaviour compared to other R packages
(such as \strong{lm.beta}) or other software packages (like SPSS). to mimic
such behaviours, either use \code{standardize="basic"} or standardize the data
with \code{datawizard::standardize(force=TRUE)} \emph{before} fitting the model.
\item For mixed models, when using methods other than \code{"refit"}, only the fixed
effects will be standardized.
\item Robust estimation (i.e., \code{vcov} set to a value other than \code{NULL}) of
standardized parameters only works when \code{standardize="refit"}.
}}
\item{group_level}{Logical, for multilevel models (i.e. models with random
effects) and when \code{effects = "all"} or \code{effects = "random"},
include the parameters for each group level from random effects. If
\code{group_level = FALSE} (the default), only information on SD and COR
are shown.}
\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
named list of regular expressions. All non-matching parameters will be
removed from the output. If \code{keep} is a character vector, every parameter
name in the \emph{"Parameter"} column that matches the regular expression in
\code{keep} will be selected from the returned data frame (and vice versa,
all parameter names matching \code{drop} will be excluded). Furthermore, if
\code{keep} has more than one element, these will be merged with an \code{OR}
operator into a regular expression pattern like this: \code{"(one|two|three)"}.
If \code{keep} is a named list of regular expression patterns, the names of the
list-element should equal the column name where selection should be
applied. This is useful for model objects where \code{model_parameters()}
returns multiple columns with parameter components, like in
\code{\link[=model_parameters.lavaan]{model_parameters.lavaan()}}. Note that the regular expression pattern
should match the parameter names as they are stored in the returned data
frame, which can be different from how they are printed. Inspect the
\verb{$Parameter} column of the parameters table to get the exact parameter
names.}
\item{drop}{See \code{keep}.}
}
\value{
A data frame of indices related to the model's parameters.
}
\description{
Model parameters from Bayesian models. This function internally calls
\code{\link[bayestestR:describe_posterior]{bayestestR::describe_posterior()}} to get the relevant information for
the output.
}
\note{
When \code{standardize = "refit"}, columns \code{diagnostic}, \code{bf_prior} and
\code{priors} refer to the \emph{original} \code{model}. If \code{model} is a data frame,
arguments \code{diagnostic}, \code{bf_prior} and \code{priors} are ignored.
There is also a
\href{https://easystats.github.io/see/articles/parameters.html}{\code{plot()}-method}
implemented in the \href{https://easystats.github.io/see/}{\strong{see}-package}.
}
\section{Confidence intervals and approximation of degrees of freedom}{
There are different ways of approximating the degrees of freedom depending
on different assumptions about the nature of the model and its sampling
distribution. The \code{ci_method} argument modulates the method for computing degrees
of freedom (df) that are used to calculate confidence intervals (CI) and the
related p-values. Following options are allowed, depending on the model
class:
\strong{Classical methods:}
Classical inference is generally based on the \strong{Wald method}.
The Wald approach to inference computes a test statistic by dividing the
parameter estimate by its standard error (Coefficient / SE),
then comparing this statistic against a t- or normal distribution.
This approach can be used to compute CIs and p-values.
\code{"wald"}:
\itemize{
\item Applies to \emph{non-Bayesian models}. For \emph{linear models}, CIs
computed using the Wald method (SE and a \emph{t-distribution with residual df});
p-values computed using the Wald method with a \emph{t-distribution with residual df}.
For other models, CIs computed using the Wald method (SE and a \emph{normal distribution});
p-values computed using the Wald method with a \emph{normal distribution}.
}
\code{"normal"}
\itemize{
\item Applies to \emph{non-Bayesian models}. Compute Wald CIs and p-values,
but always use a normal distribution.
}
\code{"residual"}
\itemize{
\item Applies to \emph{non-Bayesian models}. Compute Wald CIs and p-values,
but always use a \emph{t-distribution with residual df} when possible. If the
residual df for a model cannot be determined, a normal distribution is
used instead.
}
\strong{Methods for mixed models:}
Compared to fixed effects (or single-level) models, determining appropriate
df for Wald-based inference in mixed models is more difficult.
See \href{https://bbolker.github.io/mixedmodels-misc/glmmFAQ.html#what-are-the-p-values-listed-by-summaryglmerfit-etc.-are-they-reliable}{the R GLMM FAQ}
for a discussion.
Several approximate methods for computing df are available, but you should
also consider instead using profile likelihood (\code{"profile"}) or bootstrap ("\verb{boot"})
CIs and p-values instead.
\code{"satterthwaite"}
\itemize{
\item Applies to \emph{linear mixed models}. CIs computed using the
Wald method (SE and a \emph{t-distribution with Satterthwaite df}); p-values
computed using the Wald method with a \emph{t-distribution with Satterthwaite df}.
}
\code{"kenward"}
\itemize{
\item Applies to \emph{linear mixed models}. CIs computed using the Wald
method (\emph{Kenward-Roger SE} and a \emph{t-distribution with Kenward-Roger df});
p-values computed using the Wald method with \emph{Kenward-Roger SE and t-distribution with Kenward-Roger df}.
}
\code{"ml1"}
\itemize{
\item Applies to \emph{linear mixed models}. CIs computed using the Wald
method (SE and a \emph{t-distribution with m-l-1 approximated df}); p-values
computed using the Wald method with a \emph{t-distribution with m-l-1 approximated df}.
See \code{\link[=ci_ml1]{ci_ml1()}}.
}
\code{"betwithin"}
\itemize{
\item Applies to \emph{linear mixed models} and \emph{generalized linear mixed models}.
CIs computed using the Wald method (SE and a \emph{t-distribution with between-within df});
p-values computed using the Wald method with a \emph{t-distribution with between-within df}.
See \code{\link[=ci_betwithin]{ci_betwithin()}}.
}
\strong{Likelihood-based methods:}
Likelihood-based inference is based on comparing the likelihood for the
maximum-likelihood estimate to the the likelihood for models with one or more
parameter values changed (e.g., set to zero or a range of alternative values).
Likelihood ratios for the maximum-likelihood and alternative models are compared
to a \eqn{\chi}-squared distribution to compute CIs and p-values.
\code{"profile"}
\itemize{
\item Applies to \emph{non-Bayesian models} of class \code{glm}, \code{polr}, \code{merMod} or \code{glmmTMB}.
CIs computed by \emph{profiling the likelihood curve for a parameter}, using
linear interpolation to find where likelihood ratio equals a critical value;
p-values computed using the Wald method with a \emph{normal-distribution} (note:
this might change in a future update!)
}
\code{"uniroot"}
\itemize{
\item Applies to \emph{non-Bayesian models} of class \code{glmmTMB}. CIs
computed by \emph{profiling the likelihood curve for a parameter}, using root
finding to find where likelihood ratio equals a critical value; p-values
computed using the Wald method with a \emph{normal-distribution} (note: this
might change in a future update!)
}
\strong{Methods for bootstrapped or Bayesian models:}
Bootstrap-based inference is based on \strong{resampling} and refitting the model
to the resampled datasets. The distribution of parameter estimates across
resampled datasets is used to approximate the parameter's sampling
distribution. Depending on the type of model, several different methods for
bootstrapping and constructing CIs and p-values from the bootstrap
distribution are available.
For Bayesian models, inference is based on drawing samples from the model
posterior distribution.
\code{"quantile"} (or \code{"eti"})
\itemize{
\item Applies to \emph{all models (including Bayesian models)}.
For non-Bayesian models, only applies if \code{bootstrap = TRUE}. CIs computed
as \emph{equal tailed intervals} using the quantiles of the bootstrap or
posterior samples; p-values are based on the \emph{probability of direction}.
See \code{\link[bayestestR:eti]{bayestestR::eti()}}.
}
\code{"hdi"}
\itemize{
\item Applies to \emph{all models (including Bayesian models)}. For non-Bayesian
models, only applies if \code{bootstrap = TRUE}. CIs computed as \emph{highest density intervals}
for the bootstrap or posterior samples; p-values are based on the \emph{probability of direction}.
See \code{\link[bayestestR:hdi]{bayestestR::hdi()}}.
}
\code{"bci"} (or \code{"bcai"})
\itemize{
\item Applies to \emph{all models (including Bayesian models)}.
For non-Bayesian models, only applies if \code{bootstrap = TRUE}. CIs computed
as \emph{bias corrected and accelerated intervals} for the bootstrap or
posterior samples; p-values are based on the \emph{probability of direction}.
See \code{\link[bayestestR:bci]{bayestestR::bci()}}.
}
\code{"si"}
\itemize{
\item Applies to \emph{Bayesian models} with proper priors. CIs computed as
\emph{support intervals} comparing the posterior samples against the prior samples;
p-values are based on the \emph{probability of direction}. See \code{\link[bayestestR:si]{bayestestR::si()}}.
}
\code{"boot"}
\itemize{
\item Applies to \emph{non-Bayesian models} of class \code{merMod}. CIs computed
using \emph{parametric bootstrapping} (simulating data from the fitted model);
p-values computed using the Wald method with a \emph{normal-distribution)}
(note: this might change in a future update!).
}
For all iteration-based methods other than \code{"boot"}
(\code{"hdi"}, \code{"quantile"}, \code{"ci"}, \code{"eti"}, \code{"si"}, \code{"bci"}, \code{"bcai"}),
p-values are based on the probability of direction (\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}}),
which is converted into a p-value using \code{\link[bayestestR:pd_to_p]{bayestestR::pd_to_p()}}.
}
\section{Model components}{
Possible values for the \code{component} argument depend on the model class.
Following are valid options:
\itemize{
\item \code{"all"}: returns all model components, applies to all models, but will only
have an effect for models with more than just the conditional model component.
\item \code{"conditional"}: only returns the conditional component, i.e. "fixed effects"
terms from the model. Will only have an effect for models with more than
just the conditional model component.
\item \code{"smooth_terms"}: returns smooth terms, only applies to GAMs (or similar
models that may contain smooth terms).
\item \code{"zero_inflated"} (or \code{"zi"}): returns the zero-inflation component.
\item \code{"dispersion"}: returns the dispersion model component. This is common
for models with zero-inflation or that can model the dispersion parameter.
\item \code{"instruments"}: for instrumental-variable or some fixed effects regression,
returns the instruments.
\item \code{"nonlinear"}: for non-linear models (like models of class \code{nlmerMod} or
\code{nls}), returns staring estimates for the nonlinear parameters.
\item \code{"correlation"}: for models with correlation-component, like \code{gls}, the
variables used to describe the correlation structure are returned.
}
\strong{Special models}
Some model classes also allow rather uncommon options. These are:
\itemize{
\item \strong{mhurdle}: \code{"infrequent_purchase"}, \code{"ip"}, and \code{"auxiliary"}
\item \strong{BGGM}: \code{"correlation"} and \code{"intercept"}
\item \strong{BFBayesFactor}, \strong{glmx}: \code{"extra"}
\item \strong{averaging}:\code{"conditional"} and \code{"full"}
\item \strong{mjoint}: \code{"survival"}
\item \strong{mfx}: \code{"precision"}, \code{"marginal"}
\item \strong{betareg}, \strong{DirichletRegModel}: \code{"precision"}
\item \strong{mvord}: \code{"thresholds"} and \code{"correlation"}
\item \strong{clm2}: \code{"scale"}
\item \strong{selection}: \code{"selection"}, \code{"outcome"}, and \code{"auxiliary"}
\item \strong{lavaan}: One or more of \code{"regression"}, \code{"correlation"}, \code{"loading"},
\code{"variance"}, \code{"defined"}, or \code{"mean"}. Can also be \code{"all"} to include
all components.
}
For models of class \code{brmsfit} (package \strong{brms}), even more options are
possible for the \code{component} argument, which are not all documented in detail
here.
}
\examples{
\dontshow{if (require("rstanarm")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
\donttest{
library(parameters)
model <- suppressWarnings(stan_glm(
Sepal.Length ~ Petal.Length * Species,
data = iris, iter = 500, refresh = 0
))
model_parameters(model)
}
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[insight:standardize_names]{insight::standardize_names()}} to rename columns into a consistent,
standardized naming scheme.
}
parameters/man/random_parameters.Rd 0000644 0001762 0000144 00000005415 14331167101 017164 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/random_parameters.R
\name{random_parameters}
\alias{random_parameters}
\title{Summary information from random effects}
\usage{
random_parameters(model, component = "conditional")
}
\arguments{
\item{model}{A mixed effects model (including \code{stanreg} models).}
\item{component}{Should all parameters, parameters for the conditional model,
for the zero-inflation part of the model, or the dispersion model be returned?
Applies to models with zero-inflation and/or dispersion component. \code{component}
may be one of \code{"conditional"}, \code{"zi"}, \code{"zero-inflated"}, \code{"dispersion"} or
\code{"all"} (default). May be abbreviated.}
}
\value{
A data frame with random effects statistics for the variance components,
including number of levels per random effect group, as well as complete
observations in the model.
}
\description{
This function extracts the different variance components of a
mixed model and returns the result as a data frame.
}
\details{
The variance components are obtained from \code{\link[insight:get_variance]{insight::get_variance()}} and
are denoted as following:
\subsection{Within-group (or residual) variance}{
The residual variance, \ifelse{html}{\out{σ2ε}}{\eqn{\sigma^2_\epsilon}},
is the sum of the distribution-specific variance and the variance due to additive dispersion.
It indicates the \emph{within-group variance}.
}
\subsection{Between-group random intercept variance}{
The random intercept variance, or \emph{between-group} variance
for the intercept (\ifelse{html}{\out{τ00}}{\eqn{\tau_{00}}}),
is obtained from \code{VarCorr()}. It indicates how much groups
or subjects differ from each other.
}
\subsection{Between-group random slope variance}{
The random slope variance, or \emph{between-group} variance
for the slopes (\ifelse{html}{\out{τ11}}{\eqn{\tau_{11}}})
is obtained from \code{VarCorr()}. This measure is only available
for mixed models with random slopes. It indicates how much groups
or subjects differ from each other according to their slopes.
}
\subsection{Random slope-intercept correlation}{
The random slope-intercept correlation
(\ifelse{html}{\out{ρ01}}{\eqn{\rho_{01}}})
is obtained from \code{VarCorr()}. This measure is only available
for mixed models with random intercepts and slopes.
\strong{Note:} For the within-group and between-group variance, variance
and standard deviations (which are simply the square root of the variance)
are shown.
}
}
\examples{
if (require("lme4")) {
data(sleepstudy)
model <- lmer(Reaction ~ Days + (1 + Days | Subject), data = sleepstudy)
random_parameters(model)
}
}
parameters/man/parameters_type.Rd 0000644 0001762 0000144 00000004411 14076243300 016662 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/parameters_type.R
\name{parameters_type}
\alias{parameters_type}
\title{Type of model parameters}
\usage{
parameters_type(model, ...)
}
\arguments{
\item{model}{A statistical model.}
\item{...}{Arguments passed to or from other methods.}
}
\value{
A data frame.
}
\description{
In a regression model, the parameters do not all have the meaning. For
instance, the intercept has to be interpreted as theoretical outcome value
under some conditions (when predictors are set to 0), whereas other
coefficients are to be interpreted as amounts of change. Others, such as
interactions, represent changes in another of the parameter. The
\code{parameters_type} function attempts to retrieve information and meaning
of parameters. It outputs a dataframe of information for each parameters,
such as the \code{Type} (whether the parameter corresponds to a factor or a
numeric predictor, or whether it is a (regular) interaction or a nested
one), the \code{Link} (whether the parameter can be interpreted as a mean
value, the slope of an association or a difference between two levels) and,
in the case of interactions, which other parameters is impacted by which
parameter.
}
\examples{
library(parameters)
model <- lm(Sepal.Length ~ Petal.Length + Species, data = iris)
parameters_type(model)
model <- lm(Sepal.Length ~ Species + poly(Sepal.Width, 2), data = iris)
parameters_type(model)
model <- lm(Sepal.Length ~ Species + poly(Sepal.Width, 2, raw = TRUE), data = iris)
parameters_type(model)
# Interactions
model <- lm(Sepal.Length ~ Sepal.Width * Species, data = iris)
parameters_type(model)
model <- lm(Sepal.Length ~ Sepal.Width * Species * Petal.Length, data = iris)
parameters_type(model)
model <- lm(Sepal.Length ~ Species * Sepal.Width, data = iris)
parameters_type(model)
model <- lm(Sepal.Length ~ Species / Sepal.Width, data = iris)
parameters_type(model)
# Complex interactions
data <- iris
data$fac2 <- ifelse(data$Sepal.Width > mean(data$Sepal.Width), "A", "B")
model <- lm(Sepal.Length ~ Species / fac2 / Petal.Length, data = data)
parameters_type(model)
model <- lm(Sepal.Length ~ Species / fac2 * Petal.Length, data = data)
parameters_type(model)
}
parameters/man/p_value_ml1.Rd 0000644 0001762 0000144 00000006415 14716604200 015671 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ci_ml1.R, R/dof_ml1.R, R/p_value_ml1.R
\name{ci_ml1}
\alias{ci_ml1}
\alias{dof_ml1}
\alias{p_value_ml1}
\title{"m-l-1" approximation for SEs, CIs and p-values}
\usage{
ci_ml1(model, ci = 0.95, ...)
dof_ml1(model)
p_value_ml1(model, dof = NULL, ...)
}
\arguments{
\item{model}{A mixed model.}
\item{ci}{Confidence Interval (CI) level. Default to \code{0.95} (\verb{95\%}).}
\item{...}{Additional arguments passed down to the underlying functions.
E.g., arguments like \code{vcov} or \code{vcov_args} can be used to compute confidence
intervals using a specific variance-covariance matrix for the standard
errors.}
\item{dof}{Degrees of Freedom.}
}
\value{
A data frame.
}
\description{
Approximation of degrees of freedom based on a "m-l-1" heuristic
as suggested by Elff et al. (2019).
}
\details{
\subsection{Small Sample Cluster corrected Degrees of Freedom}{
Inferential statistics (like p-values, confidence intervals and
standard errors) may be biased in mixed models when the number of clusters
is small (even if the sample size of level-1 units is high). In such cases
it is recommended to approximate a more accurate number of degrees of freedom
for such inferential statistics (see \emph{Li and Redden 2015}). The
\emph{m-l-1} heuristic is such an approach that uses a t-distribution with
fewer degrees of freedom (\code{dof_ml1()}) to calculate p-values
(\code{p_value_ml1()}) and confidence intervals (\code{ci(method = "ml1")}).
}
\subsection{Degrees of Freedom for Longitudinal Designs (Repeated Measures)}{
In particular for repeated measure designs (longitudinal data analysis),
the \emph{m-l-1} heuristic is likely to be more accurate than simply using the
residual or infinite degrees of freedom, because \code{dof_ml1()} returns
different degrees of freedom for within-cluster and between-cluster effects.
}
\subsection{Limitations of the "m-l-1" Heuristic}{
Note that the "m-l-1" heuristic is not applicable (or at least less accurate)
for complex multilevel designs, e.g. with cross-classified clusters. In such cases,
more accurate approaches like the Kenward-Roger approximation (\code{dof_kenward()})
is recommended. However, the "m-l-1" heuristic also applies to generalized
mixed models, while approaches like Kenward-Roger or Satterthwaite are limited
to linear mixed models only.
}
}
\examples{
\donttest{
if (require("lme4")) {
model <- lmer(Petal.Length ~ Sepal.Length + (1 | Species), data = iris)
p_value_ml1(model)
}
}
}
\references{
\itemize{
\item Elff, M.; Heisig, J.P.; Schaeffer, M.; Shikano, S. (2019). Multilevel
Analysis with Few Clusters: Improving Likelihood-based Methods to Provide
Unbiased Estimates and Accurate Inference, British Journal of Political
Science.
\item Li, P., Redden, D. T. (2015). Comparing denominator degrees of freedom
approximations for the generalized linear mixed model in analyzing binary
outcome in small sample cluster-randomized trials. BMC Medical Research
Methodology, 15(1), 38. \doi{10.1186/s12874-015-0026-x}
}
}
\seealso{
\code{\link[=dof_ml1]{dof_ml1()}} is a small helper-function to calculate approximated
degrees of freedom of model parameters, based on the "m-l-1" heuristic.
}
parameters/man/select_parameters.Rd 0000644 0001762 0000144 00000004734 14716604200 017171 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/select_parameters.R
\name{select_parameters}
\alias{select_parameters}
\alias{select_parameters.lm}
\alias{select_parameters.merMod}
\title{Automated selection of model parameters}
\usage{
select_parameters(model, ...)
\method{select_parameters}{lm}(model, direction = "both", steps = 1000, k = 2, ...)
\method{select_parameters}{merMod}(model, direction = "backward", steps = 1000, ...)
}
\arguments{
\item{model}{A statistical model (of class \code{lm}, \code{glm}, or \code{merMod}).}
\item{...}{Arguments passed to or from other methods.}
\item{direction}{
the mode of stepwise search, can be one of \code{"both"},
\code{"backward"}, or \code{"forward"}, with a default of \code{"both"}.
If the \code{scope} argument is missing the default for
\code{direction} is \code{"backward"}. Values can be abbreviated.
}
\item{steps}{
the maximum number of steps to be considered. The default is 1000
(essentially as many as required). It is typically used to stop the
process early.
}
\item{k}{The multiple of the number of degrees of freedom used for the penalty.
Only \code{k = 2} gives the genuine AIC: \code{k = log(n)} is sometimes referred to as
BIC or SBC.}
}
\value{
The model refitted with optimal number of parameters.
}
\description{
This function performs an automated selection of the 'best' parameters,
updating and returning the "best" model.
}
\section{Classical lm and glm}{
For frequentist GLMs, \code{select_parameters()} performs an AIC-based stepwise
selection.
}
\section{Mixed models}{
For mixed-effects models of class \code{merMod}, stepwise selection is based on
\code{\link[cAIC4:stepcAIC]{cAIC4::stepcAIC()}}. This step function only searches the "best" model
based on the random-effects structure, i.e. \code{select_parameters()} adds or
excludes random-effects until the cAIC can't be improved further.
}
\examples{
\dontshow{if (requireNamespace("lme4")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
model <- lm(mpg ~ ., data = mtcars)
select_parameters(model)
model <- lm(mpg ~ cyl * disp * hp * wt, data = mtcars)
select_parameters(model)
\donttest{
# lme4 -------------------------------------------
model <- lme4::lmer(
Sepal.Width ~ Sepal.Length * Petal.Width * Petal.Length + (1 | Species),
data = iris
)
select_parameters(model)
}
\dontshow{\}) # examplesIf}
}
parameters/man/model_parameters.principal.Rd 0000644 0001762 0000144 00000017311 14717343001 020765 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/methods_lavaan.R, R/methods_psych.R
\name{model_parameters.lavaan}
\alias{model_parameters.lavaan}
\alias{model_parameters.principal}
\title{Parameters from PCA, FA, CFA, SEM}
\usage{
\method{model_parameters}{lavaan}(
model,
ci = 0.95,
standardize = FALSE,
component = c("regression", "correlation", "loading", "defined"),
keep = NULL,
drop = NULL,
verbose = TRUE,
...
)
\method{model_parameters}{principal}(
model,
sort = FALSE,
threshold = NULL,
labels = NULL,
verbose = TRUE,
...
)
}
\arguments{
\item{model}{Model object.}
\item{ci}{Confidence Interval (CI) level. Default to \code{0.95} (\verb{95\%}).}
\item{standardize}{Return standardized parameters (standardized coefficients).
Can be \code{TRUE} (or \code{"all"} or \code{"std.all"}) for standardized
estimates based on both the variances of observed and latent variables;
\code{"latent"} (or \code{"std.lv"}) for standardized estimates based
on the variances of the latent variables only; or \code{"no_exogenous"}
(or \code{"std.nox"}) for standardized estimates based on both the
variances of observed and latent variables, but not the variances of
exogenous covariates. See \code{lavaan::standardizedsolution} for details.}
\item{component}{What type of links to return. Can be \code{"all"} or some of
\code{c("regression", "correlation", "loading", "variance", "mean")}.}
\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
named list of regular expressions. All non-matching parameters will be
removed from the output. If \code{keep} is a character vector, every parameter
name in the \emph{"Parameter"} column that matches the regular expression in
\code{keep} will be selected from the returned data frame (and vice versa,
all parameter names matching \code{drop} will be excluded). Furthermore, if
\code{keep} has more than one element, these will be merged with an \code{OR}
operator into a regular expression pattern like this: \code{"(one|two|three)"}.
If \code{keep} is a named list of regular expression patterns, the names of the
list-element should equal the column name where selection should be
applied. This is useful for model objects where \code{model_parameters()}
returns multiple columns with parameter components, like in
\code{\link[=model_parameters.lavaan]{model_parameters.lavaan()}}. Note that the regular expression pattern
should match the parameter names as they are stored in the returned data
frame, which can be different from how they are printed. Inspect the
\verb{$Parameter} column of the parameters table to get the exact parameter
names.}
\item{drop}{See \code{keep}.}
\item{verbose}{Toggle warnings.}
\item{...}{Arguments passed to or from other methods.}
\item{sort}{Sort the loadings.}
\item{threshold}{A value between 0 and 1 indicates which (absolute) values
from the loadings should be removed. An integer higher than 1 indicates the
n strongest loadings to retain. Can also be \code{"max"}, in which case it
will only display the maximum loading per variable (the most simple
structure).}
\item{labels}{A character vector containing labels to be added to the
loadings data. Usually, the question related to the item.}
}
\value{
A data frame of indices or loadings.
}
\description{
Format structural models from the \strong{psych} or \strong{FactoMineR} packages.
}
\details{
For the structural models obtained with \strong{psych}, the following indices
are present:
\itemize{
\item \strong{Complexity} (\cite{Hoffman's, 1978; Pettersson and Turkheimer,
2010}) represents the number of latent components needed to account for
the observed variables. Whereas a perfect simple structure solution has a
complexity of 1 in that each item would only load on one factor, a
solution with evenly distributed items has a complexity greater than 1.
\item \strong{Uniqueness} represents the variance that is 'unique' to the
variable and not shared with other variables. It is equal to \verb{1 – communality} (variance that is shared with other variables). A uniqueness
of \code{0.20} suggests that \verb{20\%} or that variable's variance is not shared
with other variables in the overall factor model. The greater 'uniqueness'
the lower the relevance of the variable in the factor model.
\item \strong{MSA} represents the Kaiser-Meyer-Olkin Measure of Sampling
Adequacy (\cite{Kaiser and Rice, 1974}) for each item. It indicates
whether there is enough data for each factor give reliable results for the
PCA. The value should be > 0.6, and desirable values are > 0.8
(\cite{Tabachnick and Fidell, 2013}).
}
}
\note{
There is also a
\href{https://easystats.github.io/see/articles/parameters.html}{\code{plot()}-method}
for \code{lavaan} models implemented in the
\href{https://easystats.github.io/see/}{\strong{see}-package}.
}
\examples{
\donttest{
library(parameters)
if (require("psych", quietly = TRUE)) {
# Principal Component Analysis (PCA) ---------
pca <- psych::principal(attitude)
model_parameters(pca)
pca <- psych::principal(attitude, nfactors = 3, rotate = "none")
model_parameters(pca, sort = TRUE, threshold = 0.2)
principal_components(attitude, n = 3, sort = TRUE, threshold = 0.2)
# Exploratory Factor Analysis (EFA) ---------
efa <- psych::fa(attitude, nfactors = 3)
model_parameters(efa,
threshold = "max", sort = TRUE,
labels = as.character(1:ncol(attitude))
)
# Omega ---------
omega <- psych::omega(mtcars, nfactors = 3)
params <- model_parameters(omega)
params
summary(params)
}
}
# lavaan
library(parameters)
# lavaan -------------------------------------
if (require("lavaan", quietly = TRUE)) {
# Confirmatory Factor Analysis (CFA) ---------
structure <- " visual =~ x1 + x2 + x3
textual =~ x4 + x5 + x6
speed =~ x7 + x8 + x9 "
model <- lavaan::cfa(structure, data = HolzingerSwineford1939)
model_parameters(model)
model_parameters(model, standardize = TRUE)
# filter parameters
model_parameters(
model,
parameters = list(
To = "^(?!visual)",
From = "^(?!(x7|x8))"
)
)
# Structural Equation Model (SEM) ------------
structure <- "
# latent variable definitions
ind60 =~ x1 + x2 + x3
dem60 =~ y1 + a*y2 + b*y3 + c*y4
dem65 =~ y5 + a*y6 + b*y7 + c*y8
# regressions
dem60 ~ ind60
dem65 ~ ind60 + dem60
# residual correlations
y1 ~~ y5
y2 ~~ y4 + y6
y3 ~~ y7
y4 ~~ y8
y6 ~~ y8
"
model <- lavaan::sem(structure, data = PoliticalDemocracy)
model_parameters(model)
model_parameters(model, standardize = TRUE)
}
}
\references{
\itemize{
\item Kaiser, H.F. and Rice. J. (1974). Little jiffy, mark iv. Educational and
Psychological Measurement, 34(1):111–117
\item Pettersson, E., and Turkheimer, E. (2010). Item selection, evaluation, and
simple structure in personality data. Journal of research in personality,
44(4), 407-420.
\item Revelle, W. (2016). How To: Use the psych package for Factor Analysis and
data reduction.
\item Tabachnick, B. G., and Fidell, L. S. (2013). Using multivariate statistics
(6th ed.). Boston: Pearson Education.
\item Rosseel Y (2012). lavaan: An R Package for Structural Equation
Modeling. Journal of Statistical Software, 48(2), 1-36.
\item Merkle EC , Rosseel Y (2018). blavaan: Bayesian Structural Equation
Models via Parameter Expansion. Journal of Statistical Software, 85(4),
1-30. http://www.jstatsoft.org/v85/i04/
}
}
parameters/man/model_parameters.aov.Rd 0000644 0001762 0000144 00000022372 14717111737 017605 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/methods_aov.R
\name{model_parameters.aov}
\alias{model_parameters.aov}
\title{Parameters from ANOVAs}
\usage{
\method{model_parameters}{aov}(
model,
type = NULL,
df_error = NULL,
ci = NULL,
alternative = NULL,
test = NULL,
power = FALSE,
es_type = NULL,
keep = NULL,
drop = NULL,
table_wide = FALSE,
verbose = TRUE,
...
)
}
\arguments{
\item{model}{Object of class \code{\link[=aov]{aov()}}, \code{\link[=anova]{anova()}},
\code{aovlist}, \code{Gam}, \code{\link[=manova]{manova()}}, \code{Anova.mlm},
\code{afex_aov} or \code{maov}.}
\item{type}{Numeric, type of sums of squares. May be 1, 2 or 3. If 2 or 3,
ANOVA-tables using \code{car::Anova()} will be returned. (Ignored for
\code{afex_aov}.)}
\item{df_error}{Denominator degrees of freedom (or degrees of freedom of the
error estimate, i.e., the residuals). This is used to compute effect sizes
for ANOVA-tables from mixed models. See 'Examples'. (Ignored for
\code{afex_aov}.)}
\item{ci}{Confidence Interval (CI) level for effect sizes specified in
\code{es_type}. The default, \code{NULL}, will compute no confidence
intervals. \code{ci} should be a scalar between 0 and 1.}
\item{alternative}{A character string specifying the alternative hypothesis;
Controls the type of CI returned: \code{"two.sided"} (default, two-sided CI),
\code{"greater"} or \code{"less"} (one-sided CI). Partial matching is allowed
(e.g., \code{"g"}, \code{"l"}, \code{"two"}...). See section \emph{One-Sided CIs} in
the \href{https://easystats.github.io/effectsize/}{effectsize_CIs vignette}.}
\item{test}{String, indicating the type of test for \code{Anova.mlm} to be
returned. If \code{"multivariate"} (or \code{NULL}), returns the summary of
the multivariate test (that is also given by the \code{print}-method). If
\code{test = "univariate"}, returns the summary of the univariate test.}
\item{power}{Logical, if \code{TRUE}, adds a column with power for each
parameter.}
\item{es_type}{The effect size of interest. Not that possibly not all
effect sizes are applicable to the model object. See 'Details'. For Anova
models, can also be a character vector with multiple effect size names.}
\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
named list of regular expressions. All non-matching parameters will be
removed from the output. If \code{keep} is a character vector, every parameter
name in the \emph{"Parameter"} column that matches the regular expression in
\code{keep} will be selected from the returned data frame (and vice versa,
all parameter names matching \code{drop} will be excluded). Furthermore, if
\code{keep} has more than one element, these will be merged with an \code{OR}
operator into a regular expression pattern like this: \code{"(one|two|three)"}.
If \code{keep} is a named list of regular expression patterns, the names of the
list-element should equal the column name where selection should be
applied. This is useful for model objects where \code{model_parameters()}
returns multiple columns with parameter components, like in
\code{\link[=model_parameters.lavaan]{model_parameters.lavaan()}}. Note that the regular expression pattern
should match the parameter names as they are stored in the returned data
frame, which can be different from how they are printed. Inspect the
\verb{$Parameter} column of the parameters table to get the exact parameter
names.}
\item{drop}{See \code{keep}.}
\item{table_wide}{Logical that decides whether the ANOVA table should be in
wide format, i.e. should the numerator and denominator degrees of freedom
be in the same row. Default: \code{FALSE}.}
\item{verbose}{Toggle warnings and messages.}
\item{...}{Arguments passed to \code{\link[effectsize:effectsize]{effectsize::effectsize()}}. For example,
to calculate \emph{partial} effect sizes types, use \code{partial = TRUE}. For objects
of class \code{htest} or \code{BFBayesFactor}, \code{adjust = TRUE} can be used to return
bias-corrected effect sizes, which is advisable for small samples and large
tables. See also
\href{https://easystats.github.io/effectsize/reference/eta_squared.html}{\code{?effectsize::eta_squared}}
for arguments \code{partial} and \code{generalized};
\href{https://easystats.github.io/effectsize/reference/phi.html}{\code{?effectsize::phi}}
for \code{adjust}; and
\href{https://easystats.github.io/effectsize/reference/oddsratio.html}{\code{?effectsize::oddratio}}
for \code{log}.}
}
\value{
A data frame of indices related to the model's parameters.
}
\description{
Parameters from ANOVAs
}
\details{
\itemize{
\item For an object of class \code{htest}, data is extracted via \code{\link[insight:get_data]{insight::get_data()}}, and passed to the relevant function according to:
\itemize{
\item A \strong{t-test} depending on \code{type}: \code{"cohens_d"} (default), \code{"hedges_g"}, or one of \code{"p_superiority"}, \code{"u1"}, \code{"u2"}, \code{"u3"}, \code{"overlap"}.
\itemize{
\item For a \strong{Paired t-test}: depending on \code{type}: \code{"rm_rm"}, \code{"rm_av"}, \code{"rm_b"}, \code{"rm_d"}, \code{"rm_z"}.
}
\item A \strong{Chi-squared tests of independence} or \strong{Fisher's Exact Test}, depending on \code{type}: \code{"cramers_v"} (default), \code{"tschuprows_t"}, \code{"phi"}, \code{"cohens_w"}, \code{"pearsons_c"}, \code{"cohens_h"}, \code{"oddsratio"}, \code{"riskratio"}, \code{"arr"}, or \code{"nnt"}.
\item A \strong{Chi-squared tests of goodness-of-fit}, depending on \code{type}: \code{"fei"} (default) \code{"cohens_w"}, \code{"pearsons_c"}
\item A \strong{One-way ANOVA test}, depending on \code{type}: \code{"eta"} (default), \code{"omega"} or \code{"epsilon"} -squared, \code{"f"}, or \code{"f2"}.
\item A \strong{McNemar test} returns \emph{Cohen's g}.
\item A \strong{Wilcoxon test} depending on \code{type}: returns "\code{rank_biserial}" correlation (default) or one of \code{"p_superiority"}, \code{"vda"}, \code{"u2"}, \code{"u3"}, \code{"overlap"}.
\item A \strong{Kruskal-Wallis test} depending on \code{type}: \code{"epsilon"} (default) or \code{"eta"}.
\item A \strong{Friedman test} returns \emph{Kendall's W}.
(Where applicable, \code{ci} and \code{alternative} are taken from the \code{htest} if not otherwise provided.)
}
\item For an object of class \code{BFBayesFactor}, using \code{\link[bayestestR:describe_posterior]{bayestestR::describe_posterior()}},
\itemize{
\item A \strong{t-test} depending on \code{type}: \code{"cohens_d"} (default) or one of \code{"p_superiority"}, \code{"u1"}, \code{"u2"}, \code{"u3"}, \code{"overlap"}.
\item A \strong{correlation test} returns \emph{r}.
\item A \strong{contingency table test}, depending on \code{type}: \code{"cramers_v"} (default), \code{"phi"}, \code{"tschuprows_t"}, \code{"cohens_w"}, \code{"pearsons_c"}, \code{"cohens_h"}, \code{"oddsratio"}, or \code{"riskratio"}, \code{"arr"}, or \code{"nnt"}.
\item A \strong{proportion test} returns \emph{p}.
}
\item Objects of class \code{anova}, \code{aov}, \code{aovlist} or \code{afex_aov}, depending on \code{type}: \code{"eta"} (default), \code{"omega"} or \code{"epsilon"} -squared, \code{"f"}, or \code{"f2"}.
\item Other objects are passed to \code{\link[parameters:standardize_parameters]{parameters::standardize_parameters()}}.
}
\strong{For statistical models it is recommended to directly use the listed
functions, for the full range of options they provide.}
}
\note{
For ANOVA-tables from mixed models (i.e. \code{anova(lmer())}), only
partial or adjusted effect sizes can be computed. Note that type 3 ANOVAs
with interactions involved only give sensible and informative results when
covariates are mean-centred and factors are coded with orthogonal contrasts
(such as those produced by \code{contr.sum}, \code{contr.poly}, or
\code{contr.helmert}, but \emph{not} by the default \code{contr.treatment}).
}
\examples{
\dontshow{if (requireNamespace("effectsize", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
df <- iris
df$Sepal.Big <- ifelse(df$Sepal.Width >= 3, "Yes", "No")
model <- aov(Sepal.Length ~ Sepal.Big, data = df)
model_parameters(model)
model_parameters(model, es_type = c("omega", "eta"), ci = 0.9)
model <- anova(lm(Sepal.Length ~ Sepal.Big, data = df))
model_parameters(model)
model_parameters(
model,
es_type = c("omega", "eta", "epsilon"),
alternative = "greater"
)
model <- aov(Sepal.Length ~ Sepal.Big + Error(Species), data = df)
model_parameters(model)
\dontshow{\}) # examplesIf}
\dontshow{if (requireNamespace("lme4", quietly = TRUE) && requireNamespace("effectsize", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
\donttest{
df <- iris
df$Sepal.Big <- ifelse(df$Sepal.Width >= 3, "Yes", "No")
mm <- lme4::lmer(Sepal.Length ~ Sepal.Big + Petal.Width + (1 | Species), data = df)
model <- anova(mm)
# simple parameters table
model_parameters(model)
# parameters table including effect sizes
model_parameters(
model,
es_type = "eta",
ci = 0.9,
df_error = dof_satterthwaite(mm)[2:3]
)
}
\dontshow{\}) # examplesIf}
}
parameters/man/print.compare_parameters.Rd 0000644 0001762 0000144 00000030670 14751367303 020502 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/format.R, R/print.compare_parameters.R,
% R/print_html.R, R/print_md.R
\name{format.compare_parameters}
\alias{format.compare_parameters}
\alias{print.compare_parameters}
\alias{print_html.compare_parameters}
\alias{print_md.compare_parameters}
\title{Print comparisons of model parameters}
\usage{
\method{format}{compare_parameters}(
x,
split_components = TRUE,
select = NULL,
digits = 2,
ci_digits = digits,
p_digits = 3,
ci_width = NULL,
ci_brackets = NULL,
zap_small = FALSE,
format = NULL,
groups = NULL,
engine = NULL,
...
)
\method{print}{compare_parameters}(
x,
split_components = TRUE,
caption = NULL,
subtitle = NULL,
footer = NULL,
digits = 2,
ci_digits = digits,
p_digits = 3,
zap_small = FALSE,
groups = NULL,
column_width = NULL,
ci_brackets = c("[", "]"),
select = NULL,
...
)
\method{print_html}{compare_parameters}(
x,
caption = NULL,
subtitle = NULL,
footer = NULL,
digits = 2,
ci_digits = digits,
p_digits = 3,
zap_small = FALSE,
groups = NULL,
select = NULL,
ci_brackets = c("(", ")"),
font_size = "100\%",
line_padding = 4,
column_labels = NULL,
engine = "gt",
...
)
\method{print_md}{compare_parameters}(
x,
digits = 2,
ci_digits = digits,
p_digits = 3,
caption = NULL,
subtitle = NULL,
footer = NULL,
select = NULL,
split_components = TRUE,
ci_brackets = c("(", ")"),
zap_small = FALSE,
groups = NULL,
engine = "tt",
...
)
}
\arguments{
\item{x}{An object returned by \code{\link[=compare_parameters]{compare_parameters()}}.}
\item{split_components}{Logical, if \code{TRUE} (default), For models with
multiple components (zero-inflation, smooth terms, ...), each component is
printed in a separate table. If \code{FALSE}, model parameters are printed
in a single table and a \code{Component} column is added to the output.}
\item{select}{Determines which columns and and which layout columns are
printed. There are three options for this argument:
\itemize{
\item \strong{Selecting columns by name or index}
\code{select} can be a character vector (or numeric index) of column names that
should be printed, where columns are extracted from the data frame returned
by \code{model_parameters()} and related functions.
There are two pre-defined options for selecting columns:
\code{select = "minimal"} prints coefficients, confidence intervals and
p-values, while \code{select = "short"} prints coefficients, standard errors and
p-values.
\item \strong{A string expression with layout pattern}
\code{select} is a string with "tokens" enclosed in braces. These tokens will be
replaced by their associated columns, where the selected columns will be
collapsed into one column. Following tokens are replaced by the related
coefficients or statistics: \code{{estimate}}, \code{{se}}, \code{{ci}} (or \code{{ci_low}} and
\code{{ci_high}}), \code{{p}} and \code{{stars}}. The token \code{{ci}} will be replaced by
\verb{\{ci_low\}, \{ci_high\}}. Example: \code{select = "{estimate}{stars} ({ci})"}
It is possible to create multiple columns as well. A \code{|} separates values
into new cells/columns. Example: \code{select = "{estimate} ({ci})|{p}"}.
If \code{format = "html"}, a \verb{
} inserts a line break inside a cell. See
'Examples'.
\item \strong{A string indicating a pre-defined layout}
\code{select} can be one of the following string values, to create one of the
following pre-defined column layouts:
\itemize{
\item \code{"ci"}: Estimates and confidence intervals, no asterisks for p-values.
This is equivalent to \code{select = "{estimate} ({ci})"}.
\item \code{"se"}: Estimates and standard errors, no asterisks for p-values. This is
equivalent to \code{select = "{estimate} ({se})"}.
\item \code{"ci_p"}: Estimates, confidence intervals and asterisks for p-values. This
is equivalent to \code{select = "{estimate}{stars} ({ci})"}.
\item \code{"se_p"}: Estimates, standard errors and asterisks for p-values. This is
equivalent to \code{select = "{estimate}{stars} ({se})"}..
\item \code{"ci_p2"}: Estimates, confidence intervals and numeric p-values, in two
columns. This is equivalent to \code{select = "{estimate} ({ci})|{p}"}.
\item \code{"se_p2"}: Estimate, standard errors and numeric p-values, in two columns.
This is equivalent to \code{select = "{estimate} ({se})|{p}"}.
}
}
For \code{model_parameters()}, glue-like syntax is still experimental in the
case of more complex models (like mixed models) and may not return expected
results.}
\item{digits, ci_digits, p_digits}{Number of digits for rounding or
significant figures. May also be \code{"signif"} to return significant
figures or \code{"scientific"} to return scientific notation. Control the
number of digits by adding the value as suffix, e.g. \code{digits = "scientific4"}
to have scientific notation with 4 decimal places, or \code{digits = "signif5"}
for 5 significant figures (see also \code{\link[=signif]{signif()}}).}
\item{ci_width}{Minimum width of the returned string for confidence
intervals. If not \code{NULL} and width is larger than the string's length,
leading whitespaces are added to the string. If \code{width="auto"}, width
will be set to the length of the longest string.}
\item{ci_brackets}{Logical, if \code{TRUE} (default), CI-values are
encompassed in square brackets (else in parentheses).}
\item{zap_small}{Logical, if \code{TRUE}, small values are rounded after
\code{digits} decimal places. If \code{FALSE}, values with more decimal
places than \code{digits} are printed in scientific notation.}
\item{format}{String, indicating the output format. Can be \code{"markdown"}
or \code{"html"}.}
\item{groups}{Named list, can be used to group parameters in the printed output.
List elements may either be character vectors that match the name of those
parameters that belong to one group, or list elements can be row numbers
of those parameter rows that should belong to one group. The names of the
list elements will be used as group names, which will be inserted as "header
row". A possible use case might be to emphasize focal predictors and control
variables, see 'Examples'. Parameters will be re-ordered according to the
order used in \code{groups}, while all non-matching parameters will be added
to the end.}
\item{engine}{Character string, naming the package or engine to be used for
printing into HTML or markdown format. Currently supported \code{"gt"} (or
\code{"default"}) to use the \emph{gt} package to print to HTML and the default easystats
engine to create markdown tables. If \code{engine = "tt"}, the \emph{tinytable} package
is used for printing to HTML or markdown. Not all \code{print()} methods support
the \code{"tt"} engine yet. If a specific \code{print()} method has no \code{engine} argument,
\code{insight::export_table()} is used, which uses \emph{gt} for HTML printing.}
\item{...}{Arguments passed down to \code{\link[=format.parameters_model]{format.parameters_model()}},
\code{\link[insight:format_table]{insight::format_table()}} and \code{\link[insight:export_table]{insight::export_table()}}}
\item{caption}{Table caption as string. If \code{NULL}, depending on the model,
either a default caption or no table caption is printed. Use \code{caption = ""}
to suppress the table caption.}
\item{subtitle}{Table title (same as caption) and subtitle, as strings. If \code{NULL},
no title or subtitle is printed, unless it is stored as attributes (\code{table_title},
or its alias \code{table_caption}, and \code{table_subtitle}). If \code{x} is a list of
data frames, \code{caption} may be a list of table captions, one for each table.}
\item{footer}{Can either be \code{FALSE} or an empty string (i.e. \code{""}) to
suppress the footer, \code{NULL} to print the default footer, or a string. The
latter will combine the string value with the default footer.}
\item{column_width}{Width of table columns. Can be either \code{NULL}, a named
numeric vector, or \code{"fixed"}. If \code{NULL}, the width for each table column is
adjusted to the minimum required width. If a named numeric vector, value
names are matched against column names, and for each match, the specified
width is used. If \code{"fixed"}, and table is split into multiple components,
columns across all table components are adjusted to have the same width.}
\item{font_size}{For HTML tables, the font size.}
\item{line_padding}{For HTML tables, the distance (in pixel) between lines.}
\item{column_labels}{Labels of columns for HTML tables. If \code{NULL}, automatic
column names are generated. See 'Examples'.}
}
\value{
Invisibly returns the original input object.
}
\description{
A \code{print()}-method for objects from \code{\link[=compare_parameters]{compare_parameters()}}.
}
\section{Global Options to Customize Messages and Tables when Printing}{
The \code{verbose} argument can be used to display or silence messages and
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_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
printing \code{model_parameters()} objects.
\item \code{parameters_exponentiate}: \code{options(parameters_exponentiate = TRUE)} will
show the additional information on how to interpret coefficients of models
with log-transformed response variables or with log-/logit-links when the
\code{exponentiate} argument in \code{model_parameters()} is not \code{TRUE}. Set this option
to \code{FALSE} to hide this message when printing \code{model_parameters()} objects.
}
There are further options that can be used to modify the default behaviour
for printed outputs:
\itemize{
\item \code{parameters_labels}: \code{options(parameters_labels = TRUE)} will use variable
and value labels for pretty names, if data is labelled. If no labels
available, default pretty names are used.
\item \code{parameters_interaction}: \verb{options(parameters_interaction =
({se})|{p}")
print_html(result)
}
\dontshow{\}) # examplesIf}
}
parameters/man/dot-n_factors_sescree.Rd 0000644 0001762 0000144 00000000615 13641634603 017742 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/n_factors.R
\name{.n_factors_sescree}
\alias{.n_factors_sescree}
\title{Standard Error Scree and Coefficient of Determination Procedures}
\usage{
.n_factors_sescree(eigen_values = NULL, model = "factors")
}
\description{
Standard Error Scree and Coefficient of Determination Procedures
}
\keyword{internal}
parameters/man/equivalence_test.lm.Rd 0000644 0001762 0000144 00000042365 14761600443 017445 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/equivalence_test.R
\name{equivalence_test.lm}
\alias{equivalence_test.lm}
\alias{equivalence_test.ggeffects}
\title{Equivalence test}
\usage{
\method{equivalence_test}{lm}(
x,
range = "default",
ci = 0.95,
rule = "classic",
effects = "fixed",
vcov = NULL,
vcov_args = NULL,
verbose = TRUE,
...
)
\method{equivalence_test}{ggeffects}(
x,
range = "default",
rule = "classic",
test = "pairwise",
verbose = TRUE,
...
)
}
\arguments{
\item{x}{A statistical model.}
\item{range}{The range of practical equivalence of an effect. May be
\code{"default"}, to automatically define this range based on properties of the
model's data.}
\item{ci}{Confidence Interval (CI) level. Default to \code{0.95} (\verb{95\%}).}
\item{rule}{Character, indicating the rules when testing for practical
equivalence. Can be \code{"bayes"}, \code{"classic"} or \code{"cet"}. See 'Details'.}
\item{effects}{Should parameters for fixed effects (\code{"fixed"}), random
effects (\code{"random"}), both fixed and random effects (\code{"all"}), or the
overall (sum of fixed and random) effects (\code{"random_total"}) be returned?
Only applies to mixed models. May be abbreviated. If the calculation of
random effects parameters takes too long, you may use \code{effects = "fixed"}.}
\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{"HC"}, \code{"HC0"}, \code{"HC1"}, \code{"HC2"},
\code{"HC3"}, \code{"HC4"}, \code{"HC4m"}, \code{"HC5"}. See \code{?sandwich::vcovHC}
\item Cluster-robust: \code{"CR"}, \code{"CR0"}, \code{"CR1"}, \code{"CR1p"}, \code{"CR1S"},
\code{"CR2"}, \code{"CR3"}. See \code{?clubSandwich::vcovCR}
\item Bootstrap: \code{"BS"}, \code{"xy"}, \code{"residual"}, \code{"wild"}, \code{"mammen"},
\code{"fractional"}, \code{"jackknife"}, \code{"norm"}, \code{"webb"}. See
\code{?sandwich::vcovBS}
\item Other \code{sandwich} package functions: \code{"HAC"}, \code{"PC"}, \code{"CL"}, \code{"OPG"},
\code{"PL"}.
}
}}
\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. If no estimation type (argument \code{type}) is given, the default
type for \code{"HC"} equals the default from the \strong{sandwich} package; for type
\code{"CR"}, the default is set to \code{"CR3"}.}
\item{verbose}{Toggle warnings and messages.}
\item{...}{Arguments passed to or from other methods.}
\item{test}{Hypothesis test for computing contrasts or pairwise comparisons.
See \href{https://strengejacke.github.io/ggeffects/reference/test_predictions.html}{\code{?ggeffects::test_predictions}}
for details.}
}
\value{
A data frame.
}
\description{
Compute the (conditional) equivalence test for frequentist models.
}
\details{
In classical null hypothesis significance testing (NHST) within a
frequentist framework, it is not possible to accept the null hypothesis, H0 -
unlike in Bayesian statistics, where such probability statements are
possible. "\link{...} one can only reject the null hypothesis if the test
statistics falls into the critical region(s), or fail to reject this
hypothesis. In the latter case, all we can say is that no significant effect
was observed, but one cannot conclude that the null hypothesis is true."
(\emph{Pernet 2017}). One way to address this issues without Bayesian methods is
\emph{Equivalence Testing}, as implemented in \code{equivalence_test()}. While you
either can reject the null hypothesis or claim an inconclusive result in
NHST, the equivalence test - according to \emph{Pernet} - adds a third category,
\emph{"accept"}. Roughly speaking, the idea behind equivalence testing in a
frequentist framework is to check whether an estimate and its uncertainty
(i.e. confidence interval) falls within a region of "practical equivalence".
Depending on the rule for this test (see below), statistical significance
does not necessarily indicate whether the null hypothesis can be rejected or
not, i.e. the classical interpretation of the p-value may differ from the
results returned from the equivalence test.
\subsection{Calculation of equivalence testing}{
\itemize{
\item "bayes" - Bayesian rule (Kruschke 2018)
This rule follows the "HDI+ROPE decision rule" (\emph{Kruschke, 2014, 2018}) used
for the \code{\link[bayestestR:equivalence_test]{Bayesian counterpart()}}. This
means, if the confidence intervals are completely outside the ROPE, the
"null hypothesis" for this parameter is "rejected". If the ROPE
completely covers the CI, the null hypothesis is accepted. Else, it's
undecided whether to accept or reject the null hypothesis. Desirable
results are low proportions inside the ROPE (the closer to zero the
better).
\item "classic" - The TOST rule (Lakens 2017)
This rule follows the "TOST rule", i.e. a two one-sided test procedure
(\emph{Lakens 2017}). Following this rule...
\itemize{
\item practical equivalence is assumed (i.e. H0 \emph{"accepted"}) when the narrow
confidence intervals are completely inside the ROPE, no matter if the
effect is statistically significant or not;
\item practical equivalence (i.e. H0) is \emph{rejected}, when the coefficient is
statistically significant, both when the narrow confidence intervals
(i.e. \code{1-2*alpha}) include or exclude the the ROPE boundaries, but the
narrow confidence intervals are \emph{not fully covered} by the ROPE;
\item else the decision whether to accept or reject practical equivalence is
undecided (i.e. when effects are \emph{not} statistically significant \emph{and}
the narrow confidence intervals overlaps the ROPE).
}
\item "cet" - Conditional Equivalence Testing (Campbell/Gustafson 2018)
The Conditional Equivalence Testing as described by \emph{Campbell and
Gustafson 2018}. According to this rule, practical equivalence is
rejected when the coefficient is statistically significant. When the
effect is \emph{not} significant and the narrow confidence intervals are
completely inside the ROPE, we accept (i.e. assume) practical equivalence,
else it is undecided.
}
}
\subsection{Levels of Confidence Intervals used for Equivalence Testing}{
For \code{rule = "classic"}, "narrow" confidence intervals are used for
equivalence testing. "Narrow" means, the the intervals is not 1 - alpha,
but 1 - 2 * alpha. Thus, if \code{ci = .95}, alpha is assumed to be 0.05
and internally a ci-level of 0.90 is used. \code{rule = "cet"} uses
both regular and narrow confidence intervals, while \code{rule = "bayes"}
only uses the regular intervals.
}
\subsection{p-Values}{
The equivalence p-value is the area of the (cumulative) confidence
distribution that is outside of the region of equivalence. It can be
interpreted as p-value for \emph{rejecting} the alternative hypothesis and
\emph{accepting} the "null hypothesis" (i.e. assuming practical equivalence). That
is, a high p-value means we reject the assumption of practical equivalence
and accept the alternative hypothesis.
}
\subsection{Second Generation p-Value (SGPV)}{
Second generation p-values (SGPV) were proposed as a statistic that
represents \emph{the proportion of data-supported hypotheses that are also null
hypotheses} \emph{(Blume et al. 2018, Lakens and Delacre 2020)}. It represents the
proportion of the \emph{full} confidence interval range (assuming a normally or
t-distributed, equal-tailed interval, based on the model) that is inside the
ROPE. The SGPV ranges from zero to one. Higher values indicate that the
effect is more likely to be practically equivalent ("not of interest").
Note that the assumed interval, which is used to calculate the SGPV, is an
estimation of the \emph{full interval} based on the chosen confidence level. For
example, if the 95\% confidence interval of a coefficient ranges from -1 to 1,
the underlying \emph{full (normally or t-distributed) interval} approximately
ranges from -1.9 to 1.9, see also following code:
\if{html}{\out{
} inserts a line break inside a cell. See
'Examples'.
\item \strong{A string indicating a pre-defined layout}
\code{select} can be one of the following string values, to create one of the
following pre-defined column layouts:
\itemize{
\item \code{"ci"}: Estimates and confidence intervals, no asterisks for p-values.
This is equivalent to \code{select = "{estimate} ({ci})"}.
\item \code{"se"}: Estimates and standard errors, no asterisks for p-values. This is
equivalent to \code{select = "{estimate} ({se})"}.
\item \code{"ci_p"}: Estimates, confidence intervals and asterisks for p-values. This
is equivalent to \code{select = "{estimate}{stars} ({ci})"}.
\item \code{"se_p"}: Estimates, standard errors and asterisks for p-values. This is
equivalent to \code{select = "{estimate}{stars} ({se})"}..
\item \code{"ci_p2"}: Estimates, confidence intervals and numeric p-values, in two
columns. This is equivalent to \code{select = "{estimate} ({ci})|{p}"}.
\item \code{"se_p2"}: Estimate, standard errors and numeric p-values, in two columns.
This is equivalent to \code{select = "{estimate} ({se})|{p}"}.
}
}
For \code{model_parameters()}, glue-like syntax is still experimental in the
case of more complex models (like mixed models) and may not return expected
results.}
\item{column_names}{Character vector with strings that should be used as
column headers. Must be of same length as number of models in \code{...}.}
\item{pretty_names}{Can be \code{TRUE}, which will return "pretty" (i.e. more human
readable) parameter names. Or \code{"labels"}, in which case value and variable
labels will be used as parameters names. The latter only works for "labelled"
data, i.e. if the data used to fit the model had \code{"label"} and \code{"labels"}
attributes. See also section \emph{Global Options to Customize Messages when Printing}.}
\item{coefficient_names}{Character vector with strings that should be used
as column headers for the coefficient column. Must be of same length as
number of models in \code{...}, or length 1. If length 1, this name will be
used for all coefficient columns. If \code{NULL}, the name for the coefficient
column will detected automatically (as in \code{model_parameters()}).}
\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
named list of regular expressions. All non-matching parameters will be
removed from the output. If \code{keep} is a character vector, every parameter
name in the \emph{"Parameter"} column that matches the regular expression in
\code{keep} will be selected from the returned data frame (and vice versa,
all parameter names matching \code{drop} will be excluded). Furthermore, if
\code{keep} has more than one element, these will be merged with an \code{OR}
operator into a regular expression pattern like this: \code{"(one|two|three)"}.
If \code{keep} is a named list of regular expression patterns, the names of the
list-element should equal the column name where selection should be
applied. This is useful for model objects where \code{model_parameters()}
returns multiple columns with parameter components, like in
\code{\link[=model_parameters.lavaan]{model_parameters.lavaan()}}. Note that the regular expression pattern
should match the parameter names as they are stored in the returned data
frame, which can be different from how they are printed. Inspect the
\verb{$Parameter} column of the parameters table to get the exact parameter
names.}
\item{drop}{See \code{keep}.}
\item{include_reference}{Logical, if \code{TRUE}, the reference level of factors will
be added to the parameters table. This is only relevant for models with
categorical predictors. The coefficient for the reference level is always
\code{0} (except when \code{exponentiate = TRUE}, then the coefficient will be \code{1}),
so this is just for completeness.}
\item{groups}{Named list, can be used to group parameters in the printed output.
List elements may either be character vectors that match the name of those
parameters that belong to one group, or list elements can be row numbers
of those parameter rows that should belong to one group. The names of the
list elements will be used as group names, which will be inserted as "header
row". A possible use case might be to emphasize focal predictors and control
variables, see 'Examples'. Parameters will be re-ordered according to the
order used in \code{groups}, while all non-matching parameters will be added
to the end.}
\item{verbose}{Toggle warnings and messages.}
}
\value{
A data frame of indices related to the model's parameters.
}
\description{
Compute and extract model parameters of multiple regression
models. See \code{\link[=model_parameters]{model_parameters()}} for further details.
}
\details{
This function is in an early stage and does not yet cope with more complex
models, and probably does not yet properly render all model components. It
should also be noted that when including models with interaction terms, not
only do the values of the parameters change, but so does their meaning (from
main effects, to simple slopes), thereby making such comparisons hard.
Therefore, you should not use this function to compare models with
interaction terms with models without interaction terms.
}
\examples{
\dontshow{if (require("gt", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
data(iris)
lm1 <- lm(Sepal.Length ~ Species, data = iris)
lm2 <- lm(Sepal.Length ~ Species + Petal.Length, data = iris)
compare_parameters(lm1, lm2)
# custom style
compare_parameters(lm1, lm2, select = "{estimate}{stars} ({se})")
\donttest{
# custom style, in HTML
result <- compare_parameters(lm1, lm2, select = "{estimate}
({se})|{p}")
print_html(result)
}
data(mtcars)
m1 <- lm(mpg ~ wt, data = mtcars)
m2 <- glm(vs ~ wt + cyl, data = mtcars, family = "binomial")
compare_parameters(m1, m2)
\donttest{
# exponentiate coefficients, but not for lm
compare_parameters(m1, m2, exponentiate = "nongaussian")
# change column names
compare_parameters("linear model" = m1, "logistic reg." = m2)
compare_parameters(m1, m2, column_names = c("linear model", "logistic reg."))
# or as list
compare_parameters(list(m1, m2))
compare_parameters(list("linear model" = m1, "logistic reg." = m2))
}
\dontshow{\}) # examplesIf}
}
parameters/man/format_parameters.Rd 0000644 0001762 0000144 00000004430 14716604200 017173 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/format_parameters.R
\name{format_parameters}
\alias{format_parameters}
\alias{format_parameters.default}
\title{Parameter names formatting}
\usage{
format_parameters(model, ...)
\method{format_parameters}{default}(model, brackets = c("[", "]"), ...)
}
\arguments{
\item{model}{A statistical model.}
\item{...}{Currently not used.}
\item{brackets}{A character vector of length two, indicating the opening and closing brackets.}
}
\value{
A (names) character vector with formatted parameter names. The value
names refer to the original names of the coefficients.
}
\description{
This functions formats the names of model parameters (coefficients)
to make them more human-readable.
}
\section{Interpretation of Interaction Terms}{
Note that the \emph{interpretation} of interaction terms depends on many
characteristics of the model. The number of parameters, and overall
performance of the model, can differ \emph{or not} between \code{a * b},
\code{a : b}, and \code{a / b}, suggesting that sometimes interaction terms
give different parameterizations of the same model, but other times it gives
completely different models (depending on \code{a} or \code{b} being factors
of covariates, included as main effects or not, etc.). Their interpretation
depends of the full context of the model, which should not be inferred
from the parameters table alone - rather, we recommend to use packages
that calculate estimated marginal means or marginal effects, such as
\CRANpkg{modelbased}, \CRANpkg{emmeans}, \CRANpkg{ggeffects}, or
\CRANpkg{marginaleffects}. To raise awareness for this issue, you may use
\code{print(...,show_formula=TRUE)} to add the model-specification to the output
of the \code{\link[=print.parameters_model]{print()}} method for \code{model_parameters()}.
}
\examples{
model <- lm(Sepal.Length ~ Species * Sepal.Width, data = iris)
format_parameters(model)
model <- lm(Sepal.Length ~ Petal.Length + (Species / Sepal.Width), data = iris)
format_parameters(model)
model <- lm(Sepal.Length ~ Species + poly(Sepal.Width, 2), data = iris)
format_parameters(model)
model <- lm(Sepal.Length ~ Species + poly(Sepal.Width, 2, raw = TRUE), data = iris)
format_parameters(model)
}
parameters/man/convert_efa_to_cfa.Rd 0000644 0001762 0000144 00000003345 14502257471 017301 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/convert_efa_to_cfa.R
\name{convert_efa_to_cfa}
\alias{convert_efa_to_cfa}
\alias{convert_efa_to_cfa.fa}
\alias{efa_to_cfa}
\title{Conversion between EFA results and CFA structure}
\usage{
convert_efa_to_cfa(model, ...)
\method{convert_efa_to_cfa}{fa}(
model,
threshold = "max",
names = NULL,
max_per_dimension = NULL,
...
)
efa_to_cfa(model, ...)
}
\arguments{
\item{model}{An EFA model (e.g., a \code{psych::fa} object).}
\item{...}{Arguments passed to or from other methods.}
\item{threshold}{A value between 0 and 1 indicates which (absolute) values
from the loadings should be removed. An integer higher than 1 indicates the
n strongest loadings to retain. Can also be \code{"max"}, in which case it
will only display the maximum loading per variable (the most simple
structure).}
\item{names}{Vector containing dimension names.}
\item{max_per_dimension}{Maximum number of variables to keep per dimension.}
}
\value{
Converted index.
}
\description{
Enables a conversion between Exploratory Factor Analysis (EFA) and
Confirmatory Factor Analysis (CFA) \code{lavaan}-ready structure.
}
\examples{
\dontshow{if (require("psych") && require("lavaan")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
\donttest{
library(parameters)
data(attitude)
efa <- psych::fa(attitude, nfactors = 3)
model1 <- efa_to_cfa(efa)
model2 <- efa_to_cfa(efa, threshold = 0.3)
model3 <- efa_to_cfa(efa, max_per_dimension = 2)
suppressWarnings(anova(
lavaan::cfa(model1, data = attitude),
lavaan::cfa(model2, data = attitude),
lavaan::cfa(model3, data = attitude)
))
}
\dontshow{\}) # examplesIf}
}
parameters/man/reshape_loadings.Rd 0000644 0001762 0000144 00000002343 14246070503 016771 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reshape_loadings.R
\name{reshape_loadings}
\alias{reshape_loadings}
\alias{reshape_loadings.parameters_efa}
\alias{reshape_loadings.data.frame}
\title{Reshape loadings between wide/long formats}
\usage{
reshape_loadings(x, ...)
\method{reshape_loadings}{parameters_efa}(x, threshold = NULL, ...)
\method{reshape_loadings}{data.frame}(x, threshold = NULL, loadings_columns = NULL, ...)
}
\arguments{
\item{x}{A data frame or a statistical model.}
\item{...}{Arguments passed to or from other methods.}
\item{threshold}{A value between 0 and 1 indicates which (absolute) values
from the loadings should be removed. An integer higher than 1 indicates the
n strongest loadings to retain. Can also be \code{"max"}, in which case it
will only display the maximum loading per variable (the most simple
structure).}
\item{loadings_columns}{Vector indicating the columns corresponding to loadings.}
}
\description{
Reshape loadings between wide/long formats.
}
\examples{
if (require("psych")) {
pca <- model_parameters(psych::fa(attitude, nfactors = 3))
loadings <- reshape_loadings(pca)
loadings
reshape_loadings(loadings)
}
}
parameters/man/p_value.Rd 0000644 0001762 0000144 00000034627 14717115325 015134 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/3_p_value.R, R/methods_emmeans.R
\name{p_value}
\alias{p_value}
\alias{p_value.default}
\alias{p_value.emmGrid}
\title{p-values}
\usage{
p_value(model, ...)
\method{p_value}{default}(
model,
dof = NULL,
method = NULL,
component = "all",
vcov = NULL,
vcov_args = NULL,
verbose = TRUE,
...
)
\method{p_value}{emmGrid}(model, ci = 0.95, adjust = "none", ...)
}
\arguments{
\item{model}{A statistical model.}
\item{...}{Additional arguments}
\item{dof}{Number of degrees of freedom to be used when calculating
confidence intervals. If \code{NULL} (default), the degrees of freedom are
retrieved by calling \code{\link[insight:get_df]{insight::get_df()}} with approximation method defined
in \code{method}. If not \code{NULL}, use this argument to override the default degrees
of freedom used to compute confidence intervals.}
\item{method}{Method for computing degrees of freedom for confidence
intervals (CI) and the related p-values. Allowed are following options (which
vary depending on the model class): \code{"residual"}, \code{"normal"}, \code{"likelihood"},
\code{"satterthwaite"}, \code{"kenward"}, \code{"wald"}, \code{"profile"}, \code{"boot"}, \code{"uniroot"},
\code{"ml1"}, \code{"betwithin"}, \code{"hdi"}, \code{"quantile"}, \code{"ci"}, \code{"eti"}, \code{"si"},
\code{"bci"}, or \code{"bcai"}. See section \emph{Confidence intervals and approximation of
degrees of freedom} in \code{\link[=model_parameters]{model_parameters()}} for further details.}
\item{component}{Model component for which parameters should be shown. See
the documentation for your object's class in \code{\link[=model_parameters]{model_parameters()}} or
\code{\link[=p_value]{p_value()}} for further details, or see section \emph{Model components}.}
\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{"HC"}, \code{"HC0"}, \code{"HC1"}, \code{"HC2"},
\code{"HC3"}, \code{"HC4"}, \code{"HC4m"}, \code{"HC5"}. See \code{?sandwich::vcovHC}
\item Cluster-robust: \code{"CR"}, \code{"CR0"}, \code{"CR1"}, \code{"CR1p"}, \code{"CR1S"},
\code{"CR2"}, \code{"CR3"}. See \code{?clubSandwich::vcovCR}
\item Bootstrap: \code{"BS"}, \code{"xy"}, \code{"residual"}, \code{"wild"}, \code{"mammen"},
\code{"fractional"}, \code{"jackknife"}, \code{"norm"}, \code{"webb"}. See
\code{?sandwich::vcovBS}
\item Other \code{sandwich} package functions: \code{"HAC"}, \code{"PC"}, \code{"CL"}, \code{"OPG"},
\code{"PL"}.
}
}}
\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. If no estimation type (argument \code{type}) is given, the default
type for \code{"HC"} equals the default from the \strong{sandwich} package; for type
\code{"CR"}, the default is set to \code{"CR3"}.}
\item{verbose}{Toggle warnings and messages.}
\item{ci}{Confidence Interval (CI) level. Default to \code{0.95} (\verb{95\%}).}
\item{adjust}{Character value naming the method used to adjust p-values or
confidence intervals. See \code{?emmeans::summary.emmGrid} for details.}
}
\value{
A data frame with at least two columns: the parameter names and the
p-values. Depending on the model, may also include columns for model
components etc.
}
\description{
This function attempts to return, or compute, p-values of a model's
parameters.
}
\details{
For Bayesian models, the p-values corresponds to the \emph{probability of
direction} (\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}}), which is converted to a p-value
using \code{bayestestR::convert_pd_to_p()}.
}
\section{Confidence intervals and approximation of degrees of freedom}{
There are different ways of approximating the degrees of freedom depending
on different assumptions about the nature of the model and its sampling
distribution. The \code{ci_method} argument modulates the method for computing degrees
of freedom (df) that are used to calculate confidence intervals (CI) and the
related p-values. Following options are allowed, depending on the model
class:
\strong{Classical methods:}
Classical inference is generally based on the \strong{Wald method}.
The Wald approach to inference computes a test statistic by dividing the
parameter estimate by its standard error (Coefficient / SE),
then comparing this statistic against a t- or normal distribution.
This approach can be used to compute CIs and p-values.
\code{"wald"}:
\itemize{
\item Applies to \emph{non-Bayesian models}. For \emph{linear models}, CIs
computed using the Wald method (SE and a \emph{t-distribution with residual df});
p-values computed using the Wald method with a \emph{t-distribution with residual df}.
For other models, CIs computed using the Wald method (SE and a \emph{normal distribution});
p-values computed using the Wald method with a \emph{normal distribution}.
}
\code{"normal"}
\itemize{
\item Applies to \emph{non-Bayesian models}. Compute Wald CIs and p-values,
but always use a normal distribution.
}
\code{"residual"}
\itemize{
\item Applies to \emph{non-Bayesian models}. Compute Wald CIs and p-values,
but always use a \emph{t-distribution with residual df} when possible. If the
residual df for a model cannot be determined, a normal distribution is
used instead.
}
\strong{Methods for mixed models:}
Compared to fixed effects (or single-level) models, determining appropriate
df for Wald-based inference in mixed models is more difficult.
See \href{https://bbolker.github.io/mixedmodels-misc/glmmFAQ.html#what-are-the-p-values-listed-by-summaryglmerfit-etc.-are-they-reliable}{the R GLMM FAQ}
for a discussion.
Several approximate methods for computing df are available, but you should
also consider instead using profile likelihood (\code{"profile"}) or bootstrap ("\verb{boot"})
CIs and p-values instead.
\code{"satterthwaite"}
\itemize{
\item Applies to \emph{linear mixed models}. CIs computed using the
Wald method (SE and a \emph{t-distribution with Satterthwaite df}); p-values
computed using the Wald method with a \emph{t-distribution with Satterthwaite df}.
}
\code{"kenward"}
\itemize{
\item Applies to \emph{linear mixed models}. CIs computed using the Wald
method (\emph{Kenward-Roger SE} and a \emph{t-distribution with Kenward-Roger df});
p-values computed using the Wald method with \emph{Kenward-Roger SE and t-distribution with Kenward-Roger df}.
}
\code{"ml1"}
\itemize{
\item Applies to \emph{linear mixed models}. CIs computed using the Wald
method (SE and a \emph{t-distribution with m-l-1 approximated df}); p-values
computed using the Wald method with a \emph{t-distribution with m-l-1 approximated df}.
See \code{\link[=ci_ml1]{ci_ml1()}}.
}
\code{"betwithin"}
\itemize{
\item Applies to \emph{linear mixed models} and \emph{generalized linear mixed models}.
CIs computed using the Wald method (SE and a \emph{t-distribution with between-within df});
p-values computed using the Wald method with a \emph{t-distribution with between-within df}.
See \code{\link[=ci_betwithin]{ci_betwithin()}}.
}
\strong{Likelihood-based methods:}
Likelihood-based inference is based on comparing the likelihood for the
maximum-likelihood estimate to the the likelihood for models with one or more
parameter values changed (e.g., set to zero or a range of alternative values).
Likelihood ratios for the maximum-likelihood and alternative models are compared
to a \eqn{\chi}-squared distribution to compute CIs and p-values.
\code{"profile"}
\itemize{
\item Applies to \emph{non-Bayesian models} of class \code{glm}, \code{polr}, \code{merMod} or \code{glmmTMB}.
CIs computed by \emph{profiling the likelihood curve for a parameter}, using
linear interpolation to find where likelihood ratio equals a critical value;
p-values computed using the Wald method with a \emph{normal-distribution} (note:
this might change in a future update!)
}
\code{"uniroot"}
\itemize{
\item Applies to \emph{non-Bayesian models} of class \code{glmmTMB}. CIs
computed by \emph{profiling the likelihood curve for a parameter}, using root
finding to find where likelihood ratio equals a critical value; p-values
computed using the Wald method with a \emph{normal-distribution} (note: this
might change in a future update!)
}
\strong{Methods for bootstrapped or Bayesian models:}
Bootstrap-based inference is based on \strong{resampling} and refitting the model
to the resampled datasets. The distribution of parameter estimates across
resampled datasets is used to approximate the parameter's sampling
distribution. Depending on the type of model, several different methods for
bootstrapping and constructing CIs and p-values from the bootstrap
distribution are available.
For Bayesian models, inference is based on drawing samples from the model
posterior distribution.
\code{"quantile"} (or \code{"eti"})
\itemize{
\item Applies to \emph{all models (including Bayesian models)}.
For non-Bayesian models, only applies if \code{bootstrap = TRUE}. CIs computed
as \emph{equal tailed intervals} using the quantiles of the bootstrap or
posterior samples; p-values are based on the \emph{probability of direction}.
See \code{\link[bayestestR:eti]{bayestestR::eti()}}.
}
\code{"hdi"}
\itemize{
\item Applies to \emph{all models (including Bayesian models)}. For non-Bayesian
models, only applies if \code{bootstrap = TRUE}. CIs computed as \emph{highest density intervals}
for the bootstrap or posterior samples; p-values are based on the \emph{probability of direction}.
See \code{\link[bayestestR:hdi]{bayestestR::hdi()}}.
}
\code{"bci"} (or \code{"bcai"})
\itemize{
\item Applies to \emph{all models (including Bayesian models)}.
For non-Bayesian models, only applies if \code{bootstrap = TRUE}. CIs computed
as \emph{bias corrected and accelerated intervals} for the bootstrap or
posterior samples; p-values are based on the \emph{probability of direction}.
See \code{\link[bayestestR:bci]{bayestestR::bci()}}.
}
\code{"si"}
\itemize{
\item Applies to \emph{Bayesian models} with proper priors. CIs computed as
\emph{support intervals} comparing the posterior samples against the prior samples;
p-values are based on the \emph{probability of direction}. See \code{\link[bayestestR:si]{bayestestR::si()}}.
}
\code{"boot"}
\itemize{
\item Applies to \emph{non-Bayesian models} of class \code{merMod}. CIs computed
using \emph{parametric bootstrapping} (simulating data from the fitted model);
p-values computed using the Wald method with a \emph{normal-distribution)}
(note: this might change in a future update!).
}
For all iteration-based methods other than \code{"boot"}
(\code{"hdi"}, \code{"quantile"}, \code{"ci"}, \code{"eti"}, \code{"si"}, \code{"bci"}, \code{"bcai"}),
p-values are based on the probability of direction (\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}}),
which is converted into a p-value using \code{\link[bayestestR:pd_to_p]{bayestestR::pd_to_p()}}.
}
\section{Model components}{
Possible values for the \code{component} argument depend on the model class.
Following are valid options:
\itemize{
\item \code{"all"}: returns all model components, applies to all models, but will only
have an effect for models with more than just the conditional model component.
\item \code{"conditional"}: only returns the conditional component, i.e. "fixed effects"
terms from the model. Will only have an effect for models with more than
just the conditional model component.
\item \code{"smooth_terms"}: returns smooth terms, only applies to GAMs (or similar
models that may contain smooth terms).
\item \code{"zero_inflated"} (or \code{"zi"}): returns the zero-inflation component.
\item \code{"dispersion"}: returns the dispersion model component. This is common
for models with zero-inflation or that can model the dispersion parameter.
\item \code{"instruments"}: for instrumental-variable or some fixed effects regression,
returns the instruments.
\item \code{"nonlinear"}: for non-linear models (like models of class \code{nlmerMod} or
\code{nls}), returns staring estimates for the nonlinear parameters.
\item \code{"correlation"}: for models with correlation-component, like \code{gls}, the
variables used to describe the correlation structure are returned.
}
\strong{Special models}
Some model classes also allow rather uncommon options. These are:
\itemize{
\item \strong{mhurdle}: \code{"infrequent_purchase"}, \code{"ip"}, and \code{"auxiliary"}
\item \strong{BGGM}: \code{"correlation"} and \code{"intercept"}
\item \strong{BFBayesFactor}, \strong{glmx}: \code{"extra"}
\item \strong{averaging}:\code{"conditional"} and \code{"full"}
\item \strong{mjoint}: \code{"survival"}
\item \strong{mfx}: \code{"precision"}, \code{"marginal"}
\item \strong{betareg}, \strong{DirichletRegModel}: \code{"precision"}
\item \strong{mvord}: \code{"thresholds"} and \code{"correlation"}
\item \strong{clm2}: \code{"scale"}
\item \strong{selection}: \code{"selection"}, \code{"outcome"}, and \code{"auxiliary"}
\item \strong{lavaan}: One or more of \code{"regression"}, \code{"correlation"}, \code{"loading"},
\code{"variance"}, \code{"defined"}, or \code{"mean"}. Can also be \code{"all"} to include
all components.
}
For models of class \code{brmsfit} (package \strong{brms}), even more options are
possible for the \code{component} argument, which are not all documented in detail
here.
}
\examples{
\dontshow{if (require("pscl", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
data(iris)
model <- lm(Petal.Length ~ Sepal.Length + Species, data = iris)
p_value(model)
data("bioChemists", package = "pscl")
model <- pscl::zeroinfl(
art ~ fem + mar + kid5 | kid5 + phd,
data = bioChemists
)
p_value(model)
p_value(model, component = "zi")
\dontshow{\}) # examplesIf}
}
parameters/man/standardize_parameters.Rd 0000644 0001762 0000144 00000026677 14716604200 020234 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/standardize_parameters.R,
% R/standardize_posteriors.R
\name{standardize_parameters}
\alias{standardize_parameters}
\alias{standardise_parameters}
\alias{standardize_posteriors}
\alias{standardise_posteriors}
\title{Parameters standardization}
\usage{
standardize_parameters(
model,
method = "refit",
ci = 0.95,
robust = FALSE,
two_sd = FALSE,
include_response = TRUE,
verbose = TRUE,
...
)
standardize_posteriors(
model,
method = "refit",
robust = FALSE,
two_sd = FALSE,
include_response = TRUE,
verbose = TRUE,
...
)
}
\arguments{
\item{model}{A statistical model.}
\item{method}{The method used for standardizing the parameters. Can be
\code{"refit"} (default), \code{"posthoc"}, \code{"smart"}, \code{"basic"}, \code{"pseudo"} or
\code{"sdy"}. See Details'.}
\item{ci}{Confidence Interval (CI) level}
\item{robust}{Logical, if \code{TRUE}, centering is done by subtracting the
median from the variables and dividing it by the median absolute deviation
(MAD). If \code{FALSE}, variables are standardized by subtracting the
mean and dividing it by the standard deviation (SD).}
\item{two_sd}{If \code{TRUE}, the variables are scaled by two times the deviation
(SD or MAD depending on \code{robust}). This method can be useful to obtain
model coefficients of continuous parameters comparable to coefficients
related to binary predictors, when applied to \strong{the predictors} (not the
outcome) (Gelman, 2008).}
\item{include_response}{If \code{TRUE} (default), the response value will also be
standardized. If \code{FALSE}, only the predictors will be standardized. For
GLMs the response value will never be standardized (see \emph{Generalized Linear
Models} section).}
\item{verbose}{Toggle warnings and messages on or off.}
\item{...}{For \code{standardize_parameters()}, arguments passed to
\code{\link[=model_parameters]{model_parameters()}}, such as:
\itemize{
\item \code{ci_method}, \code{centrality} for Mixed models and Bayesian models...
\item \code{exponentiate}, ...
\item etc.
}}
}
\value{
A data frame with the standardized parameters (\verb{Std_*}, depending on
the model type) and their CIs (\code{CI_low} and \code{CI_high}). Where applicable,
standard errors (SEs) are returned as an attribute (\code{attr(x, "standard_error")}).
}
\description{
Compute standardized model parameters (coefficients).
}
\details{
\subsection{Standardization Methods}{
\itemize{
\item \strong{refit}: This method is based on a complete model re-fit with a
standardized version of the data. Hence, this method is equal to
standardizing the variables before fitting the model. It is the "purest" and
the most accurate (Neter et al., 1989), but it is also the most
computationally costly and long (especially for heavy models such as Bayesian
models). This method is particularly recommended for complex models that
include interactions or transformations (e.g., polynomial or spline terms).
The \code{robust} (default to \code{FALSE}) argument enables a robust standardization
of data, i.e., based on the \code{median} and \code{MAD} instead of the \code{mean} and
\code{SD}. \strong{See \code{\link[datawizard:standardize]{datawizard::standardize()}} for more details.}
\itemize{
\item \strong{Note} that \code{standardize_parameters(method = "refit")} may not return
the same results as fitting a model on data that has been standardized with
\code{standardize()}; \code{standardize_parameters()} used the data used by the model
fitting function, which might not be same data if there are missing values.
see the \code{remove_na} argument in \code{standardize()}.
}
\item \strong{posthoc}: Post-hoc standardization of the parameters, aiming at
emulating the results obtained by "refit" without refitting the model. The
coefficients are divided by the standard deviation (or MAD if \code{robust}) of
the outcome (which becomes their expression 'unit'). Then, the coefficients
related to numeric variables are additionally multiplied by the standard
deviation (or MAD if \code{robust}) of the related terms, so that they correspond
to changes of 1 SD of the predictor (e.g., "A change in 1 SD of \code{x} is
related to a change of 0.24 of the SD of \code{y}). This does not apply to binary
variables or factors, so the coefficients are still related to changes in
levels. This method is not accurate and tend to give aberrant results when
interactions are specified.
\item \strong{basic}: This method is similar to \code{method = "posthoc"}, but treats all
variables as continuous: it also scales the coefficient by the standard
deviation of model's matrix' parameter of factors levels (transformed to
integers) or binary predictors. Although being inappropriate for these cases,
this method is the one implemented by default in other software packages,
such as \code{\link[lm.beta:lm.beta]{lm.beta::lm.beta()}}.
\item \strong{smart} (Standardization of Model's parameters with Adjustment,
Reconnaissance and Transformation - \emph{experimental}): Similar to \code{method = "posthoc"} in that it does not involve model refitting. The difference is
that the SD (or MAD if \code{robust}) of the response is computed on the relevant
section of the data. For instance, if a factor with 3 levels A (the
intercept), B and C is entered as a predictor, the effect corresponding to B
vs. A will be scaled by the variance of the response at the intercept only.
As a results, the coefficients for effects of factors are similar to a Glass'
delta.
\item \strong{pseudo} (\emph{for 2-level (G)LMMs only}): In this (post-hoc) method, the
response and the predictor are standardized based on the level of prediction
(levels are detected with \code{\link[performance:check_heterogeneity_bias]{performance::check_heterogeneity_bias()}}): Predictors
are standardized based on their SD at level of prediction (see also
\code{\link[datawizard:demean]{datawizard::demean()}}); The outcome (in linear LMMs) is standardized based
on a fitted random-intercept-model, where \code{sqrt(random-intercept-variance)}
is used for level 2 predictors, and \code{sqrt(residual-variance)} is used for
level 1 predictors (Hoffman 2015, page 342). A warning is given when a
within-group variable is found to have access between-group variance.
\item \strong{sdy} (\emph{for logistic regression models only}): This y-standardization
is useful when comparing coefficients of logistic regression models across
models for the same sample. Unobserved heterogeneity varies across models
with different independent variables, and thus, odds ratios from the same
predictor of different models cannot be compared directly. The
y-standardization makes coefficients "comparable across models by dividing
them with the estimated standard deviation of the latent variable for each
model" (Mood 2010). Thus, whenever one has multiple logistic regression models
that are fit to the same data and share certain predictors (e.g. nested
models), it can be useful to use this standardization approach to make
log-odds or odds ratios comparable.
}
}
\subsection{Transformed Variables}{
When the model's formula contains transformations (e.g. \code{y ~ exp(X)}) \code{method = "refit"} will give different results compared to \code{method = "basic"}
(\code{"posthoc"} and \code{"smart"} do not support such transformations): While
\code{"refit"} standardizes the data \emph{prior} to the transformation (e.g.
equivalent to \code{exp(scale(X))}), the \code{"basic"} method standardizes the
transformed data (e.g. equivalent to \code{scale(exp(X))}).
\cr\cr
See the \emph{Transformed Variables} section in \code{\link[datawizard:standardize.default]{datawizard::standardize.default()}}
for more details on how different transformations are dealt with when
\code{method = "refit"}.
}
\subsection{Confidence Intervals}{
The returned confidence intervals are re-scaled versions of the
unstandardized confidence intervals, and not "true" confidence intervals of
the standardized coefficients (cf. Jones & Waller, 2015).
}
\subsection{Generalized Linear Models}{
Standardization for generalized linear models (GLM, GLMM, etc) is done only
with respect to the predictors (while the outcome remains as-is,
unstandardized) - maintaining the interpretability of the coefficients (e.g.,
in a binomial model: the exponent of the standardized parameter is the OR of
a change of 1 SD in the predictor, etc.)
}
\subsection{Dealing with Factors}{
\code{standardize(model)} or \code{standardize_parameters(model, method = "refit")} do
\emph{not} standardize categorical predictors (i.e. factors) / their
dummy-variables, which may be a different behaviour compared to other R
packages (such as \pkg{lm.beta}) or other software packages (like SPSS). To
mimic such behaviours, either use \code{standardize_parameters(model, method = "basic")} to obtain post-hoc standardized parameters, or standardize the data
with \code{datawizard::standardize(data, force = TRUE)} \emph{before} fitting the
model.
}
}
\examples{
model <- lm(len ~ supp * dose, data = ToothGrowth)
standardize_parameters(model, method = "refit")
\donttest{
standardize_parameters(model, method = "posthoc")
standardize_parameters(model, method = "smart")
standardize_parameters(model, method = "basic")
# Robust and 2 SD
standardize_parameters(model, robust = TRUE)
standardize_parameters(model, two_sd = TRUE)
model <- glm(am ~ cyl * mpg, data = mtcars, family = "binomial")
standardize_parameters(model, method = "refit")
standardize_parameters(model, method = "posthoc")
standardize_parameters(model, method = "basic", exponentiate = TRUE)
}
\dontshow{if (require("lme4", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
\donttest{
m <- lme4::lmer(mpg ~ cyl + am + vs + (1 | cyl), mtcars)
standardize_parameters(m, method = "pseudo", ci_method = "satterthwaite")
}
\dontshow{\}) # examplesIf}
\dontshow{if (require("rstanarm", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
\donttest{
model <- rstanarm::stan_glm(rating ~ critical + privileges, data = attitude, refresh = 0)
standardize_posteriors(model, method = "refit", verbose = FALSE)
standardize_posteriors(model, method = "posthoc", verbose = FALSE)
standardize_posteriors(model, method = "smart", verbose = FALSE)
head(standardize_posteriors(model, method = "basic", verbose = FALSE))
}
\dontshow{\}) # examplesIf}
}
\references{
\itemize{
\item Hoffman, L. (2015). Longitudinal analysis: Modeling within-person fluctuation
and change. Routledge.
\item Jones, J. A., & Waller, N. G. (2015). The normal-theory and asymptotic
distribution-free (ADF) covariance matrix of standardized regression
coefficients: theoretical extensions and finite sample behavior.
Psychometrika, 80(2), 365-378.
\item Neter, J., Wasserman, W., & Kutner, M. H. (1989). Applied linear
regression models.
\item Gelman, A. (2008). Scaling regression inputs by dividing by two standard
deviations. Statistics in medicine, 27(15), 2865-2873.
\item Mood C. Logistic Regression: Why We Cannot Do What We Think We Can Do, and
What We Can Do About It. European Sociological Review (2010) 26:67–82.
}
}
\seealso{
See also \href{https://easystats.github.io/parameters/articles/standardize_parameters_effsize.html}{package vignette}.
Other standardize:
\code{\link{standardize_info}()}
}
\concept{effect size indices}
\concept{standardize}
parameters/man/sort_parameters.Rd 0000644 0001762 0000144 00000002324 14227755134 016704 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sort_parameters.R
\name{sort_parameters}
\alias{sort_parameters}
\alias{sort_parameters.default}
\title{Sort parameters by coefficient values}
\usage{
sort_parameters(x, ...)
\method{sort_parameters}{default}(x, sort = "none", column = "Coefficient", ...)
}
\arguments{
\item{x}{A data frame or a \code{parameters_model} object.}
\item{...}{Arguments passed to or from other methods.}
\item{sort}{If \code{"none"} (default) do not sort, \code{"ascending"} sort by
increasing coefficient value, or \code{"descending"} sort by decreasing
coefficient value.}
\item{column}{The column containing model parameter estimates. This will be
\code{"Coefficient"} (default) in \emph{easystats} packages, \code{"estimate"} in \emph{broom}
package, etc.}
}
\value{
A sorted data frame or original object.
}
\description{
Sort parameters by coefficient values
}
\examples{
# creating object to sort (can also be a regular data frame)
mod <- model_parameters(stats::lm(wt ~ am * cyl, data = mtcars))
# original output
mod
# sorted outputs
sort_parameters(mod, sort = "ascending")
sort_parameters(mod, sort = "descending")
}
parameters/man/dot-factor_to_dummy.Rd 0000644 0001762 0000144 00000000506 13641634603 017445 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/utils.R
\name{.factor_to_dummy}
\alias{.factor_to_dummy}
\title{Safe transformation from factor/character to numeric}
\usage{
.factor_to_dummy(x)
}
\description{
Safe transformation from factor/character to numeric
}
\keyword{internal}
parameters/man/pool_parameters.Rd 0000644 0001762 0000144 00000012747 14761600443 016673 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pool_parameters.R
\name{pool_parameters}
\alias{pool_parameters}
\title{Pool Model Parameters}
\usage{
pool_parameters(
x,
exponentiate = FALSE,
effects = "fixed",
component = "all",
verbose = TRUE,
...
)
}
\arguments{
\item{x}{A list of \code{parameters_model} objects, as returned by
\code{\link[=model_parameters]{model_parameters()}}, or a list of model-objects that is supported by
\code{model_parameters()}.}
\item{exponentiate}{Logical, indicating whether or not to exponentiate the
coefficients (and related confidence intervals). This is typical for
logistic regression, or more generally speaking, for models with log or
logit links. It is also recommended to use \code{exponentiate = TRUE} for models
with log-transformed response values. For models with a log-transformed
response variable, when \code{exponentiate = TRUE}, a one-unit increase in the
predictor is associated with multiplying the outcome by that predictor's
coefficient. \strong{Note:} Delta-method standard errors are also computed (by
multiplying the standard errors by the transformed coefficients). This is
to mimic behaviour of other software packages, such as Stata, but these
standard errors poorly estimate uncertainty for the transformed
coefficient. The transformed confidence interval more clearly captures this
uncertainty. For \code{compare_parameters()}, \code{exponentiate = "nongaussian"}
will only exponentiate coefficients from non-Gaussian families.}
\item{effects}{Should parameters for fixed effects (\code{"fixed"}), random
effects (\code{"random"}), both fixed and random effects (\code{"all"}), or the
overall (sum of fixed and random) effects (\code{"random_total"}) be returned?
Only applies to mixed models. May be abbreviated. If the calculation of
random effects parameters takes too long, you may use \code{effects = "fixed"}.}
\item{component}{Which type of parameters to return, such as parameters for the
conditional model, the zero-inflation part of the model, the dispersion
term, or other auxiliary parameters be returned? Applies to models with
zero-inflation and/or dispersion formula, or if parameters such as \code{sigma}
should be included. May be abbreviated. Note that the \emph{conditional}
component is also called \emph{count} or \emph{mean} component, depending on the
model. There are three convenient shortcuts: \code{component = "all"} returns
all possible parameters. If \code{component = "location"}, location parameters
such as \code{conditional}, \code{zero_inflated}, or \code{smooth_terms}, are returned
(everything that are fixed or random effects - depending on the \code{effects}
argument - but no auxiliary parameters). For \code{component = "distributional"}
(or \code{"auxiliary"}), components like \code{sigma}, \code{dispersion}, or \code{beta}
(and other auxiliary parameters) are returned.}
\item{verbose}{Toggle warnings and messages.}
\item{...}{Arguments passed down to \code{model_parameters()}, if \code{x} is a list
of model-objects. Can be used, for instance, to specify arguments like
\code{ci} or \code{ci_method} etc.}
}
\value{
A data frame of indices related to the model's parameters.
}
\description{
This function "pools" (i.e. combines) model parameters in a similar fashion
as \code{mice::pool()}. However, this function pools parameters from
\code{parameters_model} objects, as returned by
\code{\link[=model_parameters]{model_parameters()}}.
}
\details{
Averaging of parameters follows Rubin's rules (\emph{Rubin, 1987, p. 76}).
The pooled degrees of freedom is based on the Barnard-Rubin adjustment for
small samples (\emph{Barnard and Rubin, 1999}).
}
\note{
Models with multiple components, (for instance, models with zero-inflation,
where predictors appear in the count and zero-inflation part, or models with
dispersion component) may fail in rare situations. In this case, compute
the pooled parameters for components separately, using the \code{component}
argument.
Some model objects do not return standard errors (e.g. objects of class
\code{htest}). For these models, no pooled confidence intervals nor p-values
are returned.
}
\examples{
\dontshow{if (require("mice") && require("datawizard")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
# example for multiple imputed datasets
data("nhanes2", package = "mice")
imp <- mice::mice(nhanes2, printFlag = FALSE)
models <- lapply(1:5, function(i) {
lm(bmi ~ age + hyp + chl, data = mice::complete(imp, action = i))
})
pool_parameters(models)
# should be identical to:
m <- with(data = imp, exp = lm(bmi ~ age + hyp + chl))
summary(mice::pool(m))
# For glm, mice used residual df, while `pool_parameters()` uses `Inf`
nhanes2$hyp <- datawizard::slide(as.numeric(nhanes2$hyp))
imp <- mice::mice(nhanes2, printFlag = FALSE)
models <- lapply(1:5, function(i) {
glm(hyp ~ age + chl, family = binomial, data = mice::complete(imp, action = i))
})
m <- with(data = imp, exp = glm(hyp ~ age + chl, family = binomial))
# residual df
summary(mice::pool(m))$df
# df = Inf
pool_parameters(models)$df_error
# use residual df instead
pool_parameters(models, ci_method = "residual")$df_error
\dontshow{\}) # examplesIf}
}
\references{
Barnard, J. and Rubin, D.B. (1999). Small sample degrees of freedom with
multiple imputation. Biometrika, 86, 948-955. Rubin, D.B. (1987). Multiple
Imputation for Nonresponse in Surveys. New York: John Wiley and Sons.
}
parameters/man/bootstrap_parameters.Rd 0000644 0001762 0000144 00000011024 14716604200 017715 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bootstrap_parameters.R
\name{bootstrap_parameters}
\alias{bootstrap_parameters}
\alias{bootstrap_parameters.default}
\title{Parameters bootstrapping}
\usage{
bootstrap_parameters(model, ...)
\method{bootstrap_parameters}{default}(
model,
iterations = 1000,
centrality = "median",
ci = 0.95,
ci_method = "quantile",
test = "p-value",
...
)
}
\arguments{
\item{model}{Statistical model.}
\item{...}{Arguments passed to other methods, like \code{\link[=bootstrap_model]{bootstrap_model()}} or
\code{\link[bayestestR:describe_posterior]{bayestestR::describe_posterior()}}.}
\item{iterations}{The number of draws to simulate/bootstrap.}
\item{centrality}{The point-estimates (centrality indices) to compute. Character
(vector) or list with one or more of these options: \code{"median"}, \code{"mean"}, \code{"MAP"}
(see \code{\link[bayestestR:map_estimate]{map_estimate()}}), \code{"trimmed"} (which is just \code{mean(x, trim = threshold)}),
\code{"mode"} or \code{"all"}.}
\item{ci}{Value or vector of probability of the CI (between 0 and 1)
to be estimated. Default to \code{0.95} (\verb{95\%}).}
\item{ci_method}{The type of index used for Credible Interval. Can be \code{"ETI"}
(default, see \code{\link[bayestestR:eti]{eti()}}), \code{"HDI"} (see \code{\link[bayestestR:hdi]{hdi()}}), \code{"BCI"} (see \code{\link[bayestestR:bci]{bci()}}),
\code{"SPI"} (see \code{\link[bayestestR:spi]{spi()}}), or \code{"SI"} (see \code{\link[bayestestR:si]{si()}}).}
\item{test}{The indices to compute. Character (vector) with one or more of
these options: \code{"p-value"} (or \code{"p"}), \code{"p_direction"} (or \code{"pd"}), \code{"rope"},
\code{"p_map"}, \code{"equivalence_test"} (or \code{"equitest"}), \code{"bayesfactor"} (or \code{"bf"})
or \code{"all"} to compute all tests. For each "test", the corresponding
\strong{bayestestR} function is called (e.g. \code{\link[bayestestR:rope]{bayestestR::rope()}} or
\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}}) and its results included in the summary output.}
}
\value{
A data frame summarizing the bootstrapped parameters.
}
\description{
Compute bootstrapped parameters and their related indices such as Confidence Intervals (CI) and p-values.
}
\details{
This function first calls \code{\link[=bootstrap_model]{bootstrap_model()}} to generate
bootstrapped coefficients. The resulting replicated for each coefficient
are treated as "distribution", and is passed to \code{\link[bayestestR:describe_posterior]{bayestestR::describe_posterior()}}
to calculate the related indices defined in the \code{"test"} argument.
Note that that p-values returned here are estimated under the assumption of
\emph{translation equivariance}: that shape of the sampling distribution is
unaffected by the null being true or not. If this assumption does not hold,
p-values can be biased, and it is suggested to use proper permutation tests
to obtain non-parametric p-values.
}
\section{Using with \strong{emmeans}}{
The output can be passed directly to the various functions from the
\strong{emmeans} package, to obtain bootstrapped estimates, contrasts, simple
slopes, etc. and their confidence intervals. These can then be passed to
\code{model_parameter()} to obtain standard errors, p-values, etc. (see
example).
Note that that p-values returned here are estimated under the assumption of
\emph{translation equivariance}: that shape of the sampling distribution is
unaffected by the null being true or not. If this assumption does not hold,
p-values can be biased, and it is suggested to use proper permutation tests
to obtain non-parametric p-values.
}
\examples{
\dontshow{if (require("boot", quietly = TRUE) && require("emmeans", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
\donttest{
set.seed(2)
model <- lm(Sepal.Length ~ Species * Petal.Width, data = iris)
b <- bootstrap_parameters(model)
print(b)
# different type of bootstrapping
set.seed(2)
b <- bootstrap_parameters(model, type = "balanced")
print(b)
est <- emmeans::emmeans(b, trt.vs.ctrl ~ Species)
print(model_parameters(est))
}
\dontshow{\}) # examplesIf}
}
\references{
Davison, A. C., & Hinkley, D. V. (1997). Bootstrap methods and their
application (Vol. 1). Cambridge university press.
}
\seealso{
\code{\link[=bootstrap_model]{bootstrap_model()}}, \code{\link[=simulate_parameters]{simulate_parameters()}}, \code{\link[=simulate_model]{simulate_model()}}
}
parameters/man/n_clusters.Rd 0000644 0001762 0000144 00000016770 14716616342 015665 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/n_clusters.R, R/n_clusters_easystats.R
\name{n_clusters}
\alias{n_clusters}
\alias{n_clusters_elbow}
\alias{n_clusters_gap}
\alias{n_clusters_silhouette}
\alias{n_clusters_dbscan}
\alias{n_clusters_hclust}
\title{Find number of clusters in your data}
\usage{
n_clusters(
x,
standardize = TRUE,
include_factors = FALSE,
package = c("easystats", "NbClust", "mclust"),
fast = TRUE,
nbclust_method = "kmeans",
n_max = 10,
...
)
n_clusters_elbow(
x,
standardize = TRUE,
include_factors = FALSE,
clustering_function = stats::kmeans,
n_max = 10,
...
)
n_clusters_gap(
x,
standardize = TRUE,
include_factors = FALSE,
clustering_function = stats::kmeans,
n_max = 10,
gap_method = "firstSEmax",
...
)
n_clusters_silhouette(
x,
standardize = TRUE,
include_factors = FALSE,
clustering_function = stats::kmeans,
n_max = 10,
...
)
n_clusters_dbscan(
x,
standardize = TRUE,
include_factors = FALSE,
method = c("kNN", "SS"),
min_size = 0.1,
eps_n = 50,
eps_range = c(0.1, 3),
...
)
n_clusters_hclust(
x,
standardize = TRUE,
include_factors = FALSE,
distance_method = "correlation",
hclust_method = "average",
ci = 0.95,
iterations = 100,
...
)
}
\arguments{
\item{x}{A data frame.}
\item{standardize}{Standardize the dataframe before clustering (default).}
\item{include_factors}{Logical, if \code{TRUE}, factors are converted to numerical
values in order to be included in the data for determining the number of
clusters. By default, factors are removed, because most methods that
determine the number of clusters need numeric input only.}
\item{package}{Package from which methods are to be called to determine the
number of clusters. Can be \code{"all"} or a vector containing
\code{"easystats"}, \code{"NbClust"}, \code{"mclust"}, and \code{"M3C"}.}
\item{fast}{If \code{FALSE}, will compute 4 more indices (sets \code{index = "allong"}
in \code{NbClust}). This has been deactivated by default as it is
computationally heavy.}
\item{nbclust_method}{The clustering method (passed to \code{NbClust::NbClust()}
as \code{method}).}
\item{n_max}{Maximal number of clusters to test.}
\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:
\itemize{
\item \code{digits}, \code{p_digits}, \code{ci_digits} and \code{footer_digits} to set the number of
digits for the output. \code{groups} can be used to group coefficients. These
arguments will be passed to the print-method, or can directly be used in
\code{print()}, see documentation in \code{\link[=print.parameters_model]{print.parameters_model()}}.
\item If \code{s_value = TRUE}, the p-value will be replaced by the S-value in the
output (cf. \emph{Rafi and Greenland 2020}).
\item \code{pd} adds an additional column with the \emph{probability of direction} (see
\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}} for details). Furthermore, see 'Examples' for
this function.
\item For developers, whose 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{clustering_function, gap_method}{Other arguments passed to other
functions. \code{clustering_function} is used by \code{fviz_nbclust()} and
can be \code{kmeans}, \code{cluster::pam}, \code{cluster::clara}, \code{cluster::fanny}, and
more. \code{gap_method} is used by \code{cluster::maxSE} to extract the optimal
numbers of clusters (see its \code{method} argument).}
\item{method, min_size, eps_n, eps_range}{Arguments for DBSCAN algorithm.}
\item{distance_method}{The distance method (passed to \code{\link[=dist]{dist()}}). Used by
algorithms relying on the distance matrix, such as \code{hclust} or \code{dbscan}.}
\item{hclust_method}{The hierarchical clustering method (passed to \code{\link[=hclust]{hclust()}}).}
\item{ci}{Confidence Interval (CI) level. Default to \code{0.95} (\verb{95\%}).}
\item{iterations}{The number of bootstrap replicates. This only apply in the
case of bootstrapped frequentist models.}
}
\description{
Similarly to \code{\link[=n_factors]{n_factors()}} for factor / principal component analysis,
\code{n_clusters()} is the main function to find out the optimal numbers of clusters
present in the data based on the maximum consensus of a large number of
methods.
Essentially, there exist many methods to determine the optimal number of
clusters, each with pros and cons, benefits and limitations. The main
\code{n_clusters} function proposes to run all of them, and find out the number of
clusters that is suggested by the majority of methods (in case of ties, it
will select the most parsimonious solution with fewer clusters).
Note that we also implement some specific, commonly used methods, like the
Elbow or the Gap method, with their own visualization functionalities. See
the examples below for more details.
}
\note{
There is also a \href{https://easystats.github.io/see/articles/parameters.html}{\code{plot()}-method} implemented in the \href{https://easystats.github.io/see/}{\strong{see}-package}.
}
\examples{
\donttest{
library(parameters)
# The main 'n_clusters' function ===============================
if (require("mclust", quietly = TRUE) && require("NbClust", quietly = TRUE) &&
require("cluster", quietly = TRUE) && require("see", quietly = TRUE)) {
n <- n_clusters(iris[, 1:4], package = c("NbClust", "mclust")) # package can be "all"
n
summary(n)
as.data.frame(n) # Duration is the time elapsed for each method in seconds
plot(n)
# The following runs all the method but it significantly slower
# n_clusters(iris[1:4], standardize = FALSE, package = "all", fast = FALSE)
}
}
\dontshow{if (require("see", quietly = TRUE) && require("factoextra", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
\donttest{
x <- n_clusters_elbow(iris[1:4])
x
as.data.frame(x)
plot(x)
}
\dontshow{\}) # examplesIf}
\donttest{
#
# Gap method --------------------
if (require("see", quietly = TRUE) &&
require("cluster", quietly = TRUE) &&
require("factoextra", quietly = TRUE)) {
x <- n_clusters_gap(iris[1:4])
x
as.data.frame(x)
plot(x)
}
}
\donttest{
#
# Silhouette method --------------------------
if (require("factoextra", quietly = TRUE)) {
x <- n_clusters_silhouette(iris[1:4])
x
as.data.frame(x)
plot(x)
}
}
\donttest{
#
if (require("dbscan", quietly = TRUE)) {
# DBSCAN method -------------------------
# NOTE: This actually primarily estimates the 'eps' parameter, the number of
# clusters is a side effect (it's the number of clusters corresponding to
# this 'optimal' EPS parameter).
x <- n_clusters_dbscan(iris[1:4], method = "kNN", min_size = 0.05) # 5 percent
x
head(as.data.frame(x))
plot(x)
x <- n_clusters_dbscan(iris[1:4], method = "SS", eps_n = 100, eps_range = c(0.1, 2))
x
head(as.data.frame(x))
plot(x)
}
}
\donttest{
#
# hclust method -------------------------------
if (require("pvclust", quietly = TRUE)) {
# iterations should be higher for real analyses
x <- n_clusters_hclust(iris[1:4], iterations = 50, ci = 0.90)
x
head(as.data.frame(x), n = 10) # Print 10 first rows
plot(x)
}
}
}
parameters/man/simulate_model.Rd 0000644 0001762 0000144 00000011647 14717115325 016501 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/5_simulate_model.R
\name{simulate_model}
\alias{simulate_model}
\alias{simulate_model.default}
\title{Simulated draws from model coefficients}
\usage{
simulate_model(model, iterations = 1000, ...)
\method{simulate_model}{default}(model, iterations = 1000, component = "all", ...)
}
\arguments{
\item{model}{Statistical model (no Bayesian models).}
\item{iterations}{The number of draws to simulate/bootstrap.}
\item{...}{Arguments passed to \code{\link[insight:get_varcov]{insight::get_varcov()}}, e.g. to allow simulated
draws to be based on heteroscedasticity consistent variance covariance matrices.}
\item{component}{Should all parameters, parameters for the conditional model,
for the zero-inflation part of the model, or the dispersion model be returned?
Applies to models with zero-inflation and/or dispersion component. \code{component}
may be one of \code{"conditional"}, \code{"zi"}, \code{"zero-inflated"}, \code{"dispersion"} or
\code{"all"} (default). May be abbreviated.}
}
\value{
A data frame.
}
\description{
Simulate draws from a statistical model to return a data frame
of estimates.
}
\details{
\subsection{Technical Details}{
\code{simulate_model()} is a computationally faster alternative
to \code{bootstrap_model()}. Simulated draws for coefficients are based
on a multivariate normal distribution (\code{MASS::mvrnorm()}) with mean
\code{mu = coef(model)} and variance \code{Sigma = vcov(model)}.
}
\subsection{Models with Zero-Inflation Component}{
For models from packages \strong{glmmTMB}, \strong{pscl}, \strong{GLMMadaptive} and
\strong{countreg}, the \code{component} argument can be used to specify
which parameters should be simulated. For all other models, parameters
from the conditional component (fixed effects) are simulated. This may
include smooth terms, but not random effects.
}
}
\section{Model components}{
Possible values for the \code{component} argument depend on the model class.
Following are valid options:
\itemize{
\item \code{"all"}: returns all model components, applies to all models, but will only
have an effect for models with more than just the conditional model component.
\item \code{"conditional"}: only returns the conditional component, i.e. "fixed effects"
terms from the model. Will only have an effect for models with more than
just the conditional model component.
\item \code{"smooth_terms"}: returns smooth terms, only applies to GAMs (or similar
models that may contain smooth terms).
\item \code{"zero_inflated"} (or \code{"zi"}): returns the zero-inflation component.
\item \code{"dispersion"}: returns the dispersion model component. This is common
for models with zero-inflation or that can model the dispersion parameter.
\item \code{"instruments"}: for instrumental-variable or some fixed effects regression,
returns the instruments.
\item \code{"nonlinear"}: for non-linear models (like models of class \code{nlmerMod} or
\code{nls}), returns staring estimates for the nonlinear parameters.
\item \code{"correlation"}: for models with correlation-component, like \code{gls}, the
variables used to describe the correlation structure are returned.
}
\strong{Special models}
Some model classes also allow rather uncommon options. These are:
\itemize{
\item \strong{mhurdle}: \code{"infrequent_purchase"}, \code{"ip"}, and \code{"auxiliary"}
\item \strong{BGGM}: \code{"correlation"} and \code{"intercept"}
\item \strong{BFBayesFactor}, \strong{glmx}: \code{"extra"}
\item \strong{averaging}:\code{"conditional"} and \code{"full"}
\item \strong{mjoint}: \code{"survival"}
\item \strong{mfx}: \code{"precision"}, \code{"marginal"}
\item \strong{betareg}, \strong{DirichletRegModel}: \code{"precision"}
\item \strong{mvord}: \code{"thresholds"} and \code{"correlation"}
\item \strong{clm2}: \code{"scale"}
\item \strong{selection}: \code{"selection"}, \code{"outcome"}, and \code{"auxiliary"}
\item \strong{lavaan}: One or more of \code{"regression"}, \code{"correlation"}, \code{"loading"},
\code{"variance"}, \code{"defined"}, or \code{"mean"}. Can also be \code{"all"} to include
all components.
}
For models of class \code{brmsfit} (package \strong{brms}), even more options are
possible for the \code{component} argument, which are not all documented in detail
here.
}
\examples{
model <- lm(Sepal.Length ~ Species * Petal.Width + Petal.Length, data = iris)
head(simulate_model(model))
\donttest{
if (require("glmmTMB", quietly = TRUE)) {
model <- glmmTMB(
count ~ spp + mined + (1 | site),
ziformula = ~mined,
family = poisson(),
data = Salamanders
)
head(simulate_model(model))
head(simulate_model(model, component = "zero_inflated"))
}
}
}
\seealso{
\code{\link[=simulate_parameters]{simulate_parameters()}}, \code{\link[=bootstrap_model]{bootstrap_model()}}, \code{\link[=bootstrap_parameters]{bootstrap_parameters()}}
}
parameters/man/model_parameters.t1way.Rd 0000644 0001762 0000144 00000004201 14507235543 020053 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/methods_wrs2.R
\name{model_parameters.t1way}
\alias{model_parameters.t1way}
\title{Parameters from robust statistical objects in \code{WRS2}}
\usage{
\method{model_parameters}{t1way}(model, keep = NULL, verbose = TRUE, ...)
}
\arguments{
\item{model}{Object from \code{WRS2} package.}
\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
named list of regular expressions. All non-matching parameters will be
removed from the output. If \code{keep} is a character vector, every parameter
name in the \emph{"Parameter"} column that matches the regular expression in
\code{keep} will be selected from the returned data frame (and vice versa,
all parameter names matching \code{drop} will be excluded). Furthermore, if
\code{keep} has more than one element, these will be merged with an \code{OR}
operator into a regular expression pattern like this: \code{"(one|two|three)"}.
If \code{keep} is a named list of regular expression patterns, the names of the
list-element should equal the column name where selection should be
applied. This is useful for model objects where \code{model_parameters()}
returns multiple columns with parameter components, like in
\code{\link[=model_parameters.lavaan]{model_parameters.lavaan()}}. Note that the regular expression pattern
should match the parameter names as they are stored in the returned data
frame, which can be different from how they are printed. Inspect the
\verb{$Parameter} column of the parameters table to get the exact parameter
names.}
\item{verbose}{Toggle warnings and messages.}
\item{...}{Arguments passed to or from other methods.}
}
\value{
A data frame of indices related to the model's parameters.
}
\description{
Parameters from robust statistical objects in \code{WRS2}
}
\examples{
if (require("WRS2") && packageVersion("WRS2") >= "1.1.3") {
model <- t1way(libido ~ dose, data = viagra)
model_parameters(model)
}
}
parameters/man/reduce_parameters.Rd 0000644 0001762 0000144 00000011205 14502257471 017157 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reduce_parameters.R
\name{reduce_parameters}
\alias{reduce_parameters}
\alias{reduce_data}
\title{Dimensionality reduction (DR) / Features Reduction}
\usage{
reduce_parameters(x, method = "PCA", n = "max", distance = "euclidean", ...)
reduce_data(x, method = "PCA", n = "max", distance = "euclidean", ...)
}
\arguments{
\item{x}{A data frame or a statistical model.}
\item{method}{The feature reduction method. Can be one of \code{"PCA"}, \code{"cMDS"},
\code{"DRR"}, \code{"ICA"} (see the 'Details' section).}
\item{n}{Number of components to extract. If \code{n="all"}, then \code{n} is set as
the number of variables minus 1 (\code{ncol(x)-1}). If \code{n="auto"} (default) or
\code{n=NULL}, the number of components is selected through \code{\link[=n_factors]{n_factors()}} resp.
\code{\link[=n_components]{n_components()}}. Else, if \code{n} is a number, \code{n} components are extracted.
If \code{n} exceeds number of variables in the data, it is automatically set to
the maximum number (i.e. \code{ncol(x)}). In \code{\link[=reduce_parameters]{reduce_parameters()}}, can also
be \code{"max"}, in which case it will select all the components that are
maximally pseudo-loaded (i.e., correlated) by at least one variable.}
\item{distance}{The distance measure to be used. Only applies when
\code{method = "cMDS"}. This must be one of \code{"euclidean"}, \code{"maximum"},
\code{"manhattan"}, \code{"canberra"}, \code{"binary"} or \code{"minkowski"}. Any unambiguous
substring can be given.}
\item{...}{Arguments passed to or from other methods.}
}
\description{
This function performs a reduction in the parameter space (the number of
variables). It starts by creating a new set of variables, based on the given
method (the default method is "PCA", but other are available via the
\code{method} argument, such as "cMDS", "DRR" or "ICA"). Then, it names this
new dimensions using the original variables that correlates the most with it.
For instance, a variable named \code{'V1_0.97/V4_-0.88'} means that the V1 and the
V4 variables correlate maximally (with respective coefficients of .97 and
-.88) with this dimension. Although this function can be useful in
exploratory data analysis, it's best to perform the dimension reduction step
in a separate and dedicated stage, as this is a very important process in the
data analysis workflow. \code{reduce_data()} is an alias for
\code{reduce_parameters.data.frame()}.
}
\details{
The different methods available are described below:
\subsection{Supervised Methods}{
\itemize{
\item \strong{PCA}: See \code{\link[=principal_components]{principal_components()}}.
\item \strong{cMDS / PCoA}: Classical Multidimensional Scaling (cMDS) takes a
set of dissimilarities (i.e., a distance matrix) and returns a set of points
such that the distances between the points are approximately equal to the
dissimilarities.
\item \strong{DRR}: Dimensionality Reduction via Regression (DRR) is a very
recent technique extending PCA (\emph{Laparra et al., 2015}). Starting from a
rotated PCA, it predicts redundant information from the remaining components
using non-linear regression. Some of the most notable advantages of
performing DRR are avoidance of multicollinearity between predictors and
overfitting mitigation. DRR tends to perform well when the first principal
component is enough to explain most of the variation in the predictors.
Requires the \strong{DRR} package to be installed.
\item \strong{ICA}: Performs an Independent Component Analysis using the
FastICA algorithm. Contrary to PCA, which attempts to find uncorrelated
sources (through least squares minimization), ICA attempts to find
independent sources, i.e., the source space that maximizes the
"non-gaussianity" of all sources. Contrary to PCA, ICA does not rank each
source, which makes it a poor tool for dimensionality reduction. Requires the
\strong{fastICA} package to be installed.
}
See also \href{https://easystats.github.io/parameters/articles/parameters_reduction.html}{package vignette}.
}
}
\examples{
data(iris)
model <- lm(Sepal.Width ~ Species * Sepal.Length + Petal.Width, data = iris)
model
reduce_parameters(model)
out <- reduce_data(iris, method = "PCA", n = "max")
head(out)
}
\references{
\itemize{
\item Nguyen, L. H., and Holmes, S. (2019). Ten quick tips for effective
dimensionality reduction. PLOS Computational Biology, 15(6).
\item Laparra, V., Malo, J., and Camps-Valls, G. (2015). Dimensionality
reduction via regression in hyperspectral imagery. IEEE Journal of Selected
Topics in Signal Processing, 9(6), 1026-1036.
}
}
parameters/man/reexports.Rd 0000644 0001762 0000144 00000002777 14716604200 015527 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/equivalence_test.R, R/methods_bayestestR.R,
% R/n_parameters.R, R/p_direction.R, R/p_significance.R, R/reexports.R
\docType{import}
\name{reexports}
\alias{reexports}
\alias{equivalence_test}
\alias{ci}
\alias{n_parameters}
\alias{p_direction}
\alias{p_significance}
\alias{standardize_names}
\alias{supported_models}
\alias{print_html}
\alias{print_md}
\alias{display}
\alias{describe_distribution}
\alias{demean}
\alias{rescale_weights}
\alias{visualisation_recipe}
\alias{kurtosis}
\alias{skewness}
\title{Objects exported from other packages}
\keyword{internal}
\description{
These objects are imported from other packages. Follow the links
below to see their documentation.
\describe{
\item{bayestestR}{\code{\link[bayestestR]{ci}}, \code{\link[bayestestR]{equivalence_test}}, \code{\link[bayestestR]{p_direction}}, \code{\link[bayestestR]{p_significance}}}
\item{datawizard}{\code{\link[datawizard]{demean}}, \code{\link[datawizard]{describe_distribution}}, \code{\link[datawizard:skewness]{kurtosis}}, \code{\link[datawizard]{rescale_weights}}, \code{\link[datawizard]{skewness}}, \code{\link[datawizard]{visualisation_recipe}}}
\item{insight}{\code{\link[insight]{display}}, \code{\link[insight]{n_parameters}}, \code{\link[insight:display]{print_html}}, \code{\link[insight:display]{print_md}}, \code{\link[insight]{standardize_names}}, \code{\link[insight:is_model_supported]{supported_models}}}
}}
parameters/man/dot-n_factors_bartlett.Rd 0000644 0001762 0000144 00000000555 13641634603 020135 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/n_factors.R
\name{.n_factors_bartlett}
\alias{.n_factors_bartlett}
\title{Bartlett, Anderson and Lawley Procedures}
\usage{
.n_factors_bartlett(eigen_values = NULL, model = "factors", nobs = NULL)
}
\description{
Bartlett, Anderson and Lawley Procedures
}
\keyword{internal}
parameters/man/model_parameters.mlm.Rd 0000644 0001762 0000144 00000026016 14721615366 017606 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/methods_mlm.R
\name{model_parameters.mlm}
\alias{model_parameters.mlm}
\title{Parameters from multinomial or cumulative link models}
\usage{
\method{model_parameters}{mlm}(
model,
ci = 0.95,
vcov = NULL,
vcov_args = NULL,
bootstrap = FALSE,
iterations = 1000,
standardize = NULL,
exponentiate = FALSE,
p_adjust = NULL,
keep = NULL,
drop = NULL,
verbose = TRUE,
...
)
}
\arguments{
\item{model}{A model with multinomial or categorical response value.}
\item{ci}{Confidence Interval (CI) level. Default to \code{0.95} (\verb{95\%}).}
\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{"HC"}, \code{"HC0"}, \code{"HC1"}, \code{"HC2"},
\code{"HC3"}, \code{"HC4"}, \code{"HC4m"}, \code{"HC5"}. See \code{?sandwich::vcovHC}
\item Cluster-robust: \code{"CR"}, \code{"CR0"}, \code{"CR1"}, \code{"CR1p"}, \code{"CR1S"},
\code{"CR2"}, \code{"CR3"}. See \code{?clubSandwich::vcovCR}
\item Bootstrap: \code{"BS"}, \code{"xy"}, \code{"residual"}, \code{"wild"}, \code{"mammen"},
\code{"fractional"}, \code{"jackknife"}, \code{"norm"}, \code{"webb"}. See
\code{?sandwich::vcovBS}
\item Other \code{sandwich} package functions: \code{"HAC"}, \code{"PC"}, \code{"CL"}, \code{"OPG"},
\code{"PL"}.
}
}}
\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. If no estimation type (argument \code{type}) is given, the default
type for \code{"HC"} equals the default from the \strong{sandwich} package; for type
\code{"CR"}, the default is set to \code{"CR3"}.}
\item{bootstrap}{Should estimates be based on bootstrapped model? If \code{TRUE},
then arguments of \link[=model_parameters.brmsfit]{Bayesian regressions} apply
(see also \code{\link[=bootstrap_parameters]{bootstrap_parameters()}}).}
\item{iterations}{The number of bootstrap replicates. This only apply in the
case of bootstrapped frequentist models.}
\item{standardize}{The method used for standardizing the parameters. Can be
\code{NULL} (default; no standardization), \code{"refit"} (for re-fitting the model
on standardized data) or one of \code{"basic"}, \code{"posthoc"}, \code{"smart"},
\code{"pseudo"}. See 'Details' in \code{\link[=standardize_parameters]{standardize_parameters()}}.
\strong{Importantly}:
\itemize{
\item The \code{"refit"} method does \emph{not} standardize categorical predictors (i.e.
factors), which may be a different behaviour compared to other R packages
(such as \strong{lm.beta}) or other software packages (like SPSS). to mimic
such behaviours, either use \code{standardize="basic"} or standardize the data
with \code{datawizard::standardize(force=TRUE)} \emph{before} fitting the model.
\item For mixed models, when using methods other than \code{"refit"}, only the fixed
effects will be standardized.
\item Robust estimation (i.e., \code{vcov} set to a value other than \code{NULL}) of
standardized parameters only works when \code{standardize="refit"}.
}}
\item{exponentiate}{Logical, indicating whether or not to exponentiate the
coefficients (and related confidence intervals). This is typical for
logistic regression, or more generally speaking, for models with log or
logit links. It is also recommended to use \code{exponentiate = TRUE} for models
with log-transformed response values. For models with a log-transformed
response variable, when \code{exponentiate = TRUE}, a one-unit increase in the
predictor is associated with multiplying the outcome by that predictor's
coefficient. \strong{Note:} Delta-method standard errors are also computed (by
multiplying the standard errors by the transformed coefficients). This is
to mimic behaviour of other software packages, such as Stata, but these
standard errors poorly estimate uncertainty for the transformed
coefficient. The transformed confidence interval more clearly captures this
uncertainty. For \code{compare_parameters()}, \code{exponentiate = "nongaussian"}
will only exponentiate coefficients from non-Gaussian families.}
\item{p_adjust}{Character vector, if not \code{NULL}, indicates the method to
adjust p-values. See \code{\link[stats:p.adjust]{stats::p.adjust()}} for details. Further
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{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
named list of regular expressions. All non-matching parameters will be
removed from the output. If \code{keep} is a character vector, every parameter
name in the \emph{"Parameter"} column that matches the regular expression in
\code{keep} will be selected from the returned data frame (and vice versa,
all parameter names matching \code{drop} will be excluded). Furthermore, if
\code{keep} has more than one element, these will be merged with an \code{OR}
operator into a regular expression pattern like this: \code{"(one|two|three)"}.
If \code{keep} is a named list of regular expression patterns, the names of the
list-element should equal the column name where selection should be
applied. This is useful for model objects where \code{model_parameters()}
returns multiple columns with parameter components, like in
\code{\link[=model_parameters.lavaan]{model_parameters.lavaan()}}. Note that the regular expression pattern
should match the parameter names as they are stored in the returned data
frame, which can be different from how they are printed. Inspect the
\verb{$Parameter} column of the parameters table to get the exact parameter
names.}
\item{drop}{See \code{keep}.}
\item{verbose}{Toggle warnings and messages.}
\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:
\itemize{
\item \code{digits}, \code{p_digits}, \code{ci_digits} and \code{footer_digits} to set the number of
digits for the output. \code{groups} can be used to group coefficients. These
arguments will be passed to the print-method, or can directly be used in
\code{print()}, see documentation in \code{\link[=print.parameters_model]{print.parameters_model()}}.
\item If \code{s_value = TRUE}, the p-value will be replaced by the S-value in the
output (cf. \emph{Rafi and Greenland 2020}).
\item \code{pd} adds an additional column with the \emph{probability of direction} (see
\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}} for details). Furthermore, see 'Examples' for
this function.
\item For developers, whose 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.
}}
}
\value{
A data frame of indices related to the model's parameters.
}
\description{
Parameters from multinomial or cumulative link models
}
\details{
Multinomial or cumulative link models, i.e. models where the
response value (dependent variable) is categorical and has more than two
levels, usually return coefficients for each response level. Hence, the
output from \code{model_parameters()} will split the coefficient tables
by the different levels of the model's response.
}
\section{Model components}{
Possible values for the \code{component} argument depend on the model class.
Following are valid options:
\itemize{
\item \code{"all"}: returns all model components, applies to all models, but will only
have an effect for models with more than just the conditional model component.
\item \code{"conditional"}: only returns the conditional component, i.e. "fixed effects"
terms from the model. Will only have an effect for models with more than
just the conditional model component.
\item \code{"smooth_terms"}: returns smooth terms, only applies to GAMs (or similar
models that may contain smooth terms).
\item \code{"zero_inflated"} (or \code{"zi"}): returns the zero-inflation component.
\item \code{"dispersion"}: returns the dispersion model component. This is common
for models with zero-inflation or that can model the dispersion parameter.
\item \code{"instruments"}: for instrumental-variable or some fixed effects regression,
returns the instruments.
\item \code{"nonlinear"}: for non-linear models (like models of class \code{nlmerMod} or
\code{nls}), returns staring estimates for the nonlinear parameters.
\item \code{"correlation"}: for models with correlation-component, like \code{gls}, the
variables used to describe the correlation structure are returned.
}
\strong{Special models}
Some model classes also allow rather uncommon options. These are:
\itemize{
\item \strong{mhurdle}: \code{"infrequent_purchase"}, \code{"ip"}, and \code{"auxiliary"}
\item \strong{BGGM}: \code{"correlation"} and \code{"intercept"}
\item \strong{BFBayesFactor}, \strong{glmx}: \code{"extra"}
\item \strong{averaging}:\code{"conditional"} and \code{"full"}
\item \strong{mjoint}: \code{"survival"}
\item \strong{mfx}: \code{"precision"}, \code{"marginal"}
\item \strong{betareg}, \strong{DirichletRegModel}: \code{"precision"}
\item \strong{mvord}: \code{"thresholds"} and \code{"correlation"}
\item \strong{clm2}: \code{"scale"}
\item \strong{selection}: \code{"selection"}, \code{"outcome"}, and \code{"auxiliary"}
\item \strong{lavaan}: One or more of \code{"regression"}, \code{"correlation"}, \code{"loading"},
\code{"variance"}, \code{"defined"}, or \code{"mean"}. Can also be \code{"all"} to include
all components.
}
For models of class \code{brmsfit} (package \strong{brms}), even more options are
possible for the \code{component} argument, which are not all documented in detail
here.
}
\examples{
\dontshow{if (require("brglm2", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
data("stemcell", package = "brglm2")
model <- brglm2::bracl(
research ~ as.numeric(religion) + gender,
weights = frequency,
data = stemcell,
type = "ML"
)
model_parameters(model)
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[insight:standardize_names]{insight::standardize_names()}} to rename
columns into a consistent, standardized naming scheme.
}
parameters/man/p_direction.lm.Rd 0000644 0001762 0000144 00000030134 14717111737 016377 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/p_direction.R
\name{p_direction.lm}
\alias{p_direction.lm}
\title{Probability of Direction (pd)}
\usage{
\method{p_direction}{lm}(
x,
ci = 0.95,
method = "direct",
null = 0,
vcov = NULL,
vcov_args = NULL,
...
)
}
\arguments{
\item{x}{A statistical model.}
\item{ci}{Confidence Interval (CI) level. Default to \code{0.95} (\verb{95\%}).}
\item{method}{Can be \code{"direct"} or one of methods of \code{\link[bayestestR:estimate_density]{estimate_density()}},
such as \code{"kernel"}, \code{"logspline"} or \code{"KernSmooth"}. See details.}
\item{null}{The value considered as a "null" effect. Traditionally 0, but
could also be 1 in the case of ratios of change (OR, IRR, ...).}
\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{"HC"}, \code{"HC0"}, \code{"HC1"}, \code{"HC2"},
\code{"HC3"}, \code{"HC4"}, \code{"HC4m"}, \code{"HC5"}. See \code{?sandwich::vcovHC}
\item Cluster-robust: \code{"CR"}, \code{"CR0"}, \code{"CR1"}, \code{"CR1p"}, \code{"CR1S"},
\code{"CR2"}, \code{"CR3"}. See \code{?clubSandwich::vcovCR}
\item Bootstrap: \code{"BS"}, \code{"xy"}, \code{"residual"}, \code{"wild"}, \code{"mammen"},
\code{"fractional"}, \code{"jackknife"}, \code{"norm"}, \code{"webb"}. See
\code{?sandwich::vcovBS}
\item Other \code{sandwich} package functions: \code{"HAC"}, \code{"PC"}, \code{"CL"}, \code{"OPG"},
\code{"PL"}.
}
}}
\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. If no estimation type (argument \code{type}) is given, the default
type for \code{"HC"} equals the default from the \strong{sandwich} package; for type
\code{"CR"}, the default is set to \code{"CR3"}.}
\item{...}{Arguments passed to other methods, e.g. \code{ci()}. Arguments like
\code{vcov} or \code{vcov_args} can be used to compute confidence intervals using a
specific variance-covariance matrix for the standard errors.}
}
\value{
A data frame.
}
\description{
Compute the \strong{Probability of Direction} (\emph{pd}, also known as
the Maximum Probability of Effect - \emph{MPE}). This can be interpreted as the
probability that a parameter (described by its full confidence, or
"compatibility" interval) is strictly positive or negative (whichever is the
most probable). Although differently expressed, this index is fairly similar
(i.e., is strongly correlated) to the frequentist \emph{p-value} (see 'Details').
}
\section{What is the \emph{pd}?}{
The Probability of Direction (pd) is an index of effect existence, representing
the certainty with which an effect goes in a particular direction (i.e., is
positive or negative / has a sign), typically ranging from 0.5 to 1 (but see
next section for cases where it can range between 0 and 1). Beyond
its simplicity of interpretation, understanding and computation, this index
also presents other interesting properties:
\itemize{
\item Like other posterior-based indices, \emph{pd} is solely based on the posterior
distributions and does not require any additional information from the data
or the model (e.g., such as priors, as in the case of Bayes factors).
\item It is robust to the scale of both the response variable and the predictors.
\item It is strongly correlated with the frequentist p-value, and can thus
be used to draw parallels and give some reference to readers non-familiar
with Bayesian statistics (Makowski et al., 2019).
}
}
\section{Relationship with the p-value}{
In most cases, it seems that the \emph{pd} has a direct correspondence with the
frequentist one-sided \emph{p}-value through the formula (for two-sided \emph{p}):
\ifelse{html}{\out{p = 2 * (1 - pd)}}{\eqn{p = 2 \times (1 - p_d)}}
Thus, a two-sided p-value of respectively \code{.1}, \code{.05}, \code{.01} and \code{.001} would
correspond approximately to a \emph{pd} of \verb{95\%}, \verb{97.5\%}, \verb{99.5\%} and \verb{99.95\%}.
See \code{\link[bayestestR:pd_to_p]{pd_to_p()}} for details.
}
\section{Possible Range of Values}{
The largest value \emph{pd} can take is 1 - the posterior is strictly directional.
However, the smallest value \emph{pd} can take depends on the parameter space
represented by the posterior.
\strong{For a continuous parameter space}, exact values of 0 (or any point null
value) are not possible, and so 100\% of the posterior has \emph{some} sign, some
positive, some negative. Therefore, the smallest the \emph{pd} can be is 0.5 -
with an equal posterior mass of positive and negative values. Values close to
0.5 \emph{cannot} be used to support the null hypothesis (that the parameter does
\emph{not} have a direction) is a similar why to how large p-values cannot be used
to support the null hypothesis (see \code{\link[bayestestR:pd_to_p]{pd_to_p()}}; Makowski et al., 2019).
\strong{For a discrete parameter space or a parameter space that is a mixture
between discrete and continuous spaces}, exact values of 0 (or any point
null value) \emph{are} possible! Therefore, the smallest the \emph{pd} can be is 0 -
with 100\% of the posterior mass on 0. Thus values close to 0 can be used to
support the null hypothesis (see van den Bergh et al., 2021).
Examples of posteriors representing discrete parameter space:
\itemize{
\item When a parameter can only take discrete values.
\item When a mixture prior/posterior is used (such as the spike-and-slab prior;
see van den Bergh et al., 2021).
\item When conducting Bayesian model averaging (e.g., \code{\link[bayestestR:weighted_posteriors]{weighted_posteriors()}} or
\code{brms::posterior_average}).
}
}
\section{Statistical inference - how to quantify evidence}{
There is no standardized approach to drawing conclusions based on the
available data and statistical models. A frequently chosen but also much
criticized approach is to evaluate results based on their statistical
significance (\emph{Amrhein et al. 2017}).
A more sophisticated way would be to test whether estimated effects exceed
the "smallest effect size of interest", to avoid even the smallest effects
being considered relevant simply because they are statistically significant,
but clinically or practically irrelevant (\emph{Lakens et al. 2018, Lakens 2024}).
A rather unconventional approach, which is nevertheless advocated by various
authors, is to interpret results from classical regression models either in
terms of probabilities, similar to the usual approach in Bayesian statistics
(\emph{Schweder 2018; Schweder and Hjort 2003; Vos 2022}) or in terms of relative
measure of "evidence" or "compatibility" with the data (\emph{Greenland et al. 2022;
Rafi and Greenland 2020}), which nevertheless comes close to a probabilistic
interpretation.
A more detailed discussion of this topic is found in the documentation of
\code{\link[=p_function]{p_function()}}.
The \strong{parameters} package provides several options or functions to aid
statistical inference. These are, for example:
\itemize{
\item \code{\link[=equivalence_test.lm]{equivalence_test()}}, to compute the (conditional)
equivalence test for frequentist models
\item \code{\link[=p_significance.lm]{p_significance()}}, to compute the probability of
\emph{practical significance}, which can be conceptualized as a unidirectional
equivalence test
\item \code{\link[=p_function]{p_function()}}, or \emph{consonance function}, to compute p-values and
compatibility (confidence) intervals for statistical models
\item the \code{pd} argument (setting \code{pd = TRUE}) in \code{model_parameters()} includes
a column with the \emph{probability of direction}, i.e. the probability that a
parameter is strictly positive or negative. See \code{\link[bayestestR:p_direction]{bayestestR::p_direction()}}
for details. If plotting is desired, the \code{\link[=p_direction.lm]{p_direction()}}
function can be used, together with \code{plot()}.
\item the \code{s_value} argument (setting \code{s_value = TRUE}) in \code{model_parameters()}
replaces the p-values with their related \emph{S}-values (\emph{Rafi and Greenland 2020})
\item finally, it is possible to generate distributions of model coefficients by
generating bootstrap-samples (setting \code{bootstrap = TRUE}) or simulating
draws from model coefficients using \code{\link[=simulate_model]{simulate_model()}}. These samples
can then be treated as "posterior samples" and used in many functions from
the \strong{bayestestR} package.
}
Most of the above shown options or functions derive from methods originally
implemented for Bayesian models (\emph{Makowski et al. 2019}). However, assuming
that model assumptions are met (which means, the model fits well to the data,
the correct model is chosen that reflects the data generating process
(distributional model family) etc.), it seems appropriate to interpret
results from classical frequentist models in a "Bayesian way" (more details:
documentation in \code{\link[=p_function]{p_function()}}).
}
\examples{
\dontshow{if (requireNamespace("bayestestR") && require("see", quietly = TRUE) && requireNamespace("sandwich")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
data(qol_cancer)
model <- lm(QoL ~ time + age + education, data = qol_cancer)
p_direction(model)
# based on heteroscedasticity-robust standard errors
p_direction(model, vcov = "HC3")
result <- p_direction(model)
plot(result)
\dontshow{\}) # examplesIf}
}
\references{
\itemize{
\item Amrhein, V., Korner-Nievergelt, F., and Roth, T. (2017). The earth is
flat (p > 0.05): Significance thresholds and the crisis of unreplicable
research. PeerJ, 5, e3544. \doi{10.7717/peerj.3544}
\item Greenland S, Rafi Z, Matthews R, Higgs M. To Aid Scientific Inference,
Emphasize Unconditional Compatibility Descriptions of Statistics. (2022)
https://arxiv.org/abs/1909.08583v7 (Accessed November 10, 2022)
\item Lakens, D. (2024). Improving Your Statistical Inferences (Version v1.5.1).
Retrieved from https://lakens.github.io/statistical_inferences/.
\doi{10.5281/ZENODO.6409077}
\item Lakens, D., Scheel, A. M., and Isager, P. M. (2018). Equivalence Testing
for Psychological Research: A Tutorial. Advances in Methods and Practices
in Psychological Science, 1(2), 259–269. \doi{10.1177/2515245918770963}
\item Makowski, D., Ben-Shachar, M. S., Chen, S. H. A., and Lüdecke, D. (2019).
Indices of Effect Existence and Significance in the Bayesian Framework.
Frontiers in Psychology, 10, 2767. \doi{10.3389/fpsyg.2019.02767}
\item Rafi Z, Greenland S. Semantic and cognitive tools to aid statistical
science: replace confidence and significance by compatibility and surprise.
BMC Medical Research Methodology (2020) 20:244.
\item Schweder T. Confidence is epistemic probability for empirical science.
Journal of Statistical Planning and Inference (2018) 195:116–125.
\doi{10.1016/j.jspi.2017.09.016}
\item Schweder T, Hjort NL. Frequentist analogues of priors and posteriors.
In Stigum, B. (ed.), Econometrics and the Philosophy of Economics: Theory
Data Confrontation in Economics, pp. 285-217. Princeton University Press,
Princeton, NJ, 2003
\item Vos P, Holbert D. Frequentist statistical inference without repeated sampling.
Synthese 200, 89 (2022). \doi{10.1007/s11229-022-03560-x}
}
}
\seealso{
See also \code{\link[=equivalence_test]{equivalence_test()}}, \code{\link[=p_function]{p_function()}} and
\code{\link[=p_significance]{p_significance()}} for functions related to checking effect existence and
significance.
}
parameters/man/model_parameters.cgam.Rd 0000644 0001762 0000144 00000017654 14721615366 017740 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/methods_cgam.R
\name{model_parameters.cgam}
\alias{model_parameters.cgam}
\title{Parameters from Generalized Additive (Mixed) Models}
\usage{
\method{model_parameters}{cgam}(
model,
ci = 0.95,
ci_method = "residual",
bootstrap = FALSE,
iterations = 1000,
standardize = NULL,
exponentiate = FALSE,
p_adjust = NULL,
keep = NULL,
drop = NULL,
verbose = TRUE,
...
)
}
\arguments{
\item{model}{A gam/gamm model.}
\item{ci}{Confidence Interval (CI) level. Default to \code{0.95} (\verb{95\%}).}
\item{ci_method}{Method for computing degrees of freedom for
confidence intervals (CI) and the related p-values. Allowed are following
options (which vary depending on the model class): \code{"residual"},
\code{"normal"}, \code{"likelihood"}, \code{"satterthwaite"}, \code{"kenward"}, \code{"wald"},
\code{"profile"}, \code{"boot"}, \code{"uniroot"}, \code{"ml1"}, \code{"betwithin"}, \code{"hdi"},
\code{"quantile"}, \code{"ci"}, \code{"eti"}, \code{"si"}, \code{"bci"}, or \code{"bcai"}. See section
\emph{Confidence intervals and approximation of degrees of freedom} in
\code{\link[=model_parameters]{model_parameters()}} for further details. When \code{ci_method=NULL}, in most
cases \code{"wald"} is used then.}
\item{bootstrap}{Should estimates be based on bootstrapped model? If \code{TRUE},
then arguments of \link[=model_parameters.brmsfit]{Bayesian regressions} apply
(see also \code{\link[=bootstrap_parameters]{bootstrap_parameters()}}).}
\item{iterations}{The number of bootstrap replicates. This only apply in the
case of bootstrapped frequentist models.}
\item{standardize}{The method used for standardizing the parameters. Can be
\code{NULL} (default; no standardization), \code{"refit"} (for re-fitting the model
on standardized data) or one of \code{"basic"}, \code{"posthoc"}, \code{"smart"},
\code{"pseudo"}. See 'Details' in \code{\link[=standardize_parameters]{standardize_parameters()}}.
\strong{Importantly}:
\itemize{
\item The \code{"refit"} method does \emph{not} standardize categorical predictors (i.e.
factors), which may be a different behaviour compared to other R packages
(such as \strong{lm.beta}) or other software packages (like SPSS). to mimic
such behaviours, either use \code{standardize="basic"} or standardize the data
with \code{datawizard::standardize(force=TRUE)} \emph{before} fitting the model.
\item For mixed models, when using methods other than \code{"refit"}, only the fixed
effects will be standardized.
\item Robust estimation (i.e., \code{vcov} set to a value other than \code{NULL}) of
standardized parameters only works when \code{standardize="refit"}.
}}
\item{exponentiate}{Logical, indicating whether or not to exponentiate the
coefficients (and related confidence intervals). This is typical for
logistic regression, or more generally speaking, for models with log or
logit links. It is also recommended to use \code{exponentiate = TRUE} for models
with log-transformed response values. For models with a log-transformed
response variable, when \code{exponentiate = TRUE}, a one-unit increase in the
predictor is associated with multiplying the outcome by that predictor's
coefficient. \strong{Note:} Delta-method standard errors are also computed (by
multiplying the standard errors by the transformed coefficients). This is
to mimic behaviour of other software packages, such as Stata, but these
standard errors poorly estimate uncertainty for the transformed
coefficient. The transformed confidence interval more clearly captures this
uncertainty. For \code{compare_parameters()}, \code{exponentiate = "nongaussian"}
will only exponentiate coefficients from non-Gaussian families.}
\item{p_adjust}{Character vector, if not \code{NULL}, indicates the method to
adjust p-values. See \code{\link[stats:p.adjust]{stats::p.adjust()}} for details. Further
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{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
named list of regular expressions. All non-matching parameters will be
removed from the output. If \code{keep} is a character vector, every parameter
name in the \emph{"Parameter"} column that matches the regular expression in
\code{keep} will be selected from the returned data frame (and vice versa,
all parameter names matching \code{drop} will be excluded). Furthermore, if
\code{keep} has more than one element, these will be merged with an \code{OR}
operator into a regular expression pattern like this: \code{"(one|two|three)"}.
If \code{keep} is a named list of regular expression patterns, the names of the
list-element should equal the column name where selection should be
applied. This is useful for model objects where \code{model_parameters()}
returns multiple columns with parameter components, like in
\code{\link[=model_parameters.lavaan]{model_parameters.lavaan()}}. Note that the regular expression pattern
should match the parameter names as they are stored in the returned data
frame, which can be different from how they are printed. Inspect the
\verb{$Parameter} column of the parameters table to get the exact parameter
names.}
\item{drop}{See \code{keep}.}
\item{verbose}{Toggle warnings and messages.}
\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:
\itemize{
\item \code{digits}, \code{p_digits}, \code{ci_digits} and \code{footer_digits} to set the number of
digits for the output. \code{groups} can be used to group coefficients. These
arguments will be passed to the print-method, or can directly be used in
\code{print()}, see documentation in \code{\link[=print.parameters_model]{print.parameters_model()}}.
\item If \code{s_value = TRUE}, the p-value will be replaced by the S-value in the
output (cf. \emph{Rafi and Greenland 2020}).
\item \code{pd} adds an additional column with the \emph{probability of direction} (see
\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}} for details). Furthermore, see 'Examples' for
this function.
\item For developers, whose 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.
}}
}
\value{
A data frame of indices related to the model's parameters.
}
\description{
Extract and compute indices and measures to describe parameters
of generalized additive models (GAM(M)s).
}
\details{
The reporting of degrees of freedom \emph{for the spline terms}
slightly differs from the output of \code{summary(model)}, for example in the
case of \code{mgcv::gam()}. The \emph{estimated degrees of freedom}, column
\code{edf} in the summary-output, is named \code{df} in the returned data
frame, while the column \code{df_error} in the returned data frame refers to
the residual degrees of freedom that are returned by \code{df.residual()}.
Hence, the values in the the column \code{df_error} differ from the column
\code{Ref.df} from the summary, which is intentional, as these reference
degrees of freedom \dQuote{is not very interpretable}
(\href{https://stat.ethz.ch/pipermail/r-help/2019-March/462135.html}{web}).
}
\examples{
library(parameters)
if (require("mgcv")) {
dat <- gamSim(1, n = 400, dist = "normal", scale = 2)
model <- gam(y ~ s(x0) + s(x1) + s(x2) + s(x3), data = dat)
model_parameters(model)
}
}
\seealso{
\code{\link[insight:standardize_names]{insight::standardize_names()}} to rename
columns into a consistent, standardized naming scheme.
}
parameters/man/figures/ 0000755 0001762 0000144 00000000000 14333155112 014632 5 ustar ligges users parameters/man/figures/card.png 0000644 0001762 0000144 00000152510 14173745737 016301 0 ustar ligges users PNG
IHDR ' m5o pHYs iTXtXML:com.adobe.xmp
} inserts a line break inside a cell. See
'Examples'.
\item \strong{A string indicating a pre-defined layout}
\code{select} can be one of the following string values, to create one of the
following pre-defined column layouts:
\itemize{
\item \code{"ci"}: Estimates and confidence intervals, no asterisks for p-values.
This is equivalent to \code{select = "{estimate} ({ci})"}.
\item \code{"se"}: Estimates and standard errors, no asterisks for p-values. This is
equivalent to \code{select = "{estimate} ({se})"}.
\item \code{"ci_p"}: Estimates, confidence intervals and asterisks for p-values. This
is equivalent to \code{select = "{estimate}{stars} ({ci})"}.
\item \code{"se_p"}: Estimates, standard errors and asterisks for p-values. This is
equivalent to \code{select = "{estimate}{stars} ({se})"}..
\item \code{"ci_p2"}: Estimates, confidence intervals and numeric p-values, in two
columns. This is equivalent to \code{select = "{estimate} ({ci})|{p}"}.
\item \code{"se_p2"}: Estimate, standard errors and numeric p-values, in two columns.
This is equivalent to \code{select = "{estimate} ({se})|{p}"}.
}
}
For \code{model_parameters()}, glue-like syntax is still experimental in the
case of more complex models (like mixed models) and may not return expected
results.}
\item{caption}{Table caption as string. If \code{NULL}, depending on the model,
either a default caption or no table caption is printed. Use \code{caption = ""}
to suppress the table caption.}
\item{subtitle}{Table title (same as caption) and subtitle, as strings. If \code{NULL},
no title or subtitle is printed, unless it is stored as attributes (\code{table_title},
or its alias \code{table_caption}, and \code{table_subtitle}). If \code{x} is a list of
data frames, \code{caption} may be a list of table captions, one for each table.}
\item{footer}{Can either be \code{FALSE} or an empty string (i.e. \code{""}) to
suppress the footer, \code{NULL} to print the default footer, or a string. The
latter will combine the string value with the default footer.}
\item{align}{Only applies to HTML tables. May be one of \code{"left"},
\code{"right"} or \code{"center"}.}
\item{digits, ci_digits, p_digits}{Number of digits for rounding or
significant figures. May also be \code{"signif"} to return significant
figures or \code{"scientific"} to return scientific notation. Control the
number of digits by adding the value as suffix, e.g. \code{digits = "scientific4"}
to have scientific notation with 4 decimal places, or \code{digits = "signif5"}
for 5 significant figures (see also \code{\link[=signif]{signif()}}).}
\item{footer_digits}{Number of decimal places for values in the footer summary.}
\item{ci_brackets}{Logical, if \code{TRUE} (default), CI-values are
encompassed in square brackets (else in parentheses).}
\item{show_sigma}{Logical, if \code{TRUE}, adds information about the residual
standard deviation.}
\item{show_formula}{Logical, if \code{TRUE}, adds the model formula to the output.}
\item{zap_small}{Logical, if \code{TRUE}, small values are rounded after
\code{digits} decimal places. If \code{FALSE}, values with more decimal
places than \code{digits} are printed in scientific notation.}
\item{font_size}{For HTML tables, the font size.}
\item{line_padding}{For HTML tables, the distance (in pixel) between lines.}
\item{column_labels}{Labels of columns for HTML tables. If \code{NULL}, automatic
column names are generated. See 'Examples'.}
\item{include_reference}{Logical, if \code{TRUE}, the reference level of factors will
be added to the parameters table. This is only relevant for models with
categorical predictors. The coefficient for the reference level is always
\code{0} (except when \code{exponentiate = TRUE}, then the coefficient will be \code{1}),
so this is just for completeness.}
\item{verbose}{Toggle messages and warnings.}
\item{...}{Arguments passed down to \code{\link[=format.parameters_model]{format.parameters_model()}},
\code{\link[insight:format_table]{insight::format_table()}} and \code{\link[insight:export_table]{insight::export_table()}}}
\item{sort}{Sort the loadings.}
\item{threshold}{A value between 0 and 1 indicates which (absolute) values
from the loadings should be removed. An integer higher than 1 indicates the
n strongest loadings to retain. Can also be \code{"max"}, in which case it
will only display the maximum loading per variable (the most simple
structure).}
\item{labels}{A character vector containing labels to be added to the
loadings data. Usually, the question related to the item.}
\item{x}{An object returned by \code{\link[=model_parameters]{model_parameters()}}.}
\item{theme}{String, indicating the table theme. Can be one of \code{"default"},
\code{"grid"}, \code{"striped"}, \code{"bootstrap"} or \code{"darklines"}.}
}
\value{
If \code{format = "markdown"}, the return value will be a character
vector in markdown-table format. If \code{format = "html"}, an object of
class \code{gt_tbl}. For \code{print_table()}, an object of class \code{tinytable} is
returned.
}
\description{
Prints tables (i.e. data frame) in different output formats.
\code{print_md()} is an alias for \code{display(format = "markdown")}, \code{print_html()}
is an alias for \code{display(format = "html")}. \code{print_table()} is for specific
use cases only, and currently only works for \code{compare_parameters()} objects.
}
\details{
\code{display()} is useful when the table-output from functions,
which is usually printed as formatted text-table to console, should
be formatted for pretty table-rendering in markdown documents, or if
knitted from rmarkdown to PDF or Word files. See
\href{https://easystats.github.io/parameters/articles/model_parameters_formatting.html}{vignette}
for examples.
\code{print_table()} is a special function for \code{compare_parameters()} objects,
which prints the output as a formatted HTML table. It is still somewhat
experimental, thus, only a fixed layout-style is available at the moment
(columns for estimates, confidence intervals and p-values). However, it
is possible to include other model components, like zero-inflation, or random
effects in the table. See 'Examples'. An alternative is to set \code{engine = "tt"}
in \code{print_html()} to use the \emph{tinytable} package for creating HTML tables.
}
\examples{
\dontshow{if (require("gt", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
model <- lm(mpg ~ wt + cyl, data = mtcars)
mp <- model_parameters(model)
display(mp)
\donttest{
data(iris)
lm1 <- lm(Sepal.Length ~ Species, data = iris)
lm2 <- lm(Sepal.Length ~ Species + Petal.Length, data = iris)
lm3 <- lm(Sepal.Length ~ Species * Petal.Length, data = iris)
out <- compare_parameters(lm1, lm2, lm3)
print_html(
out,
select = "{coef}{stars}|({ci})",
column_labels = c("Estimate", "95\% CI")
)
# line break, unicode minus-sign
print_html(
out,
select = "{estimate}{stars}
({ci_low} \u2212 {ci_high})",
column_labels = c("Est. (95\% CI)")
)
}
\dontshow{\}) # examplesIf}
\dontshow{if (require("tinytable") && require("lme4") && require("glmmTMB")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
\donttest{
data(iris)
data(Salamanders, package = "glmmTMB")
m1 <- lm(Sepal.Length ~ Species * Petal.Length, data = iris)
m2 <- lme4::lmer(
Sepal.Length ~ Petal.Length + Petal.Width + (1 | Species),
data = iris
)
m3 <- glmmTMB::glmmTMB(
count ~ spp + mined + (1 | site),
ziformula = ~mined,
family = poisson(),
data = Salamanders
)
out <- compare_parameters(m1, m2, m3, effects = "all", component = "all")
print_table(out)
}
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[=print.parameters_model]{print.parameters_model()}} and \code{\link[=print.compare_parameters]{print.compare_parameters()}}
}
parameters/man/model_parameters.Rd 0000644 0001762 0000144 00000065607 14721615366 017033 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/1_model_parameters.R
\name{model_parameters}
\alias{model_parameters}
\alias{parameters}
\title{Model Parameters}
\usage{
model_parameters(model, ...)
parameters(model, ...)
}
\arguments{
\item{model}{Statistical Model.}
\item{...}{Arguments passed to or from other methods. Non-documented
arguments are
\itemize{
\item \code{digits}, \code{p_digits}, \code{ci_digits} and \code{footer_digits} to set the number of
digits for the output. \code{groups} can be used to group coefficients. These
arguments will be passed to the print-method, or can directly be used in
\code{print()}, see documentation in \code{\link[=print.parameters_model]{print.parameters_model()}}.
\item If \code{s_value = TRUE}, the p-value will be replaced by the S-value in the
output (cf. \emph{Rafi and Greenland 2020}).
\item \code{pd} adds an additional column with the \emph{probability of direction} (see
\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}} for details). Furthermore, see 'Examples' in
\code{\link[=model_parameters.default]{model_parameters.default()}}.
\item For developers, whose 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.
}}
}
\value{
A data frame of indices related to the model's parameters.
}
\description{
Compute and extract model parameters. The available options and arguments depend
on the modeling \strong{package} and model \code{class}. Follow one of these links to read
the model-specific documentation:
\itemize{
\item \link[=model_parameters.default]{Default method}: \code{lm}, \code{glm}, \strong{stats}, \strong{censReg},
\strong{MASS}, \strong{survey}, ...
\item \link[=model_parameters.cgam]{Additive models}: \strong{bamlss}, \strong{gamlss}, \strong{mgcv},
\strong{scam}, \strong{VGAM}, \code{Gam} (although the output of \code{Gam} is more Anova-alike),
\code{gamm}, ...
\item \link[=model_parameters.aov]{ANOVA}: \strong{afex}, \code{aov}, \code{anova}, \code{Gam}, ...
\item \link[=model_parameters.brmsfit]{Bayesian}: \strong{BayesFactor}, \strong{blavaan}, \strong{brms},
\strong{MCMCglmm}, \strong{posterior}, \strong{rstanarm}, \code{bayesQR}, \code{bcplm}, \code{BGGM}, \code{blmrm},
\code{blrm}, \code{mcmc.list}, \code{MCMCglmm}, ...
\item \link[=model_parameters.hclust]{Clustering}: \strong{hclust}, \strong{kmeans}, \strong{mclust}, \strong{pam}, ...
\item \link[=model_parameters.htest]{Correlations, t-tests, etc.}: \strong{lmtest}, \code{htest},
\code{pairwise.htest}, ...
\item \link[=model_parameters.rma]{Meta-Analysis}: \strong{metaBMA}, \strong{metafor}, \strong{metaplus}, ...
\item \link[=model_parameters.glmmTMB]{Mixed models}: \strong{cplm}, \strong{glmmTMB}, \strong{lme4},
\strong{lmerTest}, \strong{nlme}, \strong{ordinal}, \strong{robustlmm}, \strong{spaMM}, \code{mixed}, \code{MixMod}, ...
\item \link[=model_parameters.mlm]{Multinomial, ordinal and cumulative link}: \strong{brglm2},
\strong{DirichletReg}, \strong{nnet}, \strong{ordinal}, \code{mlm}, ...
\item \link[=model_parameters.mira]{Multiple imputation}: \strong{mice}
\item \link[=model_parameters.principal]{PCA, FA, CFA, SEM}: \strong{FactoMineR}, \strong{lavaan},
\strong{psych}, \code{sem}, ...
\item \link[=model_parameters.zcpglm]{Zero-inflated and hurdle}: \strong{cplm}, \strong{mhurdle},
\strong{pscl}, ...
\item \link[=model_parameters.glimML]{Other models}: \strong{aod}, \strong{bbmle}, \strong{betareg},
\strong{emmeans}, \strong{epiR}, \strong{ggeffects}, \strong{glmx}, \strong{ivfixed}, \strong{ivprobit},
\strong{JRM}, \strong{lmodel2}, \strong{logitsf}, \strong{marginaleffects}, \strong{margins}, \strong{maxLik},
\strong{mediation}, \strong{mfx}, \strong{multcomp}, \strong{mvord}, \strong{plm}, \strong{PMCMRplus},
\strong{quantreg}, \strong{selection}, \strong{systemfit}, \strong{tidymodels}, \strong{varEST},
\strong{WRS2}, \code{bfsl}, \code{deltaMethod}, \code{fitdistr}, \code{mjoint}, \code{mle}, \code{model.avg}, ...
}
}
\details{
A full overview can be found here:
https://easystats.github.io/parameters/reference/
}
\note{
The \code{\link[=print.parameters_model]{print()}} method has several
arguments to tweak the output. There is also a
\href{https://easystats.github.io/see/articles/parameters.html}{\code{plot()}-method}
implemented in the
\href{https://easystats.github.io/see/}{\strong{see}-package}, and a dedicated
method for use inside rmarkdown files,
\code{\link[=print_md.parameters_model]{print_md()}}. \cr \cr \strong{For developers}, if
speed performance is an issue, you can use the (undocumented) \code{pretty_names}
argument, e.g. \code{model_parameters(..., pretty_names = FALSE)}. This will
skip the formatting of the coefficient names and makes \code{model_parameters()}
faster.
}
\section{Standardization of model coefficients}{
Standardization is based on \code{\link[=standardize_parameters]{standardize_parameters()}}. In case
of \code{standardize = "refit"}, the data used to fit the model will be
standardized and the model is completely refitted. In such cases, standard
errors and confidence intervals refer to the standardized coefficient. The
default, \code{standardize = "refit"}, never standardizes categorical predictors
(i.e. factors), which may be a different behaviour compared to other R
packages or other software packages (like SPSS). To mimic behaviour of SPSS
or packages such as \strong{lm.beta}, use \code{standardize = "basic"}.
}
\section{Standardization Methods}{
\itemize{
\item \strong{refit}: This method is based on a complete model re-fit with a
standardized version of the data. Hence, this method is equal to
standardizing the variables before fitting the model. It is the "purest" and
the most accurate (Neter et al., 1989), but it is also the most
computationally costly and long (especially for heavy models such as Bayesian
models). This method is particularly recommended for complex models that
include interactions or transformations (e.g., polynomial or spline terms).
The \code{robust} (default to \code{FALSE}) argument enables a robust standardization
of data, i.e., based on the \code{median} and \code{MAD} instead of the \code{mean} and
\code{SD}. \strong{See \code{\link[datawizard:standardize]{datawizard::standardize()}} for more details.}
\strong{Note} that \code{standardize_parameters(method = "refit")} may not return
the same results as fitting a model on data that has been standardized with
\code{standardize()}; \code{standardize_parameters()} used the data used by the model
fitting function, which might not be same data if there are missing values.
see the \code{remove_na} argument in \code{standardize()}.
\item \strong{posthoc}: Post-hoc standardization of the parameters, aiming at
emulating the results obtained by "refit" without refitting the model. The
coefficients are divided by the standard deviation (or MAD if \code{robust}) of
the outcome (which becomes their expression 'unit'). Then, the coefficients
related to numeric variables are additionally multiplied by the standard
deviation (or MAD if \code{robust}) of the related terms, so that they correspond
to changes of 1 SD of the predictor (e.g., "A change in 1 SD of \code{x} is
related to a change of 0.24 of the SD of \code{y}). This does not apply to binary
variables or factors, so the coefficients are still related to changes in
levels. This method is not accurate and tend to give aberrant results when
interactions are specified.
\item \strong{basic}: This method is similar to \code{method = "posthoc"}, but treats all
variables as continuous: it also scales the coefficient by the standard
deviation of model's matrix' parameter of factors levels (transformed to
integers) or binary predictors. Although being inappropriate for these cases,
this method is the one implemented by default in other software packages,
such as \code{\link[lm.beta:lm.beta]{lm.beta::lm.beta()}}.
\item \strong{smart} (Standardization of Model's parameters with Adjustment,
Reconnaissance and Transformation - \emph{experimental}): Similar to \code{method = "posthoc"} in that it does not involve model refitting. The difference is
that the SD (or MAD if \code{robust}) of the response is computed on the relevant
section of the data. For instance, if a factor with 3 levels A (the
intercept), B and C is entered as a predictor, the effect corresponding to B
vs. A will be scaled by the variance of the response at the intercept only.
As a results, the coefficients for effects of factors are similar to a Glass'
delta.
\item \strong{pseudo} (\emph{for 2-level (G)LMMs only}): In this (post-hoc) method, the
response and the predictor are standardized based on the level of prediction
(levels are detected with \code{\link[performance:check_heterogeneity_bias]{performance::check_heterogeneity_bias()}}): Predictors
are standardized based on their SD at level of prediction (see also
\code{\link[datawizard:demean]{datawizard::demean()}}); The outcome (in linear LMMs) is standardized based
on a fitted random-intercept-model, where \code{sqrt(random-intercept-variance)}
is used for level 2 predictors, and \code{sqrt(residual-variance)} is used for
level 1 predictors (Hoffman 2015, page 342). A warning is given when a
within-group variable is found to have access between-group variance.
}
See also \href{https://easystats.github.io/parameters/articles/standardize_parameters_effsize.html}{package vignette}.
}
\section{Labeling the Degrees of Freedom}{
Throughout the \strong{parameters} package, we decided to label the residual
degrees of freedom \emph{df_error}. The reason for this is that these degrees
of freedom not always refer to the residuals. For certain models, they refer
to the estimate error - in a linear model these are the same, but in - for
instance - any mixed effects model, this isn't strictly true. Hence, we
think that \code{df_error} is the most generic label for these degrees of
freedom.
}
\section{Confidence intervals and approximation of degrees of freedom}{
There are different ways of approximating the degrees of freedom depending
on different assumptions about the nature of the model and its sampling
distribution. The \code{ci_method} argument modulates the method for computing degrees
of freedom (df) that are used to calculate confidence intervals (CI) and the
related p-values. Following options are allowed, depending on the model
class:
\strong{Classical methods:}
Classical inference is generally based on the \strong{Wald method}.
The Wald approach to inference computes a test statistic by dividing the
parameter estimate by its standard error (Coefficient / SE),
then comparing this statistic against a t- or normal distribution.
This approach can be used to compute CIs and p-values.
\code{"wald"}:
\itemize{
\item Applies to \emph{non-Bayesian models}. For \emph{linear models}, CIs
computed using the Wald method (SE and a \emph{t-distribution with residual df});
p-values computed using the Wald method with a \emph{t-distribution with residual df}.
For other models, CIs computed using the Wald method (SE and a \emph{normal distribution});
p-values computed using the Wald method with a \emph{normal distribution}.
}
\code{"normal"}
\itemize{
\item Applies to \emph{non-Bayesian models}. Compute Wald CIs and p-values,
but always use a normal distribution.
}
\code{"residual"}
\itemize{
\item Applies to \emph{non-Bayesian models}. Compute Wald CIs and p-values,
but always use a \emph{t-distribution with residual df} when possible. If the
residual df for a model cannot be determined, a normal distribution is
used instead.
}
\strong{Methods for mixed models:}
Compared to fixed effects (or single-level) models, determining appropriate
df for Wald-based inference in mixed models is more difficult.
See \href{https://bbolker.github.io/mixedmodels-misc/glmmFAQ.html#what-are-the-p-values-listed-by-summaryglmerfit-etc.-are-they-reliable}{the R GLMM FAQ}
for a discussion.
Several approximate methods for computing df are available, but you should
also consider instead using profile likelihood (\code{"profile"}) or bootstrap ("\verb{boot"})
CIs and p-values instead.
\code{"satterthwaite"}
\itemize{
\item Applies to \emph{linear mixed models}. CIs computed using the
Wald method (SE and a \emph{t-distribution with Satterthwaite df}); p-values
computed using the Wald method with a \emph{t-distribution with Satterthwaite df}.
}
\code{"kenward"}
\itemize{
\item Applies to \emph{linear mixed models}. CIs computed using the Wald
method (\emph{Kenward-Roger SE} and a \emph{t-distribution with Kenward-Roger df});
p-values computed using the Wald method with \emph{Kenward-Roger SE and t-distribution with Kenward-Roger df}.
}
\code{"ml1"}
\itemize{
\item Applies to \emph{linear mixed models}. CIs computed using the Wald
method (SE and a \emph{t-distribution with m-l-1 approximated df}); p-values
computed using the Wald method with a \emph{t-distribution with m-l-1 approximated df}.
See \code{\link[=ci_ml1]{ci_ml1()}}.
}
\code{"betwithin"}
\itemize{
\item Applies to \emph{linear mixed models} and \emph{generalized linear mixed models}.
CIs computed using the Wald method (SE and a \emph{t-distribution with between-within df});
p-values computed using the Wald method with a \emph{t-distribution with between-within df}.
See \code{\link[=ci_betwithin]{ci_betwithin()}}.
}
\strong{Likelihood-based methods:}
Likelihood-based inference is based on comparing the likelihood for the
maximum-likelihood estimate to the the likelihood for models with one or more
parameter values changed (e.g., set to zero or a range of alternative values).
Likelihood ratios for the maximum-likelihood and alternative models are compared
to a \eqn{\chi}-squared distribution to compute CIs and p-values.
\code{"profile"}
\itemize{
\item Applies to \emph{non-Bayesian models} of class \code{glm}, \code{polr}, \code{merMod} or \code{glmmTMB}.
CIs computed by \emph{profiling the likelihood curve for a parameter}, using
linear interpolation to find where likelihood ratio equals a critical value;
p-values computed using the Wald method with a \emph{normal-distribution} (note:
this might change in a future update!)
}
\code{"uniroot"}
\itemize{
\item Applies to \emph{non-Bayesian models} of class \code{glmmTMB}. CIs
computed by \emph{profiling the likelihood curve for a parameter}, using root
finding to find where likelihood ratio equals a critical value; p-values
computed using the Wald method with a \emph{normal-distribution} (note: this
might change in a future update!)
}
\strong{Methods for bootstrapped or Bayesian models:}
Bootstrap-based inference is based on \strong{resampling} and refitting the model
to the resampled datasets. The distribution of parameter estimates across
resampled datasets is used to approximate the parameter's sampling
distribution. Depending on the type of model, several different methods for
bootstrapping and constructing CIs and p-values from the bootstrap
distribution are available.
For Bayesian models, inference is based on drawing samples from the model
posterior distribution.
\code{"quantile"} (or \code{"eti"})
\itemize{
\item Applies to \emph{all models (including Bayesian models)}.
For non-Bayesian models, only applies if \code{bootstrap = TRUE}. CIs computed
as \emph{equal tailed intervals} using the quantiles of the bootstrap or
posterior samples; p-values are based on the \emph{probability of direction}.
See \code{\link[bayestestR:eti]{bayestestR::eti()}}.
}
\code{"hdi"}
\itemize{
\item Applies to \emph{all models (including Bayesian models)}. For non-Bayesian
models, only applies if \code{bootstrap = TRUE}. CIs computed as \emph{highest density intervals}
for the bootstrap or posterior samples; p-values are based on the \emph{probability of direction}.
See \code{\link[bayestestR:hdi]{bayestestR::hdi()}}.
}
\code{"bci"} (or \code{"bcai"})
\itemize{
\item Applies to \emph{all models (including Bayesian models)}.
For non-Bayesian models, only applies if \code{bootstrap = TRUE}. CIs computed
as \emph{bias corrected and accelerated intervals} for the bootstrap or
posterior samples; p-values are based on the \emph{probability of direction}.
See \code{\link[bayestestR:bci]{bayestestR::bci()}}.
}
\code{"si"}
\itemize{
\item Applies to \emph{Bayesian models} with proper priors. CIs computed as
\emph{support intervals} comparing the posterior samples against the prior samples;
p-values are based on the \emph{probability of direction}. See \code{\link[bayestestR:si]{bayestestR::si()}}.
}
\code{"boot"}
\itemize{
\item Applies to \emph{non-Bayesian models} of class \code{merMod}. CIs computed
using \emph{parametric bootstrapping} (simulating data from the fitted model);
p-values computed using the Wald method with a \emph{normal-distribution)}
(note: this might change in a future update!).
}
For all iteration-based methods other than \code{"boot"}
(\code{"hdi"}, \code{"quantile"}, \code{"ci"}, \code{"eti"}, \code{"si"}, \code{"bci"}, \code{"bcai"}),
p-values are based on the probability of direction (\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}}),
which is converted into a p-value using \code{\link[bayestestR:pd_to_p]{bayestestR::pd_to_p()}}.
}
\section{Statistical inference - how to quantify evidence}{
There is no standardized approach to drawing conclusions based on the
available data and statistical models. A frequently chosen but also much
criticized approach is to evaluate results based on their statistical
significance (\emph{Amrhein et al. 2017}).
A more sophisticated way would be to test whether estimated effects exceed
the "smallest effect size of interest", to avoid even the smallest effects
being considered relevant simply because they are statistically significant,
but clinically or practically irrelevant (\emph{Lakens et al. 2018, Lakens 2024}).
A rather unconventional approach, which is nevertheless advocated by various
authors, is to interpret results from classical regression models either in
terms of probabilities, similar to the usual approach in Bayesian statistics
(\emph{Schweder 2018; Schweder and Hjort 2003; Vos 2022}) or in terms of relative
measure of "evidence" or "compatibility" with the data (\emph{Greenland et al. 2022;
Rafi and Greenland 2020}), which nevertheless comes close to a probabilistic
interpretation.
A more detailed discussion of this topic is found in the documentation of
\code{\link[=p_function]{p_function()}}.
The \strong{parameters} package provides several options or functions to aid
statistical inference. These are, for example:
\itemize{
\item \code{\link[=equivalence_test.lm]{equivalence_test()}}, to compute the (conditional)
equivalence test for frequentist models
\item \code{\link[=p_significance.lm]{p_significance()}}, to compute the probability of
\emph{practical significance}, which can be conceptualized as a unidirectional
equivalence test
\item \code{\link[=p_function]{p_function()}}, or \emph{consonance function}, to compute p-values and
compatibility (confidence) intervals for statistical models
\item the \code{pd} argument (setting \code{pd = TRUE}) in \code{model_parameters()} includes
a column with the \emph{probability of direction}, i.e. the probability that a
parameter is strictly positive or negative. See \code{\link[bayestestR:p_direction]{bayestestR::p_direction()}}
for details. If plotting is desired, the \code{\link[=p_direction.lm]{p_direction()}}
function can be used, together with \code{plot()}.
\item the \code{s_value} argument (setting \code{s_value = TRUE}) in \code{model_parameters()}
replaces the p-values with their related \emph{S}-values (\emph{Rafi and Greenland 2020})
\item finally, it is possible to generate distributions of model coefficients by
generating bootstrap-samples (setting \code{bootstrap = TRUE}) or simulating
draws from model coefficients using \code{\link[=simulate_model]{simulate_model()}}. These samples
can then be treated as "posterior samples" and used in many functions from
the \strong{bayestestR} package.
}
Most of the above shown options or functions derive from methods originally
implemented for Bayesian models (\emph{Makowski et al. 2019}). However, assuming
that model assumptions are met (which means, the model fits well to the data,
the correct model is chosen that reflects the data generating process
(distributional model family) etc.), it seems appropriate to interpret
results from classical frequentist models in a "Bayesian way" (more details:
documentation in \code{\link[=p_function]{p_function()}}).
}
\section{Interpretation of Interaction Terms}{
Note that the \emph{interpretation} of interaction terms depends on many
characteristics of the model. The number of parameters, and overall
performance of the model, can differ \emph{or not} between \code{a * b},
\code{a : b}, and \code{a / b}, suggesting that sometimes interaction terms
give different parameterizations of the same model, but other times it gives
completely different models (depending on \code{a} or \code{b} being factors
of covariates, included as main effects or not, etc.). Their interpretation
depends of the full context of the model, which should not be inferred
from the parameters table alone - rather, we recommend to use packages
that calculate estimated marginal means or marginal effects, such as
\CRANpkg{modelbased}, \CRANpkg{emmeans}, \CRANpkg{ggeffects}, or
\CRANpkg{marginaleffects}. To raise awareness for this issue, you may use
\code{print(...,show_formula=TRUE)} to add the model-specification to the output
of the \code{\link[=print.parameters_model]{print()}} method for \code{model_parameters()}.
}
\section{Global Options to Customize Messages and Tables when Printing}{
The \code{verbose} argument can be used to display or silence messages and
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_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
printing \code{model_parameters()} objects.
\item \code{parameters_exponentiate}: \code{options(parameters_exponentiate = TRUE)} will
show the additional information on how to interpret coefficients of models
with log-transformed response variables or with log-/logit-links when the
\code{exponentiate} argument in \code{model_parameters()} is not \code{TRUE}. Set this option
to \code{FALSE} to hide this message when printing \code{model_parameters()} objects.
}
There are further options that can be used to modify the default behaviour
for printed outputs:
\itemize{
\item \code{parameters_labels}: \code{options(parameters_labels = TRUE)} will use variable
and value labels for pretty names, if data is labelled. If no labels
available, default pretty names are used.
\item \code{parameters_interaction}: \verb{options(parameters_interaction =