Skip to contents

Run Diagnostics on Fitted Linear or Mixed Effects Models

Source: R/run_model_diagnostics.R
run_model_diagnostics.Rd

This function runs a suite of diagnostic checks on one or more fitted models (`lm` or `lmerMod`). It supports parallel processing, customizable diagnostic selection, and optional PDF export with index and summary pages. Designed to help users assess model quality and identify potential issues such as outliers, heteroscedasticity, multicollinearity, and more.

A summary page provides layperson-friendly explanations of each diagnostic. Outlier percentages are calculated for each model and reported, but no models are removed or filtered based on these values.

Parallel processing uses `future::multisession()` and automatically resets the plan after execution to avoid side effects.

Usage

run_model_diagnostics(
  models,
  diagnostics = c("heteroscedasticity", "outliers", "collinearity", "normality",
    "autocorrelation", "random_effects"),
  parallel = FALSE,
  outlier_threshold = 10,
  save_pdf = FALSE,
  pdf_path = "model_diagnostics.pdf",
  index_labels = NULL,
  chunk_size = 100,
  readme_url = "https://github.com/drhealy013/turtle"
)

Arguments

models

A single fitted model (`lm` or `lmerMod`) or a named list of such models.

diagnostics

A character vector specifying which diagnostics to run. Options include `"heteroscedasticity"`, `"outliers"`, `"collinearity"`, `"normality"`, `"autocorrelation"`, `"random_effects"`. Defaults to all.

parallel

Logical. If `TRUE`, diagnostics are run in parallel using `furrr`. Defaults to `FALSE`.

outlier_threshold

Numeric. Percentage threshold used for reporting (not filtering). Defaults to `10`.

save_pdf

Logical. If `TRUE`, saves diagnostic plots to a PDF. Defaults to `FALSE`.

pdf_path

String. File path for saving the PDF if `save_pdf = TRUE`. Defaults to `"model_diagnostics.pdf"`.

index_labels

Optional character vector of labels for grouping models in the index page.

chunk_size

Integer. Number of models per chunk for parallel processing. Defaults to `100`.

readme_url

String. URL to the online guide or README for further explanation. Defaults to `"https://github.com/drhealy013/turtle"`.

Value

An object of class `"model_diagnostics_result"` containing:

plots

A list of diagnostic plots for each model.

all_results

A list of diagnostic results, including plots and outlier percentages.

Examples

if (FALSE) { # \dontrun{
# Multiple models
models <- list(
  lm1 = lm(mpg ~ cyl + wt, data = mtcars),
  lm2 = lm(hp ~ wt + qsec, data = mtcars)
)
run_model_diagnostics(models,
                      diagnostics = c("outliers", "normality"),
                      parallel = FALSE,
                      save_pdf = TRUE,
                      pdf_path = "diagnostics_output.pdf")

# Single model
model <- lm(mpg ~ wt + hp, data = mtcars)
run_model_diagnostics(model, diagnostics = c("normality", "outliers"))
} # }