Return residuals of a DHARMa simulation
Usage
# S3 method for class 'DHARMa'
residuals(object, quantileFunction = NULL,
outlierValues = NULL, ...)Arguments
- object
an object with simulated residuals created by simulateResiduals.
- quantileFunction
optional - a quantile function to transform the uniform 0/1 scaling of DHARMa to another distribution.
- outlierValues
if a quantile function with infinite support (such as qnorm) is used, residuals that are 0/1 are mapped to -Inf / Inf. outlierValues allows to convert -Inf / Inf values to an optional min / max value.
- ...
optional arguments for compatibility with the generic function, no function implemented.
Details
The function accesses the slot $scaledResiduals in a fitted DHARMa object, and optionally transforms the standard DHARMa quantile residuals (which have a uniform distribution) to a particular pdf.
Note
Some of the papers on simulated quantile residuals transforming the residuals (which are natively uniform) back to a normal distribution. I presume this is because of the larger familiarity of most users with normal residuals. Personally, I never considered this desirable, for the reasons explained in https://github.com/florianhartig/DHARMa/issues/39, but with this function, I wanted to give users the option to plot normal residuals if they so wish.
Examples
library(lme4)
testData = createData(sampleSize = 100, overdispersion = 0.5, family = poisson())
fittedModel <- glmer(observedResponse ~ Environment1 + (1|group),
family = "poisson", data = testData)
# simulate residuals (default behavior, conditional on the fitted random effects)
simulationOutput1 <- simulateResiduals(fittedModel = fittedModel)
plot(simulationOutput1, quantreg = FALSE)
# simulate residuals unconditional on the fitted random effects (REs are re-simulated)
simulationOutput2 <- simulateResiduals(fittedModel = fittedModel,
simulateREs = "unconditional")
plot(simulationOutput2, quantreg = FALSE)
# simulate residuals user-specified using lme4 syntax (e.g. conditional only on a specific RE)
simulationOutput3 <- simulateResiduals(fittedModel = fittedModel,
simulateREs = "user-specified",
re.form = ~(1|group))
plot(simulationOutput3, quantreg = FALSE)
# one of the possible test, for other options see ?testResiduals / vignette
testDispersion(simulationOutput1)
#>
#> DHARMa nonparametric dispersion test via sd of residuals fitted vs.
#> simulated
#>
#> data: simulationOutput
#> dispersion = 1.2711, p-value = 0.104
#> alternative hypothesis: two.sided
#>
# the calculated residuals can be accessed via
residuals(simulationOutput1)
#> [1] 0.620634580 0.266950787 0.998116672 0.952564868 0.810212152 0.225556192
#> [7] 0.117954129 0.577680009 0.133752668 0.185770127 0.640149953 0.073312477
#> [13] 0.992678531 0.152317698 0.581744443 0.747178346 0.810929247 0.031048380
#> [19] 0.204071611 0.244843692 0.403585675 0.303335818 0.228946695 0.863436555
#> [25] 0.151685437 0.995897300 0.569594714 0.051518212 0.880622404 0.514885300
#> [31] 0.360589449 0.301336847 0.012818835 0.937416859 0.232387464 0.782909852
#> [37] 0.852546496 0.487039842 0.280580613 0.383870949 0.580004219 0.397818764
#> [43] 0.896283520 0.481714232 0.056181687 0.546743376 0.825875100 0.353121945
#> [49] 0.421411893 0.754450159 0.051999741 0.759808604 0.711481884 0.184575561
#> [55] 0.798358203 0.808871603 0.766435867 0.300412906 0.574352341 0.126099316
#> [61] 0.039171829 0.286210237 0.677588822 0.596995997 0.571358071 0.151107279
#> [67] 0.831241827 0.583411904 0.959549489 0.410474619 0.690793881 0.286498899
#> [73] 0.123338922 0.999759164 0.028000000 0.565686787 0.057960191 0.996000000
#> [79] 0.005664088 0.517813340 0.128155211 0.415172259 0.372634563 0.899201555
#> [85] 0.292651966 0.595901202 0.764137404 0.906254324 0.589586888 0.680222335
#> [91] 0.654369027 0.181675965 0.233500817 0.318947267 0.677166516 0.406242840
#> [97] 0.980071967 0.888253543 0.335840215 0.421271530
# transform residuals to other pdf, see ?residuals.DHARMa for details
residuals(simulationOutput1, quantileFunction = qnorm, outlierValues = c(-7,7))
#> [1] 0.30714785 -0.62206128 2.89707014 1.67024821 0.87867836 -0.75356181
#> [7] -1.18527621 0.19596191 -1.10882580 -0.89359195 0.35885964 -1.45155653
#> [13] 2.44109164 -1.02654366 0.20635821 0.66563675 0.88132580 -1.86560421
#> [19] -0.82716557 -0.69080613 -0.24407679 -0.51483026 -0.74232014 1.09589006
#> [25] -1.02923156 2.64349905 0.17534243 -1.63030797 1.17810389 0.03732057
#> [31] -0.35688367 -0.52055946 -2.23165658 1.53344487 -0.73100692 0.78205833
#> [37] 1.04741762 -0.03249201 -0.58111756 -0.29532987 0.20190427 -0.25899704
#> [43] 1.26065559 -0.04585169 -1.58765942 0.11743765 0.93798951 -0.37690542
#> [49] -0.19828283 0.68856082 -1.62576582 0.70568702 0.55771907 -0.89806458
#> [55] 0.83577127 0.87374563 0.72715948 -0.52321332 0.18746595 -1.14502541
#> [61] -1.76037847 -0.56449034 0.46096689 0.24557918 0.17983277 -1.03169599
#> [67] 0.95908417 0.21062975 1.74548189 -0.22632425 0.49810188 -0.56364200
#> [73] -1.15845637 3.49074664 -1.91103565 0.16540347 -1.57213010 2.65206981
#> [79] -2.53240900 0.04466627 -1.13515490 -0.21425973 -0.32488366 1.27701518
#> [85] -0.54565380 0.24275190 0.71967489 1.31803673 0.22648243 0.46832061
#> [91] 0.39714309 -0.90899658 -0.72736623 -0.47064463 0.45978999 -0.23722057
#> [97] 2.05523754 1.21729259 -0.42384284 -0.19864166
# get residuals that are outside the simulation envelope
outliers(simulationOutput1)
#> integer(0)
# calculating aggregated residuals per group
# group here specified as formula (recommended)
# but you can also use a variable from your environment, e.g. testData$group
simulationOutput4 = recalculateResiduals(simulationOutput1, group = ~group)
plot(simulationOutput4, quantreg = FALSE)
# we see one residual point per RE
# with group as variable in your environment
# but then you need to exclude NAs by hand
simulationOutput5 = recalculateResiduals(simulationOutput1, group = testData$group)
# calculating residuals only for subset of the data
simulationOutput6 = recalculateResiduals(simulationOutput1, sel = testData$group == 1)
plot(simulationOutput6, quantreg = FALSE)
# or with sel as formula
simulationOutput7 = recalculateResiduals(simulationOutput1, sel = ~Environment1<0.5)
# as condition based on a variable in your environment
simulationOutput8 = recalculateResiduals(simulationOutput1, sel = testData$Environment1<0.5)
# or combine group and sel
simulationOutput9 = recalculateResiduals(simulationOutput1, group = ~group, sel = ~Environment1<0.5)
# or as subset of rows
# (note: order of rows is based on residuals, not on original dataframe)
# so be careful with NAs!
simulationOutput10 = recalculateResiduals(simulationOutput1, sel = 1:20)