Estimate generalization performance across folds
Model evaluation
Scikit-Learn · Function
cross_validate
Evaluate one or more metrics across cross-validation folds while recording fit and score times. Optional outputs include training scores, fitted estimators, and the indices used for each split.
How it works
The function repeatedly fits cloned copies of an estimator on training folds and evaluates them on held-out folds. It can use one or several scorers, select the splitting strategy, run folds in parallel, and optionally include training scores, fitted estimators, and train/test indices in its result dictionary.
Syntax
cross_validate(estimator, X, y=None, *, groups=None, scoring=None, cv=None, n_jobs=None, verbose=0, params=None, pre_dispatch='2*n_jobs', return_train_score=False, return_estimator=False, return_indices=False, error_score=nan)Parameters
| Name | Type | Description |
|---|---|---|
estimator | estimator object | Estimator implementing fit; the object fitted on each training split. |
X | array-like or sparse matrix | Input samples with shape (n_samples, n_features). |
y | array-like or None | Target values for supervised learning; defaults to None. |
groups | array-like or None | Group labels passed to the splitter when grouping is used. |
scoring | str, callable, list, tuple, or dict | Scorer, collection of scorers, or callable used for evaluation. |
cv | int, splitter, iterable, or None | Cross-validation strategy; None defaults to five folds. |
n_jobs | int or None | Number of parallel jobs; None means one job unless a backend changes it. |
verbose | int | Verbosity level. |
params | dict or None | Metadata routed to estimator and splitter methods. |
pre_dispatch | int or str | Number of jobs dispatched in advance; default is 2*n_jobs. |
return_train_score | bool | Whether to include training scores. |
return_estimator | bool | Whether to include fitted estimators. |
Returns
A dictionary of arrays containing test scores, optional train scores, fit and score times, and optionally fitted estimators and train/test indices.
Key points
- cross_validate combines fold-based metric evaluation with measurements of fitting and scoring duration.
- The estimator must be an object implementing fit and is independently trained for each fold.
- The cv argument accepts a default, fold count, splitter, or iterable of train/test index arrays.
- The output is a dictionary whose arrays contain per-fold scores and timing information.
Common mistakes
- With the default integer or None splitter, binary and multiclass classifiers use stratified folds rather than ordinary K-fold splits.
- Choose error_score carefully: failures can either raise immediately or produce a numeric score with a warning.
Example: Evaluate classification metrics with cross-validation
from sklearn.datasets import load_iris
from sklearn.model_selection import cross_validate
from sklearn.linear_model import LogisticRegression
X, y = load_iris(return_X_y=True)
result = cross_validate(
LogisticRegression(max_iter=1000),
X,
y,
cv=5,
scoring=["accuracy", "f1_macro"],
return_train_score=True,
)
print(result["test_accuracy"])
print(result["fit_time"])
Runs five-fold validation with two metrics and returns per-fold test scores, training scores, and fitting times.
When to use it
Collect several evaluation metrics in one run
Metric comparison
Measure fitting and scoring time
Performance profiling
Retain fold-specific estimators and split indices
Model inspection
Interview questions
QWhat does cross_validate return?
It evaluates one or more metrics across cross-validation folds and records fit and score times. The returned dictionary contains arrays with one entry per fold, using keys such as test_score, fit_time, and score_time.
Follow-up: How would you compare training and validation behavior? Set return_train_score=True, then compare the train_* arrays with the corresponding test_* arrays.
QHow is the cross-validation scheme selected?
cv controls the splitting strategy. None uses five folds by default; an integer sets the number of folds, while a splitter or iterable can provide custom train/test index splits.
Follow-up: How can fold-specific fitted models be inspected? Set return_estimator=True to include the fitted estimator from each fold.
QHow can multiple evaluation metrics be collected?
scoring can be a single scorer, a list or tuple of scorer names, a dictionary of names to scorers, or a callable. With multiple metrics, result keys are named using each scorer, such as test_accuracy.
Follow-up: How can computation be parallelized? Set n_jobs to the number of parallel jobs, and use pre_dispatch to limit jobs dispatched ahead of execution.
Related
cross_val_scorecross_val_predictKFoldStratifiedKFoldGroupKFoldcheck_cv