New 'add_submodels()' function

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: emmeans
 Type: Package
 Title: Estimated Marginal Means, aka Least-Squares Means
-Version: 1.10.5
-Date: 2024-10-14
+Version: 1.10.5-0900001
+Date: 2024-11-21
 Authors@R: c(person("Russell V.", "Lenth", role = c("aut", "cre", "cph"), 
     email = "russell-lenth@uiowa.edu"),
     person("Balazs", "Banfai", role = "ctb"),

NAMESPACE

@@ -167,6 +167,7 @@ export(.recover_data)
 export(.std.link.labels)
 export(.zi.support)
 export(add_grouping)
+export(add_submodels)
 export(as.emmGrid)
 export(as.emm_list)
 export(as.glht)

NEWS.md

@@ -2,6 +2,11 @@
 title: "NEWS for the emmeans package"
 ---
 
+## emmeans 1.10.5.900xxx
+  * Added new `add_submodels()` function that allows for comparison od estimates
+    from different submodels (when supported)
+
+
 ## emmeans 1.10.5
   * Fix for long-standing `weights` bug in `lme()` (#356)
   * Fix for inconsistent contrasts in case of missing levels (#508, #509)

R/factors.R

@@ -306,6 +306,31 @@ add_grouping = function(object, newname, refname, newlevs, ...) {
     object
 }
 
+#' @rdname manip-factors
+#' @export
+#' 
+#' @section The \code{add_submodels} function:
+#' This function updates \code{object} with a named list of submodels specified in 
+#' \code{...}. These are \code{rbind}ed together and the corresponding rows
+#' for each submodel are assigned a factor named \code{newname} with levels 
+#' equal to the names in \code{...}. This facilitates comparing estimates obtained
+#' from different submodels. For this to work, the underlying model object must be of
+#' a class supported by the \code{submodel} argument of \code{\link{update.emmGrid}}.
+#' 
+#' @examples
+#' ## Using 'add_submodels' to compare adjusted and unadjusted means
+#' fibs <- add_submodels(frg, adj = ~ ., unadj = ~ machine)
+#' emmeans(fibs, consec ~ model | machine)
+#' 
+add_submodels = function(object, ..., newname = "model") {
+    all = lapply(list(...), \(s) update(object, submodel = s))
+    class(all) = c("emm_list", "list")
+    comb = rbind(all)
+    levels(comb)[[newname]] = names(all)
+    comb
+}
+
+
 
 #' @rdname manip-factors
 #' @param pos Integer vector consisting of some permutation of the sequence
@@ -329,6 +354,7 @@ add_grouping = function(object, newname, refname, newlevs, ...) {
 #' you must add the arguments \code{style = "factor"} and \code{nesting.order = TRUE}.
 #' 
 #' @examples
+#' # Permuting factor levels...
 #' str(v.c.g)
 #' str(permute_levels(v.c.g, "cyl", c(2,3,1)))
 #' 

R/rbind.R

@@ -103,7 +103,7 @@ rbind.emmGrid = function(..., deparse.level = 1, adjust = "bonferroni") {
     names(obj@levels) = gnms
     obj@roles$predictors = setdiff(names(obj@levels), obj@roles$multresp)
     obj@misc$con.coef = obj@misc$orig.grid = obj@misc$.pairby = NULL
-    update(obj, pri.vars = gnms, by.vars = NULL, adjust = adjust,
+    update(obj, pri.vars = gnms, by.vars = NULL, adjust = adjust, initMesg = NULL,
            estType = "rbind",
            famSize = n,   # instead of round((1 + sqrt(1 + 8*n)) / 2, 3),
            avgd.over = avgd.over)

R/test.R

@@ -241,7 +241,8 @@ test.emmGrid = function(object, null = 0,
 #'   preceding rows.
 #'   
 #'   The returned object also includes an \code{"est.fcns"} attribute, which is a
-#'   named list containing the linear functions associated with each joint test. 
+#'   named list containing the linear functions associated with each joint test.
+#'   Each row of these is standardized to have length 1. 
 #'   No estimable functions are included for confounded effects.
 #'   
 #' @section Dealing with covariates:

vignettes/models.Rmd

@@ -75,6 +75,7 @@ Scroll down or follow the links to those groups for more information.
 |gnls         |nlme     |[A](#A)  |Supports `params` part. Requires `param = "<name>"`          |
 |hurdle       |pscl     |[C](#C)  |`mode = c("response", "count", "zero", "prob0"),`            |
 |             |         |         |`lin.pred = c(FALSE~, TRUE)`                                 |
+|lavaan       |lavaan    |[P](#P)  |Supported by the **semTools** package (see `? lavaan2emmeans`) |
 |lm           |stats    |[A](#A)  |Several other classes inherit from this and may be supported |
 |lme          |nlme     |[K](#K)  |`sigmaAdjust = c(TRUE, FALSE),`                              |
 |             |         |         |`mode = c("auto", containment", "satterthwaite", "asymptotic"),`|
@@ -463,8 +464,8 @@ together.
 
 ## Group P -- Other packages {#P}
 
-Models in this group have their **emmeans** support provided by the package
-that implements the model-fitting procedure. Users should refer to the
+Models in this group have their **emmeans** support provided by another package
+(usually the one that implements the model-fitting procedure). Users should refer to the
 package documentation for details on **emmeans** support. In some cases, a
 package's models may have been supported here in **emmeans**; if so, the 
 other package's support overrides it.