diff --git a/R/methods_aod.R b/R/methods_aod.R index 1243e984f..1e6945960 100644 --- a/R/methods_aod.R +++ b/R/methods_aod.R @@ -19,7 +19,7 @@ #' `"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.stanreg +#' @inheritParams model_parameters.brmsfit #' @inheritParams simulate_model #' #' @seealso [insight::standardize_names()] to rename columns into a consistent, diff --git a/R/methods_base.R b/R/methods_base.R index 826a39e06..1e071ca52 100644 --- a/R/methods_base.R +++ b/R/methods_base.R @@ -1,3 +1,4 @@ +#' @rdname model_parameters.brmsfit #' @export model_parameters.data.frame <- function(model, as_draws = FALSE, diff --git a/R/methods_brms.R b/R/methods_brms.R index 3ec843058..6ed2dcdab 100644 --- a/R/methods_brms.R +++ b/R/methods_brms.R @@ -1,4 +1,69 @@ +#' @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 relvant 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", diff --git a/R/methods_glmmTMB.R b/R/methods_glmmTMB.R index edc7a30fe..044af85c4 100644 --- a/R/methods_glmmTMB.R +++ b/R/methods_glmmTMB.R @@ -55,7 +55,7 @@ #' up computation of the summary table. #' #' @inheritParams model_parameters.default -#' @inheritParams model_parameters.stanreg +#' @inheritParams model_parameters.brmsfit #' @inheritParams simulate_model #' #' @inheritSection model_parameters.zcpglm Model components diff --git a/R/methods_hclust.R b/R/methods_hclust.R index a4a0773e2..cd9bf93b0 100644 --- a/R/methods_hclust.R +++ b/R/methods_hclust.R @@ -3,7 +3,9 @@ #' Format cluster models obtained for example by [kmeans()]. #' #' @param model Cluster model. -#' @inheritParams model_parameters.default +#' @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) @@ -123,9 +125,6 @@ model_parameters.hclust <- function(model, data = NULL, clusters = NULL, ...) { } - - -#' @inheritParams n_clusters #' @export model_parameters.pvclust <- function(model, data = NULL, clusters = NULL, ci = 0.95, ...) { if (is.null(data)) { diff --git a/R/methods_rstanarm.R b/R/methods_rstanarm.R index 50af6d454..21e49cd42 100644 --- a/R/methods_rstanarm.R +++ b/R/methods_rstanarm.R @@ -1,65 +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. -#' -#' 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.stanreg <- function(model, centrality = "median", diff --git a/man/cluster_performance.Rd b/man/cluster_performance.Rd index 025a3edb8..0051ef67c 100644 --- a/man/cluster_performance.Rd +++ b/man/cluster_performance.Rd @@ -13,6 +13,11 @@ cluster_performance(model, ...) \item{model}{Cluster model.} \item{...}{Arguments passed to or from other methods.} + +\item{data}{A data frame.} + +\item{clusters}{A vector with clusters assignments (must be same length as +rows in data).} } \description{ Compute performance indices for clustering solutions. diff --git a/man/model_parameters.stanreg.Rd b/man/model_parameters.brmsfit.Rd similarity index 97% rename from man/model_parameters.stanreg.Rd rename to man/model_parameters.brmsfit.Rd index 54558a6f7..11e2337d3 100644 --- a/man/model_parameters.stanreg.Rd +++ b/man/model_parameters.brmsfit.Rd @@ -1,10 +1,19 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/methods_rstanarm.R -\name{model_parameters.stanreg} -\alias{model_parameters.stanreg} +% Please edit documentation in R/methods_base.R, R/methods_brms.R +\name{model_parameters.data.frame} +\alias{model_parameters.data.frame} +\alias{model_parameters.brmsfit} \title{Parameters from Bayesian Models} \usage{ -\method{model_parameters}{stanreg}( +\method{model_parameters}{data.frame}( + model, + as_draws = FALSE, + exponentiate = FALSE, + verbose = TRUE, + ... +) + +\method{model_parameters}{brmsfit}( model, centrality = "median", dispersion = FALSE, @@ -15,8 +24,9 @@ rope_ci = 0.95, bf_prior = NULL, diagnostic = c("ESS", "Rhat"), - priors = TRUE, + priors = FALSE, effects = "fixed", + component = "all", exponentiate = FALSE, standardize = NULL, group_level = FALSE, @@ -31,6 +41,48 @@ 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)}), @@ -81,20 +133,19 @@ with one or more of these options: \code{"ESS"}, \code{"Rhat"}, \code{"MCSE"} or \item{effects}{Should results for fixed effects, random effects or both be returned? Only applies to mixed models. May be abbreviated.} -\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{component}{Which type of parameters to return, such as parameters for the +conditional model, the zero-inflation part of the model, the dispersion +term, or other auxiliary parameters be returned? Applies to models with +zero-inflation and/or dispersion formula, or if parameters such as \code{sigma} +should be included. May be abbreviated. Note that the \emph{conditional} +component is also called \emph{count} or \emph{mean} component, depending on the +model. There are three convenient shortcuts: \code{component = "all"} returns +all possible parameters. If \code{component = "location"}, location parameters +such as \code{conditional}, \code{zero_inflated}, or \code{smooth_terms}, are returned +(everything that are fixed or random effects - depending on the \code{effects} +argument - but no auxiliary parameters). For \code{component = "distributional"} +(or \code{"auxiliary"}), components like \code{sigma}, \code{dispersion}, or \code{beta} +(and other auxiliary parameters) are returned.} \item{standardize}{The method used for standardizing the parameters. Can be \code{NULL} (default; no standardization), \code{"refit"} (for re-fitting the model @@ -140,53 +191,14 @@ frame, which can be different from how they are printed. Inspect the names.} \item{drop}{See \code{keep}.} - -\item{verbose}{Toggle warnings and messages.} - -\item{...}{Arguments passed to or from other methods. For instance, when -\code{bootstrap = TRUE}, arguments like \code{type} or \code{parallel} are passed down to -\code{bootstrap_model()}. - -Further non-documented arguments are: -\itemize{ -\item \code{digits}, \code{p_digits}, \code{ci_digits} and \code{footer_digits} to set the number of -digits for the output. \code{groups} can be used to group coefficients. These -arguments will be passed to the print-method, or can directly be used in -\code{print()}, see documentation in \code{\link[=print.parameters_model]{print.parameters_model()}}. -\item If \code{s_value = TRUE}, the p-value will be replaced by the S-value in the -output (cf. \emph{Rafi and Greenland 2020}). -\item \code{pd} adds an additional column with the \emph{probability of direction} (see -\code{\link[bayestestR:p_direction]{bayestestR::p_direction()}} for details). Furthermore, see 'Examples' for -this function. -\item For developers, whose interest mainly is to get a "tidy" data frame of -model summaries, it is recommended to set \code{pretty_names = FALSE} to speed -up computation of the summary table. -}} - -\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{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()}.} } \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 relvant information for +the output. } \note{ When \code{standardize = "refit"}, columns \code{diagnostic}, \code{bf_prior} and diff --git a/man/model_parameters.hclust.Rd b/man/model_parameters.hclust.Rd index 39fe4c989..2593c9786 100644 --- a/man/model_parameters.hclust.Rd +++ b/man/model_parameters.hclust.Rd @@ -9,6 +9,11 @@ \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{