Skip to content

README.md

Latest commit

 

History

History
207 lines (163 loc) · 9.36 KB

README.md

File metadata and controls

207 lines (163 loc) · 9.36 KB
Raw

statgpu

PyPI version Python versions License GitHub stars Downloads

GPU-accelerated statistical methods with an sklearn-style API.

Core Features

  • 🚀 Three backends: NumPy (CPU), CuPy (CUDA), and PyTorch (CUDA), with automatic device selection
  • 🧭 Explicit backend semantics: core numerical arrays remain on the selected backend where supported; explicit device requests do not silently switch backend, and model-specific metadata, control-flow, and scalar boundaries are documented per method
  • 🔧 sklearn-style estimators: familiar fit/predict/score methods and parameter conventions
  • 📊 GLM + robust + quantile + Cox: Gaussian and non-Gaussian regression, robust losses, quantile regression, and survival analysis
  • 🔥 Penalty framework: L1, L2, Elastic Net, SCAD, MCP, adaptive, and grouped penalties
  • ⚡ Solver framework: exact, IRLS, Newton, L-BFGS, FISTA-family, proximal IRLS, proximal Newton, and ADMM implementations where supported
  • 🧮 Inference: covariance, standard errors, hypothesis tests, confidence intervals, penalized sandwich/oracle inference where supported, debiased Lasso, bootstrap, and simultaneous inference
  • 📈 Nonparametric: KDE, kernel regression, kernel approximation, B-splines, and GAM
  • 🧬 Unsupervised: PCA, KMeans, DBSCAN, GMM, UMAP, t-SNE, NNDescent, and related methods
  • 📐 Distributions: backend-aware distribution functions through get_distribution()
  • 🧪 Multiple testing: adjust_pvalues, combine_pvalues, and permutation_test
  • 🔁 Cross-validation: PenalizedGLM_CV, RidgeCV, LassoCV, ElasticNetCV, LogisticRegressionCV, and CoxPHCV

Implemented Methods

Full method list with solvers, penalties, and link functions →

Category Highlights
Regression & GLM LinearRegression, Ridge, Lasso, ElasticNet, Logistic, Poisson, Gamma, Inverse Gaussian, Negative Binomial, Tweedie, QuantileRegression, and ordered models
Penalized models Unified penalized GLM, typed family wrappers, penalized quantile/robust regression, and PenalizedCoxPHModel
Cross-validation RidgeCV, LassoCV, ElasticNetCV, LogisticRegressionCV, PenalizedGLM_CV, and CoxPHCV
ANOVA One-way, two-way, Welch ANOVA, post-hoc comparisons, and effect sizes
Covariance Empirical and shrinkage covariance, MinCovDet, GraphicalLasso, and GraphicalLassoCV
Panel data PanelOLS, RandomEffects, PooledOLS, BetweenOLS, FirstDifferenceOLS, and FamaMacBeth
Nonparametric KDE, kernel regression, KernelRidge/CV, KernelPCA, Nystroem, spline bases, and SplineTransformer
Semiparametric GAM with penalized B-splines and GCV
Unsupervised PCA, SVD, NMF, UMAP, t-SNE, KMeans, DBSCAN, GMM, and AgglomerativeClustering
Survival CoxPH/CoxPHCV with Breslow, Efron, or Exact ties, (start, stop] data, strata, robust covariance, and subject-grouped CV; PenalizedCoxPHModel
Feature selection Stepwise selection plus fixed-X and model-X knockoff filters and wrappers
Diagnostics RegressionDiagnostics and diagnose_model
Multiple testing adjust_pvalues, combine_pvalues, and permutation_test

Documentation

Installation

# CPU only
pip install statgpu

# CuPy backend — choose the CUDA major version that matches your environment
pip install "statgpu[gpu11]"
pip install "statgpu[gpu12]"

# PyTorch backend
pip install "statgpu[torch]"

# Formula/dataframe interfaces
pip install "statgpu[formula]"

# Optional statsmodels dependency for external Cox validation
pip install "statgpu[survival]"

# Development environment
pip install -e ".[dev,validation,formula]"

