@jnothman Sure. I will replace the example with a Note defining the appropriate usage. Thanks!

Also, I think the case of blended estimators is worth mentioning.

Pushed a new commit. Please take a look @jnothman.

@jnothman Please let me know if this looks good. I have quoted the note in the comment. If everything looks good will make a push.

The result of :func:cross_val_predict may be slightly 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 of over cross-validation
folds where as :func:cross_val_predict just returns the labels without taking
average of cross-validation folds. Thus, the function :func:cross_val_predict
is not an appropriate measure of generalisation error.

The :func:cross_val_predict is appropriate for visualisation of training set predictions
with y_train values to study the model on train set. Additionally, it can be used
in model blending techniques to get ensembled predictions.

where as :func:cross_val_predict just returns the labels without taking
average of cross-validation folds.

Well it returns the labels (or probabilities, etc) from several distinct models undistinguished.

Maybe "Additionally, it can be used when predictions of one supervised estimator are used to train another estimator in ensemble methods" would be clearer.

Thanks @jnothman for the corrections. How does this revised note look?

The result of :func:cross_val_predict may be slightly 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 of over cross-validation
folds where as :func:cross_val_predict just returns the labels (or probabilities, etc) from several distinct models undistinguished without taking average of cross-validation folds. Thus, the function :func:cross_val_predict is not an appropriate measure of generalisation error.

The :func:cross_val_predict is appropriate for visualisation of training set predictions with y_train values to study the model on train set. Additionally, it can be used when predictions of one supervised estimator are used to train another estimator in ensemble methods.

Thanks for the reveiw @jnothman. I have made it shorter. How does this look?

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 of over cross-validation folds where as :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 :func:cross_val_predict is appropriate for;

1. Visualization of training set predictions to study the model on train set.
2. Model blending: When predictions of one supervised estimator are used to train another estimator in ensemble methods.

Pushed a new commit @jnothman. Please take a look!

@lesteve Made changes as suggested. Please take a look

See rendering at http://scikit-learn.org/circle/?14255/_changed.html

@jnothman Ping. Is this PR good to go?

Thanks @shaz13 :)