scikit-learn and statsmodels boundaries
Choose the library from the question, not from API familiarity. scikit-learn owns
out-of-sample prediction workflows; statsmodels owns model-based estimation and
inference when its assumptions match the design. Using both does not make a result
automatically predictive or inferential.
Decide the objective
| Need |
Primary path |
| estimate a defined parameter with standard errors or tests |
statsmodels |
| predict new observations and compare pipelines out of sample |
scikit-learn |
| exploratory prediction followed by confirmatory inference |
separate discovery and inference datasets or label the second stage exploratory |
| deploy a predictor but inspect coefficients |
scikit-learn pipeline; coefficients are not automatically causal or valid inferential estimates |
Read estimands.md,
design-matrices.md, and
validation.md.
Workflow
- Define observation unit, target/estimand, prediction time, available features,
dependence structure, and intended population.
- Split by the real deployment boundary before learning preprocessing. Use group or
time-aware splits when rows are not exchangeable.
- For scikit-learn, put every learned transformation inside a
Pipeline or
ColumnTransformer. Tune only within the training resampling procedure.
- For statsmodels, construct the design deliberately: intercept, reference levels,
interactions, weights, missing-data policy, and covariance estimator are modeling
choices.
- Never reuse a fitted sklearn transformer on a statsmodels model without freezing
and recording its column order and meaning. Formula encoders and sklearn encoders
are not interchangeable contracts.
- Validate the artifact according to its purpose: held-out performance and
calibration for prediction; assumptions, estimand, uncertainty, and sensitivity for
inference.
- Keep outputs separate: predictions with evaluation provenance; estimates with model
specification, covariance choice, interval, and population scope.
Boundary rules
- Do not preprocess the full dataset before splitting. This leaks information even
when the transformation does not use the label.
- Do not select features on all data and then report ordinary statsmodels p-values as
confirmatory inference.
- Do not compare in-sample fit statistics with cross-validated predictive scores as if
they measured the same quantity.
- If repeated observations or clusters exist, use grouped validation and an inferential
covariance/model that represents that dependence.
- If categorical levels can appear at prediction time, define unknown-category
behavior and verify identical feature ordering.
Completion checks
- The split matches deployment or sampling structure and no learned operation sees the
test fold.
- Feature names/order are inspectable after preprocessing.
- Prediction metrics include a baseline and uncertainty or repeated-resampling context.
- Inferential claims identify estimand, assumptions, covariance choice, effect size,
and interval—not just p-values.
- A handoff between libraries has a tested shape/schema contract and preserves row IDs.
1---2name: scikit-learn-statsmodels-boundaries3description: >-4 Use when choosing between or composing scikit-learn predictive workflows and5 statsmodels inferential models: estimand versus prediction target, preprocessing,6 leakage, design matrices, validation, uncertainty, and result handoff. Do not use7 for work entirely inside one library.8---910# scikit-learn and statsmodels boundaries1112Choose the library from the question, not from API familiarity. scikit-learn owns13out-of-sample prediction workflows; statsmodels owns model-based estimation and14inference when its assumptions match the design. Using both does not make a result15automatically predictive or inferential.1617## Decide the objective1819| Need | Primary path |20|---|---|21| estimate a defined parameter with standard errors or tests | statsmodels |22| predict new observations and compare pipelines out of sample | scikit-learn |23| exploratory prediction followed by confirmatory inference | separate discovery and inference datasets or label the second stage exploratory |24| deploy a predictor but inspect coefficients | scikit-learn pipeline; coefficients are not automatically causal or valid inferential estimates |2526Read [estimands.md](references/estimands.md),27[design-matrices.md](references/design-matrices.md), and28[validation.md](references/validation.md).2930## Workflow31321. Define observation unit, target/estimand, prediction time, available features,33 dependence structure, and intended population.342. Split by the real deployment boundary before learning preprocessing. Use group or35 time-aware splits when rows are not exchangeable.363. For scikit-learn, put every learned transformation inside a `Pipeline` or37 `ColumnTransformer`. Tune only within the training resampling procedure.384. For statsmodels, construct the design deliberately: intercept, reference levels,39 interactions, weights, missing-data policy, and covariance estimator are modeling40 choices.415. Never reuse a fitted sklearn transformer on a statsmodels model without freezing42 and recording its column order and meaning. Formula encoders and sklearn encoders43 are not interchangeable contracts.446. Validate the artifact according to its purpose: held-out performance and45 calibration for prediction; assumptions, estimand, uncertainty, and sensitivity for46 inference.477. Keep outputs separate: predictions with evaluation provenance; estimates with model48 specification, covariance choice, interval, and population scope.4950## Boundary rules5152- Do not preprocess the full dataset before splitting. This leaks information even53 when the transformation does not use the label.54- Do not select features on all data and then report ordinary statsmodels p-values as55 confirmatory inference.56- Do not compare in-sample fit statistics with cross-validated predictive scores as if57 they measured the same quantity.58- If repeated observations or clusters exist, use grouped validation and an inferential59 covariance/model that represents that dependence.60- If categorical levels can appear at prediction time, define unknown-category61 behavior and verify identical feature ordering.6263## Completion checks6465- The split matches deployment or sampling structure and no learned operation sees the66 test fold.67- Feature names/order are inspectable after preprocessing.68- Prediction metrics include a baseline and uncertainty or repeated-resampling context.69- Inferential claims identify estimand, assumptions, covariance choice, effect size,70 and interval—not just p-values.71- A handoff between libraries has a tested shape/schema contract and preserves row IDs.
schattenspiegel