Allow NA factor levels (#500)

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: emmeans
 Type: Package
 Title: Estimated Margin2l Means, aka Least-Squares Means
-Version: 1.10.3-090002
-Date: 2024-07-06
+Version: 1.10.3-090003
+Date: 2024-07-08
 Authors@R: c(person("Russell V.", "Lenth", role = c("aut", "cre", "cph"), 
     email = "russell-lenth@uiowa.edu"),
     person("Ben", "Bolker", role = "ctb"),

NEWS.md

@@ -6,6 +6,9 @@ title: "NEWS for the emmeans package"
   * Refinements in tracking static offsets
   * Made d.f. consistent for `geeglm` and `glmgee` (#496)
   * Fixed suggestion for installing from GitHub (#497)
+  * Change that allows factors to have `NA` levels (#500). This
+    was previously not allowed, and we added an `"allow.na.levs"` option
+    (defaults to `TRUE`) just in case we broke anything that used to work.
 
 
 ## emmeans 1.10.3

R/0nly-internal.R

@@ -56,6 +56,14 @@
     ok
 }
 
+### Internal function to implement 'allow.na.levs' option
+.chk.fac = function(x) {
+    if(get_emm_option("allow.na.levs"))
+        x
+    else
+        factor(x)
+}
+
 
 
 ## Alternative to all.vars, but keeps vars like foo$x and foo[[1]] as-is

R/emmGrid-methods.R

@@ -505,6 +505,10 @@ update.emmGrid = function(object, ..., silent = FALSE) {
 #'   \code{\link{summary.emmGrid}}, \code{\link{predict.emmGrid}}, \code{\link{test.emmGrid}},
 #'   \code{\link{confint.emmGrid}}, and \code{\link{emmip}}. The only option that can
 #'   affect the latter four is \code{"predict.method"}.}
+#' \item{\code{allow.na.levs}}{A logical value that if \code{TRUE} (the default), allows
+#'   \code{NA} to be among the levels of a factor. Older versions of \pkg{emmeans} did not
+#'   allow this. So if problems come up (say in a messy dataset that includes incomplete cases), 
+#'   try setting this to \code{FALSE}.}
 #' \item{\code{sep}}{A character value to use as a separator in labeling factor combinations.
 #'   Such labels are potentially used in several places such as \code{\link{contrast}} and 
 #'   \code{\link{plot.emmGrid}} when combinations of factors are compared or plotted.
@@ -680,6 +684,7 @@ emm_defaults = list (
     emmeans = list(infer = c(TRUE, FALSE)),
     contrast = list(infer = c(FALSE, TRUE)),
     save.ref_grid = FALSE,    # save new ref_grid in .Last.ref_grid
+    allow.na.levs = TRUE,     # Do we allow factors to have NA as a level?
     cov.keep = "2",           # default for cov.keep arg in ref_grid
     sep = " ",                # separator for combining factor levels
     parens = c("-|\\+|\\/|\\*", "(", ")"), # patterns for what/how to parenthesize in contrast

R/ref-grid.R

@@ -548,8 +548,8 @@ ref_grid <- function(object, at, cov.reduce = mean, cov.keep = get_emm_option("c
 
         # Save the original levels of factors, no matter what
         if (is.factor(x) && !(nm %in% coerced$covariates))
-            xlev[[nm]] = levels(factor(x))
-            # (applying factor drops any unused levels)
+            xlev[[nm]] = levels(.chk.fac(x))
+            # (drops any used levels unless allow.na.levs option is TRUE)
         else if (is.character(x)) # just like a factor
             xlev[[nm]] = sort(unique(x))
 
@@ -559,7 +559,7 @@ ref_grid <- function(object, at, cov.reduce = mean, cov.keep = get_emm_option("c
             ref.levels[[nm]] = at[[nm]]
         # factors not in 'at'
         else if (is.factor(x) && !(nm %in% coerced$covariates))
-            ref.levels[[nm]] = levels(factor(x))
+            ref.levels[[nm]] = levels(.chk.fac(x))
         else if (is.character(x) || is.logical(x))
             ref.levels[[nm]] = chrlev[[nm]] = sort.unique(x)
         # matrices

R/summary.R

@@ -1364,7 +1364,7 @@ print.summary_emm = function(x, ..., digits=NULL, quote=FALSE, right=TRUE, expor
         x[[estn]] = format(est, digits=digits)
         x[[estn]][is.na(est)] = "nonEst"
     }
-    xc = as.matrix(format.data.frame(x, digits=digits, na.encode=FALSE))
+    xc = as.matrix(format.data.frame(x, digits=digits, na.encode=TRUE))
     m = apply(rbind(just, names(x), xc), 2, function(x) {
         w = max(sapply(x, nchar))
         if (x[1] == "R") format(x[-seq_len(2)], width = w, justify="right")

README.md

@@ -72,17 +72,20 @@ easily produce these results, as well as various graphs of them
     may be viewed.
 
   * **GitHub** To install the latest development version from GitHub, 
-    install the newest version of the **devtools** 
-    package; then run
+    install the newest version of the **remotes** 
+    package. If you are a Windows user, you should also first download and
+      install the latest version of
+      [`Rtools`](https://cran.r-project.org/bin/windows/Rtools/).
+      Then run
 
 ```r
 remotes::install_github("rvlenth/emmeans", dependencies = TRUE, build_vignettes = TRUE)
 ```
-Omitting the `build_vignettes` argument can save some time if you don't want the vignettes. They can always be found on the (emmeans pkgdown site)[https://rvlenth.github.io/emmeans/].
+Omitting the `build_vignettes` argument can save some time if you don't want the vignettes. 
+They can always be found [for the latest CRAN version](https://cran.r-project.org/package=emmeans) or 
+-- perhaps more up-to-date -- the [emmeans site](https://rvlenth.github.io/emmeans/).
 
-*Note:* If you are a Windows user, you should also first download and
-      install the latest version of
-      [`Rtools`](https://cran.r-project.org/bin/windows/Rtools/).
+*Note:* 
 
 For the latest release notes on this development version, see the 
 [NEWS file](https://github.com/rvlenth/emmeans/blob/master/NEWS.md)