Skip to main content
v2026.11,986 entries · CC-BY 4.0

K fold sklearn: KFold Syntax and Fold Checks

Run KFold on 150 iris measurements, check row coverage and unequal fold sizes, and evaluate a regression pipeline on recorded partitions.

Written and maintained by CASRAI Editorial Board

Published · Last updated

On this page

For k fold sklearn workflows, use sklearn.model_selection.KFold to generate training and validation row indices, then pass those partitions to a scoring function. This walkthrough audits seven folds on 150 flower measurements, checks for overlapping rows, and evaluates a regression pipeline on the exact partitions inspected.

What it is used for in research

KFold separates the partitioning decision from model fitting. Its split() method yields pairs of integer arrays: one identifies training rows, the other identifies held-out rows. Calling it does not fit a model or calculate a score. Each fold supplies the validation data once while the other folds supply training data.

That separation is useful when an analysis needs inspectable partitions rather than an implicit split hidden inside another function. A collaborator can inspect the same held-out positions used in evaluation. For the statistical purpose of resampling and reporting, see cross-validation in statistics; the task here is implementing the specific Python class.

The example below deliberately uses seven folds so the row count does not divide evenly. It combines three checks: inspect partition sizes, verify row coverage, and connect those partitions to actual model scores. Passing the structural checks confirms the index arrangement; it does not establish that observations are independent or that a model will generalize to a different study population.

Install or access

KFold is included in scikit-learn. The installation name is scikit-learn, while the Python import namespace is sklearn. The official Linux instructions create a virtual environment, activate it, and install the package:

python3 -m venv sklearn-env
source sklearn-env/bin/activate
pip3 install -U scikit-learn
python3 -c "import sklearn; sklearn.show_versions()"

The documentation also gives a conda route: conda create -n sklearn-env -c conda-forge scikit-learn, followed by conda activate sklearn-env.

Run the diagnostic command in the interpreter that will execute the analysis. The worked example here ran with scikit-learn 1.9.1 and NumPy 2.5.5. Preserve the environment information with the analysis so a later rerun can distinguish software changes from changes to the data or split configuration.

KFold syntax and arguments

from sklearn.model_selection import KFold

cv = KFold(n_splits=7, shuffle=True, random_state=42)

The documented constructor is KFold(n_splits=5, *, shuffle=False, random_state=None). Its three arguments control the partitioning:

  • n_splits: the number of folds, at least two. The default is five.
  • shuffle: whether to shuffle observations before assigning folds. The default preserves consecutive blocks.
  • random_state: the randomization control when shuffling. An integer makes repeated split calls reproducible for the same input ordering.

cv.get_n_splits() returns the configured fold count. The optional groups argument accepted by KFold.split() is ignored: passing subject identifiers does not create grouped validation. The distinction matters when several rows belong to one experimental unit.

Step-by-step task

This illustrative reanalysis uses the observed iris flower measurements bundled with scikit-learn. It predicts sepal length from sepal width, petal length, and petal width. That is an explicitly chosen regression exercise, rather than the dataset’s usual species-classification task. It demonstrates the software workflow; the results are not a new botanical study.

  1. Load the measurements and define the target. The loader provides 150 rows and four measurement columns. Inspecting feature_names makes the column selection explicit.
import numpy as np
from sklearn.datasets import load_iris

iris = load_iris()
print(iris.feature_names)
X = iris.data[:, 1:]
y = iris.data[:, 0]
print(X.shape, y.shape)

The shapes are (150, 3) and (150,). The first measurement, sepal length in centimeters, becomes the target. It is excluded from the predictor matrix. Using the species labels in iris.target would define a different modelling problem. For other loader interfaces, see scikit-learn datasets and their return containers.

  1. Construct and materialize the partitions. A list records exactly which index arrays the evaluation will receive.
from sklearn.model_selection import KFold

cv = KFold(n_splits=7, shuffle=True, random_state=42)
splits = list(cv.split(X))
for fold, (train, test) in enumerate(splits, 1):
    print(fold, len(train), len(test))

Folds 1–3 have 128 training rows and 22 validation rows; folds 4–7 have 129 and 21. The arithmetic follows the documented remainder rule: 150 divided by 7 leaves a remainder of 3, so three validation folds receive an extra row beyond the base size of 21.

  1. Audit overlap and coverage. Check that each fold separates training from validation and that all validation arrays together contain every position exactly once.
for train, test in splits:
    assert np.intersect1d(train, test).size == 0
    assert len(train) + len(test) == len(X)

held_out = np.concatenate([test for _, test in splits])
assert np.array_equal(np.sort(held_out), np.arange(len(X)))

The final assertion compares the sorted held-out positions with the complete sequence from zero through 149. Repeated positions, omitted positions, or a different row count would break that equality. These are reproducibility checks for this example, not a substitute for checking whether multiple rows refer to the same subject, specimen, or experiment.

  1. Keep learned preprocessing inside the model pipeline. Use a scaler followed by ridge regression, with a fixed penalty for this demonstration.
from sklearn.linear_model import Ridge
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import StandardScaler

model = make_pipeline(StandardScaler(), Ridge(alpha=1.0))

Ridge fits a least-squares regression with an L2 penalty controlled by alpha. The value 1.0 is fixed here; no optimization or claim of an optimal setting is implied. Placing the scaler inside the pipeline means its parameters are learned separately from each training partition. Fitting it on all 150 rows before validation would introduce data leakage during preprocessing.

  1. Evaluate the materialized splits. The documented cv argument accepts an iterable of training and test index pairs.
from sklearn.model_selection import cross_validate

