|
4 | 4 | # model_parameters ----- |
5 | 5 |
|
6 | 6 |
|
| 7 | +#' @title Parameters from Mixed Models |
| 8 | +#' @name model_parameters.glmmTMB |
| 9 | +#' |
| 10 | +#' @description Parameters from (linear) mixed models. |
| 11 | +#' |
| 12 | +#' @param model A mixed model. |
| 13 | +#' @param effects Should parameters for fixed effects (`"fixed"`), random |
| 14 | +#' effects (`"random"`), or both (`"all"`) be returned? Only applies |
| 15 | +#' to mixed models. May be abbreviated. If the calculation of random effects |
| 16 | +#' parameters takes too long, you may use `effects = "fixed"`. |
| 17 | +#' @param wb_component Logical, if `TRUE` and models contains within- and |
| 18 | +#' between-effects (see `datawizard::demean()`), the `Component` column |
| 19 | +#' will indicate which variables belong to the within-effects, |
| 20 | +#' between-effects, and cross-level interactions. By default, the |
| 21 | +#' `Component` column indicates, which parameters belong to the |
| 22 | +#' conditional or zero-inflation component of the model. |
| 23 | +#' @param include_sigma Logical, if `TRUE`, includes the residual standard |
| 24 | +#' deviation. For mixed models, this is defined as the sum of the distribution-specific |
| 25 | +#' variance and the variance for the additive overdispersion term (see |
| 26 | +#' [insight::get_variance()] for details). Defaults to `FALSE` for mixed models |
| 27 | +#' due to the longer computation time. |
| 28 | +#' @param ci_random Logical, if `TRUE`, includes the confidence intervals for |
| 29 | +#' random effects parameters. Only applies if `effects` is not `"fixed"` and |
| 30 | +#' if `ci` is not `NULL`. Set `ci_random = FALSE` if computation of the model |
| 31 | +#' summary is too much time consuming. By default, `ci_random = NULL`, which |
| 32 | +#' uses a heuristic to guess if computation of confidence intervals for random |
| 33 | +#' effects is fast enough or not. For models with larger sample size and/or |
| 34 | +#' more complex random effects structures, confidence intervals will not be |
| 35 | +#' computed by default, for simpler models or fewer observations, confidence |
| 36 | +#' intervals will be included. Set explicitly to `TRUE` or `FALSE` to enforce |
| 37 | +#' or omit calculation of confidence intervals. |
| 38 | +#' @param ... Arguments passed to or from other methods. For instance, when |
| 39 | +#' `bootstrap = TRUE`, arguments like `type` or `parallel` are passed down to |
| 40 | +#' `bootstrap_model()`. |
| 41 | +#' |
| 42 | +#' Further non-documented arguments are: |
| 43 | +#' |
| 44 | +#' - `digits`, `p_digits`, `ci_digits` and `footer_digits` to set the number of |
| 45 | +#' digits for the output. `groups` can be used to group coefficients. These |
| 46 | +#' arguments will be passed to the print-method, or can directly be used in |
| 47 | +#' `print()`, see documentation in [`print.parameters_model()`]. |
| 48 | +#' - If `s_value = TRUE`, the p-value will be replaced by the S-value in the |
| 49 | +#' output (cf. _Rafi and Greenland 2020_). |
| 50 | +#' - `pd` adds an additional column with the _probability of direction_ (see |
| 51 | +#' [`bayestestR::p_direction()`] for details). Furthermore, see 'Examples' for |
| 52 | +#' this function. |
| 53 | +#' - For developers, whose interest mainly is to get a "tidy" data frame of |
| 54 | +#' model summaries, it is recommended to set `pretty_names = FALSE` to speed |
| 55 | +#' up computation of the summary table. |
| 56 | +#' |
| 57 | +#' @inheritParams model_parameters.default |
| 58 | +#' @inheritParams model_parameters.stanreg |
7 | 59 | #' @inheritParams simulate_model |
8 | | -#' @rdname model_parameters.merMod |
| 60 | +#' |
| 61 | +#' @inheritSection model_parameters.zcpglm Model components |
| 62 | +#' |
| 63 | +#' @inheritSection model_parameters Confidence intervals and approximation of degrees of freedom |
| 64 | +#' |
| 65 | +#' @section Confidence intervals for random effects variances: |
| 66 | +#' For models of class `merMod` and `glmmTMB`, confidence intervals for random |
| 67 | +#' effect variances can be calculated. |
| 68 | +#' |
| 69 | +#' - For models of from package **lme4**, when `ci_method` is either `"profile"` |
| 70 | +#' or `"boot"`, and `effects` is either `"random"` or `"all"`, profiled resp. |
| 71 | +#' bootstrapped confidence intervals are computed for the random effects. |
| 72 | +#' |
| 73 | +#' - For all other options of `ci_method`, and only when the **merDeriv** |
| 74 | +#' package is installed, confidence intervals for random effects are based on |
| 75 | +#' normal-distribution approximation, using the delta-method to transform |
| 76 | +#' standard errors for constructing the intervals around the log-transformed |
| 77 | +#' SD parameters. These are than back-transformed, so that random effect |
| 78 | +#' variances, standard errors and confidence intervals are shown on the original |
| 79 | +#' scale. Due to the transformation, the intervals are asymmetrical, however, |
| 80 | +#' they are within the correct bounds (i.e. no negative interval for the SD, |
| 81 | +#' and the interval for the correlations is within the range from -1 to +1). |
| 82 | +#' |
| 83 | +#' - For models of class `glmmTMB`, confidence intervals for random effect |
| 84 | +#' variances always use a Wald t-distribution approximation. |
| 85 | +#' |
| 86 | +#' @section Singular fits (random effects variances near zero): |
| 87 | +#' If a model is "singular", this means that some dimensions of the |
| 88 | +#' variance-covariance matrix have been estimated as exactly zero. This |
| 89 | +#' often occurs for mixed models with complex random effects structures. |
| 90 | +#' |
| 91 | +#' There is no gold-standard about how to deal with singularity and which |
| 92 | +#' random-effects specification to choose. One way is to fully go Bayesian |
| 93 | +#' (with informative priors). Other proposals are listed in the documentation |
| 94 | +#' of [`performance::check_singularity()`]. However, since version 1.1.9, the |
| 95 | +#' **glmmTMB** package allows to use priors in a frequentist framework, too. One |
| 96 | +#' recommendation is to use a Gamma prior (_Chung et al. 2013_). The mean may |
| 97 | +#' vary from 1 to very large values (like `1e8`), and the shape parameter should |
| 98 | +#' be set to a value of 2.5. You can then `update()` your model with the specified |
| 99 | +#' prior. In **glmmTMB**, the code would look like this: |
| 100 | +#' |
| 101 | +#' ``` |
| 102 | +#' # "model" is an object of class gmmmTMB |
| 103 | +#' prior <- data.frame( |
| 104 | +#' prior = "gamma(1, 2.5)", # mean can be 1, but even 1e8 |
| 105 | +#' class = "ranef" # for random effects |
| 106 | +#' ) |
| 107 | +#' model_with_priors <- update(model, priors = prior) |
| 108 | +#' ``` |
| 109 | +#' |
| 110 | +#' Large values for the mean parameter of the Gamma prior have no large impact |
| 111 | +#' on the random effects variances in terms of a "bias". Thus, if `1` doesn't |
| 112 | +#' fix the singular fit, you can safely try larger values. |
| 113 | +#' |
| 114 | +#' @section Dispersion parameters in *glmmTMB*: |
| 115 | +#' For some models from package **glmmTMB**, both the dispersion parameter and |
| 116 | +#' the residual variance from the random effects parameters are shown. Usually, |
| 117 | +#' these are the same but presented on different scales, e.g. |
| 118 | +#' |
| 119 | +#' ``` |
| 120 | +#' model <- glmmTMB(Sepal.Width ~ Petal.Length + (1|Species), data = iris) |
| 121 | +#' exp(fixef(model)$disp) # 0.09902987 |
| 122 | +#' sigma(model)^2 # 0.09902987 |
| 123 | +#' ``` |
| 124 | +#' |
| 125 | +#' For models where the dispersion parameter and the residual variance are |
| 126 | +#' the same, only the residual variance is shown in the output. |
| 127 | +#' |
| 128 | +#' @seealso [insight::standardize_names()] to |
| 129 | +#' rename columns into a consistent, standardized naming scheme. |
| 130 | +#' |
| 131 | +#' @note If the calculation of random effects parameters takes too long, you may |
| 132 | +#' use `effects = "fixed"`. There is also a [`plot()`-method](https://easystats.github.io/see/articles/parameters.html) |
| 133 | +#' implemented in the [**see**-package](https://easystats.github.io/see/). |
| 134 | +#' |
| 135 | +#' @references |
| 136 | +#' Chung Y, Rabe-Hesketh S, Dorie V, Gelman A, and Liu J. 2013. "A Nondegenerate |
| 137 | +#' Penalized Likelihood Estimator for Variance Parameters in Multilevel Models." |
| 138 | +#' Psychometrika 78 (4): 685–709. \doi{10.1007/s11336-013-9328-2} |
| 139 | +#' |
| 140 | +#' @examplesIf require("lme4") && require("glmmTMB") |
| 141 | +#' library(parameters) |
| 142 | +#' data(mtcars) |
| 143 | +#' model <- lme4::lmer(mpg ~ wt + (1 | gear), data = mtcars) |
| 144 | +#' model_parameters(model) |
| 145 | +#' |
| 146 | +#' \donttest{ |
| 147 | +#' data(Salamanders, package = "glmmTMB") |
| 148 | +#' model <- glmmTMB::glmmTMB( |
| 149 | +#' count ~ spp + mined + (1 | site), |
| 150 | +#' ziformula = ~mined, |
| 151 | +#' family = poisson(), |
| 152 | +#' data = Salamanders |
| 153 | +#' ) |
| 154 | +#' model_parameters(model, effects = "all") |
| 155 | +#' |
| 156 | +#' model <- lme4::lmer(mpg ~ wt + (1 | gear), data = mtcars) |
| 157 | +#' model_parameters(model, bootstrap = TRUE, iterations = 50, verbose = FALSE) |
| 158 | +#' } |
| 159 | +#' @return A data frame of indices related to the model's parameters. |
9 | 160 | #' @export |
10 | 161 | model_parameters.glmmTMB <- function(model, |
11 | 162 | ci = 0.95, |
|
0 commit comments