From 460ea9697b9fe70b0ec9c1d4a307872afa274b77 Mon Sep 17 00:00:00 2001
From: Daniel <mail@danielluedecke.de>
Date: Fri, 5 Apr 2024 11:23:57 +0200
Subject: [PATCH] docs

---
 R/check_singularity.R    | 31 +++++++++++++++++++++++++------
 man/check_singularity.Rd | 25 ++++++++++++++++++++++---
 2 files changed, 47 insertions(+), 9 deletions(-)

diff --git a/R/check_singularity.R b/R/check_singularity.R
index b446708bd..59ead29a7 100644
--- a/R/check_singularity.R
+++ b/R/check_singularity.R
@@ -36,6 +36,22 @@
 #' - "keep it maximal", i.e. fit the most complex model consistent with the
 #'   experimental design, removing only terms required to allow a non-singular
 #'   fit (_Barr et al. 2013_)
+#' - since version 1.1.9, the **glmmTMB** allows to use priors in a frequentist
+#'   framework, too. One recommendation is to use a Gamma prior (_Chung et al. 2013_).
+#'   The mean may vary from 1 to very large values (like `1e8`), and the shape
+#'   parameter should be set to a value of 2.5. You can then `update()` your model
+#'   with the specified prior. In **glmmTMB**, the code would look like this:
+#'   ```
+#'   # "model" is an object of class gmmmTMB
+#'   prior <- data.frame(
+#'     prior = "gamma(1, 2.5)", # mean can be 1, but even 1e8
+#'     class = "ranef" # for random effects
+#'   )
+#'   model_with_priors <- update(model, priors = prior)
+#'   ```
+#'   Large values for the mean parameter of the Gamma prior have no large impact
+#'   on the random effects variances in terms of a "bias". Thus, if `1` doesn't
+#'   fix the singular fit, you can try larger values.
 #'
 #' Note the different meaning between singularity and convergence: singularity
 #' indicates an issue with the "true" best estimate, i.e. whether the maximum
@@ -48,15 +64,18 @@
 #'
 #' @references
 #' - Bates D, Kliegl R, Vasishth S, Baayen H. Parsimonious Mixed Models.
-#'  arXiv:1506.04967, June 2015.
+#'   arXiv:1506.04967, June 2015.
 #'
 #' - Barr DJ, Levy R, Scheepers C, Tily HJ. Random effects structure for
-#'  confirmatory hypothesis testing: Keep it maximal. Journal of Memory and
-#'  Language, 68(3):255-278, April 2013.
+#'   confirmatory hypothesis testing: Keep it maximal. Journal of Memory and
+#'   Language, 68(3):255-278, April 2013.
 #'
-#' - Matuschek H, Kliegl R, Vasishth S, Baayen H, Bates D. Balancing type
-#'  I error and power in linear mixed models. Journal of Memory and Language,
-#'  94:305-315, 2017.
+#' - Chung Y, Rabe-Hesketh S, Dorie V, Gelman A, and Liu J. 2013. "A Nondegenerate
+#'   Penalized Likelihood Estimator for Variance Parameters in Multilevel Models."
+#'   Psychometrika 78 (4): 685–709. \doi{10.1007/s11336-013-9328-2}
+#'
+#' - Matuschek H, Kliegl R, Vasishth S, Baayen H, Bates D. Balancing type I error
+#'   and power in linear mixed models. Journal of Memory and Language, 94:305-315, 2017.
 #'
 #' - lme4 Reference Manual, <https://cran.r-project.org/package=lme4>
 #'
diff --git a/man/check_singularity.Rd b/man/check_singularity.Rd
index 67f47f9df..7f578c816 100644
--- a/man/check_singularity.Rd
+++ b/man/check_singularity.Rd
@@ -47,6 +47,23 @@ predictive accuracy and overfitting/type I error (\emph{Bates et al. 2015},
 \item "keep it maximal", i.e. fit the most complex model consistent with the
 experimental design, removing only terms required to allow a non-singular
 fit (\emph{Barr et al. 2013})
+\item since version 1.1.9, the \strong{glmmTMB} allows to use priors in a frequentist
+framework, too. One recommendation is to use a Gamma prior (\emph{Chung et al. 2013}).
+The mean may vary from 1 to very large values (like \code{1e8}), and the shape
+parameter should be set to a value of 2.5. You can then \code{update()} your model
+with the specified prior. In \strong{glmmTMB}, the code would look like this:
+
+\if{html}{\out{<div class="sourceCode">}}\preformatted{# "model" is an object of class gmmmTMB
+prior <- data.frame(
+  prior = "gamma(1, 2.5)", # mean can be 1, but even 1e8
+  class = "ranef" # for random effects
+)
+model_with_priors <- update(model, priors = prior)
+}\if{html}{\out{</div>}}
+
+Large values for the mean parameter of the Gamma prior have no large impact
+on the random effects variances in terms of a "bias". Thus, if \code{1} doesn't
+fix the singular fit, you can try larger values.
 }
 
 Note the different meaning between singularity and convergence: singularity
@@ -84,9 +101,11 @@ arXiv:1506.04967, June 2015.
 \item Barr DJ, Levy R, Scheepers C, Tily HJ. Random effects structure for
 confirmatory hypothesis testing: Keep it maximal. Journal of Memory and
 Language, 68(3):255-278, April 2013.
-\item Matuschek H, Kliegl R, Vasishth S, Baayen H, Bates D. Balancing type
-I error and power in linear mixed models. Journal of Memory and Language,
-94:305-315, 2017.
+\item Chung Y, Rabe-Hesketh S, Dorie V, Gelman A, and Liu J. 2013. "A Nondegenerate
+Penalized Likelihood Estimator for Variance Parameters in Multilevel Models."
+Psychometrika 78 (4): 685–709. \doi{10.1007/s11336-013-9328-2}
+\item Matuschek H, Kliegl R, Vasishth S, Baayen H, Bates D. Balancing type I error
+and power in linear mixed models. Journal of Memory and Language, 94:305-315, 2017.
 \item lme4 Reference Manual, \url{https://cran.r-project.org/package=lme4}
 }
 }