'***' denotes important announcements
'**' denotes big changes visible to the user
'*' denotes minor changes visible to the user
'.' denotes minor fixes
2.11 (2023-10-24)
*** Revert a change introduced in v2.10 that sometimes caused comparisons
between models to be based on REML where this was not correct (due to
differences being present between the fixed-effect structures). Thanks to
Paul Warren for the report.
* 'control' is no longer treated as an NSE argument (but it is still getting
properly patched by the patcher functions). This fixes the argument being
evaluated too late when offloading fitting to clusters using the 'cl'
argument to buildmerControl(). Bug reported by Rebecca Bieber.
2.10.1 (2023-09-11)
. Fix bug introduced in v2.10 involving namespacing that caused an error when
trying to call buildmerControl() from other packages.
2.10 (2023-09-11)
*** Development has been migrated from GitHub to GitLab.
* The PQL guard now also blocks gam with outer iteration in the generalized
case.
. remove.terms() now correctly removes the intercept if asked to.
. The error about providing a tabulated formula without a 'dep' argument in
buildmerControl() is now disabled if I_KNOW_WHAT_I_AM_DOING is TRUE.
. A bug was fixed in re2mgcv() which made it unable to produce non-intercept
columns.
. Backward elimination now no longer erroneously fits an ML reference model if
REML is forced on.
2.9 (2023-05-19)
* re2mgcv() now detects and suppresses constant r.e. predictors. An optional
'drop' argument (default TRUE) allows for this new behavior to be turned off
(which is done by setting 'drop' to FALSE).
* converged() no longer incorrectly bails out early if lme4 did not provide
convergence information.
* converged() can now be called on buildmer models.
. Correct processing of crit.name and elim.name.
. Due to glmertree updates, the buildmertree test results have changed to a
*near*-singular convergence. The test has been updated to account for this.
2.8 (2023-01-06)
* New control option in buildmerControl(): scale.est. Mostly for internal
use. Fixes crit.deviance/crit.F not working on non-gam models. Thanks to
Sarah Rösch for reporting the bug.
* Slightly rearrange buildmerControl() options.
* Update checking logic for ddf option. It now raises a more informative
message if the user attempts to use lmerTest ddf with negative-binomial
models.
* Add support for optional 'crit.name' and 'elim.name' attributes for custom
(i.e. function) 'crit' and 'elim' arguments. Fixes an unnecessary warning
about mismatched crit and elim when LRTalpha() is used. Thanks to Juris
Breidaks.
* backward() no longer fits an unnecessary ML model if all terms to be
compared are r.e. terms.
. Fix a [ vs [[ decision in the patcher functions, which turned out to (a)
cause problems and (b) be unnecessary. Thanks to Alexandra Pike.
2.7 (2022-10-20)
* An informative error is now thrown if the user attempts to use
buildmerControl incorrectly.
* Singularity checks for lme models.
* remove.terms() now has an optional 'check' argument (default TRUE) through
which the user can disable marginality checks, causing it to unconditionally
remove terms from the formula.
* buildmer now always converts lme4 models to lmerTest, if lmerTest is
available, unless Wald ddf had been requested.
. Patcher functions will no longer set the calling function incorrectly for
'gamm' and 'gamm4' models.
. Patcher functions now correctly propagate all NSE names.
. Remove plyr dependency.
. Fix setting the data name in patch.gamm4.
. patch.mertree now respects singular.ok in buildmerControl().
2.6 (2022-07-13)
** glmer.nb/glm.nb support.
* The 'include' control argument can now also be a character vector, as had
been intended. There are now also examples on how to use it in the
'buildmer' function. GH issue #16.
* 'include' random effects are now also included in the fixed-effects
ordering stage. This is necessary if, e.g., they are observation-level
random effects for zero-inflation purposes.
* Guard even further against mismatched 'crit' and 'elim'. GH issue #15.
. Fix passing of I_KNOW_WHAT_I_AM_DOING.
. Recognize more NSE arguments.
. Pass can.use.reml=FALSE to buildclmm, resulting in it no longer fitting a
pointless second model for each r.e. test.
. Fix buildclmm when run without any supplementary arguments.
2.5 (2022-06-14)
*** 'Old-style' passing of buildmer control parameters in the build...(...)
function call has been removed (deprecated since 2020-06-05). In addition,
passing extra arguments to the fitting function in ... has been removed.
(deprecated since 2021-08-13). For both, 'buildmerControl' is the
replacement (use its 'args' argument for the latter; use it itself for the
former).
. Fix a bug preventing random-effect terms from expanding properly, thereby
breaking e.g. the common nesting syntax for random effects. Thanks to
Jonathan Richir.
2.4 (2022-04-06)
* Full support for double-bar syntax for random effects, including in
GLMMadaptive for diagonal r.e. covariance (GH issue #14).
* Fix incorrect tolerances (i.e. not actually multiplied by 100) in
buildbam().
. Further improvements to the handling of NSE terms, which are important
technically but for end users should only result in cosmetic improvements.
. Change the intercept-hackery in buildbam to work with latest mgcv versions.
. Update tests.
2.3 (2022-01-04)
* Fix an important bug swallowing NSE arguments passed in buildmerControl().
Thanks to Juris Breidaks for reporting it.
. Provide a slightly more informative error message when passing incorrect
formula objects (e.g. trying to fit a multi-formula GAM using buildgam()).
2.2 (2021-11-02)
. Keep respecting 'include' when a model is reduced due to nonconvergence
during backward elimination. Bug reported by Adam Parker.
. Make crit.LRT safe for use even for custom model functions that do not use
standard formulae.
2.1 (2021-09-16)
* buildmerControl() now also supports NSE arguments (weights, offset,
AR.start).
* New function LRTalpha() has been added, which generates an LRT elimination
function with a custom alpha level. GH issue #5.
. Some minor cosmetic documentation changes.
. Fix cosmetic bug swapping outer iteration and PQL in the message reporting
successful convergence of gam models in converged().
. Add support for outer-iteration models without smooth terms in converged()
. Also support convergence checking for glmertree models --- this was already
supported inside buildmertree, but is now user-facing as well.
2.0 (2021-08-19)
*** Passing extra arguments to the fitting function in ... is now deprecated;
please use buildmerControl=list(args=list(...)) instead. Using ... at all,
and moreover using it both for buildmer arguments and for arguments to be
passed to the fitting function, was a design flaw; this deprecation is the
first step towards fixing it.
** Use actual R-squared instead of adjusted R-squared in the R-squared
criterion. Also ensure that the model and residual df sum to N.
* Remove deprecated function conv(); use converged() instead.
* Refits due to convergence failure now only indicate failures, not also
successes, during term ordering and backward elimination.
* More extensive convergence checks for GAMs, with less special-casing.
* Further convergence tweaks for bam() models.
* The R-squared criterion now also works for nnet::multinom() models.
. An error is now raised if 'data' is specified where it shouldn't have been.
. Allow terms to be specified both in the model formula as well as in
'include'. Bug reported by Nick Pandža.
. Fix bug preventing numeric 'cl' arguments from working.
. Convergence checks will no longer fail for very big matrices (for which
eigen() can sometimes return complex vectors).
1.9 (2021-03-27)
* If 'crit' is specified but 'elim' is not, all buildmer functions will now
automatically choose the matching 'elim' function, rather than use the
default likelihood-ratio test. GH issue #10.
* Only p-values for lme4-style random-effect terms are now corrected using
the Stram & Lee approach. Importantly, this means that degrees of freedom
from GAM(M)s are now trusted as they are. See GH issue #9 for the
justification.
* Fix a subtle bug whereby the first model during backward elimination was
always fit with REML even when it shouldn't be. GH issue #7.
. Now using testthat for unit testing.
. bam's 'discrete' option is now automatically set to FALSE on ML fits.
. tabulate.formula() can now also tabulate empty models.
. 'forward' and 'backward' now both respect the 'quiet' option.
1.8 (2021-02-14)
* 'REML' is now in buildmerControl().
* Buildmer no longer exports its own internal functions to cluster nodes, as
the cluster nodes inherit the buildmer::: environment anyway.
* Buildmer no longer incorrectly prohibits Satterthwaite ddf for non-Gaussian
models. For Gamma and inverse Gaussian errors, they could still be quite
useful. For binomial and Poisson, a more informative warning is now raised
explaining that ddf approximations make no sense for these distributions.
1.7.1 (2020-08-26)
*** Buildmer control parameters (e.g. crit, direction, cl, ...) are now passed
via a new argument buildmerControl=list(...). The 'old-style' passing of
these arguments as part of the buildX() call itself is still supported,
but is now deprecated. If a control parameter is passed both 'old-style'
and in buildmerControl, the former takes precedence. All parameters are
now documented in a single place: ?buildmerControl.
* Implement gradient and Hessian tolerances in converged(). These can now also
be passed as arguments to buildmer functions.
* New elimination criterion for gam/bam models only: 'F'. This uses the change
in R-squared, and has the advantage of being a valid formal test even for
models that were fitted using PQL.
* If singular.ok=TRUE, converged() will now also test singular fits for
convergence, rather than accept them outright.
* The optional 'quiet' argument has been added back.
* The REML+no-random-effects path now uses mgcv::gam rather than nlme::gls,
because the latter expects a non-compatible form for the 'weights' argument.
. Fixes to environment handling support, in particular concerning
tabulate.formula(), which now preserves the formula's environment.
. glmmTMB models are now also checked for gradient convergence, not just for
positive-definiteness of the Hessian.
. A workaround has been implemented to enable fitting glmmTMB models with
offset terms.
. Offset terms are now understood properly by tabulate.formula().
. Changed the wording of the give-up message in order().
1.6 (2020-05-27)
*** Function conv() has been renamed to converged(). Of course, an alias
remains, but it is now deprecated and will be removed in a future release.
** clm and clmm support.
* Argument 'cl' now accepts an integer argument, in which case buildmer will
create and manage a cluster for you.
* REML can now be forced on by passing REML=TRUE. As an optimization, REML is
forced on if the deviance-explained criterion is used. This can be disabled
by passing REML=NA, which will fall back to the default behavior of
differentiating between ML and REML. The ability to force REML off by
passing REML=FALSE remains. This 'hidden' argument is now properly
documented, as is the other hidden argument, 'dep'. For buildcustom(), where
this option was already used explicitly with a different meaning, the old
behavior remains as the new behavior doesn't make much sense if the user is
specifying their own fitting function anyway.
* Remove deprecated 'reduce.fixed' and 'reduce.random' arguments (deprecated
since 2019-11-27).
* Print the failure details when convergence failures cause order() or
backward() to exit early.
. Fix a bug combining backward() with the 'include' argument (GH issue #3).
. Fix a bug in calculating Wald p-values for ANOVA F scores affecting ndf >1.
. Allow ddf='KR' as an abbreviation for ddf='Kenward-Roger'.
1.5 (2020-03-01)
*** API change to the 'crit' function, which now has a new function signature
(p,cur,alt).
*** Deprecate buildjulia due to the maintenance cost of duplicating all the
important likelihood functions. You can code these yourself using
buildcustom().
** Likelihood-ratio tests for random effects are now modeled as a mixture of
chi squares (Stram & Lee 1994), rather than by dividing the p-value by 2.
This makes a difference only for model terms with >1 change in df.
** PQL is okay with Gaussian errors (Breslow & Clayton 1993); this is now
known to buildbam(), buildgam(), and buildgamm(). These now default to LRT,
and give an error message with advice if errors are not Gaussian.
* Relax convergence tolerances for negative eigenvalues to -0.002 (mgcv and
glmmTMB models only).
* Relax convergence tolerance for gradients to 0.04 (mgcv models only).
* Convergence messages are now more informative due to an added human-readable
'reason' attribute.
. re2mgcv no longer uses 'by', to possibly work around segmentation faults
. Progress messages are now word-wrapped properly.
. Fix incorrect filtering of '...' for (g)lmtree models.
1.4 (2019-12-03)
*** The 'reduce.fixed' and 'reduce.random' arguments have been deprecated; use
the 'include' argument instead.
** Add new criterion 'devexp' (alias: 'deviance') based on the explained
deviance. Modify buildbam() so that, in the generalized case, it only
accepts this criterion. bam() and gam() with non-outer optimization use PQL,
which was incorrectly permitted by the previous version of the PQL guard
** S3 and S4 method passthrough support.
** gamm support.
** buildgam() has gained an experimental 'quickstart' argument that prefits
each gam model using bam() to obtain starting values. Specifically for the
'scat' family, the optimized theta values indicating the degrees of freedom
and the scale parameter will also be passed on to the gam() call, but only
if the mgcv version is at least 1.8-32.
** Added new function 're2mgcv()' that makes it possible to use buildgam()
with lme4-style random effects (with correlations removed).
* Smooth terms are now no longer forced to be evaluated after parametric
terms.
* For general families that are fitted with REML only, buildgam() now makes
the appropriate modifications to the gam() call and include list.
* buildcustom() has gained the ability to use buildmer's ML/REML
differentiation facilities; turn this on by passing REML=TRUE to the call to
buildcustom().
* Split up buildmer() and buildgamm4().
. Filter ... argument more precisely in the various buildmer() fitting paths
for non-mixed models (lm/glm/gls).
. Fix bugs in remove.terms() and in order() affecting certain models containing
smooths.
. buildgam() is now properly able to fit intercept-only models.
. Convergence for glmmTMB models is now checked correctly if there are/seem to
be (as with REML=TRUE) no fixed effects.
. Work around glmmTMB issue with REML for poisson and binomial models.
. build.formula() now also handles formulas where fixed and random effects are
not strictly in that order (which fixes 'include' for random effects).
. Implement workaround in buildgls() to work with rank-deficiency.
. Wrap examples in requireNamespace().
. Explicitly fit (fixed/random)-intercept models as well, which was skipped in
earlier versions. Add dependency on nlme, as gls() is used when
transitioning from fixed to random effects in lme4 models.
. Fix diag() and add.terms() for one-sided formulas.
1.3 (2019-09-28)
** GLMMadaptive support.
* lme models (package nlme) now have full support for the random part as well.
* glmertree models now have full support for stepwise elimination.
* calc.anova is now FALSE by default. Most users will not use it anyway, and
for some lmerTest-based models it can cause an error.
* It is now (experimentally) possible to pass REML=FALSE to all buildmer
functions to disable REML detection and always use ML. This may be useful if
you are fitting GLMMs using glmmTMB and do not want to use their REML
approximation.
. Nonconvergence of the fixed-effects part of the term-ordering step is now
handled properly.
. Fix bugs in order() and forward() breaking ML-only GLMM fits (GitHub issue #2)
. The 'include' argument was not being processed correctly when a cluster was
provided. This is now fixed.
1.2.1 (2019-09-03)
. Avoid the use of reformulate(), as its env= argument is only available on R
>= 3.6 (bug reported by Willemijn Heeren).
. Relax the convergence checks for negative eigenvalues (affects mgcv and
glmmTMB models).
. Improve detection of random effects.
. Remove terms by block when a reference model fails to converge and detect
empty models.
1.2 (2019-08-27)
** Proper environment support.
** glmertree support.
* More formal support for diagonal covariance structures via a new 'groups'
argument to tabulate.formula.
* Retire the 'quiet' argument.
* Overhaul documentation.
* Significantly improve family handling.
* Allow 'include' to take a tabulated formula.
* conv() now accepts a singular.ok argument, which is always FALSE inside
buildmer.
. Improve REML detection.
. Increase robustness with user-provided formula tab.
. Make convergence checks more consistent between model types.
. Rework add.terms and related random-effects detection to fix obscure bug
when tabulating non-r.e. terms that fool lme4::findbars (e.g. 'ar1(x|g)').
1.1 (2019-05-18)
** Large rewrite of internal code organization. You can now specify arbitrary
fitting functions, criteria, and elimination functions.
* Add 'include' argument to force terms to always be in the formula (fixes
GH bug #1).
* New function 'buildcustom'.
* Added raw log-likelihood as a criterion: 'LL'.
. Fix bug in calculating anova table with lmerTest ddf options.
. Make calcWald respect numerator df in anova table.
. Remove incorrect gradient check for mgcv models in conv(), instead check for
'full convergence' string.
1.0 (2019-03-31)
*** First public release.