diff --git a/DESCRIPTION b/DESCRIPTION index ca5575ef6..84b882f55 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Type: Package Package: parameters Title: Processing of Model Parameters -Version: 0.23.0.10 +Version: 0.23.0.11 Authors@R: c(person(given = "Daniel", family = "Lüdecke", diff --git a/NEWS.md b/NEWS.md index 10e876bf2..dd50ab627 100644 --- a/NEWS.md +++ b/NEWS.md @@ -11,6 +11,9 @@ * Added support for `anova()` from models of the *survey* package. +* Documentation was re-organized and clarified, and the index reduced by removing + redundant class-documentation. + ## Bug fixes * Fixed bug when extracting 'pretty labels' for model parameters, which could diff --git a/R/1_model_parameters.R b/R/1_model_parameters.R index 458c49600..15f5020e1 100644 --- a/R/1_model_parameters.R +++ b/R/1_model_parameters.R @@ -10,16 +10,17 @@ #' - [Default method][model_parameters.default()]: `lm`, `glm`, **stats**, **censReg**, #' **MASS**, **survey**, ... #' - [Additive models][model_parameters.cgam()]: **bamlss**, **gamlss**, **mgcv**, -#' **scam**, **VGAM**, `Gam`, `gamm`, ... -#' - [ANOVA][model_parameters.aov()]: **afex**, `aov`, `anova`, ... +#' **scam**, **VGAM**, `Gam` (although the output of `Gam` is more Anova-alike), +#' `gamm`, ... +#' - [ANOVA][model_parameters.aov()]: **afex**, `aov`, `anova`, `Gam`, ... #' - [Bayesian][model_parameters.stanreg()]: **BayesFactor**, **blavaan**, **brms**, #' **MCMCglmm**, **posterior**, **rstanarm**, `bayesQR`, `bcplm`, `BGGM`, `blmrm`, #' `blrm`, `mcmc.list`, `MCMCglmm`, ... -#' - [Clustering][model_parameters.kmeans()]: **hclust**, **kmeans**, **mclust**, **pam**, ... +#' - [Clustering][model_parameters.hclust()]: **hclust**, **kmeans**, **mclust**, **pam**, ... #' - [Correlations, t-tests, etc.][model_parameters.htest()]: **lmtest**, `htest`, #' `pairwise.htest`, ... #' - [Meta-Analysis][model_parameters.rma()]: **metaBMA**, **metafor**, **metaplus**, ... -#' - [Mixed models][model_parameters.merMod()]: **cplm**, **glmmTMB**, **lme4**, +#' - [Mixed models][model_parameters.glmmTMB()]: **cplm**, **glmmTMB**, **lme4**, #' **lmerTest**, **nlme**, **ordinal**, **robustlmm**, **spaMM**, `mixed`, `MixMod`, ... #' - [Multinomial, ordinal and cumulative link][model_parameters.mlm()]: **brglm2**, #' **DirichletReg**, **nnet**, **ordinal**, `mlm`, ... @@ -28,13 +29,16 @@ #' **psych**, `sem`, ... #' - [Zero-inflated and hurdle][model_parameters.zcpglm()]: **cplm**, **mhurdle**, #' **pscl**, ... -#' - [Other models][model_parameters.averaging()]: **aod**, **bbmle**, **betareg**, +#' - [Other models][model_parameters.glimML()]: **aod**, **bbmle**, **betareg**, #' **emmeans**, **epiR**, **ggeffects**, **glmx**, **ivfixed**, **ivprobit**, #' **JRM**, **lmodel2**, **logitsf**, **marginaleffects**, **margins**, **maxLik**, #' **mediation**, **mfx**, **multcomp**, **mvord**, **plm**, **PMCMRplus**, #' **quantreg**, **selection**, **systemfit**, **tidymodels**, **varEST**, #' **WRS2**, `bfsl`, `deltaMethod`, `fitdistr`, `mjoint`, `mle`, `model.avg`, ... #' +#' A full overview can be found here: +#' https://easystats.github.io/parameters/reference/ +#' #' @param model Statistical Model. #' @param ... Arguments passed to or from other methods. Non-documented #' arguments are @@ -757,7 +761,6 @@ model_parameters.default <- function(model, #################### .glm ---------------------- -#' @rdname model_parameters.default #' @export model_parameters.glm <- function(model, ci = 0.95, diff --git a/R/2_ci.R b/R/2_ci.R index 9a6da89f1..0c55d3d02 100644 --- a/R/2_ci.R +++ b/R/2_ci.R @@ -6,33 +6,35 @@ #' @param x A statistical model. #' @param ci Confidence Interval (CI) level. Default to `0.95` (`95%`). #' @param dof Number of degrees of freedom to be used when calculating -#' confidence intervals. If `NULL` (default), the degrees of freedom are -#' retrieved by calling [`insight::get_df()`] with approximation method -#' defined in `method`. If not `NULL`, use this argument to override the -#' default degrees of freedom used to compute confidence intervals. -#' @param 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): `"residual"`, -#' `"normal"`, `"likelihood"`, `"satterthwaite"`, `"kenward"`, `"wald"`, -#' `"profile"`, `"boot"`, `"uniroot"`, `"ml1"`, `"betwithin"`, `"hdi"`, -#' `"quantile"`, `"ci"`, `"eti"`, `"si"`, `"bci"`, or `"bcai"`. See section -#' _Confidence intervals and approximation of degrees of freedom_ in -#' [`model_parameters()`] for further details. +#' confidence intervals. If `NULL` (default), the degrees of freedom are +#' retrieved by calling [`insight::get_df()`] with approximation method defined +#' in `method`. If not `NULL`, use this argument to override the default degrees +#' of freedom used to compute confidence intervals. +#' @param 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): `"residual"`, `"normal"`, `"likelihood"`, +#' `"satterthwaite"`, `"kenward"`, `"wald"`, `"profile"`, `"boot"`, `"uniroot"`, +#' `"ml1"`, `"betwithin"`, `"hdi"`, `"quantile"`, `"ci"`, `"eti"`, `"si"`, +#' `"bci"`, or `"bcai"`. See section _Confidence intervals and approximation of +#' degrees of freedom_ in [`model_parameters()`] for further details. #' @param component Model component for which parameters should be shown. See -#' the documentation for your object's class in [`model_parameters()`] or -#' [`p_value()`] for further details. +#' the documentation for your object's class in [`model_parameters()`] or +#' [`p_value()`] for further details, or see section _Model components_. #' @param iterations The number of bootstrap replicates. Only applies to models -#' of class `merMod` when `method=boot`. +#' of class `merMod` when `method=boot`. #' @param verbose Toggle warnings and messages. #' @param ... Additional arguments passed down to the underlying functions. #' E.g., arguments like `vcov` or `vcov_args` can be used to compute confidence #' intervals using a specific variance-covariance matrix for the standard #' errors. +#' @inheritParams standard_error #' #' @return A data frame containing the CI bounds. #' #' @inheritSection model_parameters Confidence intervals and approximation of degrees of freedom #' +#' @inheritSection model_parameters.zcpglm Model components +#' #' @examplesIf require("glmmTMB") && requireNamespace("sandwich") #' data(qol_cancer) #' model <- lm(QoL ~ time + age + education, data = qol_cancer) @@ -57,10 +59,29 @@ #' ci(model, component = "zi") #' } #' @export -ci.default <- function(x, ci = 0.95, dof = NULL, method = NULL, ...) { +ci.default <- function(x, + ci = 0.95, + dof = NULL, + method = NULL, + iterations = 500, + component = "all", + vcov = NULL, + vcov_args = NULL, + verbose = TRUE, + ...) { # check for valid input .is_model_valid(x) - .ci_generic(model = x, ci = ci, dof = dof, method = method, ...) + .ci_generic( + model = x, + ci = ci, + dof = dof, + method = method, + component = component, + vcov = vcov, + vcov_args = vcov_args, + verbose = verbose, + ... + ) } @@ -73,7 +94,10 @@ ci.glm <- function(x, vcov_args = NULL, verbose = TRUE, ...) { - method <- insight::validate_argument(method, c("profile", "wald", "normal", "residual")) + method <- insight::validate_argument( + method, + c("profile", "wald", "normal", "residual") + ) # No robust vcov for profile method if (method == "profile") { diff --git a/R/3_p_value.R b/R/3_p_value.R index e0f0e1bfe..397e71bf0 100644 --- a/R/3_p_value.R +++ b/R/3_p_value.R @@ -2,11 +2,7 @@ #' @name p_value #' #' @description This function attempts to return, or compute, p-values of a model's -#' parameters. See the documentation for your object's class: -#' - [Bayesian models][p_value.BFBayesFactor] (**rstanarm**, **brms**, **MCMCglmm**, ...) -#' - [Zero-inflated models][p_value.zeroinfl] (`hurdle`, `zeroinfl`, `zerocount`, ...) -#' - [Marginal effects models][p_value.poissonmfx] (**mfx**) -#' - [Models with special components][p_value.DirichletRegModel] (`DirichletRegModel`, `clm2`, `cgam`, ...) +#' parameters. #' #' @param model A statistical model. #' @param adjust Character value naming the method used to adjust p-values or @@ -17,14 +13,29 @@ #' #' @inheritSection model_parameters Confidence intervals and approximation of degrees of freedom #' +#' @inheritSection model_parameters.zcpglm Model components +#' +#' @details +#' For Bayesian models, the p-values corresponds to the *probability of +#' direction* ([`bayestestR::p_direction()`]), which is converted to a p-value +#' using `bayestestR::convert_pd_to_p()`. +#' #' @return 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. #' -#' @examples +#' @examplesIf require("pscl", quietly = TRUE) #' 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") #' @export p_value <- function(model, ...) { UseMethod("p_value") diff --git a/R/4_standard_error.R b/R/4_standard_error.R index b7327b108..07a7c9c46 100644 --- a/R/4_standard_error.R +++ b/R/4_standard_error.R @@ -1,6 +1,7 @@ -#' Standard Errors +#' @title Standard Errors +#' @name standard_error #' -#' `standard_error()` attempts to return standard errors of model +#' @description `standard_error()` attempts to return standard errors of model #' parameters. #' #' @param model A model. @@ -21,8 +22,8 @@ #' - Cluster-robust: `"CR"`, `"CR0"`, `"CR1"`, `"CR1p"`, `"CR1S"`, #' `"CR2"`, `"CR3"`. See `?clubSandwich::vcovCR` #' - Bootstrap: `"BS"`, `"xy"`, `"residual"`, `"wild"`, `"mammen"`, -#' `"fractional"`, `"jackknife"`, `"norm"`, `"webb"`. -#' See `?sandwich::vcovBS` +#' `"fractional"`, `"jackknife"`, `"norm"`, `"webb"`. See +#' `?sandwich::vcovBS` #' - Other `sandwich` package functions: `"HAC"`, `"PC"`, `"CL"`, `"OPG"`, #' `"PL"`. #' @param vcov_args List of arguments to be passed to the function identified by @@ -75,6 +76,7 @@ standard_error <- function(model, ...) { #' @rdname standard_error #' @export standard_error.default <- function(model, + effects = "fixed", component = "all", vcov = NULL, vcov_args = NULL, diff --git a/R/5_simulate_model.R b/R/5_simulate_model.R index 41bacfb6e..8cafc20b4 100644 --- a/R/5_simulate_model.R +++ b/R/5_simulate_model.R @@ -15,6 +15,8 @@ #' @inheritParams bootstrap_model #' @inheritParams p_value #' +#' @inheritSection model_parameters.zcpglm Model components +#' #' @return A data frame. #' #' @seealso [`simulate_parameters()`], [`bootstrap_model()`], [`bootstrap_parameters()`] @@ -57,9 +59,9 @@ simulate_model <- function(model, iterations = 1000, ...) { # Models with single component only ----------------------------------------- - +#' @rdname simulate_model #' @export -simulate_model.default <- function(model, iterations = 1000, ...) { +simulate_model.default <- function(model, iterations = 1000, component = "all", ...) { # check for valid input .is_model_valid(model) @@ -229,7 +231,11 @@ simulate_model.bracl <- simulate_model.default # helper ----------------------------------------- -.simulate_model <- function(model, iterations, component = "conditional", effects = "fixed", ...) { +.simulate_model <- function(model, + iterations, + component = "conditional", + effects = "fixed", + ...) { if (is.null(iterations)) iterations <- 1000 params <- insight::get_parameters(model, effects = effects, component = component, verbose = FALSE) diff --git a/R/bootstrap_model.R b/R/bootstrap_model.R index 71d0d11a6..46a18a1ae 100644 --- a/R/bootstrap_model.R +++ b/R/bootstrap_model.R @@ -66,8 +66,9 @@ bootstrap_model <- function(model, bootstrap_model.default <- function(model, iterations = 1000, type = "ordinary", - parallel = c("no", "multicore", "snow"), + parallel = "no", n_cpus = 1, + cluster = NULL, verbose = FALSE, ...) { # check for valid input @@ -75,8 +76,11 @@ bootstrap_model.default <- function(model, insight::check_if_installed("boot") - type <- insight::validate_argument(type, c("ordinary", "parametric", "balanced", "permutation", "antithetic")) - parallel <- match.arg(parallel) + type <- insight::validate_argument( + type, + c("ordinary", "parametric", "balanced", "permutation", "antithetic") + ) + parallel <- insight::validate_argument(parallel, c("no", "multicore", "snow")) model_data <- data <- insight::get_data(model, verbose = FALSE) # nolint model_response <- insight::find_response(model) @@ -144,12 +148,11 @@ bootstrap_model.default <- function(model, } -#' @rdname bootstrap_model #' @export bootstrap_model.merMod <- function(model, iterations = 1000, type = "parametric", - parallel = c("no", "multicore", "snow"), + parallel = "no", n_cpus = 1, cluster = NULL, verbose = FALSE, @@ -157,7 +160,7 @@ bootstrap_model.merMod <- function(model, insight::check_if_installed("lme4") type <- insight::validate_argument(type, c("parametric", "semiparametric")) - parallel <- match.arg(parallel) + parallel <- insight::validate_argument(parallel, c("no", "multicore", "snow")) boot_function <- function(model) { params <- insight::get_parameters(model, verbose = FALSE) @@ -222,14 +225,17 @@ bootstrap_model.glmmTMB <- bootstrap_model.merMod bootstrap_model.nestedLogit <- function(model, iterations = 1000, type = "ordinary", - parallel = c("no", "multicore", "snow"), + parallel = "no", n_cpus = 1, verbose = FALSE, ...) { insight::check_if_installed("boot") - type <- insight::validate_argument(type, c("ordinary", "balanced", "permutation", "antithetic")) - parallel <- match.arg(parallel) + type <- insight::validate_argument( + type, + c("ordinary", "balanced", "permutation", "antithetic") + ) + parallel <- insight::validate_argument(parallel, c("no", "multicore", "snow")) model_data <- data <- insight::get_data(model, verbose = FALSE) # nolint model_response <- insight::find_response(model) diff --git a/R/cluster_performance.R b/R/cluster_performance.R index 9c7f506db..3cae1dfde 100644 --- a/R/cluster_performance.R +++ b/R/cluster_performance.R @@ -2,19 +2,28 @@ #' #' Compute performance indices for clustering solutions. #' -#' @inheritParams model_parameters.kmeans +#' @inheritParams model_parameters.hclust #' #' @examples #' # kmeans #' model <- kmeans(iris[1:4], 3) #' cluster_performance(model) +#' +#' # hclust +#' data <- iris[1:4] +#' model <- hclust(dist(data)) +#' clusters <- cutree(model, 3) +#' cluster_performance(model, data, clusters) +#' +#' # Retrieve performance from parameters +#' params <- model_parameters(kmeans(iris[1:4], 3)) +#' cluster_performance(params) #' @export cluster_performance <- function(model, ...) { UseMethod("cluster_performance") } -#' @rdname cluster_performance #' @export cluster_performance.kmeans <- function(model, ...) { out <- as.data.frame(model[c("totss", "betweenss", "tot.withinss")]) @@ -29,18 +38,7 @@ cluster_performance.kmeans <- function(model, ...) { } - - - #' @rdname cluster_performance -#' @examples -#' # hclust -#' data <- iris[1:4] -#' model <- hclust(dist(data)) -#' clusters <- cutree(model, 3) -#' -#' rez <- cluster_performance(model, data, clusters) -#' rez #' @export cluster_performance.hclust <- function(model, data, clusters, ...) { if (is.null(data)) { @@ -60,13 +58,6 @@ cluster_performance.hclust <- function(model, data, clusters, ...) { } -#' @rdname cluster_performance -#' @examplesIf require("dbscan", quietly = TRUE) -#' # DBSCAN -#' model <- dbscan::dbscan(iris[1:4], eps = 1.45, minPts = 10) -#' -#' rez <- cluster_performance(model, iris[1:4]) -#' rez #' @export cluster_performance.dbscan <- function(model, data, ...) { if (is.null(data)) { @@ -84,12 +75,6 @@ cluster_performance.dbscan <- function(model, data, ...) { # Base -------------------------------------------------------------------- - -#' @rdname cluster_performance -#' @examples -#' # Retrieve performance from parameters -#' params <- model_parameters(kmeans(iris[1:4], 3)) -#' cluster_performance(params) #' @export cluster_performance.parameters_clusters <- function(model, ...) { valid <- model$Cluster != 0 & model$Cluster != "0" # Valid clusters diff --git a/R/compare_parameters.R b/R/compare_parameters.R index 9d4d49e43..2b23ceeea 100644 --- a/R/compare_parameters.R +++ b/R/compare_parameters.R @@ -22,7 +22,7 @@ #' used for all coefficient columns. If `NULL`, the name for the coefficient #' column will detected automatically (as in `model_parameters()`). #' @inheritParams model_parameters.default -#' @inheritParams model_parameters.cpglmm +#' @inheritParams model_parameters.glmmTMB #' @inheritParams print.parameters_model #' #' @details diff --git a/R/equivalence_test.R b/R/equivalence_test.R index 8247de837..93aea99fb 100644 --- a/R/equivalence_test.R +++ b/R/equivalence_test.R @@ -20,7 +20,7 @@ bayestestR::equivalence_test #' for details. #' @param verbose Toggle warnings and messages. #' @param ... Arguments passed to or from other methods. -#' @inheritParams model_parameters.merMod +#' @inheritParams model_parameters.glmmTMB #' @inheritParams p_value #' #' @seealso For more details, see [bayestestR::equivalence_test()]. Further @@ -241,11 +241,12 @@ equivalence_test.lm <- function(x, range = "default", ci = 0.95, rule = "classic", + effects = "fixed", vcov = NULL, vcov_args = NULL, verbose = TRUE, ...) { - rule <- match.arg(tolower(rule), choices = c("bayes", "classic", "cet")) + rule <- insight::validate_argument(tolower(rule), c("bayes", "classic", "cet")) out <- .equivalence_test_frequentist( x, range = range, @@ -309,21 +310,20 @@ equivalence_test.rma <- equivalence_test.lm # mixed models, also random effects ---------------------- -#' @rdname equivalence_test.lm #' @export equivalence_test.merMod <- function(x, range = "default", ci = 0.95, rule = "classic", - effects = c("fixed", "random"), + effects = "fixed", vcov = NULL, vcov_args = NULL, verbose = TRUE, ...) { # ==== argument matching ==== - rule <- match.arg(tolower(rule), choices = c("bayes", "classic", "cet")) - effects <- match.arg(effects) + rule <- insight::validate_argument(tolower(rule), c("bayes", "classic", "cet")) + effects <- insight::validate_argument(effects, c("fixed", "random")) # ==== equivalent testing for fixed or random effects ==== diff --git a/R/extract_random_variances.R b/R/extract_random_variances.R index 368779fe8..ddc159155 100644 --- a/R/extract_random_variances.R +++ b/R/extract_random_variances.R @@ -45,7 +45,10 @@ ci_random = NULL, verbose = FALSE, ...) { - component <- insight::validate_argument(component, c("all", "conditional", "zero_inflated", "zi", "dispersion")) + component <- insight::validate_argument( + component, + c("all", "conditional", "zero_inflated", "zi", "dispersion") + ) out <- suppressWarnings( .extract_random_variances_helper( diff --git a/R/methods_BayesFactor.R b/R/methods_BayesFactor.R index cb8b85cd8..af09804ae 100644 --- a/R/methods_BayesFactor.R +++ b/R/methods_BayesFactor.R @@ -243,24 +243,6 @@ model_parameters.BFBayesFactor <- function(model, } -#' p-values for Bayesian Models -#' -#' This function attempts to return, or compute, p-values of Bayesian models. -#' -#' @param model A statistical model. -#' @inheritParams p_value -#' -#' @details -#' For Bayesian models, the p-values corresponds to the *probability of -#' direction* ([`bayestestR::p_direction()`]), which is converted to a p-value -#' using `bayestestR::convert_pd_to_p()`. -#' -#' @return The p-values. -#' -#' @examples -#' data(iris) -#' model <- lm(Petal.Length ~ Sepal.Length + Species, data = iris) -#' p_value(model) #' @export p_value.BFBayesFactor <- function(model, ...) { p <- bayestestR::p_direction(model) diff --git a/R/methods_DirichletReg.R b/R/methods_DirichletReg.R index 300a8c2a0..2b9233702 100644 --- a/R/methods_DirichletReg.R +++ b/R/methods_DirichletReg.R @@ -1,10 +1,9 @@ -#' @rdname model_parameters.mlm #' @export model_parameters.DirichletRegModel <- function(model, ci = 0.95, bootstrap = FALSE, iterations = 1000, - component = c("all", "conditional", "precision"), + component = "all", standardize = NULL, exponentiate = FALSE, p_adjust = NULL, @@ -12,7 +11,10 @@ model_parameters.DirichletRegModel <- function(model, drop = NULL, verbose = TRUE, ...) { - component <- match.arg(component) + component <- insight::validate_argument( + component, + c("all", "conditional", "precision") + ) if (component == "all") { merge_by <- c("Parameter", "Component", "Response") } else { @@ -45,11 +47,11 @@ model_parameters.DirichletRegModel <- function(model, #' @export -ci.DirichletRegModel <- function(x, - ci = 0.95, - component = c("all", "conditional", "precision"), - ...) { - component <- match.arg(component) +ci.DirichletRegModel <- function(x, ci = 0.95, component = "all", ...) { + component <- insight::validate_argument( + component, + c("all", "conditional", "precision") + ) params <- insight::get_parameters(x, component = component) out <- .ci_generic(model = x, ci = ci, dof = Inf, ...) @@ -68,10 +70,11 @@ ci.DirichletRegModel <- function(x, #' @export -standard_error.DirichletRegModel <- function(model, - component = "all", - ...) { - component <- match.arg(component, choices = c("all", "conditional", "precision")) +standard_error.DirichletRegModel <- function(model, component = "all", ...) { + component <- insight::validate_argument( + component, + c("all", "conditional", "precision") + ) params <- insight::get_parameters(model) out <- .data_frame( @@ -80,10 +83,10 @@ standard_error.DirichletRegModel <- function(model, SE = as.vector(model$se) ) - if (!is.null(params$Component)) { - out$Component <- params$Component - } else { + if (is.null(params$Component)) { component <- "all" + } else { + out$Component <- params$Component } if (component != "all") { @@ -94,25 +97,12 @@ standard_error.DirichletRegModel <- function(model, } -#' @title p-values for Models with Special Components -#' @name p_value.DirichletRegModel -#' -#' @description This function attempts to return, or compute, p-values of models -#' with special model components. -#' -#' @param model A statistical model. -#' @param component Should all parameters, parameters for the conditional model, -#' precision- or scale-component or smooth_terms be returned? `component` -#' may be one of `"conditional"`, `"precision"`, `"scale"`, -#' `"smooth_terms"`, `"full"` or `"all"` (default). -#' @inheritParams p_value -#' -#' @return The p-values. #' @export -p_value.DirichletRegModel <- function(model, - component = c("all", "conditional", "precision"), - ...) { - component <- match.arg(component) +p_value.DirichletRegModel <- function(model, component = "all", ...) { + component <- insight::validate_argument( + component, + c("all", "conditional", "precision") + ) params <- insight::get_parameters(model) out <- .data_frame( @@ -121,10 +111,10 @@ p_value.DirichletRegModel <- function(model, p = as.vector(2 * stats::pnorm(-abs(params$Estimate / model$se))) ) - if (!is.null(params$Component)) { - out$Component <- params$Component - } else { + if (is.null(params$Component)) { component <- "all" + } else { + out$Component <- params$Component } if (component != "all") { diff --git a/R/methods_MCMCglmm.R b/R/methods_MCMCglmm.R index 296307485..d83240b61 100644 --- a/R/methods_MCMCglmm.R +++ b/R/methods_MCMCglmm.R @@ -21,7 +21,6 @@ p_value.MCMCglmm <- function(model, ...) { } -#' @rdname model_parameters.stanreg #' @export model_parameters.MCMCglmm <- function(model, centrality = "median", diff --git a/R/methods_aod.R b/R/methods_aod.R index ef067d3e2..1e6945960 100644 --- a/R/methods_aod.R +++ b/R/methods_aod.R @@ -6,14 +6,46 @@ #################### .glimML ------ - -#' @rdname model_parameters.averaging +#' @title Parameters from special models +#' @name model_parameters.glimML +#' +#' @description +#' Parameters from special regression models not listed under one of the +#' previous categories yet. +#' +#' @param component Model component for which parameters should be shown. May be +#' one of `"conditional"`, `"precision"` (e.g. **betareg**), `"scale"` (e.g. +#' **ordinal**), `"extra"` (e.g. **glmx**), `"marginal"` (e.g. **mfx**), +#' `"conditional"` or `"full"` (for `MuMIn::model.avg()`) or `"all"`. See section +#' _Model components_ for an overview of possible options for `component`. +#' @inheritParams model_parameters.default +#' @inheritParams model_parameters.brmsfit +#' @inheritParams simulate_model +#' +#' @seealso [insight::standardize_names()] to rename columns into a consistent, +#' standardized naming scheme. +#' +#' @inheritSection model_parameters.zcpglm Model components +#' +#' @examples +#' library(parameters) +#' if (require("brglm2", quietly = TRUE)) { +#' data("stemcell") +#' model <- bracl( +#' research ~ as.numeric(religion) + gender, +#' weights = frequency, +#' data = stemcell, +#' type = "ML" +#' ) +#' model_parameters(model) +#' } +#' @return A data frame of indices related to the model's parameters. #' @export model_parameters.glimML <- function(model, ci = 0.95, bootstrap = FALSE, iterations = 1000, - component = c("conditional", "random", "dispersion", "all"), + component = "conditional", standardize = NULL, exponentiate = FALSE, p_adjust = NULL, @@ -23,7 +55,10 @@ model_parameters.glimML <- function(model, drop = NULL, verbose = TRUE, ...) { - component <- match.arg(component) + component <- insight::validate_argument( + component, + c("conditional", "random", "dispersion", "all") + ) if (component == "all") { merge_by <- c("Parameter", "Component") } else { diff --git a/R/methods_aov.R b/R/methods_aov.R index a70f25e6e..b3af12ea6 100644 --- a/R/methods_aov.R +++ b/R/methods_aov.R @@ -247,7 +247,6 @@ model_parameters.aovlist <- model_parameters.aov # .afex_aov ------ -#' @rdname model_parameters.aov #' @export model_parameters.afex_aov <- function(model, es_type = NULL, @@ -366,7 +365,10 @@ model_parameters.seqanova.svyglm <- model_parameters.aov .anova_alternative <- function(params, alternative) { alternative_footer <- NULL if (!is.null(alternative)) { - alternative <- match.arg(tolower(alternative), choices = c("two.sided", "greater", "less")) + alternative <- insight::validate_argument( + tolower(alternative), + c("two.sided", "greater", "less") + ) if (alternative != "two.sided") { ci_low <- which(endsWith(colnames(params), "CI_low")) ci_high <- which(endsWith(colnames(params), "CI_high")) diff --git a/R/methods_averaging.R b/R/methods_averaging.R index f3c7e00a3..c2abcbf05 100644 --- a/R/methods_averaging.R +++ b/R/methods_averaging.R @@ -2,42 +2,10 @@ #################### .averaging - -#' Parameters from special models -#' -#' Parameters from special regression models not listed under one of the previous categories yet. -#' -#' @param component Model component for which parameters should be shown. May be -#' one of `"conditional"`, `"precision"` (**betareg**), -#' `"scale"` (**ordinal**), `"extra"` (**glmx**), -#' `"marginal"` (**mfx**), `"conditional"` or `"full"` (for -#' `MuMIn::model.avg()`) or `"all"`. -#' @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.stanreg -#' @inheritParams simulate_model -#' -#' @seealso [insight::standardize_names()] to rename -#' columns into a consistent, standardized naming scheme. -#' -#' @examples -#' library(parameters) -#' if (require("brglm2", quietly = TRUE)) { -#' data("stemcell") -#' model <- bracl( -#' research ~ as.numeric(religion) + gender, -#' weights = frequency, -#' data = stemcell, -#' type = "ML" -#' ) -#' model_parameters(model) -#' } -#' @return A data frame of indices related to the model's parameters. #' @export model_parameters.averaging <- function(model, ci = 0.95, - component = c("conditional", "full"), + component = "conditional", exponentiate = FALSE, p_adjust = NULL, summary = getOption("parameters_summary", FALSE), @@ -46,7 +14,7 @@ model_parameters.averaging <- function(model, drop = NULL, verbose = TRUE, ...) { - component <- match.arg(component) + component <- insight::validate_argument(component, c("conditional", "full")) ## TODO remove deprecated later if (!missing(summary)) { @@ -74,7 +42,7 @@ model_parameters.averaging <- function(model, #' @export standard_error.averaging <- function(model, component = "conditional", ...) { - component <- match.arg(component, choices = c("conditional", "full")) + component <- insight::validate_argument(component, c("conditional", "full")) params <- insight::get_parameters(model, component = component) if (component == "full") { s <- summary(model)$coefmat.full @@ -88,10 +56,9 @@ standard_error.averaging <- function(model, component = "conditional", ...) { } -#' @rdname p_value.DirichletRegModel #' @export -p_value.averaging <- function(model, component = c("conditional", "full"), ...) { - component <- match.arg(component) +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 @@ -107,7 +74,7 @@ p_value.averaging <- function(model, component = c("conditional", "full"), ...) #' @export -ci.averaging <- function(x, ci = 0.95, component = c("conditional", "full"), ...) { - component <- match.arg(component) +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) } diff --git a/R/methods_bamlss.R b/R/methods_bamlss.R index 9b8c540bc..8c58d7244 100644 --- a/R/methods_bamlss.R +++ b/R/methods_bamlss.R @@ -1,4 +1,3 @@ -#' @inheritParams insight::get_parameters #' @export model_parameters.bamlss <- function(model, centrality = "median", diff --git a/R/methods_base.R b/R/methods_base.R index 08236bab4..1e071ca52 100644 --- a/R/methods_base.R +++ b/R/methods_base.R @@ -1,4 +1,4 @@ -#' @rdname model_parameters.stanreg +#' @rdname model_parameters.brmsfit #' @export model_parameters.data.frame <- function(model, as_draws = FALSE, diff --git a/R/methods_betareg.R b/R/methods_betareg.R index 37fbb8124..8c3434b4b 100644 --- a/R/methods_betareg.R +++ b/R/methods_betareg.R @@ -1,12 +1,11 @@ ## TODO add ci_method later? -#' @rdname model_parameters.averaging #' @export model_parameters.betareg <- function(model, ci = 0.95, bootstrap = FALSE, iterations = 1000, - component = c("conditional", "precision", "all"), + component = "conditional", standardize = NULL, exponentiate = FALSE, p_adjust = NULL, @@ -30,7 +29,7 @@ model_parameters.betareg <- function(model, include_info <- summary } - component <- match.arg(component) + component <- insight::validate_argument(component, c("conditional", "precision", "all")) if (component == "all") { merge_by <- c("Parameter", "Component") } else { @@ -64,11 +63,7 @@ model_parameters.betareg <- function(model, #' @export -ci.betareg <- function(x, - ci = 0.95, - component = "all", - verbose = TRUE, - ...) { +ci.betareg <- function(x, ci = 0.95, component = "all", verbose = TRUE, ...) { # validation check, warn if unsupported argument is used. dot_args <- .check_dots( dots = list(...), @@ -84,10 +79,7 @@ ci.betareg <- function(x, #' @export -standard_error.betareg <- function(model, - component = "all", - verbose = TRUE, - ...) { +standard_error.betareg <- function(model, component = "all", verbose = TRUE, ...) { # validation check, warn if unsupported argument is used. dot_args <- .check_dots( dots = list(...), @@ -117,12 +109,8 @@ standard_error.betareg <- function(model, } -#' @rdname p_value.DirichletRegModel #' @export -p_value.betareg <- function(model, - component = c("all", "conditional", "precision"), - verbose = TRUE, - ...) { +p_value.betareg <- function(model, component = "all", verbose = TRUE, ...) { # validation check, warn if unsupported argument is used. dot_args <- .check_dots( dots = list(...), @@ -132,7 +120,10 @@ p_value.betareg <- function(model, verbose = verbose ) - component <- match.arg(component) + component <- insight::validate_argument( + component, + c("all", "conditional", "precision") + ) params <- insight::get_parameters(model) cs <- do.call(rbind, stats::coef(summary(model))) @@ -153,11 +144,11 @@ p_value.betareg <- function(model, #' @export -simulate_model.betareg <- function(model, - iterations = 1000, - component = c("all", "conditional", "precision"), - ...) { - component <- match.arg(component) +simulate_model.betareg <- function(model, iterations = 1000, component = "all", ...) { + component <- insight::validate_argument( + component, + c("all", "conditional", "precision") + ) out <- .simulate_model(model, iterations, component = component, ...) class(out) <- c("parameters_simulate_model", class(out)) diff --git a/R/methods_brms.R b/R/methods_brms.R index c2a7637fa..c6eff080c 100644 --- a/R/methods_brms.R +++ b/R/methods_brms.R @@ -1,5 +1,69 @@ -#' @rdname model_parameters.stanreg +#' @title Parameters from Bayesian Models +#' @name model_parameters.brmsfit +#' +#' @description +#' Model parameters from Bayesian models. This function internally calls +#' [`bayestestR::describe_posterior()`] to get the relevant information for +#' the output. +#' +#' @param model Bayesian model (including SEM from **blavaan**. May also be +#' a data frame with posterior samples, however, `as_draws` must be set to +#' `TRUE` (else, for data frames `NULL` is returned). +#' @param ci Credible Interval (CI) level. Default to `0.95` (`95%`). See +#' [bayestestR::ci()] for further details. +#' @param group_level Logical, for multilevel models (i.e. models with random +#' effects) and when `effects = "all"` or `effects = "random"`, +#' include the parameters for each group level from random effects. If +#' `group_level = FALSE` (the default), only information on SD and COR +#' are shown. +#' @param 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 `sigma` +#' should be included. May be abbreviated. Note that the *conditional* +#' component is also called *count* or *mean* component, depending on the +#' model. There are three convenient shortcuts: `component = "all"` returns +#' all possible parameters. If `component = "location"`, location parameters +#' such as `conditional`, `zero_inflated`, or `smooth_terms`, are returned +#' (everything that are fixed or random effects - depending on the `effects` +#' argument - but no auxiliary parameters). For `component = "distributional"` +#' (or `"auxiliary"`), components like `sigma`, `dispersion`, or `beta` +#' (and other auxiliary parameters) are returned. +#' @param as_draws Logical, if `TRUE` and `model` is of class `data.frame`, +#' the data frame is treated as posterior samples and handled similar to +#' Bayesian models. All arguments in `...` are passed to +#' `model_parameters.draws()`. +#' @inheritParams model_parameters.default +#' @inheritParams bayestestR::describe_posterior #' @inheritParams insight::get_parameters +#' +#' @seealso [insight::standardize_names()] to rename columns into a consistent, +#' standardized naming scheme. +#' +#' @note When `standardize = "refit"`, columns `diagnostic`, `bf_prior` and +#' `priors` refer to the *original* `model`. If `model` is a data frame, +#' arguments `diagnostic`, `bf_prior` and `priors` are ignored. +#' +#' There is also a +#' [`plot()`-method](https://easystats.github.io/see/articles/parameters.html) +#' implemented in the [**see**-package](https://easystats.github.io/see/). +#' +#' @inheritSection model_parameters Confidence intervals and approximation of degrees of freedom +#' +#' @inheritSection model_parameters.zcpglm Model components +#' +#' @examples +#' \donttest{ +#' library(parameters) +#' if (require("rstanarm")) { +#' model <- suppressWarnings(stan_glm( +#' Sepal.Length ~ Petal.Length * Species, +#' data = iris, iter = 500, refresh = 0 +#' )) +#' model_parameters(model) +#' } +#' } +#' @return A data frame of indices related to the model's parameters. #' @export model_parameters.brmsfit <- function(model, centrality = "median", @@ -209,11 +273,17 @@ model_parameters.brmsfit <- function(model, #' @export standard_error.brmsfit <- function(model, - effects = c("fixed", "random"), - component = c("all", "conditional", "zi", "zero_inflated"), + effects = "fixed", + component = "all", ...) { - effects <- match.arg(effects) - component <- match.arg(component) + effects <- insight::validate_argument( + effects, + c("fixed", "random") + ) + component <- insight::validate_argument( + component, + c("all", "conditional", "zi", "zero_inflated") + ) params <- insight::get_parameters(model, effects = effects, component = component, ...) diff --git a/R/methods_censReg.R b/R/methods_censReg.R index d17667da1..2d60883ee 100644 --- a/R/methods_censReg.R +++ b/R/methods_censReg.R @@ -1,4 +1,3 @@ -#' @rdname model_parameters.default #' @export model_parameters.censReg <- model_parameters.default diff --git a/R/methods_cgam.R b/R/methods_cgam.R index 0204efa0f..1f9fc0422 100644 --- a/R/methods_cgam.R +++ b/R/methods_cgam.R @@ -126,11 +126,12 @@ model_parameters.cgam <- function(model, } - -#' @rdname p_value.DirichletRegModel #' @export -p_value.cgam <- function(model, component = c("all", "conditional", "smooth_terms"), ...) { - component <- match.arg(component) +p_value.cgam <- function(model, component = "all", ...) { + component <- insight::validate_argument( + component, + c("all", "conditional", "smooth_terms") + ) params <- insight::get_parameters(model, component = "all") cs <- summary(model) diff --git a/R/methods_cplm.R b/R/methods_cplm.R index ad8efa25f..2419fde97 100644 --- a/R/methods_cplm.R +++ b/R/methods_cplm.R @@ -18,21 +18,58 @@ #' @seealso [insight::standardize_names()] to rename #' columns into a consistent, standardized naming scheme. #' -#' @examples -#' library(parameters) -#' if (require("pscl")) { -#' data("bioChemists") -#' model <- zeroinfl(art ~ fem + mar + kid5 + ment | kid5 + phd, data = bioChemists) -#' model_parameters(model) -#' } +#' @section Model components: +#' Possible values for the `component` argument depend on the model class. +#' Following are valid options: +#' - `"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. +#' - `"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. +#' - `"smooth_terms"`: returns smooth terms, only applies to GAMs (or similar +#' models that may contain smooth terms). +#' - `"zero_inflated"` (or `"zi"`): returns the zero-inflation component. +#' - `"dispersion"`: returns the dispersion model component. This is common +#' for models with zero-inflation or that can model the dispersion parameter. +#' - `"instruments"`: for instrumental-variable or some fixed effects regression, +#' returns the instruments. +#' - `"nonlinear"`: for non-linear models (like models of class `nlmerMod` or +#' `nls`), returns staring estimates for the nonlinear parameters. +#' - `"correlation"`: for models with correlation-component, like `gls`, the +#' variables used to describe the correlation structure are returned. +#' +#' **Special models** +#' +#' Some model classes also allow rather uncommon options. These are: +#' - **mhurdle**: `"infrequent_purchase"`, `"ip"`, and `"auxiliary"` +#' - **BGGM**: `"correlation"` and `"intercept"` +#' - **BFBayesFactor**, **glmx**: `"extra"` +#' - **averaging**:`"conditional"` and `"full"` +#' - **mjoint**: `"survival"` +#' - **mfx**: `"precision"`, `"marginal"` +#' - **betareg**, **DirichletRegModel**: `"precision"` +#' - **mvord**: `"thresholds"` and `"correlation"` +#' - **clm2**: `"scale"` +#' - **selection**: `"selection"`, `"outcome"`, and `"auxiliary"` +#' +#' For models of class `brmsfit` (package **brms**), even more options are +#' possible for the `component` argument, which are not all documented in detail +#' here. +#' +#' @examplesIf require("pscl") +#' data("bioChemists", package = "pscl") +#' model <- pscl::zeroinfl( +#' art ~ fem + mar + kid5 + ment | kid5 + phd, +#' data = bioChemists +#' ) +#' model_parameters(model) #' @return A data frame of indices related to the model's parameters. -#' @inheritParams simulate_model #' @export model_parameters.zcpglm <- function(model, ci = 0.95, bootstrap = FALSE, iterations = 1000, - component = c("all", "conditional", "zi", "zero_inflated"), + component = "all", standardize = NULL, exponentiate = FALSE, p_adjust = NULL, @@ -42,7 +79,7 @@ model_parameters.zcpglm <- function(model, drop = NULL, verbose = TRUE, ...) { - component <- match.arg(component) + component <- insight::validate_argument(component, c("all", "conditional", "zi", "zero_inflated")) # fix argument, if model has no zi-part if (!insight::model_info(model, verbose = FALSE)$is_zero_inflated && component != "conditional") { @@ -93,12 +130,13 @@ model_parameters.zcpglm <- function(model, #' @export -standard_error.zcpglm <- function(model, - component = c("all", "conditional", "zi", "zero_inflated"), - ...) { +standard_error.zcpglm <- function(model, component = "all", ...) { insight::check_if_installed("cplm") - component <- match.arg(component) + component <- insight::validate_argument( + component, + c("all", "conditional", "zi", "zero_inflated") + ) junk <- utils::capture.output(stats <- cplm::summary(model)$coefficients) # nolint params <- insight::get_parameters(model) @@ -119,34 +157,14 @@ standard_error.zcpglm <- function(model, } -#' p-values for Models with Zero-Inflation -#' -#' This function attempts to return, or compute, p-values of hurdle and -#' zero-inflated models. -#' -#' @param model A statistical model. -#' @inheritParams p_value -#' @inheritParams simulate_model -#' @inheritParams standard_error -#' -#' @return -#' 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. -#' -#' @examples -#' if (require("pscl", quietly = TRUE)) { -#' data("bioChemists") -#' model <- zeroinfl(art ~ fem + mar + kid5 | kid5 + phd, data = bioChemists) -#' p_value(model) -#' p_value(model, component = "zi") -#' } #' @export -p_value.zcpglm <- function(model, - component = c("all", "conditional", "zi", "zero_inflated"), - ...) { +p_value.zcpglm <- function(model, component = "all", ...) { insight::check_if_installed("cplm") - component <- match.arg(component) + component <- insight::validate_argument( + component, + c("all", "conditional", "zi", "zero_inflated") + ) junk <- utils::capture.output(stats <- cplm::summary(model)$coefficients) # nolint params <- insight::get_parameters(model) @@ -168,7 +186,6 @@ p_value.zcpglm <- function(model, - ########## .bcpglm --------------- #' @export @@ -180,10 +197,8 @@ p_value.bcplm <- p_value.brmsfit - ########## .cpglm --------------- - #' @export p_value.cpglm <- function(model, ...) { insight::check_if_installed("cplm") @@ -213,12 +228,8 @@ standard_error.cpglm <- function(model, ...) { - - ########## .cpglmm --------------- - -#' @rdname model_parameters.merMod #' @export model_parameters.cpglmm <- function(model, ci = 0.95, @@ -238,7 +249,7 @@ model_parameters.cpglmm <- function(model, ...) { # p-values, CI and se might be based on different df-methods ci_method <- .check_df_method(ci_method) - effects <- match.arg(effects, choices = c("fixed", "random", "all")) + effects <- insight::validate_argument(effects, c("fixed", "random", "all")) # standardize only works for fixed effects... if (!is.null(standardize) && standardize != "refit") { @@ -296,7 +307,6 @@ standard_error.cpglmm <- function(model, ...) { - # tools -------------------- .check_df_method <- function(df_method) { @@ -306,7 +316,13 @@ standard_error.cpglmm <- function(model, ...) { insight::format_alert("Satterthwaite or Kenward-Rogers approximation of degrees of freedom is only available for linear mixed models.") df_method <- "wald" } - df_method <- match.arg(df_method, choices = c("wald", "normal", "residual", "ml1", "betwithin", "profile", "boot", "uniroot")) + df_method <- insight::validate_argument( + df_method, + c( + "wald", "normal", "residual", "ml1", "betwithin", "profile", + "boot", "uniroot" + ) + ) } df_method } diff --git a/R/methods_dbscan.R b/R/methods_dbscan.R index 7ccfbb9b9..965539a9a 100644 --- a/R/methods_dbscan.R +++ b/R/methods_dbscan.R @@ -1,30 +1,3 @@ -#' @rdname model_parameters.kmeans -#' @inheritParams cluster_centers -#' -#' @examples -#' \donttest{ -#' # DBSCAN --------------------------- -#' if (require("dbscan", quietly = TRUE)) { -#' 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.dbscan <- function(model, data = NULL, clusters = NULL, ...) { if (is.null(data)) { diff --git a/R/methods_emmeans.R b/R/methods_emmeans.R index c8ed97188..1cd68e539 100644 --- a/R/methods_emmeans.R +++ b/R/methods_emmeans.R @@ -142,7 +142,6 @@ model_parameters.emmGrid <- function(model, } -#' @rdname model_parameters.averaging #' @export model_parameters.emm_list <- function(model, ci = 0.95, diff --git a/R/methods_glmmTMB.R b/R/methods_glmmTMB.R index fde221f10..694e2740e 100644 --- a/R/methods_glmmTMB.R +++ b/R/methods_glmmTMB.R @@ -4,8 +4,159 @@ # model_parameters ----- +#' @title Parameters from Mixed Models +#' @name model_parameters.glmmTMB +#' +#' @description Parameters from (linear) mixed models. +#' +#' @param model A mixed model. +#' @param effects Should parameters for fixed effects (`"fixed"`), random +#' effects (`"random"`), or both (`"all"`) be returned? Only applies +#' to mixed models. May be abbreviated. If the calculation of random effects +#' parameters takes too long, you may use `effects = "fixed"`. +#' @param wb_component Logical, if `TRUE` and models contains within- and +#' between-effects (see `datawizard::demean()`), the `Component` column +#' will indicate which variables belong to the within-effects, +#' between-effects, and cross-level interactions. By default, the +#' `Component` column indicates, which parameters belong to the +#' conditional or zero-inflation component of the model. +#' @param include_sigma Logical, if `TRUE`, includes the residual standard +#' deviation. For mixed models, this is defined as the sum of the distribution-specific +#' variance and the variance for the additive overdispersion term (see +#' [insight::get_variance()] for details). Defaults to `FALSE` for mixed models +#' due to the longer computation time. +#' @param ci_random Logical, if `TRUE`, includes the confidence intervals for +#' random effects parameters. Only applies if `effects` is not `"fixed"` and +#' if `ci` is not `NULL`. Set `ci_random = FALSE` if computation of the model +#' summary is too much time consuming. By default, `ci_random = NULL`, which +#' uses a heuristic to guess if computation of confidence intervals for random +#' effects is fast enough or not. For models with larger sample size and/or +#' more complex random effects structures, confidence intervals will not be +#' computed by default, for simpler models or fewer observations, confidence +#' intervals will be included. Set explicitly to `TRUE` or `FALSE` to enforce +#' or omit calculation of confidence intervals. +#' @param ... Arguments passed to or from other methods. For instance, when +#' `bootstrap = TRUE`, arguments like `type` or `parallel` are passed down to +#' `bootstrap_model()`. +#' +#' Further non-documented arguments are: +#' +#' - `digits`, `p_digits`, `ci_digits` and `footer_digits` to set the number of +#' digits for the output. `groups` can be used to group coefficients. These +#' arguments will be passed to the print-method, or can directly be used in +#' `print()`, see documentation in [`print.parameters_model()`]. +#' - If `s_value = TRUE`, the p-value will be replaced by the S-value in the +#' output (cf. _Rafi and Greenland 2020_). +#' - `pd` adds an additional column with the _probability of direction_ (see +#' [`bayestestR::p_direction()`] for details). Furthermore, see 'Examples' for +#' this function. +#' - For developers, whose interest mainly is to get a "tidy" data frame of +#' model summaries, it is recommended to set `pretty_names = FALSE` to speed +#' up computation of the summary table. +#' +#' @inheritParams model_parameters.default +#' @inheritParams model_parameters.brmsfit #' @inheritParams simulate_model -#' @rdname model_parameters.merMod +#' +#' @inheritSection model_parameters.zcpglm Model components +#' +#' @inheritSection model_parameters Confidence intervals and approximation of degrees of freedom +#' +#' @section Confidence intervals for random effects variances: +#' For models of class `merMod` and `glmmTMB`, confidence intervals for random +#' effect variances can be calculated. +#' +#' - For models of from package **lme4**, when `ci_method` is either `"profile"` +#' or `"boot"`, and `effects` is either `"random"` or `"all"`, profiled resp. +#' bootstrapped confidence intervals are computed for the random effects. +#' +#' - For all other options of `ci_method`, and only when the **merDeriv** +#' package is installed, confidence intervals for random effects are based on +#' normal-distribution approximation, using the delta-method to transform +#' standard errors for constructing the intervals around the log-transformed +#' SD parameters. These are than back-transformed, so that random effect +#' variances, standard errors and confidence intervals are shown on the original +#' scale. Due to the transformation, the intervals are asymmetrical, however, +#' they are within the correct bounds (i.e. no negative interval for the SD, +#' and the interval for the correlations is within the range from -1 to +1). +#' +#' - For models of class `glmmTMB`, confidence intervals for random effect +#' variances always use a Wald t-distribution approximation. +#' +#' @section Singular fits (random effects variances near zero): +#' If a model is "singular", this means that some dimensions of the +#' variance-covariance matrix have been estimated as exactly zero. This +#' often occurs for mixed models with complex random effects structures. +#' +#' There is no gold-standard about how to deal with singularity and which +#' random-effects specification to choose. One way is to fully go Bayesian +#' (with informative priors). Other proposals are listed in the documentation +#' of [`performance::check_singularity()`]. However, since version 1.1.9, the +#' **glmmTMB** package allows to use priors in a frequentist framework, too. One +#' recommendation is to use a Gamma prior (_Chung et al. 2013_). The mean may +#' vary from 1 to very large values (like `1e8`), and the shape parameter should +#' be set to a value of 2.5. You can then `update()` your model with the specified +#' prior. In **glmmTMB**, the code would look like this: +#' +#' ``` +#' # "model" is an object of class gmmmTMB +#' prior <- data.frame( +#' prior = "gamma(1, 2.5)", # mean can be 1, but even 1e8 +#' class = "ranef" # for random effects +#' ) +#' model_with_priors <- update(model, priors = prior) +#' ``` +#' +#' Large values for the mean parameter of the Gamma prior have no large impact +#' on the random effects variances in terms of a "bias". Thus, if `1` doesn't +#' fix the singular fit, you can safely try larger values. +#' +#' @section Dispersion parameters in *glmmTMB*: +#' For some models from package **glmmTMB**, both the dispersion parameter and +#' the residual variance from the random effects parameters are shown. Usually, +#' these are the same but presented on different scales, e.g. +#' +#' ``` +#' model <- glmmTMB(Sepal.Width ~ Petal.Length + (1|Species), data = iris) +#' exp(fixef(model)$disp) # 0.09902987 +#' sigma(model)^2 # 0.09902987 +#' ``` +#' +#' For models where the dispersion parameter and the residual variance are +#' the same, only the residual variance is shown in the output. +#' +#' @seealso [insight::standardize_names()] to +#' rename columns into a consistent, standardized naming scheme. +#' +#' @note If the calculation of random effects parameters takes too long, you may +#' use `effects = "fixed"`. There is also a [`plot()`-method](https://easystats.github.io/see/articles/parameters.html) +#' implemented in the [**see**-package](https://easystats.github.io/see/). +#' +#' @references +#' Chung Y, Rabe-Hesketh S, Dorie V, Gelman A, and Liu J. 2013. "A Nondegenerate +#' Penalized Likelihood Estimator for Variance Parameters in Multilevel Models." +#' Psychometrika 78 (4): 685–709. \doi{10.1007/s11336-013-9328-2} +#' +#' @examplesIf require("lme4") && require("glmmTMB") +#' library(parameters) +#' data(mtcars) +#' model <- lme4::lmer(mpg ~ wt + (1 | gear), data = mtcars) +#' model_parameters(model) +#' +#' \donttest{ +#' data(Salamanders, package = "glmmTMB") +#' model <- glmmTMB::glmmTMB( +#' count ~ spp + mined + (1 | site), +#' ziformula = ~mined, +#' family = poisson(), +#' data = Salamanders +#' ) +#' model_parameters(model, effects = "all") +#' +#' model <- lme4::lmer(mpg ~ wt + (1 | gear), data = mtcars) +#' model_parameters(model, bootstrap = TRUE, iterations = 50, verbose = FALSE) +#' } +#' @return A data frame of indices related to the model's parameters. #' @export model_parameters.glmmTMB <- function(model, ci = 0.95, @@ -47,8 +198,14 @@ model_parameters.glmmTMB <- function(model, ci_method <- .check_df_method(ci_method) # which components to return? - effects <- insight::validate_argument(effects, c("fixed", "random", "all")) - component <- insight::validate_argument(component, c("all", "conditional", "zi", "zero_inflated", "dispersion")) + effects <- insight::validate_argument( + effects, + c("fixed", "random", "all") + ) + component <- insight::validate_argument( + component, + c("all", "conditional", "zi", "zero_inflated", "dispersion") + ) # standardize only works for fixed effects... if (!is.null(standardize) && standardize != "refit") { @@ -258,7 +415,6 @@ model_parameters.glmmTMB <- function(model, # ci ----- -#' @rdname ci.default #' @export ci.glmmTMB <- function(x, ci = 0.95, @@ -268,8 +424,14 @@ ci.glmmTMB <- function(x, verbose = TRUE, ...) { method <- tolower(method) - method <- insight::validate_argument(method, c("wald", "normal", "ml1", "betwithin", "profile", "uniroot", "robust")) - component <- insight::validate_argument(component, c("all", "conditional", "zi", "zero_inflated", "dispersion")) + method <- insight::validate_argument( + method, + c("wald", "normal", "ml1", "betwithin", "profile", "uniroot", "robust") + ) + component <- insight::validate_argument( + component, + c("all", "conditional", "zi", "zero_inflated", "dispersion") + ) if (is.null(.check_component(x, component, verbose = verbose))) { return(NULL) @@ -307,16 +469,20 @@ ci.glmmTMB <- function(x, # standard_error ----- - -#' @rdname standard_error #' @export standard_error.glmmTMB <- function(model, effects = "fixed", component = "all", verbose = TRUE, ...) { - component <- insight::validate_argument(component, c("all", "conditional", "zi", "zero_inflated", "dispersion")) - effects <- insight::validate_argument(effects, c("fixed", "random")) + component <- insight::validate_argument( + component, + c("all", "conditional", "zi", "zero_inflated", "dispersion") + ) + effects <- insight::validate_argument( + effects, + c("fixed", "random") + ) dot_args <- .check_dots( dots = list(...), @@ -327,12 +493,14 @@ standard_error.glmmTMB <- function(model, ) if (effects == "random") { - if (!requireNamespace("TMB", quietly = TRUE) && !requireNamespace("glmmTMB", quietly = TRUE)) { + if (!all(insight::check_if_installed(c("TMB", "glmmTMB"), quietly = TRUE))) { return(NULL) } + s1 <- TMB::sdreport(model$obj, getJointPrecision = TRUE) s2 <- sqrt(s1$diag.cov.random) rand.ef <- glmmTMB::ranef(model)[[1]] + rand.se <- lapply(rand.ef, function(.x) { cnt <- nrow(.x) * ncol(.x) s3 <- s2[1:cnt] @@ -370,14 +538,16 @@ standard_error.glmmTMB <- function(model, # simulate model ----- -#' @rdname simulate_model #' @export simulate_model.glmmTMB <- function(model, iterations = 1000, component = "all", verbose = FALSE, ...) { - component <- insight::validate_argument(component, c("all", "conditional", "zi", "zero_inflated", "dispersion")) + component <- insight::validate_argument( + component, + c("all", "conditional", "zi", "zero_inflated", "dispersion") + ) info <- insight::model_info(model, verbose = FALSE) ## TODO remove is.list() when insight 0.8.3 on CRAN @@ -461,8 +631,6 @@ simulate_model.glmmTMB <- function(model, # simulate_parameters ----- - -#' @rdname simulate_parameters #' @export simulate_parameters.glmmTMB <- function(model, iterations = 1000, diff --git a/R/methods_glmx.R b/R/methods_glmx.R index b6e49fb85..90711db4e 100644 --- a/R/methods_glmx.R +++ b/R/methods_glmx.R @@ -1,10 +1,9 @@ -#' @rdname model_parameters.averaging #' @export model_parameters.glmx <- function(model, ci = 0.95, bootstrap = FALSE, iterations = 1000, - component = c("all", "conditional", "extra"), + component = "all", standardize = NULL, exponentiate = FALSE, p_adjust = NULL, @@ -12,7 +11,7 @@ model_parameters.glmx <- function(model, drop = NULL, verbose = TRUE, ...) { - component <- match.arg(component) + component <- insight::validate_argument(component, c("all", "conditional", "extra")) if (component == "all") { merge_by <- c("Parameter", "Component") } else { @@ -67,8 +66,11 @@ p_value.glmx <- function(model, ...) { #' @export -simulate_model.glmx <- function(model, iterations = 1000, component = c("all", "conditional", "extra"), ...) { - component <- match.arg(component) +simulate_model.glmx <- function(model, iterations = 1000, component = "all", ...) { + component <- insight::validate_argument( + component, + c("all", "conditional", "extra") + ) out <- .simulate_model(model, iterations, component = component, ...) class(out) <- c("parameters_simulate_model", class(out)) diff --git a/R/methods_hclust.R b/R/methods_hclust.R index 4698080f5..cd9bf93b0 100644 --- a/R/methods_hclust.R +++ b/R/methods_hclust.R @@ -1,7 +1,31 @@ -#' @rdname model_parameters.kmeans -#' @inheritParams cluster_centers +#' 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 #' -#' @examples #' # #' # Hierarchical clustering (hclust) --------------------------- #' data <- iris[1:4] @@ -20,6 +44,52 @@ #' # 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)) { @@ -55,37 +125,6 @@ model_parameters.hclust <- function(model, data = NULL, clusters = NULL, ...) { } - - -#' @inheritParams n_clusters -#' @rdname model_parameters.kmeans -#' @examples -#' \donttest{ -#' # -#' # pvclust (finds "significant" clusters) --------------------------- -#' if (require("pvclust", quietly = TRUE)) { -#' data <- iris[1:4] -#' # NOTE: pvclust works on transposed data -#' model <- pvclust::pvclust(datawizard::data_transpose(data, verbose = FALSE), -#' method.dist = "euclidean", -#' nboot = 50, -#' quiet = TRUE -#' ) -#' -#' rez <- model_parameters(model, data, ci = 0.90) -#' 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 -#' } -#' } #' @export model_parameters.pvclust <- function(model, data = NULL, clusters = NULL, ci = 0.95, ...) { if (is.null(data)) { diff --git a/R/methods_kmeans.R b/R/methods_kmeans.R index e28a7a11f..3ee0d0241 100644 --- a/R/methods_kmeans.R +++ b/R/methods_kmeans.R @@ -1,29 +1,3 @@ -#' Parameters from Cluster Models (k-means, ...) -#' -#' Format cluster models obtained for example by [kmeans()]. -#' -#' @param model Cluster model. -#' @inheritParams model_parameters.default -#' @param ... Arguments passed to or from other methods. -#' -#' @examples -#' \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 -#' } #' @export model_parameters.kmeans <- function(model, ...) { params <- cbind( @@ -64,32 +38,6 @@ model_parameters.kmeans <- function(model, ...) { # factoextra::hkmeans ----------------------------------------------------- - -#' @rdname model_parameters.kmeans -#' @inheritParams cluster_centers -#' -#' @examples -#' \donttest{ -#' # -#' # Hierarchical K-means (factoextra::hkclust) ---------------------- -#' if (require("factoextra", quietly = TRUE)) { -#' 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 -#' } -#' } #' @export model_parameters.hkmeans <- model_parameters.kmeans @@ -98,8 +46,6 @@ model_parameters.hkmeans <- model_parameters.kmeans # Methods ------------------------------------------------------------------- - - #' @export print.parameters_clusters <- function(x, digits = 2, ...) { clusterHeading <- "# Clustering Solution" diff --git a/R/methods_lme4.R b/R/methods_lme4.R index 653bde9a5..fc8ad47f4 100644 --- a/R/methods_lme4.R +++ b/R/methods_lme4.R @@ -1,156 +1,6 @@ ############# .merMod ----------------- -#' @title Parameters from Mixed Models -#' @name model_parameters.merMod -#' -#' @description Parameters from (linear) mixed models. -#' -#' @param model A mixed model. -#' @param effects Should parameters for fixed effects (`"fixed"`), random -#' effects (`"random"`), or both (`"all"`) be returned? Only applies -#' to mixed models. May be abbreviated. If the calculation of random effects -#' parameters takes too long, you may use `effects = "fixed"`. -#' @param wb_component Logical, if `TRUE` and models contains within- and -#' between-effects (see `datawizard::demean()`), the `Component` column -#' will indicate which variables belong to the within-effects, -#' between-effects, and cross-level interactions. By default, the -#' `Component` column indicates, which parameters belong to the -#' conditional or zero-inflation component of the model. -#' @param include_sigma Logical, if `TRUE`, includes the residual standard -#' deviation. For mixed models, this is defined as the sum of the distribution-specific -#' variance and the variance for the additive overdispersion term (see -#' [insight::get_variance()] for details). Defaults to `FALSE` for mixed models -#' due to the longer computation time. -#' @param ci_random Logical, if `TRUE`, includes the confidence intervals for -#' random effects parameters. Only applies if `effects` is not `"fixed"` and -#' if `ci` is not `NULL`. Set `ci_random = FALSE` if computation of the model -#' summary is too much time consuming. By default, `ci_random = NULL`, which -#' uses a heuristic to guess if computation of confidence intervals for random -#' effects is fast enough or not. For models with larger sample size and/or -#' more complex random effects structures, confidence intervals will not be -#' computed by default, for simpler models or fewer observations, confidence -#' intervals will be included. Set explicitly to `TRUE` or `FALSE` to enforce -#' or omit calculation of confidence intervals. -#' @param ... Arguments passed to or from other methods. For instance, when -#' `bootstrap = TRUE`, arguments like `type` or `parallel` are passed down to -#' `bootstrap_model()`. -#' -#' Further non-documented arguments are: -#' -#' - `digits`, `p_digits`, `ci_digits` and `footer_digits` to set the number of -#' digits for the output. `groups` can be used to group coefficients. These -#' arguments will be passed to the print-method, or can directly be used in -#' `print()`, see documentation in [`print.parameters_model()`]. -#' - If `s_value = TRUE`, the p-value will be replaced by the S-value in the -#' output (cf. _Rafi and Greenland 2020_). -#' - `pd` adds an additional column with the _probability of direction_ (see -#' [`bayestestR::p_direction()`] for details). Furthermore, see 'Examples' for -#' this function. -#' - For developers, whose interest mainly is to get a "tidy" data frame of -#' model summaries, it is recommended to set `pretty_names = FALSE` to speed -#' up computation of the summary table. -#' -#' @inheritParams model_parameters.default -#' @inheritParams model_parameters.stanreg -#' -#' @inheritSection model_parameters Confidence intervals and approximation of degrees of freedom -#' -#' @section Confidence intervals for random effects variances: -#' For models of class `merMod` and `glmmTMB`, confidence intervals for random -#' effect variances can be calculated. -#' -#' - For models of from package **lme4**, when `ci_method` is either `"profile"` -#' or `"boot"`, and `effects` is either `"random"` or `"all"`, profiled resp. -#' bootstrapped confidence intervals are computed for the random effects. -#' -#' - For all other options of `ci_method`, and only when the **merDeriv** -#' package is installed, confidence intervals for random effects are based on -#' normal-distribution approximation, using the delta-method to transform -#' standard errors for constructing the intervals around the log-transformed -#' SD parameters. These are than back-transformed, so that random effect -#' variances, standard errors and confidence intervals are shown on the original -#' scale. Due to the transformation, the intervals are asymmetrical, however, -#' they are within the correct bounds (i.e. no negative interval for the SD, -#' and the interval for the correlations is within the range from -1 to +1). -#' -#' - For models of class `glmmTMB`, confidence intervals for random effect -#' variances always use a Wald t-distribution approximation. -#' -#' @section Singular fits (random effects variances near zero): -#' If a model is "singular", this means that some dimensions of the -#' variance-covariance matrix have been estimated as exactly zero. This -#' often occurs for mixed models with complex random effects structures. -#' -#' There is no gold-standard about how to deal with singularity and which -#' random-effects specification to choose. One way is to fully go Bayesian -#' (with informative priors). Other proposals are listed in the documentation -#' of [`performance::check_singularity()`]. However, since version 1.1.9, the -#' **glmmTMB** package allows to use priors in a frequentist framework, too. One -#' recommendation is to use a Gamma prior (_Chung et al. 2013_). The mean may -#' vary from 1 to very large values (like `1e8`), and the shape parameter should -#' be set to a value of 2.5. You can then `update()` your model with the specified -#' prior. In **glmmTMB**, the code would look like this: -#' -#' ``` -#' # "model" is an object of class gmmmTMB -#' prior <- data.frame( -#' prior = "gamma(1, 2.5)", # mean can be 1, but even 1e8 -#' class = "ranef" # for random effects -#' ) -#' model_with_priors <- update(model, priors = prior) -#' ``` -#' -#' Large values for the mean parameter of the Gamma prior have no large impact -#' on the random effects variances in terms of a "bias". Thus, if `1` doesn't -#' fix the singular fit, you can safely try larger values. -#' -#' @section Dispersion parameters in *glmmTMB*: -#' For some models from package **glmmTMB**, both the dispersion parameter and -#' the residual variance from the random effects parameters are shown. Usually, -#' these are the same but presented on different scales, e.g. -#' -#' ``` -#' model <- glmmTMB(Sepal.Width ~ Petal.Length + (1|Species), data = iris) -#' exp(fixef(model)$disp) # 0.09902987 -#' sigma(model)^2 # 0.09902987 -#' ``` -#' -#' For models where the dispersion parameter and the residual variance are -#' the same, only the residual variance is shown in the output. -#' -#' @seealso [insight::standardize_names()] to -#' rename columns into a consistent, standardized naming scheme. -#' -#' @note If the calculation of random effects parameters takes too long, you may -#' use `effects = "fixed"`. There is also a [`plot()`-method](https://easystats.github.io/see/articles/parameters.html) -#' implemented in the [**see**-package](https://easystats.github.io/see/). -#' -#' @references -#' Chung Y, Rabe-Hesketh S, Dorie V, Gelman A, and Liu J. 2013. "A Nondegenerate -#' Penalized Likelihood Estimator for Variance Parameters in Multilevel Models." -#' Psychometrika 78 (4): 685–709. \doi{10.1007/s11336-013-9328-2} -#' -#' @examplesIf require("lme4") && require("glmmTMB") -#' library(parameters) -#' data(mtcars) -#' model <- lme4::lmer(mpg ~ wt + (1 | gear), data = mtcars) -#' model_parameters(model) -#' -#' \donttest{ -#' data(Salamanders, package = "glmmTMB") -#' model <- glmmTMB::glmmTMB( -#' count ~ spp + mined + (1 | site), -#' ziformula = ~mined, -#' family = poisson(), -#' data = Salamanders -#' ) -#' model_parameters(model, effects = "all") -#' -#' model <- lme4::lmer(mpg ~ wt + (1 | gear), data = mtcars) -#' model_parameters(model, bootstrap = TRUE, iterations = 50, verbose = FALSE) -#' } -#' @return A data frame of indices related to the model's parameters. #' @export model_parameters.merMod <- function(model, ci = 0.95, @@ -338,7 +188,6 @@ model_parameters.merMod <- function(model, } -#' @rdname ci.default #' @export ci.merMod <- function(x, ci = 0.95, @@ -374,7 +223,6 @@ ci.merMod <- function(x, } -#' @rdname standard_error #' @export standard_error.merMod <- function(model, effects = "fixed", @@ -447,7 +295,6 @@ standard_error.merMod <- function(model, } - se_mixed_default <- function(model) { params <- insight::find_parameters(model, effects = "fixed", @@ -458,7 +305,5 @@ se_mixed_default <- function(model) { } - - #' @export p_value.merMod <- p_value.cpglmm diff --git a/R/methods_marginaleffects.R b/R/methods_marginaleffects.R index 8d21acbea..cec52a9ca 100644 --- a/R/methods_marginaleffects.R +++ b/R/methods_marginaleffects.R @@ -3,7 +3,6 @@ # model_parameters ---------------- -#' @rdname model_parameters.averaging #' @export model_parameters.marginaleffects <- function(model, ci = 0.95, diff --git a/R/methods_mass.R b/R/methods_mass.R index 7d1f54728..bfdb891a4 100644 --- a/R/methods_mass.R +++ b/R/methods_mass.R @@ -97,7 +97,6 @@ p_value.polr <- function(model, method = NULL, ...) { # parameters ----------------- -#' @rdname model_parameters.default #' @export model_parameters.ridgelm <- function(model, verbose = TRUE, ...) { parameters <- insight::get_parameters(model) diff --git a/R/methods_mclust.R b/R/methods_mclust.R index 2ea99b033..f8cc2993b 100644 --- a/R/methods_mclust.R +++ b/R/methods_mclust.R @@ -1,10 +1,3 @@ -#' @rdname model_parameters.kmeans -#' -#' @examples -#' if (require("mclust", quietly = TRUE)) { -#' model <- mclust::Mclust(iris[1:4], verbose = FALSE) -#' model_parameters(model) -#' } #' @export model_parameters.Mclust <- function(model, data = NULL, clusters = NULL, ...) { if (is.null(data)) data <- as.data.frame(model$data) diff --git a/R/methods_metafor.R b/R/methods_metafor.R index 8ba1432b3..d8c275dbc 100644 --- a/R/methods_metafor.R +++ b/R/methods_metafor.R @@ -8,8 +8,10 @@ #' #' 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.averaging +#' @inheritParams model_parameters.glimML #' #' @examples #' library(parameters) diff --git a/R/methods_metaplus.R b/R/methods_metaplus.R index 72641bfd1..6eb71c55f 100644 --- a/R/methods_metaplus.R +++ b/R/methods_metaplus.R @@ -4,7 +4,6 @@ ###### .metaplus ------------------- -#' @rdname model_parameters.averaging #' @export model_parameters.metaplus <- function(model, ci = 0.95, @@ -148,7 +147,6 @@ ci.metaplus <- function(x, ...) { ###### .meta_random ------------------- -#' @rdname model_parameters.averaging #' @export model_parameters.meta_random <- function(model, ci = 0.95, @@ -307,7 +305,6 @@ ci.meta_fixed <- ci.meta_random ###### .meta_bma ------------------- -#' @rdname model_parameters.averaging #' @export model_parameters.meta_bma <- function(model, ci = 0.95, @@ -318,7 +315,7 @@ model_parameters.meta_bma <- function(model, ...) { # process arguments params <- as.data.frame(model$estimates) - ci_method <- match.arg(ci_method, choices = c("hdi", "eti", "quantile")) + ci_method <- insight::validate_argument(ci_method, c("hdi", "eti", "quantile")) # parameters of studies included study_params <- model$meta$fixed$data diff --git a/R/methods_mfx.R b/R/methods_mfx.R index 847eb79a7..3e970577f 100644 --- a/R/methods_mfx.R +++ b/R/methods_mfx.R @@ -1,6 +1,5 @@ # model parameters --------------------- - #' @export model_parameters.logitor <- function(model, ci = 0.95, @@ -37,7 +36,7 @@ model_parameters.poissonmfx <- function(model, ci = 0.95, bootstrap = FALSE, iterations = 1000, - component = c("all", "conditional", "marginal"), + component = "all", standardize = NULL, exponentiate = FALSE, p_adjust = NULL, @@ -45,7 +44,10 @@ model_parameters.poissonmfx <- function(model, drop = NULL, verbose = TRUE, ...) { - component <- match.arg(component) + component <- insight::validate_argument( + component, + c("all", "conditional", "marginal") + ) out <- .model_parameters_generic( model = model, ci = ci, @@ -79,19 +81,21 @@ model_parameters.probitmfx <- model_parameters.poissonmfx model_parameters.negbinmfx <- model_parameters.poissonmfx -#' @rdname model_parameters.averaging #' @export model_parameters.betaor <- function(model, ci = 0.95, bootstrap = FALSE, iterations = 1000, - component = c("conditional", "precision", "all"), + component = "conditional", standardize = NULL, exponentiate = FALSE, p_adjust = NULL, verbose = TRUE, ...) { - component <- match.arg(component) + component <- insight::validate_argument( + component, + c("conditional", "precision", "all") + ) model_parameters.betareg( model$fit, ci = ci, @@ -106,13 +110,12 @@ model_parameters.betaor <- function(model, } -#' @rdname model_parameters.averaging #' @export model_parameters.betamfx <- function(model, ci = 0.95, bootstrap = FALSE, iterations = 1000, - component = c("all", "conditional", "precision", "marginal"), + component = "all", standardize = NULL, exponentiate = FALSE, p_adjust = NULL, @@ -120,7 +123,10 @@ model_parameters.betamfx <- function(model, drop = NULL, verbose = TRUE, ...) { - component <- match.arg(component) + component <- insight::validate_argument( + component, + c("all", "conditional", "precision", "marginal") + ) out <- .model_parameters_generic( model = model, ci = ci, @@ -143,10 +149,8 @@ model_parameters.betamfx <- function(model, - # ci ------------------ - #' @export ci.logitor <- function(x, ci = 0.95, method = NULL, ...) { .ci_generic(model = x$fit, ci = ci, method = method, ...) @@ -162,12 +166,11 @@ ci.negbinirr <- ci.logitor #' @export -ci.poissonmfx <- function(x, - ci = 0.95, - component = c("all", "conditional", "marginal"), - method = NULL, - ...) { - component <- match.arg(component) +ci.poissonmfx <- function(x, ci = 0.95, component = "all", method = NULL, ...) { + component <- insight::validate_argument( + component, + c("all", "conditional", "marginal") + ) .ci_generic(model = x, ci = ci, component = component, method = method, ...) } @@ -185,11 +188,11 @@ ci.probitmfx <- ci.poissonmfx #' @export -ci.betaor <- function(x, - ci = 0.95, - component = c("all", "conditional", "precision"), - ...) { - component <- match.arg(component) +ci.betaor <- function(x, ci = 0.95, component = "all", ...) { + component <- insight::validate_argument( + component, + c("all", "conditional", "precision") + ) .ci_generic(model = x$fit, ci = ci, dof = Inf, component = component) } @@ -198,18 +201,19 @@ ci.betaor <- function(x, ci.betamfx <- function(x, ci = 0.95, method = NULL, - component = c("all", "conditional", "precision", "marginal"), + component = "all", ...) { - component <- match.arg(component) + component <- insight::validate_argument( + component, + c("all", "conditional", "precision", "marginal") + ) .ci_generic(model = x, ci = ci, component = component, method = method, ...) } - # standard error ------------------ - #' @export standard_error.negbin <- standard_error.default @@ -229,9 +233,7 @@ standard_error.negbinirr <- standard_error.logitor #' @export -standard_error.poissonmfx <- function(model, - component = "all", - ...) { +standard_error.poissonmfx <- function(model, component = "all", ...) { parms <- insight::get_parameters(model, component = "all") cs <- stats::coef(summary(model$fit)) se <- c(as.vector(model$mfxest[, 2]), as.vector(cs[, 2])) @@ -242,7 +244,10 @@ standard_error.poissonmfx <- function(model, Component = parms$Component ) - component <- match.arg(component, choices = c("all", "conditional", "marginal")) + component <- insight::validate_argument( + component, + c("all", "conditional", "marginal") + ) if (component != "all") { out <- out[out$Component == component, ] } @@ -264,18 +269,17 @@ standard_error.negbinmfx <- standard_error.poissonmfx #' @export -standard_error.betaor <- function(model, - component = c("all", "conditional", "precision"), - ...) { - component <- match.arg(component) +standard_error.betaor <- function(model, component = "all", ...) { + component <- insight::validate_argument( + component, + c("all", "conditional", "precision") + ) standard_error.betareg(model$fit, component = component, ...) } #' @export -standard_error.betamfx <- function(model, - component = "all", - ...) { +standard_error.betamfx <- function(model, component = "all", ...) { parms <- insight::get_parameters(model, component = "all") cs <- do.call(rbind, stats::coef(summary(model$fit))) se <- c(as.vector(model$mfxest[, 2]), as.vector(cs[, 2])) @@ -286,7 +290,10 @@ standard_error.betamfx <- function(model, Component = parms$Component ) - component <- match.arg(component, choices = c("all", "conditional", "precision", "marginal")) + component <- insight::validate_argument( + component, + c("all", "conditional", "precision", "marginal") + ) if (component != "all") { out <- out[out$Component == component, ] } @@ -298,38 +305,8 @@ standard_error.betamfx <- function(model, # p values ------------------ - -#' p-values for Marginal Effects Models -#' -#' This function attempts to return, or compute, p-values of marginal effects -#' models from package **mfx**. -#' -#' @param model A statistical model. -#' @param component Should all parameters, parameters for the conditional model, -#' precision-component or marginal effects be returned? `component` may be one -#' of `"conditional"`, `"precision"`, `"marginal"` or `"all"` (default). -#' @param ... Currently not used. -#' -#' @return 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. -#' -#' @examples -#' if (require("mfx", quietly = TRUE)) { -#' set.seed(12345) -#' n <- 1000 -#' x <- rnorm(n) -#' y <- rnegbin(n, mu = exp(1 + 0.5 * x), theta = 0.5) -#' d <- data.frame(y, x) -#' model <- poissonmfx(y ~ x, data = d) -#' -#' p_value(model) -#' p_value(model, component = "marginal") -#' } -#' @export -p_value.poissonmfx <- function(model, - component = c("all", "conditional", "marginal"), - ...) { +#' @export +p_value.poissonmfx <- function(model, component = "all", ...) { parms <- insight::get_parameters(model, component = "all") cs <- stats::coef(summary(model$fit)) p <- c(as.vector(model$mfxest[, 4]), as.vector(cs[, 4])) @@ -340,7 +317,10 @@ p_value.poissonmfx <- function(model, Component = parms$Component ) - component <- match.arg(component) + component <- insight::validate_argument( + component, + c("all", "conditional", "marginal") + ) if (component != "all") { out <- out[out$Component == component, ] } @@ -375,21 +355,18 @@ p_value.probitmfx <- p_value.poissonmfx p_value.negbinmfx <- p_value.poissonmfx -#' @rdname p_value.poissonmfx #' @export -p_value.betaor <- function(model, - component = c("all", "conditional", "precision"), - ...) { - component <- match.arg(component) +p_value.betaor <- function(model, component = "all", ...) { + component <- insight::validate_argument( + component, + c("all", "conditional", "precision") + ) p_value.betareg(model$fit, component = component, ...) } -#' @rdname p_value.poissonmfx #' @export -p_value.betamfx <- function(model, - component = c("all", "conditional", "precision", "marginal"), - ...) { +p_value.betamfx <- function(model, component = "all", ...) { parms <- insight::get_parameters(model, component = "all") cs <- do.call(rbind, stats::coef(summary(model$fit))) p <- c(as.vector(model$mfxest[, 4]), as.vector(cs[, 4])) @@ -400,7 +377,10 @@ p_value.betamfx <- function(model, Component = parms$Component ) - component <- match.arg(component) + component <- insight::validate_argument( + component, + c("all", "conditional", "precision", "marginal") + ) if (component != "all") { out <- out[out$Component == component, ] } @@ -410,16 +390,14 @@ p_value.betamfx <- function(model, - # simulate model ------------------ - #' @export -simulate_model.betaor <- function(model, - iterations = 1000, - component = c("all", "conditional", "precision"), - ...) { - component <- match.arg(component) +simulate_model.betaor <- function(model, iterations = 1000, component = "all", ...) { + component <- insight::validate_argument( + component, + c("all", "conditional", "precision") + ) simulate_model.betareg(model$fit, iterations = iterations, diff --git a/R/methods_mgcv.R b/R/methods_mgcv.R index 79ee31e3e..6d924d3de 100644 --- a/R/methods_mgcv.R +++ b/R/methods_mgcv.R @@ -1,4 +1,3 @@ -#' @rdname model_parameters.cgam #' @export model_parameters.gamm <- function(model, ci = 0.95, diff --git a/R/methods_mhurdle.R b/R/methods_mhurdle.R index 47775b8c2..8d6a97f8c 100644 --- a/R/methods_mhurdle.R +++ b/R/methods_mhurdle.R @@ -1,15 +1,17 @@ -#' @rdname model_parameters.zcpglm #' @export model_parameters.mhurdle <- function(model, ci = 0.95, - component = c("all", "conditional", "zi", "zero_inflated", "infrequent_purchase", "ip", "auxiliary"), + component = "all", exponentiate = FALSE, p_adjust = NULL, keep = NULL, drop = NULL, verbose = TRUE, ...) { - component <- match.arg(component) + component <- insight::validate_argument( + component, + c("all", "conditional", "zi", "zero_inflated", "infrequent_purchase", "ip", "auxiliary") + ) params <- .model_parameters_generic( model, diff --git a/R/methods_mixed.R b/R/methods_mixed.R index bbdfbb038..54b8c4697 100644 --- a/R/methods_mixed.R +++ b/R/methods_mixed.R @@ -1,3 +1,2 @@ -#' @rdname model_parameters.merMod #' @export model_parameters.mixed <- model_parameters.glmmTMB diff --git a/R/methods_mixmod.R b/R/methods_mixmod.R index a34da3fc2..deb63d39d 100644 --- a/R/methods_mixmod.R +++ b/R/methods_mixmod.R @@ -1,4 +1,3 @@ -#' @rdname model_parameters.merMod #' @export model_parameters.MixMod <- model_parameters.glmmTMB diff --git a/R/methods_mjoint.R b/R/methods_mjoint.R index ba02e6f02..258382dd2 100644 --- a/R/methods_mjoint.R +++ b/R/methods_mjoint.R @@ -1,17 +1,16 @@ -#' @rdname model_parameters.averaging #' @export model_parameters.mjoint <- function(model, ci = 0.95, effects = "fixed", - component = c("all", "conditional", "survival"), + component = "all", exponentiate = FALSE, p_adjust = NULL, keep = NULL, drop = NULL, verbose = TRUE, ...) { - effects <- match.arg(effects, choices = c("fixed", "random", "all")) - component <- match.arg(component) + effects <- insight::validate_argument(effects, c("fixed", "random", "all")) + component <- insight::validate_argument(component, c("all", "conditional", "survival")) params <- params_variance <- NULL diff --git a/R/methods_mlm.R b/R/methods_mlm.R index 0ec4ee2a1..06126f69b 100644 --- a/R/methods_mlm.R +++ b/R/methods_mlm.R @@ -20,6 +20,8 @@ #' @seealso [insight::standardize_names()] to rename #' columns into a consistent, standardized naming scheme. #' +#' @inheritSection model_parameters.zcpglm Model components +#' #' @examplesIf require("brglm2", quietly = TRUE) #' data("stemcell", package = "brglm2") #' model <- brglm2::bracl( diff --git a/R/methods_mvord.R b/R/methods_mvord.R index 43ec187f1..4fad1cb1a 100644 --- a/R/methods_mvord.R +++ b/R/methods_mvord.R @@ -3,11 +3,10 @@ #################### .mvord -#' @rdname model_parameters.averaging #' @export model_parameters.mvord <- function(model, ci = 0.95, - component = c("all", "conditional", "thresholds", "correlation"), + component = "all", standardize = NULL, exponentiate = FALSE, p_adjust = NULL, @@ -17,7 +16,7 @@ model_parameters.mvord <- function(model, drop = NULL, verbose = TRUE, ...) { - component <- match.arg(component) + component <- insight::validate_argument(component, c("all", "conditional", "thresholds", "correlation")) ## TODO remove deprecated later if (!missing(summary)) { diff --git a/R/methods_nlme.R b/R/methods_nlme.R index ecd99429d..d84421bb7 100644 --- a/R/methods_nlme.R +++ b/R/methods_nlme.R @@ -2,7 +2,6 @@ ############### .lme -------------- -#' @rdname model_parameters.merMod #' @export model_parameters.lme <- model_parameters.merMod diff --git a/R/methods_ordinal.R b/R/methods_ordinal.R index 09ada5454..3c4a024bc 100644 --- a/R/methods_ordinal.R +++ b/R/methods_ordinal.R @@ -7,7 +7,7 @@ model_parameters.clm2 <- function(model, ci = 0.95, bootstrap = FALSE, iterations = 1000, - component = c("all", "conditional", "scale"), + component = "all", standardize = NULL, exponentiate = FALSE, p_adjust = NULL, @@ -17,7 +17,7 @@ model_parameters.clm2 <- function(model, drop = NULL, verbose = TRUE, ...) { - component <- match.arg(component) + component <- insight::validate_argument(component, c("all", "conditional", "scale")) if (component == "all") { merge_by <- c("Parameter", "Component") } else { @@ -53,12 +53,10 @@ model_parameters.clm2 <- function(model, } -#' @rdname model_parameters.merMod #' @export model_parameters.clmm2 <- model_parameters.clm2 -#' @rdname model_parameters.merMod #' @export model_parameters.clmm <- model_parameters.cpglmm @@ -108,10 +106,12 @@ standard_error.clmm2 <- standard_error.clm2 # p values ---------------- -#' @rdname p_value.DirichletRegModel #' @export -p_value.clm2 <- function(model, component = c("all", "conditional", "scale"), ...) { - component <- match.arg(component) +p_value.clm2 <- function(model, component = "all", ...) { + component <- insight::validate_argument( + component, + c("all", "conditional", "scale") + ) params <- insight::get_parameters(model) cs <- stats::coef(summary(model)) @@ -138,11 +138,11 @@ p_value.clmm2 <- p_value.clm2 #' @export -simulate_model.clm2 <- function(model, - iterations = 1000, - component = c("all", "conditional", "scale"), - ...) { - component <- match.arg(component) +simulate_model.clm2 <- function(model, iterations = 1000, component = "all", ...) { + component <- insight::validate_argument( + component, + c("all", "conditional", "scale") + ) out <- .simulate_model(model, iterations, component = component, ...) class(out) <- c("parameters_simulate_model", class(out)) diff --git a/R/methods_other.R b/R/methods_other.R index 1da9fccef..f92090ac1 100644 --- a/R/methods_other.R +++ b/R/methods_other.R @@ -25,7 +25,6 @@ ci.complmrob <- ci.default ############# .Gam -------------- -#' @rdname model_parameters.cgam #' @inheritParams model_parameters.aov #' @export model_parameters.Gam <- function(model, diff --git a/R/methods_pam.R b/R/methods_pam.R index 313f600ea..a6621b7e6 100644 --- a/R/methods_pam.R +++ b/R/methods_pam.R @@ -1,18 +1,3 @@ -#' @rdname model_parameters.kmeans -#' -#' @examples -#' \donttest{ -#' # -#' # K-Medoids (PAM and HPAM) ============== -#' if (require("cluster", quietly = TRUE)) { -#' model <- cluster::pam(iris[1:4], k = 3) -#' model_parameters(model) -#' } -#' if (require("fpc", quietly = TRUE)) { -#' model <- fpc::pamk(iris[1:4], criterion = "ch") -#' model_parameters(model) -#' } -#' } #' @export model_parameters.pam <- function(model, data = NULL, clusters = NULL, ...) { if (is.null(data)) data <- as.data.frame(model$data) diff --git a/R/methods_panelr.R b/R/methods_panelr.R index 74e3ad887..b64b015be 100644 --- a/R/methods_panelr.R +++ b/R/methods_panelr.R @@ -3,7 +3,6 @@ # model parameters ------------------- -#' @inheritParams model_parameters.merMod #' @export model_parameters.wbm <- function(model, ci = 0.95, diff --git a/R/methods_posterior.R b/R/methods_posterior.R index a79e9bb08..eecbc83ac 100644 --- a/R/methods_posterior.R +++ b/R/methods_posterior.R @@ -1,4 +1,3 @@ -#' @rdname model_parameters.stanreg #' @export model_parameters.draws <- function(model, centrality = "median", diff --git a/R/methods_pscl.R b/R/methods_pscl.R index a0ac9d7e5..6cb4846c9 100644 --- a/R/methods_pscl.R +++ b/R/methods_pscl.R @@ -13,7 +13,6 @@ model_parameters.zerocount <- model_parameters.zcpglm - # ci ----------------- #' @export @@ -25,8 +24,14 @@ ci.zeroinfl <- function(x, verbose = TRUE, ...) { method <- tolower(method) - method <- match.arg(method, choices = c("wald", "normal", "residual", "robust")) - component <- match.arg(component, choices = c("all", "conditional", "zi", "zero_inflated")) + method <- insight::validate_argument( + method, + c("wald", "normal", "residual", "robust") + ) + component <- insight::validate_argument( + component, + c("all", "conditional", "zi", "zero_inflated") + ) if (is.null(.check_component(x, component, verbose = verbose))) { return(NULL) @@ -44,17 +49,18 @@ ci.zerocount <- ci.zeroinfl - # standard error ----------------- - #' @export standard_error.zeroinfl <- function(model, component = "all", method = NULL, verbose = TRUE, ...) { - component <- match.arg(component, choices = c("all", "conditional", "zi", "zero_inflated")) + component <- insight::validate_argument( + component, + c("all", "conditional", "zi", "zero_inflated") + ) if (is.null(.check_component(model, component, verbose = verbose))) { return(NULL) } @@ -102,18 +108,14 @@ standard_error.zerocount <- standard_error.zeroinfl - # p values ----------------------- - -#' @rdname p_value.zcpglm #' @export -p_value.zeroinfl <- function(model, - component = c("all", "conditional", "zi", "zero_inflated"), - method = NULL, - verbose = TRUE, - ...) { - component <- match.arg(component) +p_value.zeroinfl <- function(model, component = "all", method = NULL, verbose = TRUE, ...) { + component <- insight::validate_argument( + component, + c("all", "conditional", "zi", "zero_inflated") + ) if (is.null(.check_component(model, component, verbose = verbose))) { return(NULL) } @@ -160,10 +162,8 @@ p_value.zerocount <- p_value.zeroinfl - # simulate model ----------------- - #' @export simulate_model.zeroinfl <- simulate_model.glmmTMB @@ -175,7 +175,6 @@ simulate_model.zerocount <- simulate_model.zeroinfl - # simulate paramaters ----------------- #' @export diff --git a/R/methods_rstanarm.R b/R/methods_rstanarm.R index 625e2b68b..21e49cd42 100644 --- a/R/methods_rstanarm.R +++ b/R/methods_rstanarm.R @@ -1,63 +1,3 @@ -#' Parameters from Bayesian Models -#' -#' Parameters from Bayesian models. -#' -#' @param model Bayesian model (including SEM from **blavaan**. May also be -#' a data frame with posterior samples, however, `as_draws` must be set to -#' `TRUE` (else, for data frames `NULL` is returned). -#' @param ci Credible Interval (CI) level. Default to `0.95` (`95%`). See -#' [bayestestR::ci()] for further details. -#' @param group_level Logical, for multilevel models (i.e. models with random -#' effects) and when `effects = "all"` or `effects = "random"`, -#' include the parameters for each group level from random effects. If -#' `group_level = FALSE` (the default), only information on SD and COR -#' are shown. -#' @param 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 `sigma` -#' should be included. May be abbreviated. Note that the *conditional* -#' component is also called *count* or *mean* component, depending on the -#' model. There are three convenient shortcuts: `component = "all"` returns -#' all possible parameters. If `component = "location"`, location parameters -#' such as `conditional`, `zero_inflated`, or `smooth_terms`, are returned -#' (everything that are fixed or random effects - depending on the `effects` -#' argument - but no auxiliary parameters). For `component = "distributional"` -#' (or `"auxiliary"`), components like `sigma`, `dispersion`, or `beta` -#' (and other auxiliary parameters) are returned. -#' @param as_draws Logical, if `TRUE` and `model` is of class `data.frame`, -#' the data frame is treated as posterior samples and handled similar to -#' Bayesian models. All arguments in `...` are passed to -#' `model_parameters.draws()`. -#' @inheritParams model_parameters.default -#' @inheritParams bayestestR::describe_posterior -#' @inheritParams insight::get_parameters -#' -#' @seealso [insight::standardize_names()] to -#' rename columns into a consistent, standardized naming scheme. -#' -#' @note When `standardize = "refit"`, columns `diagnostic`, -#' `bf_prior` and `priors` refer to the *original* -#' `model`. If `model` is a data frame, arguments `diagnostic`, -#' `bf_prior` and `priors` are ignored. \cr \cr There is also a -#' [`plot()`-method](https://easystats.github.io/see/articles/parameters.html) -#' implemented in the -#' [**see**-package](https://easystats.github.io/see/). -#' -#' @inheritSection model_parameters Confidence intervals and approximation of degrees of freedom -#' -#' @examples -#' \donttest{ -#' library(parameters) -#' if (require("rstanarm")) { -#' model <- suppressWarnings(stan_glm( -#' Sepal.Length ~ Petal.Length * Species, -#' data = iris, iter = 500, refresh = 0 -#' )) -#' model_parameters(model) -#' } -#' } -#' @return A data frame of indices related to the model's parameters. #' @export model_parameters.stanreg <- function(model, centrality = "median", diff --git a/R/methods_scam.R b/R/methods_scam.R index ce5ecfef7..743fea4b7 100644 --- a/R/methods_scam.R +++ b/R/methods_scam.R @@ -10,6 +10,5 @@ standard_error.scam <- standard_error.gam p_value.scam <- p_value.gam -#' @rdname model_parameters.cgam #' @export model_parameters.scam <- model_parameters.cgam diff --git a/R/methods_selection.R b/R/methods_selection.R index 728adba85..59b7f5a8f 100644 --- a/R/methods_selection.R +++ b/R/methods_selection.R @@ -1,8 +1,7 @@ -#' @rdname model_parameters.averaging #' @export model_parameters.selection <- function(model, ci = 0.95, - component = c("all", "selection", "outcome", "auxiliary"), + component = "all", bootstrap = FALSE, iterations = 1000, standardize = NULL, @@ -14,7 +13,10 @@ model_parameters.selection <- function(model, drop = NULL, verbose = TRUE, ...) { - component <- match.arg(component) + component <- insight::validate_argument( + component, + c("all", "selection", "outcome", "auxiliary") + ) ## TODO remove deprecated later if (!missing(summary)) { diff --git a/R/n_clusters.R b/R/n_clusters.R index 0b5712542..91bd53794 100644 --- a/R/n_clusters.R +++ b/R/n_clusters.R @@ -41,7 +41,7 @@ #' @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.glm +#' @inheritParams model_parameters.default #' #' #' diff --git a/R/pool_parameters.R b/R/pool_parameters.R index 8693641af..2ce65d4d0 100644 --- a/R/pool_parameters.R +++ b/R/pool_parameters.R @@ -13,7 +13,7 @@ #' `ci` or `ci_method` etc. #' @inheritParams model_parameters.default #' @inheritParams bootstrap_model -#' @inheritParams model_parameters.merMod +#' @inheritParams model_parameters.glmmTMB #' #' @note #' Models with multiple components, (for instance, models with zero-inflation, diff --git a/R/simulate_parameters.R b/R/simulate_parameters.R index e26a4e2b5..aa57275a4 100644 --- a/R/simulate_parameters.R +++ b/R/simulate_parameters.R @@ -54,8 +54,6 @@ simulate_parameters <- function(model, ...) { } - - #' @rdname simulate_parameters #' @export simulate_parameters.default <- function(model, diff --git a/R/utils_model_parameters.R b/R/utils_model_parameters.R index 4896982c1..2ae4c0efc 100644 --- a/R/utils_model_parameters.R +++ b/R/utils_model_parameters.R @@ -458,7 +458,7 @@ not_allowed_string <- datawizard::text_concatenate(not_allowed, enclose = "\"") insight::format_alert( sprintf("Following arguments are not supported in `%s()` for models of class `%s` and will be ignored: %s", function_name, model_class, not_allowed_string), # nolint - sprintf("Please run `%s()` again without specifying the above mentioned arguments to obtain expected results.", function_name) # nolint + sprintf("In case you obtain expected results, please run `%s()` again without specifying the above mentioned arguments.", function_name) # nolint ) } dots[not_allowed] <- NULL diff --git a/inst/WORDLIST b/inst/WORDLIST index 70fddfdf6..5d922bcb6 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -13,6 +13,7 @@ BMJ Bayarri BayesFM BayesFactor +BFBayesFactor Bentler Bergh Biometrics @@ -38,6 +39,7 @@ Davison De Delacre DirichletReg +DirichletRegModel DoF DoFs Dom @@ -215,6 +217,7 @@ ci clubSandwich cmprsk countreg +clm cplm datanovia datawizard @@ -287,6 +290,7 @@ maxLik mblogit mclogit mclust +mjoint meaned merDeriv merMod diff --git a/man/bootstrap_model.Rd b/man/bootstrap_model.Rd index b17d793f9..d030a0cb8 100644 --- a/man/bootstrap_model.Rd +++ b/man/bootstrap_model.Rd @@ -3,7 +3,6 @@ \name{bootstrap_model} \alias{bootstrap_model} \alias{bootstrap_model.default} -\alias{bootstrap_model.merMod} \title{Model bootstrapping} \usage{ bootstrap_model(model, iterations = 1000, ...) @@ -12,17 +11,7 @@ bootstrap_model(model, iterations = 1000, ...) model, iterations = 1000, type = "ordinary", - parallel = c("no", "multicore", "snow"), - n_cpus = 1, - verbose = FALSE, - ... -) - -\method{bootstrap_model}{merMod}( - model, - iterations = 1000, - type = "parametric", - parallel = c("no", "multicore", "snow"), + parallel = "no", n_cpus = 1, cluster = NULL, verbose = FALSE, @@ -46,10 +35,10 @@ other models, see argument \code{sim} in \code{?boot::boot} (defaults to \item{n_cpus}{Number of processes to be used in parallel operation.} -\item{verbose}{Toggle warnings and messages.} - \item{cluster}{Optional cluster when \code{parallel = "snow"}. See \code{?lme4::bootMer} for details.} + +\item{verbose}{Toggle warnings and messages.} } \value{ A data frame of bootstrapped estimates. diff --git a/man/ci.default.Rd b/man/ci.default.Rd index e1ca2e1eb..7446511c0 100644 --- a/man/ci.default.Rd +++ b/man/ci.default.Rd @@ -1,24 +1,21 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/2_ci.R, R/methods_glmmTMB.R, R/methods_lme4.R +% Please edit documentation in R/2_ci.R \name{ci.default} \alias{ci.default} -\alias{ci.glmmTMB} -\alias{ci.merMod} \title{Confidence Intervals (CI)} \usage{ -\method{ci}{default}(x, ci = 0.95, dof = NULL, method = NULL, ...) - -\method{ci}{glmmTMB}( +\method{ci}{default}( x, ci = 0.95, dof = NULL, - method = "wald", + method = NULL, + iterations = 500, component = "all", + vcov = NULL, + vcov_args = NULL, verbose = TRUE, ... ) - -\method{ci}{merMod}(x, ci = 0.95, dof = NULL, method = "wald", iterations = 500, ...) } \arguments{ \item{x}{A statistical model.} @@ -27,32 +24,60 @@ \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.} +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{...}{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{iterations}{The number of bootstrap replicates. Only applies to models +of class \code{merMod} when \code{method=boot}.} \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.} +\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{iterations}{The number of bootstrap replicates. Only applies to models -of class \code{merMod} when \code{method=boot}.} +\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.} } \value{ A data frame containing the CI bounds. @@ -226,6 +251,50 @@ p-values are based on the probability of direction (\code{\link[bayestestR:p_dir 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"} +} + +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("glmmTMB") && requireNamespace("sandwich")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} data(qol_cancer) diff --git a/man/cluster_performance.Rd b/man/cluster_performance.Rd index 90e3ff15c..0051ef67c 100644 --- a/man/cluster_performance.Rd +++ b/man/cluster_performance.Rd @@ -2,30 +2,22 @@ % Please edit documentation in R/cluster_performance.R \name{cluster_performance} \alias{cluster_performance} -\alias{cluster_performance.kmeans} \alias{cluster_performance.hclust} -\alias{cluster_performance.dbscan} -\alias{cluster_performance.parameters_clusters} \title{Performance of clustering models} \usage{ cluster_performance(model, ...) -\method{cluster_performance}{kmeans}(model, ...) - \method{cluster_performance}{hclust}(model, data, clusters, ...) - -\method{cluster_performance}{dbscan}(model, data, ...) - -\method{cluster_performance}{parameters_clusters}(model, ...) } \arguments{ \item{model}{Cluster model.} \item{...}{Arguments passed to or from other methods.} -\item{data}{A data.frame.} +\item{data}{A data frame.} -\item{clusters}{A vector with clusters assignments (must be same length as rows in data).} +\item{clusters}{A vector with clusters assignments (must be same length as +rows in data).} } \description{ Compute performance indices for clustering solutions. @@ -34,20 +26,13 @@ Compute performance indices for clustering solutions. # kmeans model <- kmeans(iris[1:4], 3) cluster_performance(model) + # hclust data <- iris[1:4] model <- hclust(dist(data)) clusters <- cutree(model, 3) +cluster_performance(model, data, clusters) -rez <- cluster_performance(model, data, clusters) -rez -\dontshow{if (require("dbscan", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} -# DBSCAN -model <- dbscan::dbscan(iris[1:4], eps = 1.45, minPts = 10) - -rez <- cluster_performance(model, iris[1:4]) -rez -\dontshow{\}) # examplesIf} # Retrieve performance from parameters params <- model_parameters(kmeans(iris[1:4], 3)) cluster_performance(params) diff --git a/man/equivalence_test.lm.Rd b/man/equivalence_test.lm.Rd index 10aed33ed..d3da954f6 100644 --- a/man/equivalence_test.lm.Rd +++ b/man/equivalence_test.lm.Rd @@ -2,7 +2,6 @@ % Please edit documentation in R/equivalence_test.R \name{equivalence_test.lm} \alias{equivalence_test.lm} -\alias{equivalence_test.merMod} \alias{equivalence_test.ggeffects} \title{Equivalence test} \usage{ @@ -11,18 +10,7 @@ range = "default", ci = 0.95, rule = "classic", - vcov = NULL, - vcov_args = NULL, - verbose = TRUE, - ... -) - -\method{equivalence_test}{merMod}( - x, - range = "default", - ci = 0.95, - rule = "classic", - effects = c("fixed", "random"), + effects = "fixed", vcov = NULL, vcov_args = NULL, verbose = TRUE, @@ -50,6 +38,11 @@ model's data.} \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"}), or both (\code{"all"}) 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 @@ -64,8 +57,8 @@ identifies the function to be used to compute the covariance matrix. \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} +\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"}. } @@ -83,11 +76,6 @@ type for \code{"HC"} equals the default from the \strong{sandwich} package; for \item{...}{Arguments passed to or from other methods.} -\item{effects}{Should parameters for fixed effects (\code{"fixed"}), random -effects (\code{"random"}), or both (\code{"all"}) 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{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.} diff --git a/man/model_parameters.Rd b/man/model_parameters.Rd index e92afb737..387a1b29c 100644 --- a/man/model_parameters.Rd +++ b/man/model_parameters.Rd @@ -40,16 +40,17 @@ the model-specific documentation: \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}, \code{gamm}, ... -\item \link[=model_parameters.aov]{ANOVA}: \strong{afex}, \code{aov}, \code{anova}, ... +\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.stanreg]{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.kmeans]{Clustering}: \strong{hclust}, \strong{kmeans}, \strong{mclust}, \strong{pam}, ... +\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.merMod]{Mixed models}: \strong{cplm}, \strong{glmmTMB}, \strong{lme4}, +\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}, ... @@ -58,7 +59,7 @@ the model-specific documentation: \strong{psych}, \code{sem}, ... \item \link[=model_parameters.zcpglm]{Zero-inflated and hurdle}: \strong{cplm}, \strong{mhurdle}, \strong{pscl}, ... -\item \link[=model_parameters.averaging]{Other models}: \strong{aod}, \strong{bbmle}, \strong{betareg}, +\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}, @@ -66,6 +67,10 @@ the model-specific documentation: \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 diff --git a/man/model_parameters.aov.Rd b/man/model_parameters.aov.Rd index bd24bb816..53e9de317 100644 --- a/man/model_parameters.aov.Rd +++ b/man/model_parameters.aov.Rd @@ -2,7 +2,6 @@ % Please edit documentation in R/methods_aov.R \name{model_parameters.aov} \alias{model_parameters.aov} -\alias{model_parameters.afex_aov} \title{Parameters from ANOVAs} \usage{ \method{model_parameters}{aov}( @@ -20,17 +19,6 @@ verbose = TRUE, ... ) - -\method{model_parameters}{afex_aov}( - model, - es_type = NULL, - df_error = NULL, - type = NULL, - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) } \arguments{ \item{model}{Object of class \code{\link[=aov]{aov()}}, \code{\link[=anova]{anova()}}, diff --git a/man/model_parameters.stanreg.Rd b/man/model_parameters.brmsfit.Rd similarity index 80% rename from man/model_parameters.stanreg.Rd rename to man/model_parameters.brmsfit.Rd index 7ea0a94bc..841f65f49 100644 --- a/man/model_parameters.stanreg.Rd +++ b/man/model_parameters.brmsfit.Rd @@ -1,32 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/methods_MCMCglmm.R, R/methods_base.R, -% R/methods_brms.R, R/methods_posterior.R, R/methods_rstanarm.R -\name{model_parameters.MCMCglmm} -\alias{model_parameters.MCMCglmm} +% 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} -\alias{model_parameters.draws} -\alias{model_parameters.stanreg} \title{Parameters from Bayesian Models} \usage{ -\method{model_parameters}{MCMCglmm}( - 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, - ... -) - \method{model_parameters}{data.frame}( model, as_draws = FALSE, @@ -57,50 +35,54 @@ verbose = TRUE, ... ) - -\method{model_parameters}{draws}( - model, - centrality = "median", - dispersion = FALSE, - ci = 0.95, - ci_method = "eti", - test = "pd", - rope_range = "default", - rope_ci = 0.95, - exponentiate = FALSE, - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) - -\method{model_parameters}{stanreg}( - 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, - effects = "fixed", - 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)}), @@ -148,52 +130,6 @@ with one or more of these options: \code{"ESS"}, \code{"Rhat"}, \code{"MCSE"} or \item{priors}{Add the prior used for each parameter.} -\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 messages and warnings.} - -\item{...}{Currently not used.} - -\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{effects}{Should results for fixed effects, random effects or both be returned? Only applies to mixed models. May be abbreviated.} @@ -233,21 +169,45 @@ 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{ -Parameters from Bayesian models. +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. \cr \cr There is also a +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}. +implemented in the \href{https://easystats.github.io/see/}{\strong{see}-package}. } \section{Confidence intervals and approximation of degrees of freedom}{ @@ -415,6 +375,50 @@ p-values are based on the probability of direction (\code{\link[bayestestR:p_dir 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"} +} + +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{ \donttest{ library(parameters) @@ -428,6 +432,6 @@ if (require("rstanarm")) { } } \seealso{ -\code{\link[insight:standardize_names]{insight::standardize_names()}} to -rename columns into a consistent, standardized naming scheme. +\code{\link[insight:standardize_names]{insight::standardize_names()}} to rename columns into a consistent, +standardized naming scheme. } diff --git a/man/model_parameters.cgam.Rd b/man/model_parameters.cgam.Rd index 72ee6f30c..d444ecba8 100644 --- a/man/model_parameters.cgam.Rd +++ b/man/model_parameters.cgam.Rd @@ -1,11 +1,7 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/methods_cgam.R, R/methods_mgcv.R, -% R/methods_other.R, R/methods_scam.R +% Please edit documentation in R/methods_cgam.R \name{model_parameters.cgam} \alias{model_parameters.cgam} -\alias{model_parameters.gamm} -\alias{model_parameters.Gam} -\alias{model_parameters.scam} \title{Parameters from Generalized Additive (Mixed) Models} \usage{ \method{model_parameters}{cgam}( @@ -22,40 +18,6 @@ verbose = TRUE, ... ) - -\method{model_parameters}{gamm}( - model, - ci = 0.95, - bootstrap = FALSE, - iterations = 1000, - verbose = TRUE, - ... -) - -\method{model_parameters}{Gam}( - model, - es_type = NULL, - df_error = NULL, - type = NULL, - table_wide = FALSE, - verbose = TRUE, - ... -) - -\method{model_parameters}{scam}( - 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.} @@ -160,23 +122,6 @@ this function. model summaries, it is recommended to set \code{pretty_names = FALSE} to speed up computation of the summary table. }} - -\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{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{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{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}.} } \value{ A data frame of indices related to the model's parameters. diff --git a/man/model_parameters.default.Rd b/man/model_parameters.default.Rd index 872270db0..25c595b89 100644 --- a/man/model_parameters.default.Rd +++ b/man/model_parameters.default.Rd @@ -1,11 +1,7 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/1_model_parameters.R, R/methods_censReg.R, -% R/methods_mass.R +% Please edit documentation in R/1_model_parameters.R \name{model_parameters.default} \alias{model_parameters.default} -\alias{model_parameters.glm} -\alias{model_parameters.censReg} -\alias{model_parameters.ridgelm} \title{Parameters from (General) Linear Models} \usage{ \method{model_parameters}{default}( @@ -26,46 +22,6 @@ verbose = TRUE, ... ) - -\method{model_parameters}{glm}( - model, - ci = 0.95, - ci_method = NULL, - bootstrap = FALSE, - iterations = 1000, - standardize = NULL, - exponentiate = FALSE, - p_adjust = NULL, - vcov = NULL, - vcov_args = NULL, - summary = getOption("parameters_summary", FALSE), - include_info = getOption("parameters_info", FALSE), - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) - -\method{model_parameters}{censReg}( - model, - ci = 0.95, - ci_method = NULL, - bootstrap = FALSE, - iterations = 1000, - standardize = NULL, - exponentiate = FALSE, - p_adjust = NULL, - vcov = NULL, - vcov_args = NULL, - summary = getOption("parameters_summary", FALSE), - include_info = getOption("parameters_info", FALSE), - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) - -\method{model_parameters}{ridgelm}(model, verbose = TRUE, ...) } \arguments{ \item{model}{Model object.} @@ -141,8 +97,8 @@ identifies the function to be used to compute the covariance matrix. \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} +\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"}. } diff --git a/man/model_parameters.averaging.Rd b/man/model_parameters.glimML.Rd similarity index 55% rename from man/model_parameters.averaging.Rd rename to man/model_parameters.glimML.Rd index 39bbfe0f0..9703b2702 100644 --- a/man/model_parameters.averaging.Rd +++ b/man/model_parameters.glimML.Rd @@ -1,23 +1,7 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/methods_aod.R, R/methods_averaging.R, -% R/methods_betareg.R, R/methods_emmeans.R, R/methods_glmx.R, -% R/methods_marginaleffects.R, R/methods_metaplus.R, R/methods_mfx.R, -% R/methods_mjoint.R, R/methods_mvord.R, R/methods_selection.R +% Please edit documentation in R/methods_aod.R \name{model_parameters.glimML} \alias{model_parameters.glimML} -\alias{model_parameters.averaging} -\alias{model_parameters.betareg} -\alias{model_parameters.emm_list} -\alias{model_parameters.glmx} -\alias{model_parameters.marginaleffects} -\alias{model_parameters.metaplus} -\alias{model_parameters.meta_random} -\alias{model_parameters.meta_bma} -\alias{model_parameters.betaor} -\alias{model_parameters.betamfx} -\alias{model_parameters.mjoint} -\alias{model_parameters.mvord} -\alias{model_parameters.selection} \title{Parameters from special models} \usage{ \method{model_parameters}{glimML}( @@ -25,171 +9,7 @@ ci = 0.95, bootstrap = FALSE, iterations = 1000, - component = c("conditional", "random", "dispersion", "all"), - standardize = NULL, - exponentiate = FALSE, - p_adjust = NULL, - summary = getOption("parameters_summary", FALSE), - include_info = getOption("parameters_info", FALSE), - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) - -\method{model_parameters}{averaging}( - model, - ci = 0.95, - component = c("conditional", "full"), - exponentiate = FALSE, - p_adjust = NULL, - summary = getOption("parameters_summary", FALSE), - include_info = getOption("parameters_info", FALSE), - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) - -\method{model_parameters}{betareg}( - model, - ci = 0.95, - bootstrap = FALSE, - iterations = 1000, - component = c("conditional", "precision", "all"), - standardize = NULL, - exponentiate = FALSE, - p_adjust = NULL, - summary = getOption("parameters_summary", FALSE), - include_info = getOption("parameters_info", FALSE), - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) - -\method{model_parameters}{emm_list}( - model, - ci = 0.95, - exponentiate = FALSE, - p_adjust = NULL, - verbose = TRUE, - ... -) - -\method{model_parameters}{glmx}( - model, - ci = 0.95, - bootstrap = FALSE, - iterations = 1000, - component = c("all", "conditional", "extra"), - standardize = NULL, - exponentiate = FALSE, - p_adjust = NULL, - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) - -\method{model_parameters}{marginaleffects}(model, ci = 0.95, exponentiate = FALSE, ...) - -\method{model_parameters}{metaplus}( - model, - ci = 0.95, - bootstrap = FALSE, - iterations = 1000, - standardize = NULL, - exponentiate = FALSE, - include_studies = TRUE, - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) - -\method{model_parameters}{meta_random}( - model, - ci = 0.95, - ci_method = "eti", - exponentiate = FALSE, - include_studies = TRUE, - verbose = TRUE, - ... -) - -\method{model_parameters}{meta_bma}( - model, - ci = 0.95, - ci_method = "eti", - exponentiate = FALSE, - include_studies = TRUE, - verbose = TRUE, - ... -) - -\method{model_parameters}{betaor}( - model, - ci = 0.95, - bootstrap = FALSE, - iterations = 1000, - component = c("conditional", "precision", "all"), - standardize = NULL, - exponentiate = FALSE, - p_adjust = NULL, - verbose = TRUE, - ... -) - -\method{model_parameters}{betamfx}( - model, - ci = 0.95, - bootstrap = FALSE, - iterations = 1000, - component = c("all", "conditional", "precision", "marginal"), - standardize = NULL, - exponentiate = FALSE, - p_adjust = NULL, - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) - -\method{model_parameters}{mjoint}( - model, - ci = 0.95, - effects = "fixed", - component = c("all", "conditional", "survival"), - exponentiate = FALSE, - p_adjust = NULL, - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) - -\method{model_parameters}{mvord}( - model, - ci = 0.95, - component = c("all", "conditional", "thresholds", "correlation"), - standardize = NULL, - exponentiate = FALSE, - p_adjust = NULL, - summary = getOption("parameters_summary", FALSE), - include_info = getOption("parameters_info", FALSE), - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) - -\method{model_parameters}{selection}( - model, - ci = 0.95, - component = c("all", "selection", "outcome", "auxiliary"), - bootstrap = FALSE, - iterations = 1000, + component = "conditional", standardize = NULL, exponentiate = FALSE, p_adjust = NULL, @@ -214,10 +34,10 @@ case of bootstrapped frequentist models.} \item{component}{Model component for which parameters should be shown. May be -one of \code{"conditional"}, \code{"precision"} (\strong{betareg}), -\code{"scale"} (\strong{ordinal}), \code{"extra"} (\strong{glmx}), -\code{"marginal"} (\strong{mfx}), \code{"conditional"} or \code{"full"} (for -\code{MuMIn::model.avg()}) or \code{"all"}.} +one of \code{"conditional"}, \code{"precision"} (e.g. \strong{betareg}), \code{"scale"} (e.g. +\strong{ordinal}), \code{"extra"} (e.g. \strong{glmx}), \code{"marginal"} (e.g. \strong{mfx}), +\code{"conditional"} or \code{"full"} (for \code{MuMIn::model.avg()}) or \code{"all"}. See section +\emph{Model components} for an overview of possible options for \code{component}.} \item{standardize}{The method used for standardizing the parameters. Can be \code{NULL} (default; no standardization), \code{"refit"} (for re-fitting the model @@ -306,29 +126,58 @@ this function. model summaries, it is recommended to set \code{pretty_names = FALSE} to speed up computation of the summary table. }} - -\item{include_studies}{Logical, if \code{TRUE} (default), includes parameters -for all studies. Else, only parameters for overall-effects are shown.} - -\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{effects}{Should results for fixed effects, random effects or both be -returned? Only applies to mixed models. May be abbreviated.} } \value{ A data frame of indices related to the model's parameters. } \description{ -Parameters from special regression models not listed under one of the previous categories yet. +Parameters from special regression models not listed under one of the +previous categories yet. +} +\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"} +} + +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{ library(parameters) if (require("brglm2", quietly = TRUE)) { @@ -343,6 +192,6 @@ if (require("brglm2", quietly = TRUE)) { } } \seealso{ -\code{\link[insight:standardize_names]{insight::standardize_names()}} to rename -columns into a consistent, standardized naming scheme. +\code{\link[insight:standardize_names]{insight::standardize_names()}} to rename columns into a consistent, +standardized naming scheme. } diff --git a/man/model_parameters.merMod.Rd b/man/model_parameters.glmmTMB.Rd similarity index 79% rename from man/model_parameters.merMod.Rd rename to man/model_parameters.glmmTMB.Rd index 7f7147de7..527fb6eb2 100644 --- a/man/model_parameters.merMod.Rd +++ b/man/model_parameters.glmmTMB.Rd @@ -1,37 +1,9 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/methods_cplm.R, R/methods_glmmTMB.R, -% R/methods_lme4.R, R/methods_mixed.R, R/methods_mixmod.R, R/methods_nlme.R, -% R/methods_ordinal.R -\name{model_parameters.cpglmm} -\alias{model_parameters.cpglmm} +% Please edit documentation in R/methods_glmmTMB.R +\name{model_parameters.glmmTMB} \alias{model_parameters.glmmTMB} -\alias{model_parameters.merMod} -\alias{model_parameters.mixed} -\alias{model_parameters.MixMod} -\alias{model_parameters.lme} -\alias{model_parameters.clmm2} -\alias{model_parameters.clmm} \title{Parameters from Mixed Models} \usage{ -\method{model_parameters}{cpglmm}( - model, - ci = 0.95, - ci_method = NULL, - ci_random = NULL, - bootstrap = FALSE, - iterations = 1000, - standardize = NULL, - effects = "all", - group_level = FALSE, - exponentiate = FALSE, - p_adjust = NULL, - include_sigma = FALSE, - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) - \method{model_parameters}{glmmTMB}( model, ci = 0.95, @@ -54,136 +26,6 @@ verbose = TRUE, ... ) - -\method{model_parameters}{merMod}( - model, - ci = 0.95, - ci_method = NULL, - ci_random = NULL, - bootstrap = FALSE, - iterations = 1000, - standardize = NULL, - effects = "all", - group_level = FALSE, - exponentiate = FALSE, - p_adjust = NULL, - vcov = NULL, - vcov_args = NULL, - wb_component = TRUE, - summary = getOption("parameters_mixed_summary", FALSE), - include_info = getOption("parameters_mixed_info", FALSE), - include_sigma = FALSE, - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) - -\method{model_parameters}{mixed}( - model, - ci = 0.95, - ci_method = "wald", - ci_random = NULL, - bootstrap = FALSE, - iterations = 1000, - standardize = NULL, - effects = "all", - component = "all", - group_level = FALSE, - exponentiate = FALSE, - p_adjust = NULL, - wb_component = TRUE, - summary = getOption("parameters_mixed_summary", FALSE), - include_info = getOption("parameters_mixed_info", FALSE), - include_sigma = FALSE, - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) - -\method{model_parameters}{MixMod}( - model, - ci = 0.95, - ci_method = "wald", - ci_random = NULL, - bootstrap = FALSE, - iterations = 1000, - standardize = NULL, - effects = "all", - component = "all", - group_level = FALSE, - exponentiate = FALSE, - p_adjust = NULL, - wb_component = TRUE, - summary = getOption("parameters_mixed_summary", FALSE), - include_info = getOption("parameters_mixed_info", FALSE), - include_sigma = FALSE, - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) - -\method{model_parameters}{lme}( - model, - ci = 0.95, - ci_method = NULL, - ci_random = NULL, - bootstrap = FALSE, - iterations = 1000, - standardize = NULL, - effects = "all", - group_level = FALSE, - exponentiate = FALSE, - p_adjust = NULL, - vcov = NULL, - vcov_args = NULL, - wb_component = TRUE, - summary = getOption("parameters_mixed_summary", FALSE), - include_info = getOption("parameters_mixed_info", FALSE), - include_sigma = FALSE, - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) - -\method{model_parameters}{clmm2}( - model, - ci = 0.95, - bootstrap = FALSE, - iterations = 1000, - component = c("all", "conditional", "scale"), - standardize = NULL, - exponentiate = FALSE, - p_adjust = NULL, - summary = getOption("parameters_summary", FALSE), - include_info = getOption("parameters_info", FALSE), - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) - -\method{model_parameters}{clmm}( - model, - ci = 0.95, - ci_method = NULL, - ci_random = NULL, - bootstrap = FALSE, - iterations = 1000, - standardize = NULL, - effects = "all", - group_level = FALSE, - exponentiate = FALSE, - p_adjust = NULL, - include_sigma = FALSE, - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) } \arguments{ \item{model}{A mixed model.} @@ -215,7 +57,8 @@ or omit calculation of confidence intervals.} \code{TRUE}, then arguments of \link[=model_parameters.stanreg]{Bayesian regressions} apply (see also \code{\link[=bootstrap_parameters]{bootstrap_parameters()}}).} -\item{iterations}{The number of draws to simulate/bootstrap.} +\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 @@ -239,6 +82,20 @@ effects (\code{"random"}), or both (\code{"all"}) 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{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 @@ -266,6 +123,19 @@ 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{wb_component}{Logical, if \code{TRUE} and models contains within- and +between-effects (see \code{datawizard::demean()}), the \code{Component} column +will indicate which variables belong to the within-effects, +between-effects, and cross-level interactions. By default, the +\code{Component} column indicates, which parameters belong to the +conditional or zero-inflation component of the model.} + +\item{summary}{Deprecated, please use \code{info} instead.} + +\item{include_info}{Logical, if \code{TRUE}, prints summary information about the +model (model formula, number of observations, residual standard deviation +and more).} + \item{include_sigma}{Logical, if \code{TRUE}, includes the residual standard deviation. For mixed models, this is defined as the sum of the distribution-specific variance and the variance for the additive overdispersion term (see @@ -315,54 +185,6 @@ this function. model summaries, it is recommended to set \code{pretty_names = FALSE} to speed up computation of the summary table. }} - -\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.} - -\item{wb_component}{Logical, if \code{TRUE} and models contains within- and -between-effects (see \code{datawizard::demean()}), the \code{Component} column -will indicate which variables belong to the within-effects, -between-effects, and cross-level interactions. By default, the -\code{Component} column indicates, which parameters belong to the -conditional or zero-inflation component of the model.} - -\item{summary}{Deprecated, please use \code{info} instead.} - -\item{include_info}{Logical, if \code{TRUE}, prints summary information about the -model (model formula, number of observations, residual standard deviation -and more).} - -\item{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"}.} } \value{ A data frame of indices related to the model's parameters. @@ -441,6 +263,50 @@ For models where the dispersion parameter and the residual variance are the same, only the residual variance is shown in the output. } +\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"} +} + +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. +} + \section{Confidence intervals and approximation of degrees of freedom}{ There are different ways of approximating the degrees of freedom depending diff --git a/man/model_parameters.hclust.Rd b/man/model_parameters.hclust.Rd new file mode 100644 index 000000000..2593c9786 --- /dev/null +++ b/man/model_parameters.hclust.Rd @@ -0,0 +1,106 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/methods_hclust.R +\name{model_parameters.hclust} +\alias{model_parameters.hclust} +\title{Parameters from Cluster Models (k-means, ...)} +\usage{ +\method{model_parameters}{hclust}(model, data = NULL, clusters = NULL, ...) +} +\arguments{ +\item{model}{Cluster model.} + +\item{data}{A data frame.} + +\item{clusters}{A vector with clusters assignments (must be same length as +rows in data).} + +\item{...}{Arguments passed to or from other methods.} +} +\description{ +Format cluster models obtained for example by \code{\link[=kmeans]{kmeans()}}. +} +\examples{ +\dontshow{if (require("factoextra", quietly = TRUE) && require("dbscan", quietly = TRUE) && require("cluster", quietly = TRUE) && require("fpc", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} +\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]) +} +\dontshow{\}) # examplesIf} +} diff --git a/man/model_parameters.kmeans.Rd b/man/model_parameters.kmeans.Rd deleted file mode 100644 index 739773efd..000000000 --- a/man/model_parameters.kmeans.Rd +++ /dev/null @@ -1,164 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/methods_dbscan.R, R/methods_hclust.R, -% R/methods_kmeans.R, R/methods_mclust.R, R/methods_pam.R -\name{model_parameters.dbscan} -\alias{model_parameters.dbscan} -\alias{model_parameters.hclust} -\alias{model_parameters.pvclust} -\alias{model_parameters.kmeans} -\alias{model_parameters.hkmeans} -\alias{model_parameters.Mclust} -\alias{model_parameters.pam} -\title{Parameters from Cluster Models (k-means, ...)} -\usage{ -\method{model_parameters}{dbscan}(model, data = NULL, clusters = NULL, ...) - -\method{model_parameters}{hclust}(model, data = NULL, clusters = NULL, ...) - -\method{model_parameters}{pvclust}(model, data = NULL, clusters = NULL, ci = 0.95, ...) - -\method{model_parameters}{kmeans}(model, ...) - -\method{model_parameters}{hkmeans}(model, ...) - -\method{model_parameters}{Mclust}(model, data = NULL, clusters = NULL, ...) - -\method{model_parameters}{pam}(model, data = NULL, clusters = NULL, ...) -} -\arguments{ -\item{model}{Cluster model.} - -\item{data}{A data.frame.} - -\item{clusters}{A vector with clusters assignments (must be same length as rows in data).} - -\item{...}{Arguments passed to or from other methods.} - -\item{ci}{Confidence Interval (CI) level. Default to \code{0.95} (\verb{95\%}).} -} -\description{ -Format cluster models obtained for example by \code{\link[=kmeans]{kmeans()}}. -} -\examples{ -\donttest{ -# DBSCAN --------------------------- -if (require("dbscan", quietly = TRUE)) { - 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]) -} -} -# -# 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 -\donttest{ -# -# pvclust (finds "significant" clusters) --------------------------- -if (require("pvclust", quietly = TRUE)) { - data <- iris[1:4] - # NOTE: pvclust works on transposed data - model <- pvclust::pvclust(datawizard::data_transpose(data, verbose = FALSE), - method.dist = "euclidean", - nboot = 50, - quiet = TRUE - ) - - rez <- model_parameters(model, data, ci = 0.90) - 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 -} -} -\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 -} -\donttest{ -# -# Hierarchical K-means (factoextra::hkclust) ---------------------- -if (require("factoextra", quietly = TRUE)) { - 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 -} -} -if (require("mclust", quietly = TRUE)) { - model <- mclust::Mclust(iris[1:4], verbose = FALSE) - model_parameters(model) -} -\donttest{ -# -# K-Medoids (PAM and HPAM) ============== -if (require("cluster", quietly = TRUE)) { - model <- cluster::pam(iris[1:4], k = 3) - model_parameters(model) -} -if (require("fpc", quietly = TRUE)) { - model <- fpc::pamk(iris[1:4], criterion = "ch") - model_parameters(model) -} -} -} diff --git a/man/model_parameters.mlm.Rd b/man/model_parameters.mlm.Rd index 11b83a4f8..7480c38c1 100644 --- a/man/model_parameters.mlm.Rd +++ b/man/model_parameters.mlm.Rd @@ -1,29 +1,13 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/methods_DirichletReg.R, R/methods_bife.R, -% R/methods_brglm2.R, R/methods_mlm.R, R/methods_ordinal.R -\name{model_parameters.DirichletRegModel} -\alias{model_parameters.DirichletRegModel} +% Please edit documentation in R/methods_bife.R, R/methods_brglm2.R, +% R/methods_mlm.R, R/methods_ordinal.R +\name{model_parameters.bifeAPEs} \alias{model_parameters.bifeAPEs} \alias{model_parameters.bracl} \alias{model_parameters.mlm} \alias{model_parameters.clm2} \title{Parameters from multinomial or cumulative link models} \usage{ -\method{model_parameters}{DirichletRegModel}( - model, - ci = 0.95, - bootstrap = FALSE, - iterations = 1000, - component = c("all", "conditional", "precision"), - standardize = NULL, - exponentiate = FALSE, - p_adjust = NULL, - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) - \method{model_parameters}{bifeAPEs}(model, ...) \method{model_parameters}{bracl}( @@ -63,7 +47,7 @@ ci = 0.95, bootstrap = FALSE, iterations = 1000, - component = c("all", "conditional", "scale"), + component = "all", standardize = NULL, exponentiate = FALSE, p_adjust = NULL, @@ -78,6 +62,26 @@ \arguments{ \item{model}{A model with multinomial or categorical response value.} +\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{ci}{Confidence Interval (CI) level. Default to \code{0.95} (\verb{95\%}).} \item{bootstrap}{Should estimates be based on bootstrapped model? If @@ -87,12 +91,6 @@ \item{iterations}{The number of bootstrap replicates. This only apply in the case of bootstrapped frequentist 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.} - \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"}, @@ -131,6 +129,12 @@ possible adjustment methods are \code{"tukey"}, \code{"scheffe"}, \code{"sidak"} and \code{"none"} to explicitly disable adjustment for \code{emmGrid} objects (from \strong{emmeans}).} +\item{summary}{Deprecated, please use \code{info} instead.} + +\item{include_info}{Logical, if \code{TRUE}, prints summary information about the +model (model formula, number of observations, residual standard deviation +and more).} + \item{keep}{Character containing a regular expression pattern that describes the parameters that should be included (for \code{keep}) or excluded (for \code{drop}) in the returned data frame. \code{keep} may also be a @@ -155,32 +159,6 @@ names.} \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{summary}{Deprecated, please use \code{info} instead.} - -\item{include_info}{Logical, if \code{TRUE}, prints summary information about the -model (model formula, number of observations, residual standard deviation -and more).} - \item{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 @@ -195,8 +173,8 @@ identifies the function to be used to compute the covariance matrix. \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} +\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"}. } @@ -209,6 +187,12 @@ 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{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 of indices related to the model's parameters. @@ -223,6 +207,50 @@ 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"} +} + +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") diff --git a/man/model_parameters.rma.Rd b/man/model_parameters.rma.Rd index e388a84b8..095a100a0 100644 --- a/man/model_parameters.rma.Rd +++ b/man/model_parameters.rma.Rd @@ -62,8 +62,8 @@ 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{include_studies}{Logical, if \code{TRUE} (default), includes parameters -for all studies. Else, only parameters for overall-effects are shown.} +\item{include_studies}{Logical, if \code{TRUE} (default), includes parameters for +all studies. Else, only parameters for overall-effects are shown.} \item{keep}{Character containing a regular expression pattern that describes the parameters that should be included (for \code{keep}) or excluded diff --git a/man/model_parameters.zcpglm.Rd b/man/model_parameters.zcpglm.Rd index d7f14b755..d80b43944 100644 --- a/man/model_parameters.zcpglm.Rd +++ b/man/model_parameters.zcpglm.Rd @@ -1,8 +1,7 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/methods_cplm.R, R/methods_mhurdle.R +% Please edit documentation in R/methods_cplm.R \name{model_parameters.zcpglm} \alias{model_parameters.zcpglm} -\alias{model_parameters.mhurdle} \title{Parameters from Zero-Inflated Models} \usage{ \method{model_parameters}{zcpglm}( @@ -10,7 +9,7 @@ ci = 0.95, bootstrap = FALSE, iterations = 1000, - component = c("all", "conditional", "zi", "zero_inflated"), + component = "all", standardize = NULL, exponentiate = FALSE, p_adjust = NULL, @@ -21,19 +20,6 @@ verbose = TRUE, ... ) - -\method{model_parameters}{mhurdle}( - model, - ci = 0.95, - component = c("all", "conditional", "zi", "zero_inflated", "infrequent_purchase", "ip", - "auxiliary"), - exponentiate = FALSE, - p_adjust = NULL, - keep = NULL, - drop = NULL, - verbose = TRUE, - ... -) } \arguments{ \item{model}{A model with zero-inflation component.} @@ -148,13 +134,59 @@ A data frame of indices related to the model's parameters. Parameters from zero-inflated models (from packages like \strong{pscl}, \strong{cplm} or \strong{countreg}). } -\examples{ -library(parameters) -if (require("pscl")) { - data("bioChemists") - model <- zeroinfl(art ~ fem + mar + kid5 + ment | kid5 + phd, data = bioChemists) - model_parameters(model) +\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"} } + +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")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} +data("bioChemists", package = "pscl") +model <- pscl::zeroinfl( + art ~ fem + mar + kid5 + ment | kid5 + phd, + data = bioChemists +) +model_parameters(model) +\dontshow{\}) # examplesIf} } \seealso{ \code{\link[insight:standardize_names]{insight::standardize_names()}} to rename diff --git a/man/p_direction.lm.Rd b/man/p_direction.lm.Rd index 683c72308..479d6bd9a 100644 --- a/man/p_direction.lm.Rd +++ b/man/p_direction.lm.Rd @@ -39,8 +39,8 @@ identifies the function to be used to compute the covariance matrix. \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} +\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"}. } diff --git a/man/p_function.Rd b/man/p_function.Rd index fd82f9f6b..df870677c 100644 --- a/man/p_function.Rd +++ b/man/p_function.Rd @@ -78,11 +78,19 @@ effects (\code{"random"}), or both (\code{"all"}) 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}{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.} +\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 @@ -98,8 +106,8 @@ identifies the function to be used to compute the covariance matrix. \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} +\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"}. } diff --git a/man/p_significance.lm.Rd b/man/p_significance.lm.Rd index 03d7163da..99e040dcd 100644 --- a/man/p_significance.lm.Rd +++ b/man/p_significance.lm.Rd @@ -49,8 +49,8 @@ identifies the function to be used to compute the covariance matrix. \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} +\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"}. } diff --git a/man/p_value.BFBayesFactor.Rd b/man/p_value.BFBayesFactor.Rd deleted file mode 100644 index d8312fdae..000000000 --- a/man/p_value.BFBayesFactor.Rd +++ /dev/null @@ -1,29 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/methods_BayesFactor.R -\name{p_value.BFBayesFactor} -\alias{p_value.BFBayesFactor} -\title{p-values for Bayesian Models} -\usage{ -\method{p_value}{BFBayesFactor}(model, ...) -} -\arguments{ -\item{model}{A statistical model.} - -\item{...}{Additional arguments} -} -\value{ -The p-values. -} -\description{ -This function attempts to return, or compute, p-values of Bayesian models. -} -\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()}. -} -\examples{ -data(iris) -model <- lm(Petal.Length ~ Sepal.Length + Species, data = iris) -p_value(model) -} diff --git a/man/p_value.DirichletRegModel.Rd b/man/p_value.DirichletRegModel.Rd deleted file mode 100644 index 949df715f..000000000 --- a/man/p_value.DirichletRegModel.Rd +++ /dev/null @@ -1,45 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/methods_DirichletReg.R, R/methods_averaging.R, -% R/methods_betareg.R, R/methods_cgam.R, R/methods_ordinal.R -\name{p_value.DirichletRegModel} -\alias{p_value.DirichletRegModel} -\alias{p_value.averaging} -\alias{p_value.betareg} -\alias{p_value.cgam} -\alias{p_value.clm2} -\title{p-values for Models with Special Components} -\usage{ -\method{p_value}{DirichletRegModel}(model, component = c("all", "conditional", "precision"), ...) - -\method{p_value}{averaging}(model, component = c("conditional", "full"), ...) - -\method{p_value}{betareg}( - model, - component = c("all", "conditional", "precision"), - verbose = TRUE, - ... -) - -\method{p_value}{cgam}(model, component = c("all", "conditional", "smooth_terms"), ...) - -\method{p_value}{clm2}(model, component = c("all", "conditional", "scale"), ...) -} -\arguments{ -\item{model}{A statistical model.} - -\item{component}{Should all parameters, parameters for the conditional model, -precision- or scale-component or smooth_terms be returned? \code{component} -may be one of \code{"conditional"}, \code{"precision"}, \code{"scale"}, -\code{"smooth_terms"}, \code{"full"} or \code{"all"} (default).} - -\item{...}{Additional arguments} - -\item{verbose}{Toggle warnings and messages.} -} -\value{ -The p-values. -} -\description{ -This function attempts to return, or compute, p-values of models -with special model components. -} diff --git a/man/p_value.Rd b/man/p_value.Rd index 8e39e7d4c..8226f6c93 100644 --- a/man/p_value.Rd +++ b/man/p_value.Rd @@ -28,22 +28,21 @@ p_value(model, ...) \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.} +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.} +\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 @@ -59,8 +58,8 @@ identifies the function to be used to compute the covariance matrix. \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} +\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"}. } @@ -88,13 +87,12 @@ components etc. } \description{ This function attempts to return, or compute, p-values of a model's -parameters. See the documentation for your object's class: -\itemize{ -\item \link[=p_value.BFBayesFactor]{Bayesian models} (\strong{rstanarm}, \strong{brms}, \strong{MCMCglmm}, ...) -\item \link[=p_value.zeroinfl]{Zero-inflated models} (\code{hurdle}, \code{zeroinfl}, \code{zerocount}, ...) -\item \link[=p_value.poissonmfx]{Marginal effects models} (\strong{mfx}) -\item \link[=p_value.DirichletRegModel]{Models with special components} (\code{DirichletRegModel}, \code{clm2}, \code{cgam}, ...) +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}{ @@ -262,8 +260,62 @@ p-values are based on the probability of direction (\code{\link[bayestestR:p_dir 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"} +} + +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} } diff --git a/man/p_value.poissonmfx.Rd b/man/p_value.poissonmfx.Rd deleted file mode 100644 index 5e38255dd..000000000 --- a/man/p_value.poissonmfx.Rd +++ /dev/null @@ -1,49 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/methods_mfx.R -\name{p_value.poissonmfx} -\alias{p_value.poissonmfx} -\alias{p_value.betaor} -\alias{p_value.betamfx} -\title{p-values for Marginal Effects Models} -\usage{ -\method{p_value}{poissonmfx}(model, component = c("all", "conditional", "marginal"), ...) - -\method{p_value}{betaor}(model, component = c("all", "conditional", "precision"), ...) - -\method{p_value}{betamfx}( - model, - component = c("all", "conditional", "precision", "marginal"), - ... -) -} -\arguments{ -\item{model}{A statistical model.} - -\item{component}{Should all parameters, parameters for the conditional model, -precision-component or marginal effects be returned? \code{component} may be one -of \code{"conditional"}, \code{"precision"}, \code{"marginal"} or \code{"all"} (default).} - -\item{...}{Currently not used.} -} -\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 marginal effects -models from package \strong{mfx}. -} -\examples{ -if (require("mfx", quietly = TRUE)) { - set.seed(12345) - n <- 1000 - x <- rnorm(n) - y <- rnegbin(n, mu = exp(1 + 0.5 * x), theta = 0.5) - d <- data.frame(y, x) - model <- poissonmfx(y ~ x, data = d) - - p_value(model) - p_value(model, component = "marginal") -} -} diff --git a/man/p_value.zcpglm.Rd b/man/p_value.zcpglm.Rd deleted file mode 100644 index 4420d2fba..000000000 --- a/man/p_value.zcpglm.Rd +++ /dev/null @@ -1,53 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/methods_cplm.R, R/methods_pscl.R -\name{p_value.zcpglm} -\alias{p_value.zcpglm} -\alias{p_value.zeroinfl} -\title{p-values for Models with Zero-Inflation} -\usage{ -\method{p_value}{zcpglm}(model, component = c("all", "conditional", "zi", "zero_inflated"), ...) - -\method{p_value}{zeroinfl}( - model, - component = c("all", "conditional", "zi", "zero_inflated"), - method = NULL, - verbose = TRUE, - ... -) -} -\arguments{ -\item{model}{A statistical model.} - -\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.} - -\item{...}{Additional arguments} - -\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{verbose}{Toggle warnings and messages.} -} -\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 hurdle and -zero-inflated models. -} -\examples{ -if (require("pscl", quietly = TRUE)) { - data("bioChemists") - model <- zeroinfl(art ~ fem + mar + kid5 | kid5 + phd, data = bioChemists) - p_value(model) - p_value(model, component = "zi") -} -} diff --git a/man/pool_parameters.Rd b/man/pool_parameters.Rd index 7a848ef03..d718923c5 100644 --- a/man/pool_parameters.Rd +++ b/man/pool_parameters.Rd @@ -38,11 +38,19 @@ effects (\code{"random"}), or both (\code{"all"}) 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}{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.} +\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.} diff --git a/man/simulate_model.Rd b/man/simulate_model.Rd index 239417538..f8d2392fc 100644 --- a/man/simulate_model.Rd +++ b/man/simulate_model.Rd @@ -1,19 +1,13 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/5_simulate_model.R, R/methods_glmmTMB.R +% Please edit documentation in R/5_simulate_model.R \name{simulate_model} \alias{simulate_model} -\alias{simulate_model.glmmTMB} +\alias{simulate_model.default} \title{Simulated draws from model coefficients} \usage{ simulate_model(model, iterations = 1000, ...) -\method{simulate_model}{glmmTMB}( - model, - iterations = 1000, - component = "all", - verbose = FALSE, - ... -) +\method{simulate_model}{default}(model, iterations = 1000, component = "all", ...) } \arguments{ \item{model}{Statistical model (no Bayesian models).} @@ -28,8 +22,6 @@ 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.} - -\item{verbose}{Toggle warnings and messages.} } \value{ A data frame. @@ -56,6 +48,50 @@ 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"} +} + +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)) diff --git a/man/simulate_parameters.Rd b/man/simulate_parameters.Rd index 0f1c4613b..01be9227d 100644 --- a/man/simulate_parameters.Rd +++ b/man/simulate_parameters.Rd @@ -1,21 +1,10 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/methods_glmmTMB.R, R/simulate_parameters.R -\name{simulate_parameters.glmmTMB} -\alias{simulate_parameters.glmmTMB} +% Please edit documentation in R/simulate_parameters.R +\name{simulate_parameters} \alias{simulate_parameters} \alias{simulate_parameters.default} \title{Simulate Model Parameters} \usage{ -\method{simulate_parameters}{glmmTMB}( - model, - iterations = 1000, - centrality = "median", - ci = 0.95, - ci_method = "quantile", - test = "p-value", - ... -) - simulate_parameters(model, ...) \method{simulate_parameters}{default}( @@ -31,6 +20,9 @@ simulate_parameters(model, ...) \arguments{ \item{model}{Statistical model (no Bayesian models).} +\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{iterations}{The number of draws to simulate/bootstrap.} \item{centrality}{The point-estimates (centrality indices) to compute. Character @@ -52,9 +44,6 @@ list with one or more of these options: \code{"p_direction"} (or \code{"pd"}), "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{...}{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.} } \value{ A data frame with simulated parameters. diff --git a/man/standard_error.Rd b/man/standard_error.Rd index 030da3447..4f0dfb306 100644 --- a/man/standard_error.Rd +++ b/man/standard_error.Rd @@ -1,18 +1,16 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/4_standard_error.R, R/methods_base.R, -% R/methods_glmmTMB.R, R/methods_lme4.R +% Please edit documentation in R/4_standard_error.R, R/methods_base.R \name{standard_error} \alias{standard_error} \alias{standard_error.default} \alias{standard_error.factor} -\alias{standard_error.glmmTMB} -\alias{standard_error.merMod} \title{Standard Errors} \usage{ standard_error(model, ...) \method{standard_error}{default}( model, + effects = "fixed", component = "all", vcov = NULL, vcov_args = NULL, @@ -21,29 +19,18 @@ standard_error(model, ...) ) \method{standard_error}{factor}(model, force = FALSE, verbose = TRUE, ...) - -\method{standard_error}{glmmTMB}( - model, - effects = "fixed", - component = "all", - verbose = TRUE, - ... -) - -\method{standard_error}{merMod}( - model, - effects = "fixed", - method = NULL, - vcov = NULL, - vcov_args = NULL, - ... -) } \arguments{ \item{model}{A model.} \item{...}{Arguments passed to or from other methods.} +\item{effects}{Should standard errors for fixed effects (\code{"fixed"}), random +effects (\code{"random"}), or both (\code{"all"}) be returned? Only applies +to mixed models. May be abbreviated. When standard errors for random +effects are requested, for each grouping factor a list of standard errors +(per group level) for random intercepts and slopes is returned.} + \item{component}{Model component for which standard errors 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.} @@ -62,8 +49,8 @@ identifies the function to be used to compute the covariance matrix. \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} +\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"}. } @@ -84,21 +71,6 @@ values to calculate the standard error, with the lowest level being the value \code{1} (unless the factor has numeric levels, which are converted to the corresponding numeric value). By default, \code{NA} is returned for factors or character vectors.} - -\item{effects}{Should standard errors for fixed effects (\code{"fixed"}), random -effects (\code{"random"}), or both (\code{"all"}) be returned? Only applies -to mixed models. May be abbreviated. When standard errors for random -effects are requested, for each grouping factor a list of standard errors -(per group level) for random intercepts and slopes is returned.} - -\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.} } \value{ A data frame with at least two columns: the parameter names and the diff --git a/pkgdown/_pkgdown.yml b/pkgdown/_pkgdown.yml index 01bc03c9d..1f99a8fe6 100644 --- a/pkgdown/_pkgdown.yml +++ b/pkgdown/_pkgdown.yml @@ -10,43 +10,40 @@ reference: - compare_parameters - dominance_analysis - model_parameters + - pool_parameters + - random_parameters + - print.parameters_model + - sort_parameters + - standardize_parameters + - standardize_info + + - title: "Documentation of Specific Class Objects" + contents: - model_parameters.aov - model_parameters.befa - model_parameters.default - model_parameters.zcpglm - model_parameters.cgam - model_parameters.mlm - - model_parameters.merMod + - model_parameters.glmmTMB - model_parameters.lavaan - - model_parameters.kmeans - - model_parameters.Mclust + - model_parameters.hclust - model_parameters.mira - model_parameters.PCA - model_parameters.principal - - model_parameters.stanreg + - model_parameters.brmsfit - model_parameters.BFBayesFactor - model_parameters.rma - model_parameters.htest - model_parameters.glht - - model_parameters.averaging + - model_parameters.glimML - model_parameters.t1way - - pool_parameters - - random_parameters - - print.parameters_model - - sort_parameters - - standardize_parameters - - standardize_info - title: "Standard Errors, Confidence Intervals, Degrees of Freedom and p-values" contents: - standard_error - ci.default - - ci.glmmTMB - p_value - - p_value.BFBayesFactor - - p_value.zeroinfl - - p_value.poissonmfx - - p_value.DirichletRegModel - degrees_of_freedom - n_parameters - subtitle: "Approximation Methods" diff --git a/tests/testthat/test-equivalence_test.R b/tests/testthat/test-equivalence_test.R index e358b690d..b7790af0d 100644 --- a/tests/testthat/test-equivalence_test.R +++ b/tests/testthat/test-equivalence_test.R @@ -80,6 +80,7 @@ test_that("equivalence_test, unequal rope-range", { test_that("equivalence_test, unequal rope-range, plots", { skip_on_cran() + skip_if_not_installed("see") skip_if_not_installed("vdiffr") data(iris) m <- lm(Sepal.Length ~ Species, data = iris) diff --git a/tests/testthat/test-model_parameters.anova.R b/tests/testthat/test-model_parameters.anova.R index 3dbe00513..9e03f2966 100644 --- a/tests/testthat/test-model_parameters.anova.R +++ b/tests/testthat/test-model_parameters.anova.R @@ -281,7 +281,7 @@ withr::with_package( "survey", test_that("anova survey", { data(api, package = "survey") - dclus2 <<- survey::svydesign(id = ~dnum + snum, weights = ~ pw, data = apiclus2) + dclus2 <<- survey::svydesign(id = ~ dnum + snum, weights = ~pw, data = apiclus2) model0 <- survey::svyglm( I(sch.wide == "Yes") ~ ell * meals, design = dclus2, diff --git a/tests/testthat/test-pretty_names.R b/tests/testthat/test-pretty_names.R index 696fac6e8..d7fb44d57 100644 --- a/tests/testthat/test-pretty_names.R +++ b/tests/testthat/test-pretty_names.R @@ -47,9 +47,9 @@ withr::with_options( b <- runif(8, -1, 1) Y <- rbinom(N, 1, prob = plogis( b[1] + b[2] * X + - b[3] * (M == "b") + b[4] * (M == "b") + b[5] * (M == "c") + - b[6] * X * (M == "a") + b[7] * X + (M == "b") + - b[8] * X * (M == "c") + b[3] * (M == "b") + b[4] * (M == "b") + b[5] * (M == "c") + + b[6] * X * (M == "a") + b[7] * X + (M == "b") + + b[8] * X * (M == "c") )) dat <- data.frame(Y, X, M, stringsAsFactors = FALSE) mod <- glm(Y ~ X * M, data = dat, family = binomial)