/statsmodels

name: statsmodels
description: Statistical models library for Python. Use when you need specific model classes (OLS, GLM, mixed models, ARIMA) with detailed diagnostics, residuals, and inference. Best for econometrics, time series, rigorous inference with coefficient tables. For guided statistical test selection with APA reporting use statistical-analysis.
allowed-tools: Read Write Edit Bash
compatibility: Requires Python 3.9+ and statsmodels 0.14.6-compatible dependencies. Use `uv pip install statsmodels==0.14.6`; optional predictive-metric examples also need scikit-learn.
license: BSD-3-Clause license
metadata:
  version: "1.3"
  skill-author: K-Dense Inc.

Statsmodels: Statistical Modeling and Econometrics

Overview

Statsmodels is Python's premier library for statistical modeling, providing tools for estimation, inference, and diagnostics across a wide range of statistical methods. Apply this skill for rigorous statistical analysis, from simple linear regression to complex time series models and econometric analyses.

Current Compatibility

Examples target statsmodels 0.14.6, released Dec 5, 2025. For reproducible environments, pin the primary package:

uv pip install statsmodels==0.14.6

Use `statsmodels.api` and `statsmodels.formula.api` for stable high-level imports, and direct module imports when examples require newer or specialized classes such as `HurdleCountModel`.

When to Use This Skill

This skill should be used when:

• Fitting regression models (OLS, WLS, GLS, quantile regression)
• Performing generalized linear modeling (logistic, Poisson, Gamma, etc.)
• Analyzing discrete outcomes (binary, multinomial, count, ordinal)
• Conducting time series analysis (ARIMA, SARIMAX, VAR, forecasting)
• Running statistical tests and diagnostics
• Testing model assumptions (heteroskedasticity, autocorrelation, normality)
• Detecting outliers and influential observations
• Comparing models (AIC/BIC, likelihood ratio tests)
• Estimating causal effects
• Producing publication-ready statistical tables and inference

Quick Start, Capabilities, and Model Selection

• [references/quick_start_guide.md](references/quick_start_guide.md): minimal worked

examples for OLS, logistic regression, ARIMA, and GLM, and how to read the summary.

• [references/modeling_capabilities.md](references/modeling_capabilities.md): linear

models, GLMs, discrete choice, time series, and the statistical tests and diagnostics.

• [references/model_selection.md](references/model_selection.md): the R-style formula API

and model comparison.

• Per-topic detail: [references/linear_models.md](references/linear_models.md),

[references/glm.md](references/glm.md), [references/discrete_choice.md](references/discrete_choice.md), [references/time_series.md](references/time_series.md), and [references/stats_diagnostics.md](references/stats_diagnostics.md).

statsmodels is for *inference* — standard errors, confidence intervals, and hypothesis tests. Reach for scikit-learn when prediction is the goal and the coefficients do not need interpreting.

Best Practices

Data Preparation

1. **Always add constant**: Use `sm.add_constant()` unless excluding intercept 2. **Check for missing values**: Handle or impute before fitting 3. **Scale if needed**: Improves convergence, interpretation (but not required for tree models) 4. **Encode categoricals**: Use formula API or manual dummy coding

Model Building

1. **Start simple**: Begin with basic model, add complexity as needed 2. **Check assumptions**: Test residuals, heteroskedasticity, autocorrelation 3. **Use appropriate model**: Match model to outcome type (binary→Logit, count→Poisson) 4. **Consider alternatives**: If assumptions violated, use robust methods or different model

Inference

1. **Report effect sizes**: Not just p-values 2. **Use robust SEs**: When heteroskedasticity or clustering present 3. **Multiple comparisons**: Correct when testing many hypotheses 4. **Confidence intervals**: Always report alongside point estimates

Model Evaluation

1. **Check residuals**: Plot residuals vs fitted, Q-Q plot 2. **Influence diagnostics**: Identify and investigate influential observations 3. **Out-of-sample validation**: Test on holdout set or cross-validate 4. **Compare models**: Use AIC/BIC for non-nested, LR test for nested

Reporting

1. **Comprehensive summary**: Use `.summary()` for detailed output 2. **Document decisions**: Note transformations, excluded observations 3. **Interpret carefully**: Account for link functions (e.g., exp(β) for log link) 4. **Visualize**: Plot predictions, confidence intervals, diagnostics

Common Workflows

Workflow 1: Linear Regression Analysis

1. Explore data (plots, descriptives) 2. Fit initial OLS model 3. Check residual diagnostics 4. Test for heteroskedasticity, autocorrelation 5. Check for multicollinearity (VIF) 6. Identify influential observations 7. Refit with robust SEs if needed 8. Interpret coefficients and inference 9. Validate on holdout or via CV

Workflow 2: Binary Classification

1. Fit logistic regression (Logit) 2. Check for convergence issues 3. Interpret odds ratios 4. Calculate marginal effects 5. Evaluate classification performance (AUC, confusion matrix) 6. Check for influential observations 7. Compare with alternative models (Probit) 8. Validate predictions on test set

Workflow 3: Count Data Analysis

1. Fit Poisson regression 2. Check for overdispersion 3. If overdispersed, fit Negative Binomial 4. Check for excess zeros (consider ZIP/ZINB) 5. Interpret rate ratios 6. Assess goodness of fit 7. Compare models via AIC 8. Validate predictions

Workflow 4: Time Series Forecasting

1. Plot series, check for trend/seasonality 2. Test for stationarity (ADF, KPSS) 3. Difference if non-stationary 4. Identify p, q from ACF/PACF 5. Fit ARIMA or SARIMAX 6. Check residual diagnostics (Ljung-Box) 7. Generate forecasts with confidence intervals 8. Evalu