Residual Diagnostics for Hierarchical (Multi-Level / Mixed) Regression Models

The 'DHARMa' package 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' and 'spaMM', 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 and temporal autocorrelation.

The DHARMa package creates readily interpretable residuals for generalized linear (mixed) models that are standardized to values between 0 and 1. This is achieved by a simulation-based approach, similar to the Bayesian p-value or the parametric bootstrap: 1) simulate new data from the fitted model 2) from this simulated data, calculate the cummulative density function 3) residual is the value of the empirical density function at the value of the observed data.

The package includes various functions that deal with issues such as

  • Misfit
  • Overdispersion
  • Zero-inflation
  • Residual temporal autocorrelation
  • Residual spatial autocorrelation

To get more information, install the package and run

vignette("DHARMa", package="DHARMa")


A question by Catalina Gutiérrez Chacón provided me with the motivation write the first version of DHARMa. Thanks to Jochen Fründ, Tomer J. Czaczkes, Luis Cayuela Delgado and Alexandre Courtiol for useful suggestions to improve the software.


NOTE: for more news about the package, see

DHARMa 0.2.4


  • corrected issues in the vignette
  • small corrections to help

DHARMa 0.2.3


DHARMa 0.2.2


  • fixes bug in Vignette (header lost)

DHARMa 0.2.1

New features

Major changes

Minor changes

  • a number of smaller updates, mostly to help files


  • fixes #82 / Bug in recalculateResiduals

DHARMa 0.2.0

New features

Major changes

Minor changes


DHARMa 0.1.6

New features

Minor changes

  • changed syntax in tests for sptial / temporal autocorrlation - null provides now random. Also, custom distance matrices can be provided to testSpatialAutocorrelation
  • slight changes to plot layout


DHARMa 0.1.5

Minor changes

  • fixes a bug in version 0.1.4 that occurred when running simulateResiduals with refit = T. Apologies for any inconvenience.

DHARMa 0.1.4

Major changes

  • new experimental non-parametric dispersion test on simulated residuals. Extended simulations to compare dispersion tests

Minor changes

DHARMa 0.1.3

Major changes

Minor changes

  • plotResiduals includes support for factors

  • updates to the help

DHARMa 0.1.2

  • This bugfix release fixes an issue with backwards compatibility introduced in the 0.1.1 release, which used the 'startsWith' function that is only available in R base since 3.3.0. In 0.1.2, all occurences of 'startsWith' were replaced with 'grepl', which restores the compatibility with older R versions.

DHARMa 0.1.1

  • including now the negative binomial models from MASS and lme4, as well as the possibility to create synthetic data from the negative binomial family

  • includes a createDHARMa function that allows using the plot functions of DHARMa also with externally created simualtions, for example for Bayesian predictive simulations

DHARMA 0.1.0

  • initial release, with support for lm, glm, lme4

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


0.4.4 by Florian Hartig, a month ago

Report a bug at

Browse source code at

Authors: Florian Hartig [aut, cre] , Lukas Lohse [ctb]

Documentation:   PDF Manual  

GPL (>= 3) license

Imports stats, graphics, utils, grDevices, Matrix, parallel, gap, lmtest, ape, qgam, lme4

Suggests knitr, testthat, rmarkdown, KernSmooth, sfsmisc, MASS, mgcv, spaMM, GLMMadaptive, glmmTMB

Enhances phyr, rstan, rjags, BayesianTools

Imported by BayesianTools, insurancerating.

Suggested by GLMMadaptive, glmmTMB, phyr, qra.

See at CRAN