DOC Note on inappropriate usage of cross_val_predict
@@ -245,16 +245,23 @@ prediction that was obtained for that element when it was in the test set. Only
cross-validation strategies that assign all elements to a test set exactly once
can be used (otherwise, an exception is raised).
-These prediction can then be used to evaluate the classifier::
- >>> from sklearn.model_selection import cross_val_predict
- >>> predicted = cross_val_predict(clf, iris.data, iris.target, cv=10)
- >>> metrics.accuracy_score(iris.target, predicted) # doctest: +ELLIPSIS
- 0.973...
+.. warning:: Note on inappropriate usage of cross_val_predict
+
+ The result of :func:`cross_val_predict` may be different from those
+ obtained using :func:`cross_val_score` as the elements are grouped in
+ different ways. The function :func:`cross_val_score` takes an average
+ over cross-validation folds, whereas :func:`cross_val_predict` simply
+ returns the labels (or probabilities) from several distinct models
+ undistinguished. Thus, :func:`cross_val_predict` is not an appropriate
+ measure of generalisation error.
+
+
+The function :func:`cross_val_predict` is appropriate for:
+ - Visualization of predictions obtained from different models.
+ - Model blending: When predictions of one supervised estimator are used to
+ train another estimator in ensemble methods.
-Note that the result of this computation may be slightly different from those
-obtained using :func:`cross_val_score` as the elements are grouped in different
-ways.
The available cross validation iterators are introduced in the following
section.
