diff --git a/DESCRIPTION b/DESCRIPTION index fb235f8..1e8d066 100644 --- a/DESCRIPTION +++ b/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"), diff --git a/NAMESPACE b/NAMESPACE index 823cbee..61ea510 100644 --- a/NAMESPACE +++ b/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) diff --git a/NEWS.md b/NEWS.md index 26f5503..8fdab89 100644 --- a/NEWS.md +++ b/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) diff --git a/R/factors.R b/R/factors.R index 0f8b3a1..8b2f573 100644 --- a/R/factors.R +++ b/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))) #' diff --git a/R/rbind.R b/R/rbind.R index 7839c7a..98d53ae 100644 --- a/R/rbind.R +++ b/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) diff --git a/R/test.R b/R/test.R index a5d599b..d16a8e6 100644 --- a/R/test.R +++ b/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: diff --git a/man/joint_tests.Rd b/man/joint_tests.Rd index a5733c6..1dbba05 100644 --- a/man/joint_tests.Rd +++ b/man/joint_tests.Rd @@ -58,7 +58,8 @@ a \code{summary_emm} object (same as is produced by 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. \code{make.meanint} returns the function diff --git a/man/manip-factors.Rd b/man/manip-factors.Rd index aff0df2..63a9544 100644 --- a/man/manip-factors.Rd +++ b/man/manip-factors.Rd @@ -4,6 +4,7 @@ \alias{comb_facs} \alias{split_fac} \alias{add_grouping} +\alias{add_submodels} \alias{permute_levels} \title{Manipulate factors in a reference grid} \usage{ @@ -14,6 +15,8 @@ split_fac(object, fac, newfacs, ...) add_grouping(object, newname, refname, newlevs, ...) +add_submodels(object, ..., newname = "model") + permute_levels(object, fac, pos) } \arguments{ @@ -113,6 +116,16 @@ When \code{refname} specifies more than one factor, this can are five different tensions (L, M, H in prod 1, and L, M in prod 2). } +\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}}. +} + \section{The \code{permute_levels} function}{ This function permutes the levels of \code{fac}. The returned object @@ -167,6 +180,10 @@ emmeans(gwrg, ~ wool * tension) # some NAs due to impossible combinations emmeans(gwrg, "prod") +## Using 'add_submodels' to compare adjusted and unadjusted means +fibs <- add_submodels(frg, adj = ~ ., unadj = ~ machine) +emmeans(fibs, consec ~ model | machine) + str(v.c.g) str(permute_levels(v.c.g, "cyl", c(2,3,1))) diff --git a/vignettes/models.Rmd b/vignettes/models.Rmd index 2d7a720..1d5a5c4 100644 --- a/vignettes/models.Rmd +++ b/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 = ""` | |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.