Prevent entity leakage
Several records come from each patient, user, device, or subject.
Scikit-Learn · Function
GroupKFold
GroupKFold performs K-fold cross-validation while keeping each group wholly within one fold. Every group is used as test data exactly once, preventing the same group from appearing in both training and test data.
How it works
GroupKFold partitions samples into folds without splitting a group across folds. Each distinct group serves as test data once; with shuffling enabled, the resulting test folds aim for approximately equal sample counts.
Syntax
class sklearn.model_selection.GroupKFold(n_splits=5, *, shuffle=False, random_state=None)Parameters
| Name | Type | Description |
|---|---|---|
n_splits | int, default=5 | Number of folds. Must be at least 2. |
shuffle | bool, default=False | Whether to shuffle groups before assigning them to folds. Samples within each split are not shuffled. |
random_state | int, RandomState instance or None, default=None | Controls randomized group ordering when shuffle=True; otherwise it has no effect. |
Returns
A cross-validation splitter whose split method yields training and test indices, with groups kept non-overlapping.
Key points
- Use it when samples belonging to the same entity, subject, session, or other group must stay together.
- Across the complete cross-validation run, each group is held out as test data one time.
- With shuffling enabled, test folds target approximate balance by sample count.
- The n_splits value cannot be less than two.
- shuffle controls group assignment order rather than within-fold sample ordering.
Common mistakes
- Choose n_splits no greater than the number of distinct group labels.
- shuffle=True changes group ordering, but does not randomize sample order inside a split.
- random_state only affects splitting when shuffle=True.
Example: Group-aware cross-validation
import numpy as np
from sklearn.model_selection import GroupKFold
X = np.array([[1], [2], [3], [4], [5], [6]])
y = np.array([0, 1, 0, 1, 0, 1])
groups = np.array([10, 10, 20, 20, 30, 30])
cv = GroupKFold(n_splits=3)
for fold, (train, test) in enumerate(cv.split(X, y, groups), 1):
print(f"fold {fold}: train={train}, test={test}")Creates three cross-validation splits while keeping every group entirely in either the training or test portion.
When to use it
Evaluate on unseen groups
Samples are correlated because they belong to the same recording, experiment, or session.
Group-based model assessment
The validation design requires each group to be held out once.
Interview questions
QWhat problem does GroupKFold solve?
GroupKFold is a K-fold iterator that keeps groups non-overlapping between folds. Every group appears exactly once in a test fold, so related samples cannot leak between training and testing.
Follow-up: How would you preserve class proportions as well? Use StratifiedGroupKFold, which combines group isolation with an attempt to preserve class distributions.
QWhat constraints apply to n_splits?
n_splits specifies the number of folds and must be at least 2. The data must also contain at least that many distinct groups.
Follow-up: What happens if there are too few groups? The splitter cannot form the requested folds and the configuration is invalid.
QHow do shuffle and random_state interact?
By default, groups are not shuffled. Setting shuffle=True changes the ordering used to assign groups to folds, and random_state controls that randomness.
Follow-up: Are individual samples shuffled within each resulting split? No; the documentation explicitly says sample order within each split is unchanged.
Related
KFoldStratifiedGroupKFoldGroupShuffleSplitLeaveOneGroupOut