DHARMa - Residual Diagnostics for HierARchical 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’, ‘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.

Installing DHARMa

From CRAN

DHARMa is on CRAN, and for most users, installing from CRAN will be the best option. To install the latest CRAN release, just run

install.packages("DHARMa")

To get an overview about its functionality once the package is installed, run

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

The vignette, which can also be read online here, provides many examples about how to use the package function for the supported regression models. To cite the package, run

citation("DHARMa")

To fit a model (from any package supported by DHARMa), run

testData = createData(sampleSize = 200, family = poisson())
m1 <- glm(observedResponse ~ Environment1, 
                     family = "poisson", data = testData)

res <- simulateResiduals(m1, plot = T)

and read the help of ?simulateResiduals and the vignette to understand what you can do with the object res. If you want to ask questions about DHARMa or report a bug, please first read how to ask for help and report issues, then use the DHARMa GitHub issue page.

Development release

New features in DHARMa will typically be available on GitHub 1-2 months before they are on CRAN. If you want to install the current (development) version from this repository, run

devtools::install_github(repo = "florianhartig/DHARMa", subdir = "DHARMa", 
dependencies = T, build_vignettes = T)

Below the status of the automatic tests via GitHub Actions

Changes between versions are listed in the release notes (NEWS).

Development branches / older releases

To install a specific (older) release, or a particular branch, decide for the version number that you want to install in https://github.com/florianhartig/DHARMa/releases (version numbering corresponds to CRAN, but there may be smaller releases that were not pushed to CRAN), or branch and run

devtools::install_github(repo = "florianhartig/DHARMa", subdir = "DHARMa", 
ref = "v0.5.0", dependencies = T, build_vignettes = T)

with the appropriate version number / branch as argument to ref.

Contributing to DHARMa

Contributions to DHARMa are welcome. Please read the contributing guidelines before opening an issue or pull request. Note in particular the policy on AI-generated contributions (see also the instructions for AI coding agents) and the criteria for acknowledgement.

Acknowledgements

The DHARMa package has been funded by the Deutsche Forschungsgemeinschaft (DFG), project number 528747641 (2024-now).

A question by Catalina Gutiérrez Chacón provided Florian with the motivation to write the first version of DHARMa. Thanks for useful suggestions to improve DHARMa by Jochen Fründ, Tomer J. Czaczkes, Luis Cayuela Delgado, Alexandre Courtiol, Jim Thorson, Lukas Lohse, jmniehaus, justintimm and many other people that made comments on GitHub, Cross Validated or via email.