Residual Diagnostics for Hierarchical (Multi-Level / Mixed) Regression Models
Overview
"Uses a simulation-based approach to create readily interpretable scaled (quantile) residuals for fitted generalized linear (mixed) models. Currently supported are linear and generalized linear (mixed) models from 'lme4' (classes 'lmerMod', 'glmerMod'), 'glmmTMB', 'GLMMadaptive', 'spaMM', and 'brms' (simple models); phylogenetic linear models from 'phylolm' (classes 'phylolm' and 'phyloglm'); generalized additive models ('gam' from 'mgcv'); 'glm' (including 'negbin' from 'MASS', but excluding quasi-distributions) and 'lm' model classes. Moreover, externally created simulations, e.g. posterior predictive simulations from Bayesian software such as 'JAGS', 'STAN', or 'BUGS' can be processed as well. The resulting residuals are standardized to values between 0 and 1 and can be interpreted as intuitively as residuals from a linear regression. The package also provides a number of plot and test functions for typical model misspecification problems, such as over/underdispersion, zero-inflation, and residual spatial, temporal and phylogenetic autocorrelation."
Major changes
- For hierarchical models (GLMMs), we changed the default simulations from the supported model's default (mostly unconditional) to conditional simulations (for most of the supported models and packages). This represents a major change in the calculated scaled residuals and is implemented to ensure higher power in dispersion and other tests. We expect different results for calculated residuals using this or older
DHARMaversions. For compatibility, you can use the argumentsimulateREs = "user-specified"to change back to the model's default (olderDHARMaversions). See package vignette for more details. - In
plotResiduals, we increased the threshold for the automatic change from quantile regression lines to the spline: from 2,000 to 10,000 data points. When it happens, a message is displayed to warn users. Also, whenquantreg = F, the color of the spline was changed to black because there is no test associated with the line (as there is for quantile regression). - In
plotResiduals, the argumentformhas a new functionality. Beyond the syntaxdata$predictor, it allows now to use the formula structure~predictor,~predictor1+predictor2,~.,~predictor|groupand~predictor|group == "group_level"to plot the residuals against specific/all predictors and grouping variables/levels. This works for most of the supported model functions. It solves problems with NAs in datasets that were excluded by the model. #407 / #425 - In
testCategorical,recalculateResiduals,testQuantiles,testSpatialAutocorrelationandtestTemporalAutocorrelation, additional predictors (catPred,group, sel,predictor,time,x,y- respectively) can now be specified as a formula (similar toplotResiduals). This handles rows with NAs that were excluded by the model automatically. brmsis now supported by DHARMa for simple models, i.e. models that could also be fit using glmmTMB (no multi-response, multinomial or structural equation models).
Bugfixes
- Fixing error in runBenchmarks.
- Fixing inconsistency in testQuantiles() #465. Including rankTransform() help function.
Minor changes
- Using 95% confidence intervals for confidence bands in plots for testQuantiles(). Before, we were using standard errors (~ 68% CI).
- Vectorize randomization of residuals to improve speed - PR#493 contributed by StaffanBetner.
Show all changes in 0.5.0Hide the rest of the changes in 0.5.0
- Adding color legend to testSpatialAutocorrelation().
- New function plotResidualsAll() to plot residuals against multiple predictors/all predictors of the model via plotResiduals().
- New function getPredictorNames() extracts names of fixed and random effects (predictors) from a model.
- testCategorical() now allows additional arguments to boxplot via ..., mainly to allow for appropriate x-axis labels when running plotResidualsAll().
- Improved appearance of user-specified titles via "main" in plotResiduals().
From NEWS.md in the release
Install
Health
NOTER code for possible problemsr-devel-linux-x86_64-debian-clang, r-devel-linux-x86_64-debian-gcc, r-devel-linux-x86_64-fedora-clang, r-devel-linux-x86_64-fedora-gcc, r-devel-windows-x86_64
Found calls to structure() using deprecated special names: DHARMa/inst/doc/DHARMa.R (.Label: 1, .Names: 1) '.Label' should be changed to 'levels'. '.Names' should be changed to 'names'.
- NOTE8 OK, 5 NOTENow
- NOTE10 OK, 3 NOTE2026-07-16
- OK13 OK2026-06-09
- ERROR12 OK, 1 ERROR2026-06-08
- OK14 OK2026-03-10
Documentation
- Help pages
- 57 (9 internal)includes a package overview page
- Examples that run
- 94%30 run in a plain check · 2 never run
- Exported functions with examples
- 68%
- Documented parameters
- 96%
- Return-value docs
- 15%
- Help pages citing references
- 7%
Downloads
Repository
- PRs merged (all time)
- 81%
- Median days to close, 50 most recently updated closed issues
- 132
- Median days to close, 50 most recently updated closed PRs
- 14
Stars over time
Forks over time
Releases over time
Issues over time
PRs over time
Commits over time
5 development-tooling and community-health practices detected across 3 families in the upstream repository
Checks run against github.com/florianhartig/dharma on 2026-10-18.
The R CMD check workflow runs on Linux, macOS and Windows, and on R-devel
GitHub Pages site last deployed 2026-10-02
This repository shows signs of AI coding tools.
- GitHub Copilotfirst seen 2025-11-23Pull request: opened by its own account
Dependencies
Installing DHARMa adds 86 packages (49 with compiled code, 88 MB of source tarballs). Heaviest: stringi 11 MB, ggplot2 6.0 MB, data.table 5.7 MB.
Show all 29 packagesHide all 29 packages
Code & Tests
Datasets
People & History
Pick two releases to compare their code metrics.
- 0.5.0Latest
- RR 4.6.0 released · 2026-04-24
- RR 4.5.0 released · 2025-04-11
- 0.4.72024-10-18 · diff ↗ ·
added 3 exports
getFamily, getPearsonResiduals, testPhylogeneticAutocorrelation - RR 4.4.0 released · 2024-04-24
- RR 4.3.0 released · 2023-04-21
- 0.4.6
- RR 4.2.0 released · 2022-04-22
- 0.4.5
- 0.4.42021-09-28 · diff ↗
- 0.4.32021-07-07 · diff ↗
- 0.4.22021-07-05 · diff ↗
- RR 4.1.0 released · 2021-05-18
- 0.4.12021-04-08 · diff ↗
- 0.4.02021-03-28 · diff ↗
- 0.3.4
Show 24 earlier eventsHide 24 earlier events
- 0.3.3.02020-09-08 · diff ↗
- 0.3.2.02020-06-18 · diff ↗
- 0.3.1
- RR 4.0.0 released · 2020-04-24
- 0.3.02020-04-20 · diff ↗ ·
removed 2 exports
getResponse, testModeladded 6 exports
getFitted, getFixedEffects, getObservedResponse, getRefit, hasWeigths, testQuantiles - 0.2.72020-02-06 · diff ↗
- 0.2.62019-11-26 · diff ↗
- 0.2.5
- RR 3.6.0 released · 2019-04-26
- 0.2.42019-03-06 · diff ↗
- 0.2.32019-02-12 · diff ↗
- 0.2.22019-01-20 · diff ↗
- 0.2.1
- 0.2.02018-06-05 · diff ↗ ·
removed 3 exports
benchmarkOverdispersion, benchmarkP, benchmarkUniformityadded 6 exports
getRandomState, recalculateResiduals, runBenchmarks, testDispersion, testGeneric, testResiduals - RR 3.5.0 released · 2018-04-23
- 0.1.6
- RR 3.4.0 released · 2017-04-21
- 0.1.52017-03-11 · diff ↗
- 0.1.42017-03-08 · diff ↗
- 0.1.32016-12-12 · diff ↗
- 0.1.22016-11-19 · diff ↗
- 0.1.1
- 0.1.02016-08-26
- RR 3.3.0 released · 2016-05-03
Package metadata
- First published
- 2016-08-26
- Total releases
- 29 / 10 yrs
- License
- GPL (>= 3) OSI
- Minimum R
- ≥ 3.5.0
- Bundled data
- 3.5 KB / 1 file
- Download size
- 3.7 MB
Cite
Cite this package
Run in R for the authors' preferred citation:
citation("DHARMa")This package has no citation file, so citation() returns this entry built from DESCRIPTION.
Cite the R Observatory
For a number measured here: a download total, a coverage figure, an archival date.
From data release v2026-10-22, which the citation names so these numbers can be found later. More on citing and the projects behind them.