Clarify how ranef works and add option to not add mean, fixes #82

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: ubms
-Version: 1.2.6.9001
-Date: 2024-09-15
+Version: 1.2.6.9002
+Date: 2024-09-16
 Title: Bayesian Models for Data from Unmarked Animals using 'Stan'
 Authors@R: person("Ken", "Kellner", email="[email protected]", 
                   role=c("cre","aut"))

R/ranef.R

@@ -5,11 +5,19 @@
 #' \code{ranef} for \code{unmarkedFit} objects. To get functionality similar
 #' to that of \code{unmarkedFit}, use \code{posterior_predict}.
 #'
+#' Note: by default this function adds the overall intercept or slope
+#' to the (mean-0) random effect to get the complete random intercept or slope.
+#' In this way the output is more like the output of \code{lme4::coef}
+#' and not \code{lme4::ranef}. You can turn this off and return just the
+#' mean-0 random effect by setting argument \code{add_mean = FALSE}.
+#'
 #' @param object A fitted model of class \code{ubmsFit}
 #' @param submodel The name of the submodel, as a character string, for
 #'  which to generate the random effects
 #' @param summary If \code{TRUE}, calculate mean, SD, and 95% uncertainty interval
 #'  for each random effect term
+#' @param add_mean If \code{TRUE} (the default) add the overall intercept or
+#'  slope mean and return the complete random intercept or slope.
 #' @param ... Currently ignored
 #'
 #' @return If \code{summary=FALSE}, a list of random effect values; if
@@ -21,7 +29,8 @@
 #' @include fit.R
 #' @importFrom unmarked ranef
 #' @export
-setMethod("ranef","ubmsFit", function(object, submodel, summary=FALSE, ...){
+setMethod("ranef","ubmsFit", function(object, submodel, summary=FALSE,
+          add_mean = TRUE, ...){
 
   sm <- object[submodel]
   if(!has_random(sm)){
@@ -42,7 +51,8 @@ setMethod("ranef","ubmsFit", function(object, submodel, summary=FALSE, ...){
     re_samples <- re_samples[,b_ind[1]:b_ind[2]]
 
     #Add mean value if this is an effects parameterization
-    if(trm %in% beta_names(sm)){
+    if(trm %in% beta_names(sm) & add_mean){
+      message("Adding the mean to get the complete random slope/intercept")
       beta_ind <- which(beta_names(sm) == trm)
       mn_samples <- extract(object, paste0("beta_",submodel))[[1]]
       mn_samples <- mn_samples[,beta_ind]

tests/testthat/test_ranef.R

@@ -69,6 +69,15 @@ test_that("ranef works with multiple random effects",{
   r2 <- ranef(fit3, "state", summary=TRUE)
 })
 
+test_that("setting add_mean = FALSE works", {
+  r <- expect_message(ranef(fit, 'state'))
+  r2 <- expect_no_message(ranef(fit, 'state', add_mean=FALSE))
+
+  # manually add the mean
+  r2_mn <- coef(fit)[1] + r2$x2[[1]] 
+  expect_equal(r$x2[[1]], r2_mn)
+})
+
 test_that("combine_same_name combines lists properly",{
   test1 <- list(a=list(a1=c(1,1)), a=list(a2=c(2,2)), b=list(b1=c(1,1)))
   expect_equal(length(test1$a), 1)