residDiagnostics: Diagnostics of residuals of the linear mixed model

View source: R/residDiagnostics.R

residDiagnosticsR Documentation

Diagnostics of residuals of the linear mixed model

Description

residDiagnostics provides several plots as well as statistical test for the examination of the normality and homoscedasticity of the residuals of the input model.

Usage

residDiagnostics(model, pvalue = 0.05, verbose = TRUE)

Arguments

model

An object of class "lme" representing the linear mixed-effects model fitted by lmmModel().

pvalue

Threshold for the p-value of outlier observations based on their normalized residuals.

verbose

Logical indicating if the normality and homoscedasticity tests results, and the list of potential outlier observations should be printed to the console.

Details

One of the assumption of the model fit by lmmModel() is that the residuals are normally distributed. For the evaluation of this assumption, residDiagnostics provides Q-Q plots of the normalized residuals (standardized residuals pre-multiplied by the inverse square-root factor of the estimated error correlation matrix, see nlme::residuals.lme), together with statistical assessment of their normality using Shapiro-Wilk, D'Agostini and Anderson-Darling normality tests. Additionally, Q-Q plots of the normalized residuals by time point and treatment group are provided to be able to detect time points or treatment groups which could be notably different from the others and be affecting the adequacy of the model.

Scatter plots of the normalized residuals versus fitted values and normalized residuals per time and per treatment are also provided to give information about variability of the residuals and possible outlier observations. These plots are accompanied by Levene and Fligner-Killend homogeneity of variance test results.

Observations with absolute standardized (normalized) residuals greater than the 1-0.05/2 quantile of the standard normal distribution are identified and reported as potential outlier observations.

Value

A list with different elements for the diagnostics of the residuals are produced:

  • plots: Different plots for evaluating the normality and homocedasticity of the residuals.

  • outliers: Data frame with the identified outliers based on the Pearson residuals and the value of pval. The column resid.p contains the value of the Pearson residuals for each observation.

  • Normality: List with the results from 3 different test of the normality of the normalized residuals of the model: Shapiro - Wilk normality test, D'Agostino normality test and Anderson - Darling normality test.

  • Levene.test: List with the Levene homoscedasticity test results of the normalized residuals by Time and Treatment.

  • Fligner.test: List with the Fligner-Killeen homoscedasticity test results of the normalized residuals by Time and Treatment.

References

  • Pinheiro JC, Bates DM (2000). Mixed-Effects Models in S and S-PLUS. Springer, New York. \Sexpr[results=rd]{tools:::Rd_expr_doi("doi:10.1007/b98882")}.

  • Andrzej Galecki & Tomasz Burzykowski (2013) Linear Mixed-Effects Models Using R: A Step-by-Step Approach First Edition. Springer, New York. ISBN 978-1-4614-3899-1

Examples

# Load the example data
data(grwth_data)
# Fit the model
lmm <- lmmModel(
  data = grwth_data,
  sample_id = "subject",
  time = "Time",
  treatment = "Treatment",
  tumor_vol = "TumorVolume",
  trt_control = "Control",
  drug_a = "DrugA",
  drug_b = "DrugB",
  combination = "Combination"
  )
  
# Residuals diagnostics
resid_diag <- residDiagnostics(model = lmm, pvalue = 0.05)

# Access outliers data frame
resid_diag$Outliers

# Access individual plots
resid_diag$Plots[1]
resid_diag$Plots[2]

# Access results of normality tests
resid_diag$Normality
resid_diag$Normality$Shapiro.test

# Access to homoscedasticity test results

resid_diag$Levene.test

resid_diag$Fligner.test


SynergyLMM documentation built on April 4, 2025, 4:13 a.m.