Choose CuPy and PyTorch builds compatible with the installed CUDA driver and runtime.

Quick Start

The default example runs after the base pip install statgpu installation. Use an explicit GPU device only after installing the corresponding CuPy or PyTorch extra.

import numpy as np
from statgpu import adjust_pvalues, combine_pvalues
from statgpu.inference import norm, poisson
from statgpu.linear_model import LinearRegression, PenalizedGLM_CV

# Generate data using statgpu distributions
X = norm.rvs(size=(10000, 100))
y = X @ norm.rvs(size=100) + norm.rvs(size=10000) * 0.5

# Portable linear regression: selects an available backend
model = LinearRegression(device="auto")
model.fit(X, y)
print(f"R²: {model.score(X, y):.4f}")

# Penalized GLM with cross-validation
y_pois = poisson.rvs(
    mu=np.exp(X[:, :5] @ np.ones(5) * 0.1),
    size=X.shape[0],
)
cv_model = PenalizedGLM_CV(
    loss="poisson",
    penalty="elasticnet",
    l1_ratio=0.5,
    cv=5,
    device="cpu",
)
cv_model.fit(X[:, :5], y_pois)
print(f"Best alpha: {cv_model.alpha_:.4f}")

# Multiple-testing correction
reject, pvals_adj = adjust_pvalues(
    np.array([0.003, 0.02, 0.5]),
    method="bh",
)

# Global p-value combination
stat, p_global = combine_pvalues(
    np.array([0.01, 0.07, 0.03, 0.40]),
    method="fisher",
)

Device Control

import statgpu as sg

# Global setting
sg.set_device("cuda")
sg.set_device("cpu")
sg.set_device("auto")

# Per-model setting; requires the matching GPU extra and runtime
from statgpu.linear_model import LinearRegression
model = LinearRegression(device="cuda", n_jobs=4)

Benchmark Results (RTX 4090)

Full reports: results/unsupervised_bench_2026-06-27.md, results/glm_solver_benchmark_2026-06-23.md

Test environment: RTX 4090 (24GB), CuPy 14.1.0, PyTorch 2.8.0+cu128, scikit-learn 1.8.0, statsmodels 0.14.6, lifelines 0.30.3. These are environment-specific benchmark results, not installation requirements or universal speed guarantees.

Selected Benchmark Results

Module Dataset n p Best Speedup Precision
Poisson GLM freMTPL2 678K 42 196.9x vs sklearn coef_corr=1.000000
Gamma GLM synthetic 678K 42 97.9x vs sklearn coef_corr=0.9995
CoxPH synthetic 1.9K 500 1.2x vs CPU coef_corr=1.000
adjust_pvalues (BH) synthetic — 1M 0.55x 100% agreement
PenalizedPoisson (L1) freMTPL2 678K 42 — OK
PenalizedCoxPH (L2) synthetic 1.9K 500 — C-index match

Precision Summary

Module Metric Result
Poisson GLM coefficient correlation vs sklearn 1.000000
Gamma GLM coefficient correlation vs sklearn 0.9995
CoxPH coefficient correlation vs lifelines 1.000
adjust_pvalues (BH) rejection agreement vs statsmodels 100%
Penalized models self-consistency validated across supported penalties

Contributing

Contributions are welcome, including bug fixes, documentation, tests, statistical validation, GPU performance work, and new methods.

  1. Read the Contributor Guide before making a substantial change.
  2. Open an issue first for new estimators, public API changes, inference methods, solvers, penalties, or large refactors.
  3. Install development and validation dependencies with python -m pip install -e ".[dev,validation,formula]".
  4. Add focused tests and run the relevant CPU and physical-GPU checks.
  5. Update English and Chinese documentation and changelogs for user-visible behavior changes.

Maintainers preparing a package release should follow the PyPI Release Guide.

Requirements

  • Python >= 3.9
  • NumPy >= 1.20
  • CuPy optional, using the wheel matching the CUDA major version
  • PyTorch optional, using a CUDA-compatible build for GPU execution
  • CUDA runtime compatible with the selected CuPy or PyTorch build

License

Apache License 2.0 — see LICENSE.