Merge branch 'main' into strengejacke/issue954

NEWS.md

@@ -37,6 +37,8 @@
 * `format_bf()` with `stars = TRUE` used the `°` symbol for inferiority
   (evidence *against* the comparison).
 
+* Overhaul of documentation for the package-functions.
+
 ## Bug fix
 
 * `clean_parameters()` now uses the correct labels for the random effects

R/find_parameters_mfx.R

@@ -4,26 +4,9 @@
 #' @description Returns the names of model parameters, like they typically
 #' appear in the `summary()` output.
 #'
-#' @param component Which type of parameters to return, such as parameters for
-#' the conditional model, the zero-inflated part of the model, the dispersion
-#' term, the instrumental variables or marginal effects be returned? Applies to
-#' models with zero-inflated and/or dispersion formula, or to models with
-#' instrumental variables (so called fixed-effects regressions), or models with
-#' marginal effects from **mfx**. See details in section _Model Components_ .May
-#' be abbreviated. Note that the *conditional* component also refers to the
-#' *count* or *mean* component - names may differ, depending on the modeling
-#' package. There are three convenient shortcuts:
-#' - `component = "all"` returns all possible parameters.
-#' - If `component = "location"`, location parameters such as `conditional`,
-#'   `zero_inflated`, `smooth_terms`, or `instruments` 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`, `beta` or `precision` (and other auxiliary
-#'   parameters) are returned.
 #' @param ... Currently not used.
-#' @inheritParams find_parameters
 #' @inheritParams find_predictors
+#' @inheritParams find_parameters
 #'
 #' @inheritSection find_predictors Model components
 #'
@@ -86,7 +69,6 @@ find_parameters.betaor <- function(x, component = "all", flatten = FALSE, ...) {
 }
 
 
