add_submodels() function that allows for comparison od estimates
from different submodels (when supported)weights bug in lme() (#356)
geeglm and glmgee (#496)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.qdrg() (#501)nuisance (#503)mvregrid() function for multivariate response transformations
such as a compositional response.mice::mira support to use Barnard-Rubin adjusted d.f. (#494)
gls support code (#495)This update is focused mostly on trying to clear up confusion with some users
on the distinction between emmGrid objects and their summaries, since they
display identically; and on encouraging users not to bypass important
annotations.
help(untidy)rbind method for summary_emm objects (#480).
Note that summary_emm objects already have estimates, P-values, etc.
computed, so rbinding them preserves those results. On the other hand,
rbinding emmGrid or emm_list objects produce new emmGrid objects
which have not yet been summarized and any adjust methods are applied
to the whole result.gls or lme models, mode = "satterthwaite"
and mode = "appx-satterthwaite" failed when model was fitted with no
explicit data argument (#465)
.emmc functions, just to make it easier to
see and use themwtcon.emmc(levs, wts, cmtype, ...) which
generates contrasts via multcomp::contrMat(wts, type = cmtype, ...)contrast() gains a new argument wts which can be passed to some
.emmc functions including eff.emmc, del.eff.emmc, and wtcon.emmc.
If wts is left missing, we pass equal weights of . If we specify wts = NA, we retrieve weights from the object (potentially different in each bygroup). Otherwise, the same fixedwts` are used in each group.weights() method for emmGrid objectspwpp() to play along if contrast() changes the
by variable via options (#472)strata() factors to be included in
the reference grid for survival models. It is up to the user to decide
what is sensible. (#429, #473)tau argument (now optional) for rq models (#458)
at even when apparently valid (#458)cross.adjust to legal arguments that can be passed via misc slotcross.adjustvcov. in glmgee support (#460)xtable() method for summary_emm objectsinner argument to make.tran() to allow for compound transform;
e.g., make.tran("inverse", inner = "sqrt") is reciprocal sqrt (#462)MuMIn support with subset argument (#455)glmtoolbox::glmgee support (#454)qdrg() modified such that we often don't need to specify data when
object is specified.rq, rqs now incorporates all tau values in the model
as a pseudofactor (#458). The tau argument itself is deprecated and ignored
if specified.make.meanint() and make.symmint() that return functions
that compute symmetric intervals. The old meanint() and symmint() functions
that return symmetric intervals of width 2 are retained for back-compatibility
multinom support so it works with a model where the
response is a matrix of counts (#439)MuMIn support (#442)qdrg() has replaced its ordinal.dim argument with ordinal, a list with
elements dim and mode -- which now fully supports all the modes available
for ordinal models (#444). (ordinal.dim still works for backward compatibility.)emtrends (#448)averaging support with certain predictor function calls (#449)contrast when tran is a list (#428)
strata() terms in survival models (#429)at (#430)qdrg() where we didn't always get V rightvcov.emmGrid() now only returns elements where object@misc$display == TRUE.
We also label the dimensions and provide a sep argument for creating labels.Correction to a bug introduced in version 1.8.4, where we tried to provide for
an offset argument in the same way as an offset() term in the model formula.
Unfortunately, that change also caused
wrong estimates to be computed when the offset involves a nonlinear function such as
log(), and made for whopping inconsistencies in the narrative about offsets
in the "sophisticated" vignette; I apologize for these embarrassing errors.
We now provide for both kinds of offset specifications, but in different ways
as explained in a new section in the "xplanations" vignette.
The "subtle difference" mentioned
in the NEWS for 1.8.4 no longer applies.
qdrg(). If object is specified, default for df is df.residual(object)
rather than object$df.residual, since df.residual() is a standard method.as.mcmc() now uses get_emm_option("sep") in labeling factor combinations (#425).emm_basis.averaging to take care of quirks in these
models (#402, #409)
decreasing argument to cld.emmGrid() for compatibility with
multcomp::cld.glht() and others.emtrends() when data is specified (semTools issue 119)
... and related tune-up to ref_grid() to avoid issues with repeat calls (#413)emm_list methods to make them more user-friendly (#417)pwts argument to recover_data.call(), needed because
prior weights did not always come through. This provides a reliable way
of passing prior weights in a recover_data() methodemmip_ggplot() (#397)
as.data.frame behavior. It has been made more forceful in
preserving annotations (i.e., summary_emm behavior) so that users don't
blind themselves to potentially important information. Also, some users
seem to force display of the data frame in order to see more digits; so we
now are taking a compromise approach: showing more digits but still as a
summary_emm object with annotations also displayed.Chisq value to results of test(..., joint = TRUE) and joint_tests()
when df2 is infinite (per request in #400)basics vignette has undergone a major revision that I hope helps
more in getting users oriented. It starts by discussing the fact that
EMMs' underpinnings are more in experiments than observational data, and
emphasizes more the process of first getting a good model.confidence-intervals vignette has been updated to reflect the same
example with pigs as is used in basicssigma
value in the @misc slot. For any models that are not in the "gaussian"
family, sigma is initialized to NA and this has some implications:
sigma value; however, for generalized linear models
the value of sigma(model) *is often inappropriate for bias adjustment,
and in fact anyway. you should not do that, and for mixed models,
you should calculate sigma based on the random effects. See the vignette
on transformations.predict(..., interval = "prediction")
will refuse to work, with no option to override. Same with specifying PIs = TRUE
in plot() or emmip(). The calculations done for prediction intervals
are only valid for Gaussian models. You may do predictions for non-Gaussian models
via simulating a posterior predictive distribution with Bayesian approach;
see an illustration in the "sophisticated" vignette.sigma value associated with them, resulting in
incorrect PIs and incorrect bias adjustments.
I have not figured out how I might help prevent that, but it probably will involve
making tedious modifications to these models' emm_basis methods. Maybe some future
improvements to be made.averaging objects (#402)mira objects when data is required (#406)scale() response transformation when either center or scale
is FALSE. I also added support for center() and standardize() from
the datawizard package as response transformations, though these are
mapped to scale().
Citation correction (#391)
Removed a message about contrasting transformed objects that even confuses me! (I added a topic in the FAQs vignette instead)
Added new exported function inverse available as a response transformation
I have quietly deprecated the previous I_bet() function, because it
produced a message that was confusing to inexperienced users. Instead, we
have tweaked some functions/methods so they seem to work the same way
with an emm_list object (using its first element) as an emmGrid object.
We have removed the functions convert_workspace() and convert_scripts()
that were intended to clean up existing code and objects for the ancient
version of lsmeans. We also completely removed several old functions
from the codebase. Previously, we just ignored them.
More reliable dispatching of recover_data() and emm_basis() methods (#392)
New permute_levels() function to change the order of levels of a factor (#393)
This may alter results of existing code for models involving offsets:
A user discovered an issue whereby offsets specified in an offset() model
term are accounted for, but those specified in an offset = ... argument
are ignored. We have revised the recover_data() and ref_grid() code so
that offsets specified either way (or even both) are treated the same way
(which is to include them in predictions unless overridden by
an offset argument in emmeans() or ref_grid()).
This change creates a subtle difference in cases where you want offsets to
depend on other predictors: In a model with formula y ~ trt + offset(off),
if you used to specify cov.reduce = off ~ trt, now you need cov.reduce = .offset. ~ trt. The latter will work the same with the model y ~ trt, offset = off.
Recoded some portions of the support functions for zeroinfl and hurdle
objects. We now use numerical differentiation to do the delta method,
and this comes out a lot cleaner.
Per the improved count-model support, we are now exporting and have documented
two new functions hurdle.support() and zi.support() that may be useful in
providing comparable support in other packages that offer zero-inflated
models.
Efficiency improvements: Several places in the code where we multiply
a matrix by a diagonal matrix, we replace this by equivalent code using
the sweep() function.
Over time, too many users have latched on to the idea that
emmeans(model, pairwise ~ treatment(s)) as the recipe for using emmeans().
It works okay when you have just one factor, but
when you have three factors, say, pairwise ~ fac1*fac2*fac3 gives you
every possible comparison among cell means; often, this creates an
intractable amount of output (e.g., 378 comparisons in a 3x3x3 case) -- most
of which are diagonal comparisons.
So now, if a user is in interactive mode, specifies contrasts in a direct
emmeans() call (i.e., sys.parent() == 0), there is more than one
primary factor (not including by factors), and there are more than 21
contrasts as a result (e.g. more than 7 levels compared pairwise), we issue
an advisory warning message: "You may have generated more contrasts than you
really wanted...". Because of the restrictions on when this warning is
issued, it should not affect reverse-dependent package checks at all.
regrid() (#287, revisited)
nbasis calculation in ordinal models (#387)addl.vars argument allows including variables (say, for
random slopes) in the reference grid.xtable methods are now
dynamically registered. This reduces the number of package dependencies
from 8 to 7 (as of this version)."atanh" to the options in make.tran() and to the
"named" response transformations that are auto-detectedmake.tran() replaces param argument with alpha and beta
(param is still supported for backward compatibility)
and documentation has been revised in hopes of making everything clearercld() so it can show findings rather than non-findings,
in two different ways: Using delta, groupings are based on actual
tests of equivalence with threshold delta; or setting signif.sets = TRUE,
means that have the same letter are significantly different.
We also added a vignette on "Re-engineering CLDs".
emtrends() (#133)emmip() so that we can specify color,
linetype, and symbol are all associated with groupings; and addition of
an example to produce a black-and-white plot. Note: While the default appearance
of plots is unchanged, plots from your existing code may be altered if
you have used linearg, dotarg, etc.vcov. to be coercible to a matrix, or a function that yields
a result coercible to a matrix (#383)"appx-satterthwaite" method (#384)counterfactuals argument to ref_grid(), setting up a reference
grid consisting of the stated factors and a constructed factor, .obs.no..
We then (by default) average this grid over the covariate distribution.
This facilitates G-computation under the exchangeability assumption for
counterfactuals.summary() introduced in #359 and reported in #364
as.data.frame.emm_list() so it preserves annotations like
in as.data.frame.emmGrid()mgcv::gam support to accommodate fancier smoothers
and more accurately detect random terms (#365, #366, #369)summary() from inside a function (#367)delta argument to hpd.summary(), thus allowing a way to
assess equivalence with Bayesian estimates (#370)stanreg estimability code when subset was used in model.emmip() and plot.emmGrid() now do appropriate things if point.est
or frequentist appear among the ... arguments, when we have Bayesian
models (note also, frequentist was removed from the visible arguments for
plot.emmGrid).emmip() plotted intervals regardless of CIs;
this has been correctedhead() and tail() methods for emmGrid objects[.summary_emm(), we changed the default to as.df = FALSE so that
annotations are still visible by default. This also preserves annotations
in head() and tail() for summariesemm_example() function used to tidy-up certain help-file examples
when they are conditional on an external packagesummary(), confint(), test(), and as.data.frame()
all produce data frames with annotations intact and visible. Additional
wrapping in data.frame(), as.data.frame(), etc. is completely unnecessary,
and if you send questions or bug reports with such code, I will regard
it as willful ignorance and will refuse to respond. See also the news for
version 1.8.0.lme support (#356)
svyolr objects from the survey package (#350)mgcv::gam support. Previously, random smoothers were
included. Thanks for Maarten Jung for observing this and helping to
identify them.test(..., joint = TRUE) and joint_tests()...
"est.fcns" attribute is actually estimable(confounded) entry in joint_tests() is now much
better formulated and more robust.xplanations vignetteestimability (>= 1.4.1) due to
a bug in version 1.4joint_tests(), we changed the default from cov.reduce = range
to cov.reduce = meanint, where meanint(x) returns mean(x) + c(-1, 1).
This centers the covariate values around their means, rather than their
midranges, and is more in line with the default of
ref_grid(..., cov.reduce = mean). However, this change in default
will change the results of joint_tests() from past experiences with
models having covariates that interact with factors or other covariates.
We also added a section on covariates to the help for joint_tests(),
and added another function symmint() for use in cov.reduce.print.summary_emm() now puts by groups in correct order rather
than in order of appearance.as.data.frame method has a new argument destroy.annotations, which
defaults to FALSE -- in which case it returns a summary_emm object
(which inherits from data.frame). I see that many users routinely wrap
their results in as.data.frame because they want to access displayed results
in later steps. But in doing so they have missed potentially useful
annotations. Users who have used as.data.frame to see results with
lots of digits should instead use emm_options(opt.digits = FALSE).>= 4.1.0, allowing freedom to use the forward pipe
operator |> and other features.trend argument in emmeans(),
which has long since been deprecated. We removed wrappers that implement
pmmeans(), pmtrends(), etc. -- which I believe nobody ever used.emm_list,
and added more complete documentation. We also added hidden
emm_list support to several functions like
add_grouping(), emmip(), and emmeans() itself.
These changes, we hope, help in situations where users create
objects like emm <- emmeans(model, pairwise ~ treatment) but are
not experienced or attuned to the distinction between emmGrid and
emm_list objects. The mechanism for this is to provide a
default of \code{I_bet(1)} for which element of the emm_list to
use. A message is shown that specifies which element was selected
and encourages the user to specify it explicitly in the future
via either [[ ]] or a which argument; for example, plot(emm[[1]])
or plot(emm, which = 1).
joint_tests() and test(..., joint = TRUE) now has
an "est.fcns" attribute, which is a list of the linear functions associated
with the joint test(s).joint_tests() results now possibly include a (confounded) entry for
effects not purely explained by a model term.fcross.adjust argument in summary.emmGrid() allows for additional
P-value adjustment across by groups.glm.nb support no longer requires data (#355) so
the documentation was updated.enhance.levels to contrast() that allows
better labeling of the levels being contrasted. For example, now
(by default) if a factor treat has numeric levels, then comparisons
will have levels like treat1 - treat2 rather than 1 - 2. We can
request similar behavior with non-numeric levels, but only if we
specify which factors.
comb_facs() and split_fac() for manipulating
the factors in an emmGrid.wts to eff.emmc and del.eff.emmc, which
allows for weighted versions of effect-style contrasts (#346)qdrg() more robust in accommodating various manifestations
of rank-deficient models.qdrg() now always uses df if provided. Previously forced df = Inf
when a link function was provided.df.error calculation with gls (#347)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)
cld() 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.4
mblogit 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 which
gee 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 posting
emmeans() 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 strata
emmeans() 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 #170
scheffe.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 in at` (#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 argument
emtrends() 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 methods
infer,
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 grouping
contrast() 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 robust
emmeans:::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 list
data 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.