ref_grid(..., transform = ...) now should be ref_grid(..., regrid = ...) to avoid confusing transform with the tran option (which kind of does the opposite). If we match transform and don’t match tran, it will still work, but a message is displayed with advice to use regrid instead.averaging support (#324). Previous versions were potentially dead wrong except for models created by lm() (and maybe some of those were bad too)which argument to emm() to select which list elements to pass to multcomp::glht()gls models (note that nlme allows such models with gls, but not lme)lqm / lqmm support (#340)averaging support (#319)by = NULL (#321) (this bug was a subtle byproduct of the name-checking in #305) Note this fixes visible errors in the vignettes for ver 1.7.1-1gamlss support (#323)withAutoprint() to documentation examples with require() clauses, so we see interactive-style resultssummary.emmGrid (#31)summary.emmGrid() so that if we have both a response transformation and a link function, then both transformations are followed through with type = "response". Previously, I took the lazy way out and used summary(regrid(object, transform = "unlink"), type = "response") (see #325)force_regular() which caused an unintended warning (#326)emtrends() (#327)by variable names (#305). Related to this are:
plot.emmGrid() now forces all names to be syntactically validas.data.frame.emmGrid(), we changed the optional argument to check.names (defaulting to TRUE), and it actually has an effect. So by default, the result will have syntactically valid names; this is a change, but only because optional did not work right (because it is an argument for `as.data.frame.list()).linfct from emmeans() (#308)gnls support (#313, #314, thanks to Fernando Miguez)glm support so that df.residual is used when the family is gaussian or gamma. Thus, e.g., we match lm results when the model is fitted with a Gaussian family. Previously we ignored the d.f. for all glm objects.rg.limit option (and argument for ref_grid()) to limit the number of rows in the reference grid (#282, #292). This change could affect existing code that used to work – but only in fairly extreme situations. Some users report extreme performance issues that can be traced to the size of the reference grid being in the billions, causing memory to be paged, etc. So providing this limit really is necessary. The default is 10,000 rows. I hope that most existing users don’t bump up against that too often. The nuisance (or non.nuisance) argument in ref_grid() (see below) can help work around this limit.nuisance option in ref_grid(), by which we can specify names of factors to exclude from the reference grid (accommodating them by averaging) (#282, #292). These must be factors that don’t interact with anything, even other nuisance factors. This provides a remedy for excessive grid sizes.qdrg():
contrasts now object$contrasts when object is specifiedordinal.dim argument to support ordinal modelsforce_regular() function adds invisible rows to an irregular emmGrid to make it regular (i.e., covers all factor combinations)regrid() with nested structures (#287)rbind() which mishandled @grid$.offset.clm and clmm support to fix issues related to rank deficiency and nested models, particularly with mode = "prob" (#300)type to be passed in emmeans() when object is already an emmGrid (incidentally noticed in #287)add_grouping with multiple reference factors (#291)ref_grid(object, vcov. = ...) (#283)emmtrends() with covariate formulas (#284)add_grouping() (#286)contrast() to avoid all-nonEst results in irregular nested structurescld() results. Also am providing an emm_list method for emm_list objects.mvcontrast() function (#281) and assoc vignette materialupdate.summary_emm()contrast() so that log2 and log10 transformations are handled just like log. (#273) Also disabled making ratios with genlog as it seems ill-advised.log1p transformationtype = "scale" argument to plot.emmGrid() and emmip(). This is the same as type = "response" except the scale itself is transformed (i.e., a log scale if the log transformation was used). Since the same transformation is used, the appearance of the plot will be the same as with type = "lp", but with an altered axis scale. Currently this is implemented only with engine = "ggplot".scheffe.rank > 1 was specified. (#171)subset() method for emmGrid objectsmcmc and mcmc.list objects (#278, #279)test() shows null whenever it is nonzero on the chosen scale (#280)This version has some changes that affect all users, e.g., not saving .Last.ref_grid, so we incremented the sub-version number.
contrast(), so that the odds-ratio transformation persists into subsequent contrast() calls e.g., interaction contrasts.contrast(..., type = ...) work correctlyp.adjust.methods work (#267)mblogit extended to work with mmblogit models (#268) (However, since, mclogit pkg incorporates its own interface)export option in print.emmGrid() and print.emm_summary()emm_options(save.ref_grid = FALSE). Years ago, it seemed potentially useful to save the last reference grid, but this is extra overhead, and writes in the user’s global environment. The option remains if you want it.as.data.frame (because we lose potentially important annotations), and information/example on how to see more digits (which I guess is why I’m seeing users do this).y ~ A:B detected A %in% B and B %in% A, and hence A %in% A*B and B %in% A*B due to a change in 1.4.6. Now we omit cases where factors are nested in themselves!cov.reduce formulas to allow use of custom models for predicting mediating covariatesmultinom “correction” in version 1.5.4 was actually an “incorrection.” It was right before, and I made it wrong! If analyzing multinom models, use a version other than 1.5.4mblogit modelssurvreg support (#258) – survreg() doesn’t handle missing factor levels the same way as lm(). This also affects results from coxph(), AER::tobit(), …auto.noise dataset, and changing that example and vignette example to have noise/10 as the response variable. (Thanks to speech and hearing professor Stuart Rosen for pointing out this issue in an e-mail comment.)appx-satterthwaite mode in gls/lme models (#263)mode = "asymptotic" for gls/lme models.facetlab argument to emmip_ggplot() so user can control how facets are labeled (#261)joint_tests() (#265)joint_tests() and interaction contrasts for nested models (#266)multinom support suggested by this SO questionrbind.emm_list() to default for whichgee models (#249)svyglm objects (#248)lqm, lqmm, and added support for rq & rqs objects (quantreg package). User may pass summary or boot arguments such as method, se, R, … (#250)multinom objects (SEs were previously incorrect) and addition of support for related mclogit::mblogit objects. If at all possible, users should re-run any pre-1.5.4 analyses of multinomial modelsN.sim argument of regrid(). We are no longer calling this a posterior sample because this is not really a Bayesian method, it is just a simulated set of regression coefficients.CLD() once and for all. We tried in version 1.5.0, but forced to cave due to downstream problems.levels<- method that maps to update(... levels =) (#237)cld() so it works with nested cases (#239)coef() method to work with contrasts of nested models. This makes it possible for pwpp() to work (#239)plot() that occurs if we use `type = “response” but there is in fact no transformation (reported on StackOverflow)"log10" and "log2" as legal transformations in regrid()stats::make.link())emmip() to route plot output to rendering functions emmip_ggplot() and emmip_lattice(). These functions allow more customization to the plot and can also be called independently. (To do later, maybe next update: the same for plot.emmGrid(). What to name rendering functions?? – suggestions?).emmc functions so that parenthesization of levels does not get in the way of ref, exclude, or include arguments (#246)emtrends() when data is specified (#247)$model slot in a lm object, as long as there are no predictor transformations. This provides a little bit more safety in cases the data have been removed or altered.rbind.emm_list() to allow subsetting. (Also documentation & example)plot.emmGrid(... comparisons = TRUE) where we determine arrow bounds and unnecessary-arrow deletions separately in each by group. See also Stack Overflow postingemmeans() with contrasts specified ignores adjust and passes to contrast() instead. Associated documentation improved (I hope)plot(..., comparisons = TRUE) (#228)plot.emmGrid() so that comparison arrows work correctly with back-transformations. (Previously we used regrid() in that case, causing different CIs and PIs depending on comparisons) (#230)stan_polr models.as.list() and as.emmGrid() to fully support nesting and submodels.submodel support. Also, much more memory-efficient code therein (#218, #219)enable.submodel so user can switch off submodel support when unwanted or to save memory.multinom support for N.sim optionrecover_data and emm_basis so that an external package’s methods are always found and given priority whether or not they are registered (#220)gamlss support. Smoothers are not supported but other aspects are more reliable. See CV postingaes argument in pwpp() for more control over rendering (#178)plot.emmGrid() where ordering of factor levels could change depending on CIs and PIs (#225)joint_tests() to reflect cov.keep (ver. 1.4.2)emm_options() gains a disable argument to use for setting aside any existing options. Useful for reproducible bug reporting.emmeans() with a contr argument or two-sided formula, we now suppress several particular ... arguments from being passed on to contrast() when they should apply only to the construction of the EMMs (#214)... arguments are passed to methodsCLD() was deprecated in version 1.3.4. THIS IS THE LAST VERSION where it will continue to be available. Users should use multcomp::cld() instead, for which an emmGrid method will continue to exist.submodel option
mgcv::gam support (#216)ubds dataset for testing with messy situationslqm and lqmm models (#213)stanreg models (#212)stanreg objects (#202)emmip() to be consistent between one curve and several, in whether points are displayed (style option)"scale" option to make.tran()emtrends() (#201)trt.vs.ctrl.emmc() now throws an error (#208)linfct (the identity) to emmobjemm_options "sep" and "parens", and a parens argument in contrast(). sep controls how factor levels are combined when ploted or contrasted, and parens sets whether, what, and how labels are parenthesized in contrast(). In constructing contrasts of contrasts, for example, labels like A - B - C - D are now (A - B) - (C - D), by default. To reproduce old labeling, do `emm_options(sep = “,”, parens = “a^”)pwpp() so it plays nice with nonestimable cases"xplanations" vignette with additional documentation on methods used. (comparison arrows, for starters)plot(), especially regarding comparison arrowsstanreg models (#196)emmeans(obj, "1", by = "something") (#197)eff_size() now supports emm_list objects with a $contrasts component, using those contrasts. This helps those who specify pairwise ~ treatment.contrast() for factor combinations with by groups were wacky (#199)emtrends() screwed up with multivariate models (#200).calc to summary(). For example, calc = c(n = ~.wgt.) will add a column of sample sizes to the summary.coxph support for models with strataemmeans() with specs of class list now passes any offset and trend arguments (#179)plim argument to pwpp() to allow controlling the scaleparams (#180)gls objects when data are incomplete (#181)joint_tests() and test(..., joint = TRUE) that can occur with nontrivial @dffun() slots (#184)gls (#185) and renamed boot-satterthwaite to appx-satterthwaite (#176)transform argument in ref_grid() so it is same as in regrid() (#188)pwpm() function for displaying estimates, pairwise comparisons, and P values in matrix form.all.vars() that addresses #170scheffe.rank in summary.emmGrid() to manually specify the desired dimensionality of a Scheffe adjustment (#171)... to be included in options in calls to emmeans() and contrast(). This allows passing any summary() argument more easily, e.g., emmeans(..., type = "response", bias.adjust = TRUE, infer = c(TRUE, TRUE)) (Before, we would have had to wrap this in summary())plotit argument to plot.emmGrid() that works similarly to that in emmip().character predictors inat` (#175)emmeans() associated with non-factors such as Date (#162)nesting.order option to emmip() (#163)style argument for emmip() allows plotting on a numeric scalepwpp() has tick marks on P-value axis (#167)regrid() for error when estimates exceed boundsformula.tools:::as.character.formula messes me up (thanks to Berwin Turloch, UWA, for alerting me)dqrg() more visible in the documentation (because it’s often useful)emm_list objects, e.g. rbind() and as.data.frame(), as.list(), and as.emm_list()"bcnPower" option to make.tran() (per car::bcnPower())emmtrends() (#153)... to hook functions (need exposed by #154)regrid() whereby we can fake any response transformation – not just "log" (again inspired by #154)merMod objects) (#157)pwpp() to make extremely small P values more distinguishableemtrends() is now object, not model, to avoid potential mis-matching of the latter with optional mode argumentemtrends() now uses more robust and efficient code whereby a single reference grid is constructed containing all needed values of var. The old version could fail, e.g., in cases where the reference grid involves post-processing. (#145)scale argument to contrast()"identity" contrast methodeff_size() function for Cohen effect sizescov.keep argument in ref_grid() for specifying covariates to be treated just like factors (#148). A side effect is that the system default for indicator variables as covariates is to treat them like 2-level factors. This could change the results obtained from some analyses using earlier versions. To replicate old analyses, set emm_options(cov.keep = character(0)).regrid ignored offsets with Bayesian models; emtrends() did not supply options and misc arguments to emm_basis() (#143)stanreg in particular (#114)max.degree argument in emtrends() making it possible to obtain higher-order trends (#133). Plus minor tuneups, e.g., smaller default increment for difference quotientsemmeans() more forgiving with ’byvariables; e.g.,emmeans(model, ~ dose | treat, by = “route”)will find bothbyvariables whereas previously“route”` would be ignored.emm_basis() and recover_data() methods are used in preference to internal ones - so package developers can provide improvements over what I’ve cobbled together.recover_data() failscontrast() in identifying true contrasts (#134)plot.summary_emm() regarding CIs and intervals (#137)log(y + 1) ~ ... and 2*sqrt(y + 0.5) ~ ... are now auto-detected. [This may cause discrepancies with examples in past usages, but if so, that would be because the response transformation was previously incorrectly interpreted.]ratios argument to contrast() to decide how to handle log and logittype = "response" but there is no way to back-transform them (or we opted out with ratios = FALSE).emm_register() to make it easier for other packages to register their emmeans support methodsinfer, explaining that Bayesian models are handled differently (#128)PIs option to plot.emmGrid() and emmip() (#131). Also, in plot.emmGrid(), the intervals argument has been changed to CIs for sake of consistency and less confusion; intervals is still supported for backaward compatibility.plot.emmGrid gains a colors argument so we can customize colors used.glht support (#132 contributed by Balsz Banfai)regrid gains sim and N.sim arguments whereby we can generate a fake posterior sample from a frequentist model.gls objects with non-matrix apVar member (#119)sigma argument to ref_grid() (defaults to sigma(object) if available)interval argument in predict.emmGrid()likelihood argument in as.mcmc to allow for simulating from the posterior predictive distributionsigma in objectcld() and CLD()exclude (#107)recover_data to emm_basisMCMCglmm supportdo.call(paste, ...) and do.call(order, ...), to prevent problems with factor names like method that are argument names for these functions (#94)summary.emmGrid() whereby transformations of class list were ignored.update.emmGrid(..., levels = levs) whereby we can easily relabel the reference grid and ensure that the grid and roles slots stay consistent. Added vignette example.emmeans(). We now ensure that the original order of the reference grid is preserved. Previously, the grid was re-ordered if any numeric or character levels occurred out of order, per order()CLD() due to its misleading display of pairwise-comparison tests.betareg objects, where the wrong terms component was sometimes used.by variables are present (#98).pwpp() function to plot P values of comparisonssummary(..., adjust = "scheffe"). We now actually compute and use the rank of the matrix of linear functions to obtain the F numerator d.f., rather than trying to guess the likely correct value.contrast() results if they are later used by emmeans(). This was first noticed with ordinal models in prob mode (#83).sommer::mmer, MuMIn::averaging, and mice::mira objectsnnet::multinom support when there are 2 outcomes (#19)gls objectsfamSize now correct when exclude or include is used in a contrast function (see #68)aovList objects, in part due to the popularity of afex::aov_ez() which uses these models.emm_options(opt.digits = FALSE)include argument to most .emmc functions (#67)ref, exclude, and include in .emmc functions (#68)... arguments in emmeans() when two-sided formulas are presentclm support when model is rank-deficientregrid(..., transform = "log") error when there are existing non-estimable cases (issue #65)brmsfit support (#43)mgcv::gam and mgcv::gamm models.my.vcov() now passes ... to clientsmanova object no longer requires data keyword (#72)aovlist models (#73)CLD fatal error when sort = TRUE (#77)lme objects (#75)"mvt" adjustment ignored by groupingcontrast() mis-labeled estimates when levels varied among by groups (most prominently this happened in CLD(..., details = TRUE))aovlist support so it re-fits the model when non-sum-to-zero contrasts were usedprint.summary_emm() now cleans up numeric columns with zapsmall()nesting in ref_grid() and update(), and addition of covnest argument for whether to include covariates when auto-detecting nestinghpd.summary() and handoff to it from summary()ref_grid() ignored mult.levs... where it shouldn’tCLD() now works for MCMC models (uses frequentist summary)opt.digits optionref.grid() put to final rest, and we no longer support packages that provide recover.data or lsm.basis methods.recover_data() and .emm_basis() to provide access for extension developers to all available methodsinst/extdata.all.vars() that could cause errors when response variable has a function call with character constants.regrid() (so results match summary() labeling with type = "response").plot.emmGrid(..., comparisons = TRUE, type = "response") produced incorrect comparison arrows; now fixeddf$y ~ df$treat + df[["cov"]]. This had failed previously for two obscure reasons, but now works correctly.simplify.names option for above types of modelsemm_options() with no arguments now returns all options in force, including the defaults. This makes it more consistent with options()emtrends(); produced incorrect results in models with offsets.update.emmGrid() and emm_options()qdrg() function (quick and dirty reference grid) for help with unsupported model objectscld() has been deprecated in favor of CLD(). This had been a headache. multcomp is the wrong place for the generic to be; it is too fancy a dance to export cld with or without having multcomp installed.xtending.Rmd vignette on how to export methodsrevpairwise.emmc and cld regarding comparing only 1 EMMcld.emm_list now returns results only for object[[ which[1] ]], along with a warning message.emmeans specs like cld ~ group, a vestige of lsmeans as it did not work correctly (and was already undocumented)Suggests (dozens and dozens fewer dependencies)lme models in “models” vignette.emmc functions (#22)exclude argument to most .emmc functions: allows user to omit certain levels when computing contrastshpd.summary() function for Bayesian models to show HPD intervals rather than frequentist summary. Note: summary() automatically reroutes to it. Also plot() and emmip() play along.nlme::lme modelsSurv() was interpreted as a response transformation.cld() is applied to an emm_list (issue #24)offset argument to ref_grid() (scalar offset only) and to emmeans() (vector offset allowed) – (issue #18)[.summary_emm to choose whether to retain its class or coerce to a data.frame (relates to issue #14)reverse option for trt.vs.ctrl and relatives (#27)terms is accessed with lme objects to make it more robustemmeans:::convert_scripts() renames output file more simply[ method for class summary_emmsimple argument for contrast - essentially the complement of byjoint_tests()ref_grid() accept ylevs list of length > 1; also slight argument change: mult.name -> mult.namesemmeans() wherein weights was ignored when specs is a listdata argument, if supplied to a data.frame (recover_data() doesn’t like tibbles…)as.data.frame method for emmGrid objects, making it often possible to pass it directly to other functions as a data argument.contrast() where by was ignored for interaction contrastsas.glht() where it choked on df = Infdata or subsetjoint_tests() function tests all [interaction] contrastsgamlss objects (but doesn’t support smoothing). Additional argument is what = c("mu", "sigma", "nu", "tau") It seems to be flaky when the model of interest is just ~ 1.emmeans() might pass data to contrast()summary.emmGrid()emm_options(summary = ...) to work as advertised.emmGrid() function to emm() as had been intended as alternative to mcp() in multcomp::glht() (result of ditto).cld.emm_list()Inf to display d.f. for asymptotic (z) tests. (NA will still work too but Inf is a better choice for consistency and meaning.)recover_data() now throws an error when it finds recovered data not reproduciblevcov() calls to comply with recent R-devel changesThis is the initial major version that replaces the lsmeans package. Changes shown below are changes made to the last real release of lsmeans (version 2.27-2). lsmeans versions greater than that are transitional to that package being retired.
emmeans(), emtrends(), emmip(), etc. But lsmeans(), lstrends(), etc. as well as pmmeans() etc. are mapped to their corresponding emxxxx() functions.ref.grid -> ref_grid, lsm.options -> emm_options, etc.ref.grid and lsmobj are gone. Both are replaced by class emmGrid. An as.emmGrid() function is provided to convert old objects to class emmGrid.lmerMod models. Also added options disable.lmerTest and lmerTest.limit, similar to those for pbkrtest.neuralgia and pigs datasetsemmmeans() methods is now top-down rather than convoluted intermingling of S3 methods-s in labels to /s to emphasize that thnese results are ratios.ref_grid. (Can be disabled via emm_options())plot() and emmip() are now ggplot2-based. Old lattice-based functionality is still available too, and there is a graphics.engine option to choose the default.Suggests pkgs to Enhances when not needed for building/testingNew developments will take place in emmeans, and lsmeans will remain static and eventually will be archived.