-#' @rdname find_parameters.betamfx
 #' @export
 find_parameters.logitmfx <- function(x, component = "all", flatten = FALSE, ...) {
   p <- text_remove_backticks(names(stats::coef(x$fit)))
@@ -112,6 +94,7 @@ find_parameters.negbinmfx <- find_parameters.logitmfx
 #' @export
 find_parameters.probitmfx <- find_parameters.logitmfx
 
+
 #' @export
 find_parameters.logitor <- function(x, flatten = FALSE, ...) {
   pars <- list(conditional = text_remove_backticks(names(stats::coef(x$fit))))

R/find_parameters_mixed.R

@@ -4,24 +4,11 @@
 #' @description Returns the names of model parameters, like they typically
 #'     appear in the `summary()` output.
 #'
-#' @param component Which type of parameters to return, such as parameters for
-#'   the conditional model, the zero-inflated part of the model or the
-#'   dispersion term? Applies to models with zero-inflated and/or dispersion
-#'   formula. 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` or `zero_inflated` 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` or `dispersion` (and
-#'   other auxiliary parameters) are returned. See section _Model Component_
-#'   for details.
 #' @param ... Currently not used.
+#' @inheritParams find_predictors
 #' @inheritParams find_parameters
 #' @inheritParams find_parameters.betamfx
 #' @inheritParams find_parameters.BGGM
-#' @inheritParams find_predictors
 #'
 #' @inheritSection find_predictors Model components
 #'

R/find_predictors.R

@@ -10,12 +10,24 @@
 #' @param effects Should variables for fixed effects (`"fixed"`), random effects
 #' (`"random"`) or both (`"all"`) be returned? Only applies to mixed models. May
 #' be abbreviated.
-#' @param component Indicates which model component should be returned. E.g.,
-#' should all predictor variables, predictor variables for the conditional
-#' model, the zero-inflated part of the model, the dispersion term or the
-#' instrumental variables be returned? See section _Model Components_ for
-#' further details. May be abbreviated. Note that the *conditional* component is
-#' also called *count* or *mean* component, depending on the model.
+#' @param component Which type of parameters to return, such as parameters for
+#' the conditional model, the zero-inflated part of the model, the dispersion
+#' term, the instrumental variables or marginal effects be returned? Applies to
+#' models with zero-inflated and/or dispersion formula, or to models with
+#' instrumental variables (so called fixed-effects regressions), or models with
+#' marginal effects (from **mfx**). See details in section _Model Components_
+#' .May be abbreviated. Note that the *conditional* component also refers to the
+#' *count* or *mean* component - names may differ, depending on the modeling
+#' package. There are three convenient shortcuts (not applicable to *all* model
+#' classes):
+#' - `component = "all"` returns all possible parameters.
+#' - If `component = "location"`, location parameters such as `conditional`,
+#'   `zero_inflated`, `smooth_terms`, or `instruments` 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`, `beta` or `precision` (and other auxiliary
+#'   parameters) are returned.
 #' @param flatten Logical, if `TRUE`, the values are returned as character
 #' vector, not as list. Duplicated values are removed.
 #' @param verbose Toggle warnings.

R/get_parameters_gam.R

@@ -5,8 +5,8 @@
 #'
 #' @param ... Currently not used.
 #'
-#' @inheritParams find_parameters
 #' @inheritParams find_predictors
+#' @inheritParams find_parameters
 #'
 #' @inheritSection find_predictors Model components
 #'
@@ -19,17 +19,16 @@
 #' m <- lm(mpg ~ wt + cyl + vs, data = mtcars)
 #' get_parameters(m)
 #' @export
-get_parameters.gamm <- function(x, component = c("all", "conditional", "smooth_terms", "location"), ...) {
+get_parameters.gamm <- function(x, component = "all", ...) {
   x <- x$gam
   class(x) <- c(class(x), c("glm", "lm"))
   get_parameters.gam(x, component, ...)
 }
 
 
-
 #' @export
-get_parameters.Gam <- function(x, component = c("all", "conditional", "smooth_terms", "location"), ...) {
-  component <- match.arg(component)
+get_parameters.Gam <- function(x, component = "all", ...) {
+  component <- validate_argument(component, c("all", "conditional", "smooth_terms", "location"))
   pars <- stats::coef(x)
 
   .return_smooth_parms(
@@ -40,11 +39,9 @@ get_parameters.Gam <- function(x, component = c("all", "conditional", "smooth_te
 }
 
 
-
-#' @rdname get_parameters.gamm
 #' @export
-get_parameters.gam <- function(x, component = c("all", "conditional", "smooth_terms", "location"), ...) {
-  component <- match.arg(component)
+get_parameters.gam <- function(x, component = "all", ...) {
+  component <- validate_argument(component, c("all", "conditional", "smooth_terms", "location"))
   pars <- stats::coef(x)
 
   st <- summary(x)$s.table
@@ -58,15 +55,13 @@ get_parameters.gam <- function(x, component = c("all", "conditional", "smooth_te
   )
 }
 
-
 #' @export
 get_parameters.scam <- get_parameters.gam
 
 
-
 #' @export
-get_parameters.vgam <- function(x, component = c("all", "conditional", "smooth_terms", "location"), ...) {
-  component <- match.arg(component)
+get_parameters.vgam <- function(x, component = "all", ...) {
+  component <- validate_argument(component, c("all", "conditional", "smooth_terms", "location"))
   pars <- stats::coef(x)
 
   .return_smooth_parms(
@@ -77,7 +72,6 @@ get_parameters.vgam <- function(x, component = c("all", "conditional", "smooth_t
 }
 
 
-
 #' @export
 get_parameters.gamlss <- function(x, ...) {
   pars <- lapply(x$parameters, function(i) {
@@ -114,10 +108,9 @@ get_parameters.gamlss <- function(x, ...) {
 }
 
 
-#' @rdname get_parameters.gamm
 #' @export
-get_parameters.rqss <- function(x, component = c("all", "conditional", "smooth_terms"), ...) {
-  component <- match.arg(component)
+get_parameters.rqss <- function(x, component = "all", ...) {
+  component <- validate_argument(component, c("all", "conditional", "smooth_terms"))
   sc <- summary(x)
 
   smooth_terms <- sc$qsstab[, 1]
@@ -131,10 +124,9 @@ get_parameters.rqss <- function(x, component = c("all", "conditional", "smooth_t
 }
 
 
-
 #' @export
-get_parameters.cgam <- function(x, component = c("all", "conditional", "smooth_terms"), ...) {
-  component <- match.arg(component)
+get_parameters.cgam <- function(x, component = "all", ...) {
+  component <- validate_argument(component, c("all", "conditional", "smooth_terms"))
   sc <- summary(x)
 
   estimates <- sc$coefficients

R/get_parameters_mfx.R

@@ -18,10 +18,11 @@
 #' m <- lm(mpg ~ wt + cyl + vs, data = mtcars)
 #' get_parameters(m)
 #' @export
-get_parameters.betamfx <- function(x,
-                                   component = c("all", "conditional", "precision", "marginal"),
-                                   ...) {
-  component <- match.arg(component)
+get_parameters.betamfx <- function(x, component = "all", ...) {
+  component <- validate_argument(
+    component,
+    c("all", "conditional", "precision", "marginal")
+  )
   params <- get_parameters.betareg(x$fit, component = "all", ...)
   mfx <- x$mfxest
 
@@ -45,20 +46,15 @@ get_parameters.betamfx <- function(x,
 
 
 #' @export
-get_parameters.betaor <- function(x,
-                                  component = c("all", "conditional", "precision"),
-                                  ...) {
-  component <- match.arg(component)
+get_parameters.betaor <- function(x, component = "all", ...) {
+  component <- validate_argument(component, c("all", "conditional", "precision"))
   get_parameters.betareg(x$fit, component = component, ...)
 }
 
 
 
-#' @rdname get_parameters.betamfx
 #' @export
-get_parameters.logitmfx <- function(x,
-                                    component = c("all", "conditional", "marginal"),
-                                    ...) {
+get_parameters.logitmfx <- function(x, component = "all", ...) {
   params <- get_parameters.default(x$fit, ...)
   params$Component <- "conditional"
   mfx <- x$mfxest
@@ -73,7 +69,7 @@ get_parameters.logitmfx <- function(x,
     params
   )
 
-  component <- match.arg(component)
+  component <- validate_argument(component, c("all", "conditional", "marginal"))
   if (component != "all") {
     params <- params[params$Component == component, , drop = FALSE]
   }

R/get_varcov.R

@@ -2,25 +2,24 @@
 #' @name get_varcov
 #'
 #' @description
-#'
 #' Returns the variance-covariance, as retrieved by `stats::vcov()`, but works
 #' for more model objects that probably don't provide a `vcov()`-method.
 #'
 #'
 #' @param x A model.
 #' @param component Should the complete variance-covariance matrix of the model
-#'   be returned, or only for specific model components only (like count or
-#'   zero-inflated model parts)? Applies to models with zero-inflated component,
-#'   or models with precision (e.g. `betareg`) component. `component` may be one
-#'   of `"conditional"`, `"zi"`, `"zero-inflated"`, `"dispersion"`,
-#'   `"precision"`, or `"all"`. May be abbreviated. Note that the *conditional*
-#'   component is also called *count* or *mean* component, depending on the
-#'   model.
+#' be returned, or only for specific model components only (like count or
+#' zero-inflated model parts)? Applies to models with zero-inflated component,
+#' or models with precision (e.g. `betareg`) component. `component` may be one
+#' of `"conditional"`, `"zi"`, `"zero-inflated"`, `"dispersion"`, `"precision"`,
+#' or `"all"`. May be abbreviated. Note that the *conditional* component also
+#' refers to the *count* or *mean* component - names may differ, depending on
+#' the modeling package.
 #' @param effects Should the complete variance-covariance matrix of the model
-#'   be returned, or only for specific model parameters only? Currently only
-#'   applies to models of class `mixor`.
+#' be returned, or only for specific model parameters only? Currently only
+#' applies to models of class `mixor`.
 #' @param complete Logical, if `TRUE`, for `aov`, returns the full
-#'   variance-covariance matrix.
+#' variance-covariance matrix.
 #' @param 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