Documentation updates

NEWS.md

@@ -12,6 +12,7 @@ title: "NEWS for the emmeans package"
   * Better default contrasts in `qdrg()` (#501)
   * Bug fix for nuisance factors when we have a multivariate response (#503)
   * Improved auto-detection of response transformation (#504)
+  * Bug fix for detecting cases where we can't use `nuisance` (#503)
 
 
 ## emmeans 1.10.3

R/emmGrid-methods.R

@@ -1017,6 +1017,7 @@ regrid = function(object, transform = c("response", "mu", "unlink", "none", "pas
         object@V = vcov(object)[estble, estble, drop = FALSE]
         object@bhat = est[[1]]
         object@linfct = diag(1, length(estble))
+        object@misc$regrid.flag = TRUE
         pargs = object@grid[names(object@levels)]
         lbls = do.call(paste, c(pargs, sep = "."))
         if (!is.null(disp <- object@misc$display)) {  # fix up for the bookkeeping in nested models
@@ -1092,6 +1093,7 @@ regrid = function(object, transform = c("response", "mu", "unlink", "none", "pas
                 L[i, ] = apply(X[idx[i,], , drop = FALSE], 2, wmn)
             object@V = L %*% tcrossprod(object@V, L)
             object@linfct = diag(1, nrow(L))
+            object@misc$regrid.flag = TRUE
             if(!is.na(PB[1])) {
                 pb = matrix(0, ncol = nrow(L), nrow = nrow(PB))
                 for (i in seq_len(nrow(idx)))

R/ref-grid.R

@@ -125,7 +125,10 @@
 #'   \code{nuisance} must not interact with other factors, not even other
 #'   nuisance factors. Specifying nuisance factors can save considerable
 #'   storage and computation time, and help avoid exceeding the maximum
-#'   reference-grid size (\code{get_emm_option("rg.limit")}).
+#'   reference-grid size (\code{get_emm_option("rg.limit")}). 
+#'   (\emph{Note:} For certain models where the \code{emm_basis} method returns a
+#'   re-gridded parameterization, nuisance factors cannot be used, and an error
+#'   is thrown.)
 #' @param rg.limit Integer limit on the number of reference-grid rows to allow
 #'   (checked before any multivariate responses are included).
 #' @param ... Optional arguments passed to \code{\link{summary.emmGrid}},
@@ -1049,13 +1052,20 @@ ref_grid <- function(object, at, cov.reduce = mean, cov.keep = get_emm_option("c
 # data.frames rbinded together:
 #   * the expanded grid for all factors *not* in nuis, with the nuis factors set 
 #     at their first levels
-#   * for each factor in f nuis, a set of rows for (levs$f), with the other 
+#   * for each factor f in nuis, a set of rows for (levs$f), with the other 
 #     factors at their first levels (this is arbitrary)
 # In addition, we return a character vector 'row.assign' corresponding to the rows 
 # in the grid, telling which is what: ".main.grid." for the first part of the grid,
 # otherwise factor names from nuis.
 # We also return 'nuis' itself - which may be reduced since illegal 
 # entries are silently removed
+###
+# Update July 2024...
+# All this trickery assumes that columns of X are associated with model terms!
+# So this does not work for anything that's been re-gridded.
+# Those (almost?) always have X = I. Unfortunately we won't see X until
+# later, but we can still stop it before we inflict damage...
+# Note: we also provide a simpler check: misc$regrid.flag is non-NULL
 .setup.nuis = function(nuis, levs, trms, rg.limit) {
     firsts =  args = lapply(levs, function(x) x[1])
     nuis = intersect(nuis, names(levs))
@@ -1093,9 +1103,12 @@ ref_grid <- function(object, at, cov.reduce = mean, cov.keep = get_emm_option("c
 # bottom part, and substitute those averages in the required columns in the top part 
 # of the model matrix.
 .basis.nuis = function(basis, info, wt, levs, data, grid, ref.levels) {
-    ra = info$row.assign
+  X = basis$X
+  if(!is.null(basis$misc$regrid.flag) || all(apply(X, 1, \(x) sum(x != 0)) == 1))   # each row has 1 nonzero element
+      stop("Sorry, 'nuisance' specs are not allowed for this situation.",
+           " Revise the call accordingly.", call. = FALSE)
+  ra = info$row.assign
     r. = rep(".", length(ra))  # fillers
-    X = basis$X
     n = sum(ra == ".main.grid.")
     k = nrow(X) / length(ra)   # multivariate dimension
     nuis = info$nuis

vignettes/vignette-topics.Rmd

@@ -172,6 +172,7 @@ vignette: >
       * [Dispatching](xtending.html#dispatch)
       * [Hook functions](xtending.html#hooks)
       * [for `lqs` objects](xtending.html#eblqs)
+      * [Re-gridded](xtending.html#regridded)
       * [for `rsm` objects](xtending.html#ebrsm)
   * [`emm_list` object](comparisons.html#formulas)
   * [`emm_options()`](utilities.html#defaults)
@@ -413,6 +414,7 @@ vignette: >
       * [Limiting](messy-data.html#rg.limit)
   * [`mira` models](models.html#I)
   * [`misc` attribute and argument](xtending.html#communic)
+  * [`misc$regrid.flag`](xtending.html#regridded)
   * [Missing cells](xplanations.html#joint_tests)
   * [`mlm` models](models.html#N)
   * [`mmer` models](models.html#G)
@@ -608,6 +610,7 @@ vignette: >
       * [`regrid` vs. `type`](transformations.html#regrid2)
       * [to obtain risk ratios](transformations.html#riskrats)
       * [`transform = "log"`](transformations.html#logs)
+  * [`regrid.flag`](xtending.html#regridded)
   * [Residual plots](basics.html#pigs)
   * [Response scale](confidence-intervals.html#tran)
   * [Response transformations](basics.html#transf)

vignettes/xtending.Rmd

@@ -26,6 +26,7 @@ you are probably better off trying to use the `qdrg()` function.
   4. [Supporting `lqs` objects](#lqs)
   5. [Communication between methods](#communic)
   5. [Hook functions](#hooks)
+  6. [Re-gridded basis](#regridded)
   6. [Exported methods from **emmeans**](#exported)
   7. [Existing support for `rsm` objects](#rsm)
   7. [Dispatching and restrictions](#dispatch)
@@ -234,6 +235,20 @@ Most linear models supported by **emmeans** have straightforward structure: Regr
 
 In addition, you may want to apply some form of special post-processing after the reference grid is constructed. To provide for this, give the name of your function to post-process the object in `misc$postGridHook`. Again, `clm` objects (as well as `polr` in the **MASS** package) serve as an example. They allow a `mode` specification that in two cases, calls for post-processing. The `"cum.prob"` mode uses the `regrid` function to transform the linear predictor to the cumulative-probability scale. And the `"prob"` mode performs this, as well as applying the contrasts necessary to convert the cumulative probabilities into the class probabilities.
 
+## Re-gridded basis {#regridded}
+<!-- @index `emm_basis()`!Re-gridded; `misc$regrid.flag`; `regrid.flag` -->
+Sometimes your `emm_basis` method may essentially create a re-gridded basis, where
+`X` and `bhat` are not actually a model matrix and regression coefficients, 
+but instead, `X` is the identity, `bhat` comprises the predictions at each grid point, 
+and `V` is the covariance matrix of those predictions. In those cases, we recommend also
+setting `misc$regrid.flag = TRUE`. Currently, this flag is used only for checking
+whether the `nuisance` argument can be used in `ref_grid()`, and it is not 
+absolutely necessary because we also check to see if `X` is the identity. But
+it provides a more efficient and reliable check. The code for nuisamce factors relies
+on the structure of model matrices where columns are associated with model terms.
+So it is not possible to process nuisance factors with a re-gridded basis.
+
+
 [Back to Contents](#contents)
 
 ## Exported methods from **emmeans** {#exported}