From 05b9c3c5a882b8184ac724651287ee070d254b3f Mon Sep 17 00:00:00 2001 From: Daniel Date: Wed, 6 Nov 2024 19:32:39 +0100 Subject: [PATCH] Reduce methods appearing in docs, to make docs clearer (#961) * Don't show "usage" for all classes (make docs clearer) * docs * docs * docs * docs * docs * typo * docs * find_param --- R/find_parameter_zi.R | 32 +++---- R/find_parameters.R | 16 +--- R/find_parameters_bayesian.R | 21 +++-- R/find_parameters_gam.R | 36 +++----- R/find_parameters_mfx.R | 30 +++---- R/find_parameters_mixed.R | 148 ++++++++++--------------------- R/find_parameters_other.R | 58 +++++------- R/find_predictors.R | 71 +++++++++------ R/find_variables.R | 10 ++- man/find_interactions.Rd | 17 ++-- man/find_parameters.BGGM.Rd | 43 ++++----- man/find_parameters.Rd | 38 ++++---- man/find_parameters.averaging.Rd | 73 +++++---------- man/find_parameters.betamfx.Rd | 19 +--- man/find_parameters.emmGrid.Rd | 4 +- man/find_parameters.gamlss.Rd | 20 +---- man/find_parameters.glmmTMB.Rd | 36 ++------ man/find_parameters.zeroinfl.Rd | 40 ++++----- man/find_predictors.Rd | 63 +++++++------ man/find_random.Rd | 4 +- man/find_smooth.Rd | 4 +- man/find_terms.Rd | 4 +- man/find_variables.Rd | 32 +++++-- man/get_data.Rd | 28 ++++-- man/get_parameters.BGGM.Rd | 18 ++-- man/get_parameters.Rd | 15 ++++ man/get_parameters.betamfx.Rd | 13 ++- man/get_parameters.betareg.Rd | 13 ++- man/get_parameters.gamm.Rd | 13 ++- man/get_parameters.zeroinfl.Rd | 13 ++- 30 files changed, 417 insertions(+), 515 deletions(-) diff --git a/R/find_parameter_zi.R b/R/find_parameter_zi.R index 920a0f6e76..d8759c1264 100644 --- a/R/find_parameter_zi.R +++ b/R/find_parameter_zi.R @@ -15,18 +15,17 @@ #' - `conditional`, the "fixed effects" part from the model. #' - `zero_inflated`, the "fixed effects" part from the zero-inflation #' component of the model. +#' - Special models are `mhurdle`, which also can have the components +#' `infrequent_purchase`, `ip`, and `auxiliary`. #' #' @examples #' data(mtcars) #' m <- lm(mpg ~ wt + cyl + vs, data = mtcars) #' find_parameters(m) #' @export -find_parameters.zeroinfl <- function(x, - component = c("all", "conditional", "zi", "zero_inflated"), - flatten = FALSE, - ...) { +find_parameters.zeroinfl <- function(x, component = "all", flatten = FALSE, ...) { cf <- names(stats::coef(x)) - component <- match.arg(component) + component <- validate_argument(component, c("all", "conditional", "zi", "zero_inflated")) l <- compact_list(list( conditional = cf[startsWith(cf, "count_")], @@ -50,12 +49,9 @@ find_parameters.zerotrunc <- find_parameters.zeroinfl #' @export -find_parameters.zcpglm <- function(x, - component = c("all", "conditional", "zi", "zero_inflated"), - flatten = FALSE, - ...) { +find_parameters.zcpglm <- function(x, component = "all", flatten = FALSE, ...) { cf <- stats::coef(x) - component <- match.arg(component) + component <- validate_argument(component, c("all", "conditional", "zi", "zero_inflated")) l <- compact_list(list( conditional = names(cf$tweedie), @@ -72,15 +68,19 @@ find_parameters.zcpglm <- function(x, } -#' @rdname find_parameters.zeroinfl #' @export -find_parameters.mhurdle <- function(x, - component = c("all", "conditional", "zi", "zero_inflated", "infrequent_purchase", "ip", "auxiliary"), - flatten = FALSE, - ...) { - component <- match.arg(component) +find_parameters.mhurdle <- function(x, component = "all", flatten = FALSE, ...) { + component <- validate_argument( + component, + c("all", "conditional", "zi", "zero_inflated", "infrequent_purchase", "ip", "auxiliary", "distributional") + ) cf <- stats::coef(x) + # handle alias + if (component == "distributional") { + component <- "auxiliary" + } + cond_pars <- which(startsWith(names(cf), "h2.")) zi_pars <- which(startsWith(names(cf), "h1.")) ip_pars <- which(startsWith(names(cf), "h3.")) diff --git a/R/find_parameters.R b/R/find_parameters.R index 6e6573868d..296e97ec75 100644 --- a/R/find_parameters.R +++ b/R/find_parameters.R @@ -259,13 +259,9 @@ find_parameters.lavaan <- function(x, flatten = FALSE, ...) { # Panel models ---------------------------------------- -#' @rdname find_parameters #' @export -find_parameters.pgmm <- function(x, - component = c("conditional", "all"), - flatten = FALSE, - ...) { - component <- match.arg(component) +find_parameters.pgmm <- function(x, component = "conditional", flatten = FALSE, ...) { + component <- validate_argument(component, c("conditional", "all")) s <- summary(x, robust = FALSE) l <- list( @@ -807,13 +803,9 @@ find_parameters.mira <- function(x, flatten = FALSE, ...) { ## For questions or problems with this ask Fernando Miguez (femiguez@iastate.edu) -#' @rdname find_parameters #' @export -find_parameters.nls <- function(x, - component = c("all", "conditional", "nonlinear"), - flatten = FALSE, - ...) { - component <- match.arg(component) +find_parameters.nls <- function(x, component = "all", flatten = FALSE, ...) { + component <- validate_argument(component, c("all", "conditional", "nonlinear")) f <- find_formula(x) elements <- .get_elements(effects = "fixed", component = component) f <- .prepare_predictors(x, f, elements) diff --git a/R/find_parameters_bayesian.R b/R/find_parameters_bayesian.R index 4c15734125..8315d19f33 100644 --- a/R/find_parameters_bayesian.R +++ b/R/find_parameters_bayesian.R @@ -37,16 +37,19 @@ #' - `mix`, mixture parameters (**brms** only) #' - `shiftprop`, shifted proportion parameters (**brms** only) #' +#' Models of class **BGGM** additionally can return the elements `correlation` +#' and `intercept`. +#' +#' Models of class **BFBayesFactor** additionally can return the element +#' `extra`. +#' #' @examples #' data(mtcars) #' m <- lm(mpg ~ wt + cyl + vs, data = mtcars) #' find_parameters(m) #' @export -find_parameters.BGGM <- function(x, - component = c("correlation", "conditional", "intercept", "all"), - flatten = FALSE, - ...) { - component <- match.arg(component) +find_parameters.BGGM <- function(x, component = "correlation", flatten = FALSE, ...) { + component <- validate_argument(component, c("correlation", "conditional", "intercept", "all")) l <- switch(component, correlation = list(correlation = colnames(get_parameters(x, component = "correlation"))), conditional = list(conditional = colnames(get_parameters(x, component = "conditional"))), @@ -71,16 +74,16 @@ find_parameters.BGGM <- function(x, #' @rdname find_parameters.BGGM #' @export find_parameters.BFBayesFactor <- function(x, - effects = c("all", "fixed", "random"), - component = c("all", "extra"), + effects = "all", + component = "all", flatten = FALSE, ...) { conditional <- NULL random <- NULL extra <- NULL - effects <- match.arg(effects) - component <- match.arg(component) + effects <- validate_argument(effects, c("all", "fixed", "random")) + component <- validate_argument(component, c("all", "extra")) if (.classify_BFBayesFactor(x) == "correlation") { conditional <- "rho" diff --git a/R/find_parameters_gam.R b/R/find_parameters_gam.R index 0ece672d52..8bb3869f90 100644 --- a/R/find_parameters_gam.R +++ b/R/find_parameters_gam.R @@ -38,12 +38,8 @@ find_parameters.gamlss <- function(x, flatten = FALSE, ...) { } -#' @rdname find_parameters.gamlss #' @export -find_parameters.gam <- function(x, - component = c("all", "conditional", "smooth_terms", "location"), - flatten = FALSE, - ...) { +find_parameters.gam <- function(x, component = "all", flatten = FALSE, ...) { pars <- list(conditional = names(stats::coef(x))) pars$conditional <- text_remove_backticks(pars$conditional) @@ -54,7 +50,7 @@ find_parameters.gam <- function(x, pars <- compact_list(pars) - component <- match.arg(component) + component <- validate_argument(component, c("all", "conditional", "smooth_terms", "location")) elements <- .get_elements(effects = "all", component = component) pars <- compact_list(pars[elements]) @@ -70,12 +66,9 @@ find_parameters.scam <- find_parameters.gam #' @export -find_parameters.Gam <- function(x, - component = c("all", "conditional", "smooth_terms", "location"), - flatten = FALSE, - ...) { +find_parameters.Gam <- function(x, component = "all", flatten = FALSE, ...) { pars <- names(stats::coef(x)) - component <- match.arg(component) + component <- validate_argument(component, c("all", "conditional", "smooth_terms", "location")) l <- compact_list(list( conditional = pars[.grep_non_smoothers(pars)], @@ -96,13 +89,10 @@ find_parameters.vgam <- find_parameters.Gam #' @export -find_parameters.gamm <- function(x, - component = c("all", "conditional", "smooth_terms", "location"), - flatten = FALSE, - ...) { +find_parameters.gamm <- function(x, component = "all", flatten = FALSE, ...) { x <- x$gam class(x) <- c(class(x), c("glm", "lm")) - component <- match.arg(component) + component <- validate_argument(component, c("all", "conditional", "smooth_terms", "location")) l <- find_parameters.gam(x, component = component) @@ -115,11 +105,8 @@ find_parameters.gamm <- function(x, #' @export -find_parameters.cgam <- function(x, - component = c("all", "conditional", "smooth_terms", "location"), - flatten = FALSE, - ...) { - component <- match.arg(component) +find_parameters.cgam <- function(x, component = "all", flatten = FALSE, ...) { + component <- validate_argument(component, c("all", "conditional", "smooth_terms", "location")) sc <- summary(x) estimates <- sc$coefficients @@ -164,10 +151,7 @@ find_parameters.selection <- find_parameters.SemiParBIV #' @export -find_parameters.rqss <- function(x, - component = c("all", "conditional", "smooth_terms", "location"), - flatten = FALSE, - ...) { +find_parameters.rqss <- function(x, component = "all", flatten = FALSE, ...) { sc <- summary(x) pars <- list( @@ -178,7 +162,7 @@ find_parameters.rqss <- function(x, pars$conditional <- text_remove_backticks(pars$conditional) pars$smooth_terms <- text_remove_backticks(pars$smooth_terms) - component <- match.arg(component) + component <- validate_argument(component, c("all", "conditional", "smooth_terms", "location")) elements <- .get_elements(effects = "all", component) pars <- compact_list(pars[elements]) diff --git a/R/find_parameters_mfx.R b/R/find_parameters_mfx.R index bc945b4100..087350a7dc 100644 --- a/R/find_parameters_mfx.R +++ b/R/find_parameters_mfx.R @@ -35,17 +35,20 @@ #' m <- lm(mpg ~ wt + cyl + vs, data = mtcars) #' find_parameters(m) #' @export -find_parameters.betamfx <- function(x, - component = c("all", "conditional", "precision", "marginal", "location", "distributional", "auxiliary"), - flatten = FALSE, - ...) { +find_parameters.betamfx <- function(x, component = "all", flatten = FALSE, ...) { pars <- list( marginal = text_remove_backticks(rownames(x$mfxest)), conditional = text_remove_backticks(names(x$fit$coefficients$mean)), precision = text_remove_backticks(names(x$fit$coefficients$precision)) ) - component <- match.arg(component) + component <- validate_argument( + component, + c( + "all", "conditional", "precision", "marginal", "location", + "distributional", "auxiliary" + ) + ) elements <- .get_elements(effects = "all", component = component) pars <- compact_list(pars[elements]) @@ -58,16 +61,16 @@ find_parameters.betamfx <- function(x, #' @export -find_parameters.betaor <- function(x, - component = c("all", "conditional", "precision", "location", "distributional", "auxiliary"), - flatten = FALSE, - ...) { +find_parameters.betaor <- function(x, component = "all", flatten = FALSE, ...) { pars <- list( conditional = text_remove_backticks(names(x$fit$coefficients$mean)), precision = text_remove_backticks(names(x$fit$coefficients$precision)) ) - component <- match.arg(component) + component <- validate_argument( + component, + c("all", "conditional", "precision", "location", "distributional", "auxiliary") + ) elements <- .get_elements(effects = "all", component = component) pars <- compact_list(pars[elements]) @@ -81,14 +84,11 @@ find_parameters.betaor <- function(x, #' @rdname find_parameters.betamfx #' @export -find_parameters.logitmfx <- function(x, - component = c("all", "conditional", "marginal", "location"), - flatten = FALSE, - ...) { +find_parameters.logitmfx <- function(x, component = "all", flatten = FALSE, ...) { p <- text_remove_backticks(names(stats::coef(x$fit))) pars <- list(marginal = text_remove_backticks(rownames(x$mfxest)), conditional = p) - component <- match.arg(component) + component <- validate_argument(component, c("all", "conditional", "marginal", "location")) elements <- .get_elements(effects = "all", component = component) pars <- compact_list(pars[elements]) diff --git a/R/find_parameters_mixed.R b/R/find_parameters_mixed.R index 6660a2d1b2..3c4a178468 100644 --- a/R/find_parameters_mixed.R +++ b/R/find_parameters_mixed.R @@ -23,7 +23,8 @@ #' @inheritParams find_predictors #' #' @return A list of parameter names. The returned list may have following -#' elements: +#' elements, usually returned based on the combination of the `effects` and +#' `component` arguments: #' #' - `conditional`, the "fixed effects" part from the model. #' - `random`, the "random effects" part from the model. @@ -41,13 +42,9 @@ #' m <- lm(mpg ~ wt + cyl + vs, data = mtcars) #' find_parameters(m) #' @export -find_parameters.glmmTMB <- function(x, - effects = c("all", "fixed", "random"), - component = c("all", "conditional", "zi", "zero_inflated", "dispersion"), - flatten = FALSE, - ...) { - effects <- match.arg(effects) - component <- match.arg(component) +find_parameters.glmmTMB <- function(x, effects = "all", component = "all", flatten = FALSE, ...) { + effects <- validate_argument(effects, c("all", "fixed", "random")) + component <- validate_argument(component, c("all", "conditional", "zi", "zero_inflated", "dispersion")) # installed check_if_installed("lme4") @@ -82,11 +79,7 @@ find_parameters.glmmTMB <- function(x, #' @export -find_parameters.MixMod <- function(x, - effects = c("all", "fixed", "random"), - component = c("all", "conditional", "zi", "zero_inflated"), - flatten = FALSE, - ...) { +find_parameters.MixMod <- function(x, effects = "all", component = "all", flatten = FALSE, ...) { # installed check_if_installed("lme4") @@ -111,8 +104,9 @@ find_parameters.MixMod <- function(x, l <- lapply(l, text_remove_backticks) - effects <- match.arg(effects) - component <- match.arg(component) + effects <- validate_argument(effects, c("all", "fixed", "random")) + component <- validate_argument(component, c("all", "conditional", "zi", "zero_inflated")) + elements <- .get_elements(effects = effects, component = component) l <- compact_list(l[elements]) @@ -124,18 +118,14 @@ find_parameters.MixMod <- function(x, } -#' @rdname find_parameters.glmmTMB #' @export -find_parameters.nlmerMod <- function(x, - effects = c("all", "fixed", "random"), - component = c("all", "conditional", "nonlinear"), - flatten = FALSE, - ...) { +find_parameters.nlmerMod <- function(x, effects = "all", component = "all", flatten = FALSE, ...) { # installed check_if_installed("lme4") - effects <- match.arg(effects) - component <- match.arg(component) + effects <- validate_argument(effects, c("all", "fixed", "random")) + component <- validate_argument(component, c("all", "conditional", "nonlinear")) + startvectors <- .get_startvector_from_env(x) if (effects == "fixed") { @@ -155,14 +145,11 @@ find_parameters.nlmerMod <- function(x, } -#' @rdname find_parameters.glmmTMB #' @export -find_parameters.hglm <- function(x, - effects = c("all", "fixed", "random"), - component = c("all", "conditional", "dispersion"), - flatten = FALSE, - ...) { - effects <- match.arg(effects) +find_parameters.hglm <- function(x, effects = "all", component = "all", flatten = FALSE, ...) { + effects <- validate_argument(effects, c("all", "fixed", "random")) + component <- validate_argument(component, c("all", "conditional", "dispersion")) + fe <- x$fixef re <- x$ranef @@ -184,13 +171,9 @@ find_parameters.hglm <- function(x, } -#' @rdname find_parameters.glmmTMB #' @export -find_parameters.merMod <- function(x, - effects = c("all", "fixed", "random"), - flatten = FALSE, - ...) { - effects <- match.arg(effects) +find_parameters.merMod <- function(x, effects = "all", flatten = FALSE, ...) { + effects <- validate_argument(effects, c("all", "fixed", "random")) # installed check_if_installed("lme4") @@ -218,21 +201,15 @@ find_parameters.rlmerMod <- find_parameters.merMod find_parameters.glmmadmb <- find_parameters.merMod #' @export -find_parameters.merModList <- function(x, - effects = c("all", "fixed", "random"), - flatten = FALSE, - ...) { - effects <- match.arg(effects) +find_parameters.merModList <- function(x, effects = "all", flatten = FALSE, ...) { + effects <- validate_argument(effects, c("all", "fixed", "random")) find_parameters(x[[1]], effects = effects, flatten = flatten, ...) } #' @export -find_parameters.svy2lme <- function(x, - effects = c("all", "fixed", "random"), - flatten = FALSE, - ...) { - effects <- match.arg(effects) +find_parameters.svy2lme <- function(x, effects = "all", flatten = FALSE, ...) { + effects <- validate_argument(effects, c("all", "fixed", "random")) # we extract random effects only when really necessary, to save # computational time. In particular model with large sample and @@ -252,11 +229,8 @@ find_parameters.svy2lme <- function(x, #' @export -find_parameters.HLfit <- function(x, - effects = c("all", "fixed", "random"), - flatten = FALSE, - ...) { - effects <- match.arg(effects) +find_parameters.HLfit <- function(x, effects = "all", flatten = FALSE, ...) { + effects <- validate_argument(effects, c("all", "fixed", "random")) # installed check_if_installed("lme4") @@ -280,16 +254,13 @@ find_parameters.HLfit <- function(x, #' @export -find_parameters.sem <- function(x, - effects = c("all", "fixed", "random"), - flatten = FALSE, - ...) { +find_parameters.sem <- function(x, effects = "all", flatten = FALSE, ...) { + effects <- validate_argument(effects, c("all", "fixed", "random")) + if (!.is_semLme(x)) { return(NULL) } - effects <- match.arg(effects) - l <- compact_list(list( conditional = names(x$coef), random = colnames(x$ranef) @@ -300,15 +271,11 @@ find_parameters.sem <- function(x, #' @export -find_parameters.cpglmm <- function(x, - effects = c("all", "fixed", "random"), - flatten = FALSE, - ...) { +find_parameters.cpglmm <- function(x, effects = "all", flatten = FALSE, ...) { + effects <- validate_argument(effects, c("all", "fixed", "random")) # installed check_if_installed("cplm") - effects <- match.arg(effects) - # we extract random effects only when really necessary, to save # computational time. In particular model with large sample and # many random effects groups may take some time to return random effects @@ -327,14 +294,10 @@ find_parameters.cpglmm <- function(x, #' @export -find_parameters.coxme <- function(x, - effects = c("all", "fixed", "random"), - flatten = FALSE, - ...) { +find_parameters.coxme <- function(x, effects = "all", flatten = FALSE, ...) { + effects <- validate_argument(effects, c("all", "fixed", "random")) check_if_installed("lme4") - effects <- match.arg(effects) - if (effects == "fixed") { l <- list(conditional = names(lme4::fixef(x))) } else { @@ -353,15 +316,11 @@ find_parameters.coxme <- function(x, #' @export -find_parameters.mixed <- function(x, - effects = c("all", "fixed", "random"), - flatten = FALSE, - ...) { +find_parameters.mixed <- function(x, effects = "all", flatten = FALSE, ...) { + effects <- validate_argument(effects, c("all", "fixed", "random")) # installed check_if_installed("lme4") - effects <- match.arg(effects) - if (effects == "fixed") { l <- list(conditional = names(lme4::fixef(x$full_model))) } else { @@ -376,14 +335,10 @@ find_parameters.mixed <- function(x, #' @export -find_parameters.lme <- function(x, - effects = c("all", "fixed", "random"), - flatten = FALSE, - ...) { +find_parameters.lme <- function(x, effects = "all", flatten = FALSE, ...) { + effects <- validate_argument(effects, c("all", "fixed", "random")) check_if_installed("lme4") - effects <- match.arg(effects) - if (effects == "fixed") { l <- list(conditional = names(lme4::fixef(x))) } else { @@ -405,11 +360,9 @@ find_parameters.lme <- function(x, #' @export -find_parameters.glmm <- function(x, - effects = c("all", "fixed", "random"), - flatten = FALSE, - ...) { - effects <- match.arg(effects) +find_parameters.glmm <- function(x, effects = "all", flatten = FALSE, ...) { + effects <- validate_argument(effects, c("all", "fixed", "random")) + s <- summary(x) fe_params <- rownames(s$coefmat) re_params <- rownames(s$nucoefmat) @@ -424,16 +377,14 @@ find_parameters.glmm <- function(x, #' @export -find_parameters.BBmm <- function(x, - effects = c("all", "fixed", "random"), - flatten = FALSE, - ...) { +find_parameters.BBmm <- function(x, effects = "all", flatten = FALSE, ...) { + effects <- validate_argument(effects, c("all", "fixed", "random")) + l <- compact_list(list( conditional = rownames(x$fixed.coef), random = x$namesRand )) - effects <- match.arg(effects) .filter_parameters(l, effects = effects, flatten = flatten, @@ -443,16 +394,14 @@ find_parameters.BBmm <- function(x, #' @export -find_parameters.glimML <- function(x, - effects = c("all", "fixed", "random"), - flatten = FALSE, - ...) { +find_parameters.glimML <- function(x, effects = "all", flatten = FALSE, ...) { + effects <- validate_argument(effects, c("all", "fixed", "random")) + l <- compact_list(list( conditional = names(x@fixed.param), random = names(x@random.param) )) - effects <- match.arg(effects) .filter_parameters(l, effects = effects, flatten = flatten, @@ -462,11 +411,8 @@ find_parameters.glimML <- function(x, #' @export -find_parameters.mixor <- function(x, - effects = c("all", "fixed", "random"), - flatten = FALSE, - ...) { - effects <- match.arg(effects) +find_parameters.mixor <- function(x, effects = "all", flatten = FALSE, ...) { + effects <- validate_argument(effects, c("all", "fixed", "random")) coefs <- x$Model random_start <- grep("(\\(Intercept\\) \\(Intercept\\)|Random\\.\\(Intercept\\))", rownames(coefs)) thresholds <- grep("Threshold\\d", rownames(coefs)) diff --git a/R/find_parameters_other.R b/R/find_parameters_other.R index 91f25c48ce..7d1e589190 100644 --- a/R/find_parameters_other.R +++ b/R/find_parameters_other.R @@ -10,21 +10,21 @@ #' @inheritParams find_predictors #' #' @return A list of parameter names. The returned list may have following -#' elements: +#' elements, usually requested via the `component` argument: #' #' - `conditional`, the "fixed effects" part from the model. #' - `full`, parameters from the full model. +#' - `precision` for models of class `betareg`. +#' - `survival` for model of class `mjoint`. +#' - `extra` for models of class `glmx`. #' #' @examples #' data(mtcars) #' m <- lm(mpg ~ wt + cyl + vs, data = mtcars) #' find_parameters(m) #' @export -find_parameters.averaging <- function(x, - component = c("conditional", "full"), - flatten = FALSE, - ...) { - component <- match.arg(component) +find_parameters.averaging <- function(x, component = "conditional", flatten = FALSE, ...) { + component <- validate_argument(component, c("conditional", "full")) cf <- stats::coef(x, full = component == "full") out <- list(conditional = text_remove_backticks(names(cf))) @@ -36,13 +36,9 @@ find_parameters.averaging <- function(x, } -#' @rdname find_parameters.averaging #' @export -find_parameters.glmgee <- function(x, - component = c("all", "conditional", "dispersion"), - flatten = FALSE, - ...) { - component <- match.arg(component) +find_parameters.glmgee <- function(x, component = "all", flatten = FALSE, ...) { + component <- validate_argument(component, c("all", "conditional", "dispersion")) junk <- utils::capture.output({ cs <- suppressWarnings(stats::coef(summary(x, corr = FALSE))) @@ -64,13 +60,13 @@ find_parameters.glmgee <- function(x, } -#' @rdname find_parameters.averaging #' @export -find_parameters.betareg <- function(x, - component = c("all", "conditional", "precision", "location", "distributional", "auxiliary"), - flatten = FALSE, - ...) { - component <- match.arg(component) +find_parameters.betareg <- function(x, component = "all", flatten = FALSE, ...) { + component <- validate_argument( + component, + c("all", "conditional", "precision", "location", "distributional", "auxiliary") + ) + pars <- list( conditional = names(x$coefficients$mean), precision = names(x$coefficients$precision) @@ -87,13 +83,12 @@ find_parameters.betareg <- function(x, } -#' @rdname find_parameters.averaging #' @export -find_parameters.DirichletRegModel <- function(x, - component = c("all", "conditional", "precision", "location", "distributional", "auxiliary"), - flatten = FALSE, - ...) { - component <- match.arg(component) +find_parameters.DirichletRegModel <- function(x, component = "all", flatten = FALSE, ...) { + component <- validate_argument( + component, + c("all", "conditional", "precision", "location", "distributional", "auxiliary") + ) if (x$parametrization == "common") { pars <- list(conditional = names(unlist(stats::coef(x)))) } else { @@ -116,13 +111,9 @@ find_parameters.DirichletRegModel <- function(x, } -#' @rdname find_parameters.averaging #' @export -find_parameters.mjoint <- function(x, - component = c("all", "conditional", "survival"), - flatten = FALSE, - ...) { - component <- match.arg(component) +find_parameters.mjoint <- function(x, component = "all", flatten = FALSE, ...) { + component <- validate_argument(component, c("all", "conditional", "survival")) s <- summary(x) out <- list( @@ -140,12 +131,9 @@ find_parameters.mjoint <- function(x, } -#' @rdname find_parameters.averaging #' @export -find_parameters.glmx <- function(x, - component = c("all", "conditional", "extra"), - flatten = FALSE, - ...) { +find_parameters.glmx <- function(x, component = "all", flatten = FALSE, ...) { + component <- validate_argument(component, c("all", "conditional", "extra")) cf <- stats::coef(summary(x)) out <- list( diff --git a/R/find_predictors.R b/R/find_predictors.R index b7919b92ff..e30d1deb8f 100644 --- a/R/find_predictors.R +++ b/R/find_predictors.R @@ -1,24 +1,22 @@ #' @title Find names of model predictors #' @name find_predictors #' -#' @description Returns the names of the predictor variables for the -#' different parts of a model (like fixed or random effects, zero-inflated -#' component, ...). Unlike [`find_parameters()`], the names from -#' `find_predictors()` match the original variable names from the data -#' that was used to fit the model. +#' @description Returns the names of the predictor variables for the different +#' parts of a model (like fixed or random effects, zero-inflated component, +#' ...). Unlike [`find_parameters()`], the names from `find_predictors()` match +#' the original variable names from the data that was used to fit the model. #' #' @param x A fitted model. #' @param effects Should variables for fixed effects, random effects -#' or both be returned? Only applies to mixed models. May be abbreviated. -#' @param component 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? Applies to models -#' with zero-inflated and/or dispersion formula, or to models with instrumental -#' variable (so called fixed-effects regressions). May be abbreviated. Note that the -#' *conditional* component is also called *count* or *mean* -#' component, depending on the model. -#' @param flatten Logical, if `TRUE`, the values are returned -#' as character vector, not as list. Duplicated values are removed. +#' or both 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 flatten Logical, if `TRUE`, the values are returned as character +#' vector, not as list. Duplicated values are removed. #' @param verbose Toggle warnings. #' @param ... Currently not used. #' @@ -37,6 +35,10 @@ #' 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. #' - `"location"`: returns location parameters such as `conditional`, #' `zero_inflated`, `smooth_terms`, or `instruments` (everything that are #' fixed or random effects - depending on the `effects` argument - but no @@ -44,6 +46,15 @@ #' - `"distributional"` (or `"auxiliary"`): components like `sigma`, `dispersion`, #' `beta` or `precision` (and other auxiliary parameters) 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"` +#' #' @section Parameters, Variables, Predictors and Terms: #' There are four functions that return information about the variables in a #' model: `find_predictors()`, `find_variables()`, `find_terms()` and @@ -70,7 +81,7 @@ #' #' @return A list of character vectors that represent the name(s) of the #' predictor variables. Depending on the combination of the arguments -#' `effects` and `component`, the returned list has following elements: +#' `effects` and `component`, the returned list can have following elements: #' #' - `conditional`, the "fixed effects" terms from the model #' - `random`, the "random effects" terms from the model @@ -83,6 +94,10 @@ #' the instrumental variables #' - `correlation`, for models with correlation-component like `gls`, the #' variables used to describe the correlation structure +#' - `nonlinear`, for non-linear models (like models of class `nlmerMod` or +#' `nls`), the staring estimates for the nonlinear parameters +#' - `smooth_terms` returns smooth terms, only applies to GAMs (or similar +#' models that may contain smooth terms) #' #' @examples #' data(mtcars) @@ -96,13 +111,19 @@ find_predictors <- function(x, ...) { #' @rdname find_predictors #' @export find_predictors.default <- function(x, - effects = c("fixed", "random", "all"), - component = c("all", "conditional", "zi", "zero_inflated", "dispersion", "instruments", "correlation", "smooth_terms"), # nolint + effects = "fixed", + component = "all", flatten = FALSE, verbose = TRUE, ...) { - effects <- match.arg(effects) - component <- match.arg(component) + effects <- validate_argument(effects, c("fixed", "random", "all")) + component <- validate_argument( + component, + c( + "all", "conditional", "zi", "zero_inflated", "dispersion", "instruments", + "correlation", "smooth_terms" + ) + ) f <- find_formula(x, verbose = verbose) is_mv <- is_multivariate(f) @@ -231,17 +252,17 @@ find_predictors.bfsl <- function(x, flatten = FALSE, verbose = TRUE, ...) { } -#' @rdname find_predictors #' @export find_predictors.afex_aov <- function(x, - effects = c("fixed", "random", "all"), - component = c("all", "conditional", "zi", "zero_inflated", "dispersion", "instruments", "correlation", "smooth_terms"), # nolint + effects = "fixed", flatten = FALSE, verbose = TRUE, ...) { - effects <- match.arg(effects) + effects <- validate_argument(effects, c("fixed", "random", "all")) - if (effects == "all") effects <- c("fixed", "random") + if (effects == "all") { + effects <- c("fixed", "random") + } l <- list( fixed = c(names(attr(x, "between")), names(attr(x, "within"))), diff --git a/R/find_variables.R b/R/find_variables.R index bd5d37415e..652ddb6c18 100644 --- a/R/find_variables.R +++ b/R/find_variables.R @@ -61,8 +61,14 @@ find_variables <- function(x, component = "all", flatten = FALSE, verbose = TRUE) { - effects <- match.arg(effects, choices = c("all", "fixed", "random")) - component <- match.arg(component, choices = c("all", "conditional", "zi", "zero_inflated", "dispersion", "instruments", "smooth_terms", "scale")) + effects <- validate_argument(effects, c("all", "fixed", "random")) + component <- validate_argument( + component, + c( + "all", "conditional", "zi", "zero_inflated", "dispersion", + "instruments", "smooth_terms", "scale" + ) + ) if (component %in% c("all", "conditional")) { resp <- find_response(x, combine = FALSE) diff --git a/man/find_interactions.Rd b/man/find_interactions.Rd index a39447300a..ea0ddb2560 100644 --- a/man/find_interactions.Rd +++ b/man/find_interactions.Rd @@ -13,16 +13,15 @@ find_interactions( \arguments{ \item{x}{A fitted model.} -\item{component}{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? Applies to models -with zero-inflated and/or dispersion formula, or to models with instrumental -variable (so called fixed-effects regressions). May be abbreviated. Note that the -\emph{conditional} component is also called \emph{count} or \emph{mean} -component, depending on the model.} +\item{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 \emph{Model Components} for +further details. May be abbreviated. Note that the \emph{conditional} component is +also called \emph{count} or \emph{mean} component, depending on the model.} -\item{flatten}{Logical, if \code{TRUE}, the values are returned -as character vector, not as list. Duplicated values are removed.} +\item{flatten}{Logical, if \code{TRUE}, the values are returned as character +vector, not as list. Duplicated values are removed.} } \value{ A list of character vectors that represent the interaction terms. diff --git a/man/find_parameters.BGGM.Rd b/man/find_parameters.BGGM.Rd index ff7497315e..68ef7a7ced 100644 --- a/man/find_parameters.BGGM.Rd +++ b/man/find_parameters.BGGM.Rd @@ -12,20 +12,9 @@ \alias{find_parameters.sim.merMod} \title{Find names of model parameters from Bayesian models} \usage{ -\method{find_parameters}{BGGM}( - x, - component = c("correlation", "conditional", "intercept", "all"), - flatten = FALSE, - ... -) +\method{find_parameters}{BGGM}(x, component = "correlation", flatten = FALSE, ...) -\method{find_parameters}{BFBayesFactor}( - x, - effects = c("all", "fixed", "random"), - component = c("all", "extra"), - flatten = FALSE, - ... -) +\method{find_parameters}{BFBayesFactor}(x, effects = "all", component = "all", flatten = FALSE, ...) \method{find_parameters}{MCMCglmm}(x, effects = c("all", "fixed", "random"), flatten = FALSE, ...) @@ -85,16 +74,24 @@ \arguments{ \item{x}{A fitted model.} -\item{component}{Should all predictor variables, predictor variables for the +\item{component}{Which type of parameters to return, such as parameters for the conditional model, the zero-inflated part of the model, the dispersion -term or the instrumental variables be returned? Applies to models -with zero-inflated and/or dispersion formula, or to models with instrumental -variable (so called fixed-effects regressions). May be abbreviated. Note that the +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 \strong{mfx}. May be abbreviated. Note that the \emph{conditional} component is also called \emph{count} or \emph{mean} -component, depending on the model.} +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}, \code{smooth_terms}, or \code{instruments} 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}, +\code{beta} or \code{precision} (and other auxiliary parameters) are returned.} -\item{flatten}{Logical, if \code{TRUE}, the values are returned -as character vector, not as list. Duplicated values are removed.} +\item{flatten}{Logical, if \code{TRUE}, the values are returned as character +vector, not as list. Duplicated values are removed.} \item{...}{Currently not used.} @@ -128,6 +125,12 @@ parameters. These may be one of the following: \item \code{mix}, mixture parameters (\strong{brms} only) \item \code{shiftprop}, shifted proportion parameters (\strong{brms} only) } + +Models of class \strong{BGGM} additionally can return the elements \code{correlation} +and \code{intercept}. + +Models of class \strong{BFBayesFactor} additionally can return the element +\code{extra}. } \description{ Returns the names of model parameters, like they typically diff --git a/man/find_parameters.Rd b/man/find_parameters.Rd index 5c3707ef55..ed3eafd8e1 100644 --- a/man/find_parameters.Rd +++ b/man/find_parameters.Rd @@ -3,40 +3,21 @@ \name{find_parameters} \alias{find_parameters} \alias{find_parameters.default} -\alias{find_parameters.pgmm} -\alias{find_parameters.nls} \title{Find names of model parameters} \usage{ find_parameters(x, ...) \method{find_parameters}{default}(x, flatten = FALSE, verbose = TRUE, ...) - -\method{find_parameters}{pgmm}(x, component = c("conditional", "all"), flatten = FALSE, ...) - -\method{find_parameters}{nls}( - x, - component = c("all", "conditional", "nonlinear"), - flatten = FALSE, - ... -) } \arguments{ \item{x}{A fitted model.} \item{...}{Currently not used.} -\item{flatten}{Logical, if \code{TRUE}, the values are returned -as character vector, not as list. Duplicated values are removed.} +\item{flatten}{Logical, if \code{TRUE}, the values are returned as character +vector, not as list. Duplicated values are removed.} \item{verbose}{Toggle messages and warnings.} - -\item{component}{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? Applies to models -with zero-inflated and/or dispersion formula, or to models with instrumental -variable (so called fixed-effects regressions). May be abbreviated. Note that the -\emph{conditional} component is also called \emph{count} or \emph{mean} -component, depending on the model.} } \value{ A list of parameter names. For simple models, only one list-element, @@ -74,6 +55,10 @@ models that may contain smooth terms). 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. \item \code{"location"}: returns location parameters such as \code{conditional}, \code{zero_inflated}, \code{smooth_terms}, or \code{instruments} (everything that are fixed or random effects - depending on the \code{effects} argument - but no @@ -81,6 +66,17 @@ auxiliary parameters). \item \code{"distributional"} (or \code{"auxiliary"}): components like \code{sigma}, \code{dispersion}, \code{beta} or \code{precision} (and other auxiliary parameters) are returned. } + +\strong{Special models} + +Some model classes also allow rather uncommon options. These are: +\itemize{ +\item \code{mhurdle}: \code{"infrequent_purchase"}, \code{"ip"}, and \code{"auxiliary"} +\item \code{BGGM}: \code{"correlation"} and \code{"intercept"} +\item \code{BFBayesFactor}, \code{glmx}: \code{"extra"} +\item \code{averaging}:\code{"conditional"} and \code{"full"} +\item \code{mjoint}: \code{"survival"} +} } \section{Parameters, Variables, Predictors and Terms}{ diff --git a/man/find_parameters.averaging.Rd b/man/find_parameters.averaging.Rd index 7e853989ed..d36a944044 100644 --- a/man/find_parameters.averaging.Rd +++ b/man/find_parameters.averaging.Rd @@ -2,74 +2,43 @@ % Please edit documentation in R/find_parameters_other.R \name{find_parameters.averaging} \alias{find_parameters.averaging} -\alias{find_parameters.glmgee} -\alias{find_parameters.betareg} -\alias{find_parameters.DirichletRegModel} -\alias{find_parameters.mjoint} -\alias{find_parameters.glmx} \title{Find model parameters from models with special components} \usage{ -\method{find_parameters}{averaging}(x, component = c("conditional", "full"), flatten = FALSE, ...) - -\method{find_parameters}{glmgee}( - x, - component = c("all", "conditional", "dispersion"), - flatten = FALSE, - ... -) - -\method{find_parameters}{betareg}( - x, - component = c("all", "conditional", "precision", "location", "distributional", - "auxiliary"), - flatten = FALSE, - ... -) - -\method{find_parameters}{DirichletRegModel}( - x, - component = c("all", "conditional", "precision", "location", "distributional", - "auxiliary"), - flatten = FALSE, - ... -) - -\method{find_parameters}{mjoint}( - x, - component = c("all", "conditional", "survival"), - flatten = FALSE, - ... -) - -\method{find_parameters}{glmx}( - x, - component = c("all", "conditional", "extra"), - flatten = FALSE, - ... -) +\method{find_parameters}{averaging}(x, component = "conditional", flatten = FALSE, ...) } \arguments{ \item{x}{A fitted model.} -\item{component}{Should all predictor variables, predictor variables for the +\item{component}{Which type of parameters to return, such as parameters for the conditional model, the zero-inflated part of the model, the dispersion -term or the instrumental variables be returned? Applies to models -with zero-inflated and/or dispersion formula, or to models with instrumental -variable (so called fixed-effects regressions). May be abbreviated. Note that the +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 \strong{mfx}. May be abbreviated. Note that the \emph{conditional} component is also called \emph{count} or \emph{mean} -component, depending on the model.} - -\item{flatten}{Logical, if \code{TRUE}, the values are returned -as character vector, not as list. Duplicated values are removed.} +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}, \code{smooth_terms}, or \code{instruments} 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}, +\code{beta} or \code{precision} (and other auxiliary parameters) are returned.} + +\item{flatten}{Logical, if \code{TRUE}, the values are returned as character +vector, not as list. Duplicated values are removed.} \item{...}{Currently not used.} } \value{ A list of parameter names. The returned list may have following -elements: +elements, usually requested via the \code{component} argument: \itemize{ \item \code{conditional}, the "fixed effects" part from the model. \item \code{full}, parameters from the full model. +\item \code{precision} for models of class \code{betareg}. +\item \code{survival} for model of class \code{mjoint}. +\item \code{extra} for models of class \code{glmx}. } } \description{ diff --git a/man/find_parameters.betamfx.Rd b/man/find_parameters.betamfx.Rd index d6ebcd71ba..714c472dfb 100644 --- a/man/find_parameters.betamfx.Rd +++ b/man/find_parameters.betamfx.Rd @@ -5,20 +5,9 @@ \alias{find_parameters.logitmfx} \title{Find names of model parameters from marginal effects models} \usage{ -\method{find_parameters}{betamfx}( - x, - component = c("all", "conditional", "precision", "marginal", "location", - "distributional", "auxiliary"), - flatten = FALSE, - ... -) +\method{find_parameters}{betamfx}(x, component = "all", flatten = FALSE, ...) -\method{find_parameters}{logitmfx}( - x, - component = c("all", "conditional", "marginal", "location"), - flatten = FALSE, - ... -) +\method{find_parameters}{logitmfx}(x, component = "all", flatten = FALSE, ...) } \arguments{ \item{x}{A fitted model.} @@ -39,8 +28,8 @@ argument - but no auxiliary parameters). For \code{component = "distributional"} (or \code{"auxiliary"}), components like \code{sigma}, \code{dispersion}, \code{beta} or \code{precision} (and other auxiliary parameters) are returned.} -\item{flatten}{Logical, if \code{TRUE}, the values are returned -as character vector, not as list. Duplicated values are removed.} +\item{flatten}{Logical, if \code{TRUE}, the values are returned as character +vector, not as list. Duplicated values are removed.} \item{...}{Currently not used.} } diff --git a/man/find_parameters.emmGrid.Rd b/man/find_parameters.emmGrid.Rd index 458b9352f4..b6168632ee 100644 --- a/man/find_parameters.emmGrid.Rd +++ b/man/find_parameters.emmGrid.Rd @@ -9,8 +9,8 @@ \arguments{ \item{x}{A fitted model.} -\item{flatten}{Logical, if \code{TRUE}, the values are returned -as character vector, not as list. Duplicated values are removed.} +\item{flatten}{Logical, if \code{TRUE}, the values are returned as character +vector, not as list. Duplicated values are removed.} \item{merge_parameters}{Logical, if \code{TRUE} and \code{x} has multiple columns for parameter names (like \code{emmGrid} objects may have), these are merged into a diff --git a/man/find_parameters.gamlss.Rd b/man/find_parameters.gamlss.Rd index 79e1838962..a5e75423fa 100644 --- a/man/find_parameters.gamlss.Rd +++ b/man/find_parameters.gamlss.Rd @@ -2,33 +2,17 @@ % Please edit documentation in R/find_parameters_gam.R \name{find_parameters.gamlss} \alias{find_parameters.gamlss} -\alias{find_parameters.gam} \title{Find names of model parameters from generalized additive models} \usage{ \method{find_parameters}{gamlss}(x, flatten = FALSE, ...) - -\method{find_parameters}{gam}( - x, - component = c("all", "conditional", "smooth_terms", "location"), - flatten = FALSE, - ... -) } \arguments{ \item{x}{A fitted model.} -\item{flatten}{Logical, if \code{TRUE}, the values are returned -as character vector, not as list. Duplicated values are removed.} +\item{flatten}{Logical, if \code{TRUE}, the values are returned as character +vector, not as list. Duplicated values are removed.} \item{...}{Currently not used.} - -\item{component}{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? Applies to models -with zero-inflated and/or dispersion formula, or to models with instrumental -variable (so called fixed-effects regressions). May be abbreviated. Note that the -\emph{conditional} component is also called \emph{count} or \emph{mean} -component, depending on the model.} } \value{ A list of parameter names. The returned list may have following diff --git a/man/find_parameters.glmmTMB.Rd b/man/find_parameters.glmmTMB.Rd index a3bea98f3c..6f1d2636c0 100644 --- a/man/find_parameters.glmmTMB.Rd +++ b/man/find_parameters.glmmTMB.Rd @@ -2,36 +2,9 @@ % Please edit documentation in R/find_parameters_mixed.R \name{find_parameters.glmmTMB} \alias{find_parameters.glmmTMB} -\alias{find_parameters.nlmerMod} -\alias{find_parameters.hglm} -\alias{find_parameters.merMod} \title{Find names of model parameters from mixed models} \usage{ -\method{find_parameters}{glmmTMB}( - x, - effects = c("all", "fixed", "random"), - component = c("all", "conditional", "zi", "zero_inflated", "dispersion"), - flatten = FALSE, - ... -) - -\method{find_parameters}{nlmerMod}( - x, - effects = c("all", "fixed", "random"), - component = c("all", "conditional", "nonlinear"), - flatten = FALSE, - ... -) - -\method{find_parameters}{hglm}( - x, - effects = c("all", "fixed", "random"), - component = c("all", "conditional", "dispersion"), - flatten = FALSE, - ... -) - -\method{find_parameters}{merMod}(x, effects = c("all", "fixed", "random"), flatten = FALSE, ...) +\method{find_parameters}{glmmTMB}(x, effects = "all", component = "all", flatten = FALSE, ...) } \arguments{ \item{x}{A fitted model.} @@ -52,14 +25,15 @@ but no auxiliary parameters). For \code{component = "distributional"} (or \code{"auxiliary"}), components like \code{sigma} or \code{dispersion} (and other auxiliary parameters) are returned.} -\item{flatten}{Logical, if \code{TRUE}, the values are returned -as character vector, not as list. Duplicated values are removed.} +\item{flatten}{Logical, if \code{TRUE}, the values are returned as character +vector, not as list. Duplicated values are removed.} \item{...}{Currently not used.} } \value{ A list of parameter names. The returned list may have following -elements: +elements, usually returned based on the combination of the \code{effects} and +\code{component} arguments: \itemize{ \item \code{conditional}, the "fixed effects" part from the model. \item \code{random}, the "random effects" part from the model. diff --git a/man/find_parameters.zeroinfl.Rd b/man/find_parameters.zeroinfl.Rd index 7b5685a23d..782553193c 100644 --- a/man/find_parameters.zeroinfl.Rd +++ b/man/find_parameters.zeroinfl.Rd @@ -2,37 +2,31 @@ % Please edit documentation in R/find_parameter_zi.R \name{find_parameters.zeroinfl} \alias{find_parameters.zeroinfl} -\alias{find_parameters.mhurdle} \title{Find names of model parameters from zero-inflated models} \usage{ -\method{find_parameters}{zeroinfl}( - x, - component = c("all", "conditional", "zi", "zero_inflated"), - flatten = FALSE, - ... -) - -\method{find_parameters}{mhurdle}( - x, - component = c("all", "conditional", "zi", "zero_inflated", "infrequent_purchase", "ip", - "auxiliary"), - flatten = FALSE, - ... -) +\method{find_parameters}{zeroinfl}(x, component = "all", flatten = FALSE, ...) } \arguments{ \item{x}{A fitted model.} -\item{component}{Should all predictor variables, predictor variables for the +\item{component}{Which type of parameters to return, such as parameters for the conditional model, the zero-inflated part of the model, the dispersion -term or the instrumental variables be returned? Applies to models -with zero-inflated and/or dispersion formula, or to models with instrumental -variable (so called fixed-effects regressions). May be abbreviated. Note that the +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 \strong{mfx}. May be abbreviated. Note that the \emph{conditional} component is also called \emph{count} or \emph{mean} -component, depending on the model.} +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}, \code{smooth_terms}, or \code{instruments} 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}, +\code{beta} or \code{precision} (and other auxiliary parameters) are returned.} -\item{flatten}{Logical, if \code{TRUE}, the values are returned -as character vector, not as list. Duplicated values are removed.} +\item{flatten}{Logical, if \code{TRUE}, the values are returned as character +vector, not as list. Duplicated values are removed.} \item{...}{Currently not used.} } @@ -43,6 +37,8 @@ elements: \item \code{conditional}, the "fixed effects" part from the model. \item \code{zero_inflated}, the "fixed effects" part from the zero-inflation component of the model. +\item Special models are \code{mhurdle}, which also can have the components +\code{infrequent_purchase}, \code{ip}, and \code{auxiliary}. } } \description{ diff --git a/man/find_predictors.Rd b/man/find_predictors.Rd index e533458d1f..9f1fae4b2f 100644 --- a/man/find_predictors.Rd +++ b/man/find_predictors.Rd @@ -3,26 +3,14 @@ \name{find_predictors} \alias{find_predictors} \alias{find_predictors.default} -\alias{find_predictors.afex_aov} \title{Find names of model predictors} \usage{ find_predictors(x, ...) \method{find_predictors}{default}( x, - effects = c("fixed", "random", "all"), - component = c("all", "conditional", "zi", "zero_inflated", "dispersion", "instruments", - "correlation", "smooth_terms"), - flatten = FALSE, - verbose = TRUE, - ... -) - -\method{find_predictors}{afex_aov}( - x, - effects = c("fixed", "random", "all"), - component = c("all", "conditional", "zi", "zero_inflated", "dispersion", "instruments", - "correlation", "smooth_terms"), + effects = "fixed", + component = "all", flatten = FALSE, verbose = TRUE, ... @@ -36,23 +24,22 @@ find_predictors(x, ...) \item{effects}{Should variables for fixed effects, random effects or both be returned? Only applies to mixed models. May be abbreviated.} -\item{component}{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? Applies to models -with zero-inflated and/or dispersion formula, or to models with instrumental -variable (so called fixed-effects regressions). May be abbreviated. Note that the -\emph{conditional} component is also called \emph{count} or \emph{mean} -component, depending on the model.} +\item{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 \emph{Model Components} for +further details. May be abbreviated. Note that the \emph{conditional} component is +also called \emph{count} or \emph{mean} component, depending on the model.} -\item{flatten}{Logical, if \code{TRUE}, the values are returned -as character vector, not as list. Duplicated values are removed.} +\item{flatten}{Logical, if \code{TRUE}, the values are returned as character +vector, not as list. Duplicated values are removed.} \item{verbose}{Toggle warnings.} } \value{ A list of character vectors that represent the name(s) of the predictor variables. Depending on the combination of the arguments -\code{effects} and \code{component}, the returned list has following elements: +\code{effects} and \code{component}, the returned list can have following elements: \itemize{ \item \code{conditional}, the "fixed effects" terms from the model \item \code{random}, the "random effects" terms from the model @@ -65,14 +52,17 @@ component of the model the instrumental variables \item \code{correlation}, for models with correlation-component like \code{gls}, the variables used to describe the correlation structure +\item \code{nonlinear}, for non-linear models (like models of class \code{nlmerMod} or +\code{nls}), the staring estimates for the nonlinear parameters +\item \code{smooth_terms} returns smooth terms, only applies to GAMs (or similar +models that may contain smooth terms) } } \description{ -Returns the names of the predictor variables for the -different parts of a model (like fixed or random effects, zero-inflated -component, ...). Unlike \code{\link[=find_parameters]{find_parameters()}}, the names from -\code{find_predictors()} match the original variable names from the data -that was used to fit the model. +Returns the names of the predictor variables for the different +parts of a model (like fixed or random effects, zero-inflated component, +...). Unlike \code{\link[=find_parameters]{find_parameters()}}, the names from \code{find_predictors()} match +the original variable names from the data that was used to fit the model. } \section{Model components}{ @@ -91,6 +81,10 @@ models that may contain smooth terms). 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. \item \code{"location"}: returns location parameters such as \code{conditional}, \code{zero_inflated}, \code{smooth_terms}, or \code{instruments} (everything that are fixed or random effects - depending on the \code{effects} argument - but no @@ -98,6 +92,17 @@ auxiliary parameters). \item \code{"distributional"} (or \code{"auxiliary"}): components like \code{sigma}, \code{dispersion}, \code{beta} or \code{precision} (and other auxiliary parameters) are returned. } + +\strong{Special models} + +Some model classes also allow rather uncommon options. These are: +\itemize{ +\item \code{mhurdle}: \code{"infrequent_purchase"}, \code{"ip"}, and \code{"auxiliary"} +\item \code{BGGM}: \code{"correlation"} and \code{"intercept"} +\item \code{BFBayesFactor}, \code{glmx}: \code{"extra"} +\item \code{averaging}:\code{"conditional"} and \code{"full"} +\item \code{mjoint}: \code{"survival"} +} } \section{Parameters, Variables, Predictors and Terms}{ diff --git a/man/find_random.Rd b/man/find_random.Rd index 70ff64a500..00b1c20e6a 100644 --- a/man/find_random.Rd +++ b/man/find_random.Rd @@ -13,8 +13,8 @@ find_random(x, split_nested = FALSE, flatten = FALSE) effects will be returned as separated elements, not as single string with colon. See 'Examples'.} -\item{flatten}{Logical, if \code{TRUE}, the values are returned -as character vector, not as list. Duplicated values are removed.} +\item{flatten}{Logical, if \code{TRUE}, the values are returned as character +vector, not as list. Duplicated values are removed.} } \value{ A list of character vectors that represent the name(s) of the diff --git a/man/find_smooth.Rd b/man/find_smooth.Rd index 05697ef1c2..a095d724a3 100644 --- a/man/find_smooth.Rd +++ b/man/find_smooth.Rd @@ -9,8 +9,8 @@ find_smooth(x, flatten = FALSE) \arguments{ \item{x}{A (gam) model.} -\item{flatten}{Logical, if \code{TRUE}, the values are returned -as character vector, not as list. Duplicated values are removed.} +\item{flatten}{Logical, if \code{TRUE}, the values are returned as character +vector, not as list. Duplicated values are removed.} } \value{ A character vector with the name(s) of the smooth terms. diff --git a/man/find_terms.Rd b/man/find_terms.Rd index 217cbdf653..6bd118027f 100644 --- a/man/find_terms.Rd +++ b/man/find_terms.Rd @@ -14,8 +14,8 @@ find_terms(x, ...) \item{...}{Currently not used.} -\item{flatten}{Logical, if \code{TRUE}, the values are returned -as character vector, not as list. Duplicated values are removed.} +\item{flatten}{Logical, if \code{TRUE}, the values are returned as character +vector, not as list. Duplicated values are removed.} \item{as_term_labels}{Logical, if \code{TRUE}, extracts model formula and tries to access the \code{"term.labels"} attribute. This should better mimic the \code{terms()} diff --git a/man/find_variables.Rd b/man/find_variables.Rd index e9a6c69966..28b0c0501c 100644 --- a/man/find_variables.Rd +++ b/man/find_variables.Rd @@ -18,16 +18,15 @@ find_variables( \item{effects}{Should variables for fixed effects, random effects or both be returned? Only applies to mixed models. May be abbreviated.} -\item{component}{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? Applies to models -with zero-inflated and/or dispersion formula, or to models with instrumental -variable (so called fixed-effects regressions). May be abbreviated. Note that the -\emph{conditional} component is also called \emph{count} or \emph{mean} -component, depending on the model.} +\item{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 \emph{Model Components} for +further details. May be abbreviated. Note that the \emph{conditional} component is +also called \emph{count} or \emph{mean} component, depending on the model.} -\item{flatten}{Logical, if \code{TRUE}, the values are returned -as character vector, not as list. Duplicated values are removed.} +\item{flatten}{Logical, if \code{TRUE}, the values are returned as character +vector, not as list. Duplicated values are removed.} \item{verbose}{Toggle warnings.} } @@ -74,6 +73,10 @@ models that may contain smooth terms). 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. \item \code{"location"}: returns location parameters such as \code{conditional}, \code{zero_inflated}, \code{smooth_terms}, or \code{instruments} (everything that are fixed or random effects - depending on the \code{effects} argument - but no @@ -81,6 +84,17 @@ auxiliary parameters). \item \code{"distributional"} (or \code{"auxiliary"}): components like \code{sigma}, \code{dispersion}, \code{beta} or \code{precision} (and other auxiliary parameters) are returned. } + +\strong{Special models} + +Some model classes also allow rather uncommon options. These are: +\itemize{ +\item \code{mhurdle}: \code{"infrequent_purchase"}, \code{"ip"}, and \code{"auxiliary"} +\item \code{BGGM}: \code{"correlation"} and \code{"intercept"} +\item \code{BFBayesFactor}, \code{glmx}: \code{"extra"} +\item \code{averaging}:\code{"conditional"} and \code{"full"} +\item \code{mjoint}: \code{"survival"} +} } \section{Parameters, Variables, Predictors and Terms}{ diff --git a/man/get_data.Rd b/man/get_data.Rd index baa8294de5..a25497f555 100644 --- a/man/get_data.Rd +++ b/man/get_data.Rd @@ -62,13 +62,12 @@ that have no missing data in the variables used for model fitting.} effects (\code{"random"}) or both (\code{"all"}) be returned? Only applies to mixed or gee models.} -\item{component}{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? Applies to models -with zero-inflated and/or dispersion formula, or to models with instrumental -variable (so called fixed-effects regressions). May be abbreviated. Note that the -\emph{conditional} component is also called \emph{count} or \emph{mean} -component, depending on the model.} +\item{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 \emph{Model Components} for +further details. May be abbreviated. Note that the \emph{conditional} component is +also called \emph{count} or \emph{mean} component, depending on the model.} \item{shape}{Return long or wide data? Only applicable in repeated measures designs.} @@ -109,6 +108,10 @@ models that may contain smooth terms). 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. \item \code{"location"}: returns location parameters such as \code{conditional}, \code{zero_inflated}, \code{smooth_terms}, or \code{instruments} (everything that are fixed or random effects - depending on the \code{effects} argument - but no @@ -116,6 +119,17 @@ auxiliary parameters). \item \code{"distributional"} (or \code{"auxiliary"}): components like \code{sigma}, \code{dispersion}, \code{beta} or \code{precision} (and other auxiliary parameters) are returned. } + +\strong{Special models} + +Some model classes also allow rather uncommon options. These are: +\itemize{ +\item \code{mhurdle}: \code{"infrequent_purchase"}, \code{"ip"}, and \code{"auxiliary"} +\item \code{BGGM}: \code{"correlation"} and \code{"intercept"} +\item \code{BFBayesFactor}, \code{glmx}: \code{"extra"} +\item \code{averaging}:\code{"conditional"} and \code{"full"} +\item \code{mjoint}: \code{"survival"} +} } \examples{ diff --git a/man/get_parameters.BGGM.Rd b/man/get_parameters.BGGM.Rd index 91f22b3065..b805724538 100644 --- a/man/get_parameters.BGGM.Rd +++ b/man/get_parameters.BGGM.Rd @@ -103,13 +103,21 @@ \arguments{ \item{x}{A fitted model.} -\item{component}{Should all predictor variables, predictor variables for the +\item{component}{Which type of parameters to return, such as parameters for the conditional model, the zero-inflated part of the model, the dispersion -term or the instrumental variables be returned? Applies to models -with zero-inflated and/or dispersion formula, or to models with instrumental -variable (so called fixed-effects regressions). May be abbreviated. Note that the +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 \strong{mfx}. May be abbreviated. Note that the \emph{conditional} component is also called \emph{count} or \emph{mean} -component, depending on the model.} +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}, \code{smooth_terms}, or \code{instruments} 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}, +\code{beta} or \code{precision} (and other auxiliary parameters) are returned.} \item{summary}{Logical, indicates whether the full posterior samples (\code{summary = FALSE})) or the summarized centrality indices of diff --git a/man/get_parameters.Rd b/man/get_parameters.Rd index f792a4d083..ad3cb08dd9 100644 --- a/man/get_parameters.Rd +++ b/man/get_parameters.Rd @@ -65,6 +65,10 @@ models that may contain smooth terms). 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. \item \code{"location"}: returns location parameters such as \code{conditional}, \code{zero_inflated}, \code{smooth_terms}, or \code{instruments} (everything that are fixed or random effects - depending on the \code{effects} argument - but no @@ -72,6 +76,17 @@ auxiliary parameters). \item \code{"distributional"} (or \code{"auxiliary"}): components like \code{sigma}, \code{dispersion}, \code{beta} or \code{precision} (and other auxiliary parameters) are returned. } + +\strong{Special models} + +Some model classes also allow rather uncommon options. These are: +\itemize{ +\item \code{mhurdle}: \code{"infrequent_purchase"}, \code{"ip"}, and \code{"auxiliary"} +\item \code{BGGM}: \code{"correlation"} and \code{"intercept"} +\item \code{BFBayesFactor}, \code{glmx}: \code{"extra"} +\item \code{averaging}:\code{"conditional"} and \code{"full"} +\item \code{mjoint}: \code{"survival"} +} } \examples{ diff --git a/man/get_parameters.betamfx.Rd b/man/get_parameters.betamfx.Rd index 7304d44683..913cac1290 100644 --- a/man/get_parameters.betamfx.Rd +++ b/man/get_parameters.betamfx.Rd @@ -16,13 +16,12 @@ \arguments{ \item{x}{A fitted model.} -\item{component}{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? Applies to models -with zero-inflated and/or dispersion formula, or to models with instrumental -variable (so called fixed-effects regressions). May be abbreviated. Note that the -\emph{conditional} component is also called \emph{count} or \emph{mean} -component, depending on the model.} +\item{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 \emph{Model Components} for +further details. May be abbreviated. Note that the \emph{conditional} component is +also called \emph{count} or \emph{mean} component, depending on the model.} \item{...}{Currently not used.} } diff --git a/man/get_parameters.betareg.Rd b/man/get_parameters.betareg.Rd index 7c4ff61590..3a87e0ce2e 100644 --- a/man/get_parameters.betareg.Rd +++ b/man/get_parameters.betareg.Rd @@ -48,13 +48,12 @@ \arguments{ \item{x}{A fitted model.} -\item{component}{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? Applies to models -with zero-inflated and/or dispersion formula, or to models with instrumental -variable (so called fixed-effects regressions). May be abbreviated. Note that the -\emph{conditional} component is also called \emph{count} or \emph{mean} -component, depending on the model.} +\item{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 \emph{Model Components} for +further details. May be abbreviated. Note that the \emph{conditional} component is +also called \emph{count} or \emph{mean} component, depending on the model.} \item{...}{Currently not used.} } diff --git a/man/get_parameters.gamm.Rd b/man/get_parameters.gamm.Rd index dfbe890beb..9eb403b12d 100644 --- a/man/get_parameters.gamm.Rd +++ b/man/get_parameters.gamm.Rd @@ -23,13 +23,12 @@ \arguments{ \item{x}{A fitted model.} -\item{component}{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? Applies to models -with zero-inflated and/or dispersion formula, or to models with instrumental -variable (so called fixed-effects regressions). May be abbreviated. Note that the -\emph{conditional} component is also called \emph{count} or \emph{mean} -component, depending on the model.} +\item{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 \emph{Model Components} for +further details. May be abbreviated. Note that the \emph{conditional} component is +also called \emph{count} or \emph{mean} component, depending on the model.} \item{...}{Currently not used.} } diff --git a/man/get_parameters.zeroinfl.Rd b/man/get_parameters.zeroinfl.Rd index d997e7b3e8..ec86b6e25d 100644 --- a/man/get_parameters.zeroinfl.Rd +++ b/man/get_parameters.zeroinfl.Rd @@ -28,13 +28,12 @@ \arguments{ \item{x}{A fitted model.} -\item{component}{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? Applies to models -with zero-inflated and/or dispersion formula, or to models with instrumental -variable (so called fixed-effects regressions). May be abbreviated. Note that the -\emph{conditional} component is also called \emph{count} or \emph{mean} -component, depending on the model.} +\item{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 \emph{Model Components} for +further details. May be abbreviated. Note that the \emph{conditional} component is +also called \emph{count} or \emph{mean} component, depending on the model.} \item{...}{Currently not used.} }