regression_diagnostics/

lib.rs

//! # regression-diagnostics
//!
//! Statistical diagnostics for **ordinary least squares** regression models in
//! Rust — the surface R's `car`/`lmtest` and Python's `statsmodels` expose, in a
//! dependency-light crate. It fills the specific ecosystem gap that no maintained
//! Rust crate offers Variance Inflation Factor, adjusted R², or residual
//! diagnostics (autocorrelation, heteroskedasticity, normality, influence).
//!
//! Everything operates on a single fitted-model type, [`OlsFit`], computed once
//! and reused by every diagnostic.
//!
//! ## Scope
//!
//! The core is **OLS diagnostics**, whose closed-form structure (a well-defined
//! hat matrix and Gaussian residuals) is what makes them well-defined. Two
//! further model families each get their own module, because their diagnostics
//! are genuinely different — not reskinned OLS formulas:
//!
//! * [`regularized`] — ridge, lasso, **elastic net**, and **penalized
//!   logistic**, where the hat matrix changes (`H_λ = X(XᵀX + λI)⁻¹Xᵀ`) or does
//!   not exist in closed form; diagnostics are built on **effective degrees of
//!   freedom** and the **active set**.
//! * [`logistic`] — binary logistic regression, a non-Gaussian likelihood with
//!   deviance/Pearson residuals, pseudo-R², and the Hosmer–Lemeshow test.
//! * [`glm`] — the other exponential-family GLMs (Poisson, negative binomial,
//!   Gamma) behind one IRLS solver and a [`Family`](glm::Family) trait, with the
//!   same deviance/Pearson residual, dispersion, and influence diagnostics.
//! * [`categorical`] — multinomial and ordinal (proportional-odds) logistic for
//!   multi-class responses, each reducing to binary logistic at `K = 2`.
//! * [`survival`] — Cox proportional hazards (stratified and time-varying too),
//!   parametric accelerated-failure-time models, and Kaplan–Meier for censored
//!   time-to-event data, with martingale/deviance/Schoenfeld residuals.
//! * [`mixed`] — random-intercept, random-slope, crossed and generalized
//!   (Laplace GLMM) mixed models for grouped data, with variance components, ICC,
//!   and BLUPs.
//!
//! ## Linear algebra
//!
//! Internals use `nalgebra` (pure-Rust QR/SVD, no system BLAS — chosen for
//! portability); the public API speaks `ndarray`. That boundary and its tradeoff
//! are documented in the README.
//!
//! ## Layout
//!
//! * [`OlsFit`] — the fitted model; constructed with [`OlsFit::new`] or
//!   [`OlsFit::with_intercept`]. **Read its intercept convention before use.**
//! * [`multicollinearity`] — [`vif`](multicollinearity::vif),
//!   [`condition_number`](multicollinearity::condition_number).
//! * [`fit_statistics`] — R²/adjusted R², F-statistic, AIC/BIC, log-likelihood.
//! * [`residuals`] — Durbin-Watson, Breusch-Pagan, White, Jarque-Bera, the scaled
//!   residual forms, and QQ-plot data.
//! * [`influence`] — leverage, Cook's distance, DFFITS.
//! * [`coefficients`] — standardized (beta) coefficients.
//! * [`Summary`] via [`OlsFit::summary`] — the one-call `statsmodels`-style report.
//! * [`regularized`] — [`RidgeFit`](regularized::RidgeFit),
//!   [`LassoFit`](regularized::LassoFit),
//!   [`ElasticNetFit`](regularized::ElasticNetFit) and
//!   [`PenalizedLogisticFit`](regularized::PenalizedLogisticFit) with their
//!   shrinkage-aware diagnostics.
//! * [`logistic`] — [`LogisticFit`](logistic::LogisticFit) with deviance/Pearson
//!   residuals, goodness-of-fit, Hosmer–Lemeshow, and logistic influence.
//! * [`glm`] — [`GlmFit`](glm::GlmFit) over a [`Family`](glm::Family) (Poisson,
//!   negative binomial, Gamma), with residuals, dispersion, and influence.
//! * [`categorical`] — [`MultinomialFit`](categorical::MultinomialFit) and
//!   [`OrdinalFit`](categorical::OrdinalFit) for multi-class responses.
//! * [`survival`] — [`CoxFit`](survival::CoxFit) (with stratified and
//!   time-varying / counting-process forms), the parametric
//!   [`AftFit`](survival::AftFit), and [`KaplanMeier`](survival::KaplanMeier)
//!   with survival residuals.
//! * [`mixed`] — [`LinearMixedModel`](mixed::LinearMixedModel) (closed-form
//!   random intercept), the general [`MixedModel`](mixed::MixedModel) (random
//!   slopes, crossed/nested), and [`GlmmFit`](mixed::GlmmFit) (Laplace GLMM),
//!   with variance components, ICC, and BLUPs.
//!
//! ## Quick start
//!
//! ```
//! use ndarray::array;
//! use regression_diagnostics::OlsFit;
//! use regression_diagnostics::multicollinearity::vif;
//!
//! // Caller supplies the intercept column (first column of ones).
//! let x = array![
//!     [1.0, 1.0, 2.0],
//!     [1.0, 2.0, 4.1],
//!     [1.0, 3.0, 5.9],
//!     [1.0, 4.0, 8.0],
//!     [1.0, 5.0, 10.1],
//! ];
//! let y = array![2.0, 4.1, 6.1, 8.0, 10.2];
//! let fit = OlsFit::new(x, y).unwrap();
//!
//! println!("{}", fit.summary());     // full statsmodels-style report
//! let v = vif(&fit);                 // per-predictor VIF (NaN for intercept)
//! assert!(v[1].is_finite());
//! ```

#![warn(missing_docs)]
#![forbid(unsafe_code)]

mod fit;
mod linalg;
mod optimize;
mod summary;

pub mod categorical;
pub mod coefficients;
pub mod error;
pub mod fit_statistics;
pub mod glm;
pub mod influence;
pub mod logistic;
pub mod mixed;
pub mod multicollinearity;
pub mod regularized;
pub mod residuals;
pub mod survival;

pub use error::{RegressionError, Result};
pub use fit::OlsFit;
pub use summary::{CoefficientRow, Summary};