From 37b4135b4636d37987c16dc46930999cd9f202b5 Mon Sep 17 00:00:00 2001
From: Daniel <mail@danielluedecke.de>
Date: Thu, 7 Nov 2024 09:14:29 +0100
Subject: [PATCH] docs

---
 R/find_parameters_mixed.R      | 15 +++++++++---
 R/get_parameters_mixed.R       |  9 ++++---
 man/find_parameters.glmmTMB.Rd | 44 +++++++++++++++++++++++++++++++++-
 man/get_parameters.glmmTMB.Rd  |  3 ++-
 4 files changed, 63 insertions(+), 8 deletions(-)

diff --git a/R/find_parameters_mixed.R b/R/find_parameters_mixed.R
index 90ab41622..307f1ec3e 100644
--- a/R/find_parameters_mixed.R
+++ b/R/find_parameters_mixed.R
@@ -15,13 +15,16 @@
 #'   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.
+#'   other auxiliary parameters) are returned. See section _Model Component_
+#'   for details.
 #' @param ... Currently not used.
 #' @inheritParams find_parameters
 #' @inheritParams find_parameters.betamfx
 #' @inheritParams find_parameters.BGGM
 #' @inheritParams find_predictors
 #'
+#' @inheritSection find_predictors Model components
+#'
 #' @return A list of parameter names. The returned list may have following
 #' elements, usually returned based on the combination of the `effects` and
 #' `component` arguments:
@@ -47,7 +50,10 @@
 #' @export
 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"))
+  component <- validate_argument(
+    component,
+    c("all", "conditional", "zi", "zero_inflated", "dispersion", "location", "distributional", "auxiliary")
+  )
 
   # installed
   check_if_installed("lme4")
@@ -151,7 +157,10 @@ find_parameters.nlmerMod <- function(x, effects = "all", component = "all", flat
 #' @export
 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"))
+  component <- validate_argument(
+    component,
+    c("all", "conditional", "dispersion", "location", "distributional", "auxiliary")
+  )
 
   fe <- x$fixef
   re <- x$ranef
diff --git a/R/get_parameters_mixed.R b/R/get_parameters_mixed.R
index c7df3cf3a..1c327a5a9 100644
--- a/R/get_parameters_mixed.R
+++ b/R/get_parameters_mixed.R
@@ -38,7 +38,7 @@ get_parameters.glmmTMB <- function(x, effects = "fixed", component = "all", ...)
   effects <- validate_argument(effects, c("fixed", "random"))
   component <- validate_argument(
     component,
-    c("all", "conditional", "zi", "zero_inflated", "dispersion")
+    c("all", "conditional", "zi", "zero_inflated", "dispersion", "location", "distributional", "auxiliary") # nolint
   )
 
   if (effects == "fixed") {
@@ -458,7 +458,7 @@ get_parameters.MixMod <- function(x, effects = "fixed", component = "all", ...)
   effects <- validate_argument(effects, c("fixed", "random"))
   component <- validate_argument(
     component,
-    c("all", "conditional", "zi", "zero_inflated", "dispersion")
+    c("all", "conditional", "zi", "zero_inflated", "dispersion", "location", "distributional", "auxiliary") # nolint
   )
 
   has_zeroinf <- !is.null(find_formula(x, verbose = FALSE)[["zero_inflated"]])
@@ -527,7 +527,10 @@ get_parameters.MixMod <- function(x, effects = "fixed", component = "all", ...)
 #' @export
 get_parameters.hglm <- function(x, effects = "fixed", component = "all", ...) {
   effects <- validate_argument(effects, c("fixed", "random"))
-  component <- validate_argument(component, c("all", "conditional", "dispersion"))
+  component <- validate_argument(
+    component,
+    c("all", "conditional", "dispersion", "location", "distributional", "auxiliary")
+  )
 
   fe <- x$fixef
   re <- x$ranef
diff --git a/man/find_parameters.glmmTMB.Rd b/man/find_parameters.glmmTMB.Rd
index 94f18ef62..b2ca6f452 100644
--- a/man/find_parameters.glmmTMB.Rd
+++ b/man/find_parameters.glmmTMB.Rd
@@ -24,7 +24,8 @@ parameters. If \code{component = "location"}, location parameters such as
 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} or \code{dispersion} (and
-other auxiliary parameters) are returned.}
+other auxiliary parameters) are returned. See section \emph{Model Component}
+for details.}
 
 \item{flatten}{Logical, if \code{TRUE}, the values are returned as character
 vector, not as list. Duplicated values are removed.}
@@ -52,6 +53,47 @@ parameters (auxiliary parameter)
 Returns the names of model parameters, like they typically
 appear in the \code{summary()} output.
 }
+\section{Model components}{
+
+Possible values for the \code{component} argument depend on the model class.
+Following are valid options:
+\itemize{
+\item \code{"all"}: returns all model components, applies to all models, but will only
+have an effect for models with more than just the conditional model component.
+\item \code{"conditional"}: only returns the conditional component, i.e. "fixed effects"
+terms from the model. Will only have an effect for models with more than
+just the conditional model component.
+\item \code{"smooth_terms"}: returns smooth terms, only applies to GAMs (or similar
+models that may contain smooth terms).
+\item \code{"zero_inflated"} (or \code{"zi"}): returns the zero-inflation component.
+\item \code{"dispersion"}: returns the dispersion model component. This is common
+for models with zero-inflation or that can model the dispersion parameter.
+\item \code{"instruments"}: for instrumental-variable or some fixed effects regression,
+returns the instruments.
+\item \code{"nonlinear"}: for non-linear models (like models of class \code{nlmerMod} or
+\code{nls}), returns staring estimates for the nonlinear parameters.
+\item \code{"correlation"}: for models with correlation-component, like \code{gls}, the
+variables used to describe the correlation structure are returned.
+\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
+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{
 \dontshow{if (requireNamespace("lme4", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
 data(sleepstudy, package = "lme4")
diff --git a/man/get_parameters.glmmTMB.Rd b/man/get_parameters.glmmTMB.Rd
index 3262c0e70..2e89657f0 100644
--- a/man/get_parameters.glmmTMB.Rd
+++ b/man/get_parameters.glmmTMB.Rd
@@ -24,7 +24,8 @@ parameters. If \code{component = "location"}, location parameters such as
 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} or \code{dispersion} (and
-other auxiliary parameters) are returned.}
+other auxiliary parameters) are returned. See section \emph{Model Component}
+for details.}
 
 \item{...}{Currently not used.}
 }