unifres: Unified Residual Diagnostics

unifres provides a unified framework for residual diagnostics in generalized linear models (GLMs) and beyond. Available in both R and Python, the package implements the functional residual methodology described in Liu, Lin, & Zhang (2025), offering powerful diagnostic tools that work seamlessly across discrete and continuous outcomes.

Why functional residuals?

Traditional residual diagnostics struggle with discrete data:

  • Binary outcomes: Residuals can only take two values
  • Count data: Discrete nature creates artificial patterns
  • Ordinal data: Difficult to interpret traditional residuals

Functional residuals solve these problems by representing the entire distribution of residual randomness, not just a single point estimate.

Key features

🎯 Unified framework

A single approach that works for:

  • Binary outcomes (logistic regression)
  • Count outcomes (Poisson, negative binomial)
  • Ordinal outcomes (proportional odds models)
  • Zero-inflated models
  • Continuous outcomes (as a special case)

📊 Powerful diagnostics

Two main diagnostic plots:

  1. Function-Function (Fn-Fn) Plots: Assess overall model adequacy
  2. Functional Residual Density (FRED) Plots: Identify specific model failures

🔧 Three residual types

  • Functional: Full distribution objects (R functions, Python scipy distributions)
  • Surrogate: Point residuals for traditional plots
  • Probability-scale: Centered residuals for interpretation

🚀 Easy to use

# R
library(unifres)
fit <- glm(y ~ x, family = binomial)
fresiduals(fit)
ffplot(fit)
fredplot(fit, x = x)
# Python
from unifres import fresiduals, ffplot, fredplot
model = sm.GLM(y, X, family=sm.families.Binomial()).fit()
fresiduals(model)
ffplot(model)
fredplot(model, x)

Installation

# Install from GitHub
remotes::install_github("bgreenwell/unifres", subdir = "r/unifres")
# Install from GitHub with pip
pip install git+https://github.com/bgreenwell/unifres.git#subdirectory=python

# Or install with uv (faster)
uv pip install git+https://github.com/bgreenwell/unifres.git#subdirectory=python

→ Full Installation Guide

Get started

📦 Installation

Install unifres in R or Python

Install Now →

💻 Examples

Comprehensive examples for R and Python

R Examples →
Python Examples →

📖 Methodology

Understand the theory behind functional residuals

Learn More →

🔗 API Reference

Detailed function documentation

R API →
Python API →

Supported models

R package

  • ✅ glm() - Binomial, Poisson, Quasi-Poisson families
  • ✅ MASS::glm.nb() - Negative Binomial
  • ✅ mgcv::gam() - Generalized Additive Models
  • ✅ VGAM::vglm() - Vector GLMs (ordinal regression)
  • ✅ pscl::zeroinfl() - Zero-Inflated Poisson

Python package

  • ✅ statsmodels.GLM - Binomial, Poisson, Negative Binomial
  • ✅ statsmodels.NegativeBinomial - Discrete Negative Binomial
  • ✅ statsmodels.OrderedModel - Ordinal Regression

Citation

If you use unifres in your research, please cite:

Liu, D., Lin, Z., & Zhang, H. (2025). A unified framework for residual diagnostics in generalized linear models and beyond. Journal of the American Statistical Association, 1–29. https://doi.org/10.1080/01621459.2025.2504037

@article{liu2025unified,
  title={A unified framework for residual diagnostics in generalized linear models and beyond},
  author={Liu, Dungang and Lin, Zewei and Zhang, Heping},
  journal={Journal of the American Statistical Association},
  pages={1--29},
  year={2025},
  publisher={Taylor \& Francis},
  doi={10.1080/01621459.2025.2504037}
}

Features at a glance

Feature R Python
Functional Residuals ✅ ✅
Fn-Fn Plots ✅ ✅
FRED Plots ✅ ✅
Surrogate Residuals ✅ ✅
Probability-scale Residuals ✅ ✅
Binary Models ✅ ✅
Count Models ✅ ✅
Negative Binomial ✅ ✅
Ordinal Models ✅ ✅
Zero-Inflated Models ✅ ⏳
GAMs ✅ ⏳

Community

Authors

License

Both R and Python packages are licensed under GPL-3 or later.

Ready to improve your model diagnostics?

View Examples