Class-balanced model evaluation
Evaluating a binary or multiclass classifier with cross-validation.
Scikit-Learn · Class
StratifiedKFold
StratifiedKFold generates classification cross-validation folds that preserve class proportions. It returns train/test indices and can optionally shuffle class samples reproducibly.
How it works
StratifiedKFold creates K-fold train/test splits while preserving approximately the class proportions in the target for binary or multiclass classification. It can optionally shuffle samples within each class before assigning them to folds, with random_state controlling that order.
Syntax
class sklearn.model_selection.StratifiedKFold(n_splits=5, *, shuffle=False, random_state=None)Parameters
| Name | Type | Description |
|---|---|---|
n_splits | int | Number of folds; must be at least 2. Default: 5. |
shuffle | bool | Whether to shuffle each class's samples before splitting into batches. Default: False. |
random_state | int, RandomState instance, or None | Controls index ordering when shuffle=True; accepts an int, RandomState instance, or None. Default: None. |
Returns
An iterator yielding train/test index arrays for each fold.
Key points
- Use this class for binary or multiclass classification when folds should reflect the target's class proportions.
- Call split(X, y) to iterate over pairs of training and testing index arrays.
- It follows the K-fold cross-validation structure while adding label-aware stratification.
- The class distribution is preserved approximately across the generated folds.
- Set n_splits to an integer of 2 or greater; the default is 5.
- Set shuffle=True when randomized class-wise assignment is desired.
Common mistakes
- random_state has an effect only when shuffle is enabled; otherwise leave it as None.
- Class counts should be sufficiently large for the requested number of folds; otherwise some folds can have very few or no samples from a class.
Example: Stratified cross-validation splits
from sklearn.model_selection import StratifiedKFold
from sklearn.datasets import load_iris
X, y = load_iris(return_X_y=True)
skf = StratifiedKFold(n_splits=5, shuffle=True, random_state=42)
for train_idx, test_idx in skf.split(X, y):
X_train, X_test = X[train_idx], X[test_idx]
y_train, y_test = y[train_idx], y[test_idx]
print(len(X_train), len(X_test), y_test.tolist())Creates five reproducible stratified splits and obtains train/test indices for each fold.
When to use it
Consistent class distributions
Working with imbalanced labels where ordinary folds could have different class mixes.
Reproducible shuffled splits
Testing models with randomized but repeatable fold assignments.
Interview questions
QWhat problem does StratifiedKFold solve?
StratifiedKFold is a K-fold cross-validator for classification that preserves the percentage of samples from each class in every fold. It provides train and test indices rather than fitting an estimator itself.
Follow-up: How does it differ from KFold? KFold does not use class labels, so StratifiedKFold is preferable when class proportions must remain comparable across folds.
QWhat does n_splits control?
n_splits determines how many folds are created and must be at least 2. Each iteration uses one fold for testing and the remaining folds for training.
Follow-up: What constraint should be checked? The target must contain enough examples of each class for the requested split count.
QHow do shuffle and random_state interact?
shuffle controls whether each class's samples are shuffled before being divided into batches. When shuffle is True, random_state controls the ordering of indices and makes the resulting assignment reproducible when fixed.
Follow-up: What happens when shuffle is False? random_state should remain None because it does not affect the split.
Related
KFoldStratifiedGroupKFoldcross_val_score