result = cross_validate(
    model, X, y, cv=splits,
    scoring='neg_root_mean_squared_error',
    return_indices=True, error_score='raise'
)
rmse = -result['test_score']
print(round(float(rmse.mean()), 4))
print(round(float(rmse.std(ddof=1)), 4))

Using the recorded list prevents the inspection step and the scoring step from silently using different partition definitions. For a manual loop with these NumPy arrays, select rows as X[train], X[test], y[train], and y[test]. The indices are row positions, not flower species labels or database identifiers.

Output and how to read it

The run above gives a mean fold RMSE of 0.3177 cm and a sample standard deviation across fold RMSE values of 0.0489 cm. The data table below contains the original seven-fold compilation of training counts, validation counts, and RMSE, rounded to six decimals. It combines the official iris input data with the documented splitter, pipeline, estimator, and scoring interfaces.

The scoring string contains neg_ because scikit-learn’s scorer convention treats larger scores as better. Negating test_score restores positive RMSE for interpretation; smaller positive RMSE means smaller squared prediction errors. Its units here are centimeters because sepal length was the target. The RMSE formula and interpretation guide explains the metric separately.

The summary is an unweighted mean of seven fold-level RMSE values. It is not the RMSE calculated after pooling all 150 held-out prediction errors: taking a square root before averaging changes the calculation, and the validation fold sizes also differ. Report which summary was used instead of treating those procedures as interchangeable.

cross_validate also returns fit_time and score_time. With return_indices=True, inspect result['indices']['train'] and result['indices']['test'] to recover the evaluated positions. This option was added in scikit-learn 1.3. The spread reported above describes these seven values; it is not presented as a confidence interval or evidence that a specific error will hold in another sample.

For a closer diagnostic, enable return_train_score=True to collect training scores alongside validation scores. Those training results appear under train_score for a single scorer. They describe performance on the fitting rows, so keep them separate from the held-out summary. Enabling return_estimator=True also returns the fitted estimators under result['estimator'], allowing inspection of individual fold models. The API leaves both options off by default. Collect these additional outputs when they answer a specific diagnostic question, rather than substituting a training result for the validation result.

For this example, a reproducible methods description is: “We predicted iris sepal length from the other three measurements using a StandardScaler–Ridge pipeline, alpha = 1.0, and seven-fold KFold validation with shuffling and random_state = 42. Mean fold RMSE was 0.3177 cm; sample SD across folds was 0.0489 cm.” Retain the target definition and software environment alongside that description.

Troubleshooting

The script produces indices but no model score

split() only constructs partitions. Pass the splitter or recorded index pairs into cross_validate, as above. Keep the partitioning object distinct from the fitted estimator: the splitter has no prediction result to inspect.

The folds have different numbers of rows

A remainder is expected when the row count is not divisible by the fold count. In a small diagnostic example, KFold(n_splits=3) applied to ten positions holds out [0, 1, 2, 3], then [4, 5, 6], then [7, 8, 9]. The resulting sizes are four, three, and three. Shuffling changes membership while retaining this size allocation.

The seed stays fixed but a rerun changes the result

A seed controls random choices rather than identifying observations. Reordering or filtering the input changes which records occupy the same positions. Preserve a stable row-identity mapping with the split arrays. Also distinguish randomness in the splitter from randomness in an estimator; scikit-learn’s common-pitfalls guidance discusses these as separate controls.

Evaluation returns NaN or fails during fitting

The documented default error_score is NaN for fitting failures. During debugging, error_score='raise' exposes the underlying exception. Diagnose the reported fitting problem rather than interpreting NaN as a measured score. If return_indices is rejected as an unknown argument, check the installed version against its documented introduction in 1.3.

Rows from one subject appear on both sides

Ordinary KFold does not enforce group separation. Use the grouped splitter appropriate to the design and supply the group identifiers through that interface. Similarly, ordinary KFold with shuffling disabled is not a forward-in-time evaluation: training for an early held-out block can still include later observations. The official cross-validation guide distinguishes grouped and time-series strategies.

A classifier behaves differently with an integer cv argument

For binary or multiclass classifiers, cross_validate(..., cv=7) selects StratifiedKFold; otherwise it selects KFold. Both defaults omit shuffling. Passing an explicit splitter or list makes the intended strategy visible. The regression target above avoids confusing species stratification with the ordinary KFold allocation being demonstrated.

Free alternatives

The official cross-validation guide describes these alternative splitters within scikit-learn. They change the validation design rather than replacing the estimator. Select the design that matches how observations were collected.

Splitter Documented distinction
StratifiedKFold Uses class labels to approximately preserve class proportions.
GroupKFold Keeps groups separate between training and validation.
RepeatedKFold Repeats KFold using different randomized partitions.
TimeSeriesSplit Uses successive training sets followed by later test blocks.

These choices are not interchangeable fixes for an inconvenient score. Repeating a split does not solve group leakage, and class stratification does not enforce time order. Keep the evaluation question explicit before inspecting which strategy yields the most attractive number.

Sources

Data: Seven-fold iris regression audit

Original computation on the official scikit-learn iris measurements, predicting sepal length from the other three measurements. StandardScaler plus Ridge(alpha=1.0), KFold(n_splits=7, shuffle=True, random_state=42), scikit-learn 1.9.1 and NumPy 2.5.5. Validation RMSE is the negated neg_root_mean_squared_error score, rounded to six decimals. Counts and scores were generated by the Python workflow shown in the guide; they are illustrative reanalysis results, not findings from a new study.

Seven-fold iris regression audit
FoldTraining rows (rows)Validation rows (rows)Validation RMSE (cm)
1128220.332037
2128220.267878
3128220.279398
4129210.313892
5129210.34326
6129210.280022
7129210.407579

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about K fold sklearn: KFold Syntax and Fold Checks

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →