Merge pull request #295 from florianhartig/0.4.4-reintroduceGLMMTMB

0.4.4 reintroduce glmmtmb

DHARMa/DESCRIPTION

@@ -1,13 +1,13 @@
 Package: DHARMa
 Title: Residual Diagnostics for Hierarchical (Multi-Level / Mixed) Regression Models
-Version: 0.4.3
+Version: 0.4.3.1
 Date: 2021-07-06
 Authors@R: c(person("Florian", "Hartig", email = "florian.hartig@biologie.uni-regensburg.de", role = c("aut", "cre"), comment=c(ORCID="0000-0002-6255-9059")), person("Lukas", "Lohse", role = "ctb"))
 Description: The 'DHARMa' package uses a simulation-based approach to create
     readily interpretable scaled (quantile) residuals for fitted (generalized) linear mixed
     models. Currently supported are linear and generalized linear (mixed) models from 'lme4'
-    (classes 'lmerMod', 'glmerMod'), 'glmmTMB' 'GLMMadaptive' and 'spaMM', generalized additive models 
-    ('gam' from 'mgcv'), 'glm' (including 'negbin' from 'MASS', but excluding quasi-distributions) and 
+    (classes 'lmerMod', 'glmerMod'), 'glmmTMB' 'GLMMadaptive' and 'spaMM', generalized additive models
+    ('gam' from 'mgcv'), 'glm' (including 'negbin' from 'MASS', but excluding quasi-distributions) and
     'lm' model classes. Moreover, externally created simulations, e.g. posterior predictive simulations
     from Bayesian software such as 'JAGS', 'STAN', or 'BUGS' can be processed as well.
     The resulting residuals are standardized to values between 0 and 1 and can be interpreted
@@ -36,15 +36,16 @@ Suggests:
     KernSmooth,
     sfsmisc,
     MASS,
-    glmmTMB (>= 1.0.1),
-    mgcv,    
+    mgcv,
     spaMM (>= 3.2.0),
-    GLMMadaptive
+    GLMMadaptive,
+    phyr,
+    glmmTMB (>= 1.0.1)
 License: GPL (>= 3)
 URL: http://florianhartig.github.io/DHARMa/
 LazyData: TRUE
 BugReports: https://github.com/florianhartig/DHARMa/issues
 RoxygenNote: 7.1.1
-Roxygen: list(old_usage = TRUE)
+Roxygen: list(old_usage = TRUE, markdown = TRUE)
 VignetteBuilder: knitr
 Encoding: UTF-8

DHARMa/R/compatibility.R

@@ -101,10 +101,13 @@ weightsWarning = "Model was fit with prior weights. These will be ignored in the
 #'
 #' @seealso \code{\link{getObservedResponse}}, \code{\link{getRefit}}, \code{\link{getFixedEffects}}, \code{\link{getFitted}}
 #'
-#' @details The function is a wrapper for for the simulate function is to return the simulations from a model in a standardized way.
-#'
-#' Note: if the model was fit with weights, the function will throw a warning if used with a model class whose simulate function does not include the weightsi in the simulations. Note that the results may or may not be appropriate in this case, depending on how you use the weights.
+#' @details The purpose of this function is to wrap or implement the simulate function of different model classes and thus return simulations from fitted models in a standardized way.
 #'
+#' Note: GLMM and other regression packages often differ in how simulations are produced, and which parameters can be used to modify this behavior.
+#' 
+#' One important difference is how to modifiy which hierarchical levels are held constant, and which are re-simulated. In lme4, this is controlled by the re.form argument (see [lme4::simulate.merMod]). For other packages, please consort the help. 
+#' 
+#' If the model was fit with weights and the respective model class does not include the weights in the simulations, getSimulations will throw a warning. The background is if weights are used on the likelihood directly, then what is fitted is effectively a pseudo likelihood, and there is no way to directly simulate from the specified likelihood. Whether or not residuals can be used in this case depends very much on what is tested and how weights are used. I'm sorry to say that it is hard to give a general recommendation, you have to consult someone that understands how weights are processed in the respective model class. 
 #'
 #' @author Florian Hartig
 #' @export