DOC Add example of using CV iterator to split train test
@@ -743,6 +743,35 @@ e.g. when searching for hyperparameters.
For example, when using a validation set, set the ``test_fold`` to 0 for all
samples that are part of the validation set, and to -1 for all other samples.
+Using cross-validation iterators to split train and test
+--------------------------------------------------------
+
+The above group cross-validation functions may also be useful for spitting a
+dataset into training and testing subsets. Note that the convenience
+function :func:`train_test_split` is a wrapper around :func:`ShuffleSplit`
+and thus only allows for stratified splitting (using the class labels)
+and cannot account for groups.
+
+To perform the train and test split, use the indices for the train and test
+subsets yielded by the generator output by the `split()` method of the
+cross-validation splitter. For example::
+
+ >>> import numpy as np
+ >>> from sklearn.model_selection import GroupShuffleSplit
+
+ >>> X = np.array([0.1, 0.2, 2.2, 2.4, 2.3, 4.55, 5.8, 0.001])
+ >>> y = np.array(["a", "b", "b", "b", "c", "c", "c", "a"])
+ >>> groups = np.array([1, 1, 2, 2, 3, 3, 4, 4])
+ >>> train_indx, test_indx = next(
+ ... GroupShuffleSplit(random_state=7).split(X, y, groups)
+ ... )
+ >>> X_train, X_test, y_train, y_test = \
+ ... X[train_indx], X[test_indx], y[train_indx], y[test_indx]
+ >>> X_train.shape, X_test.shape
+ ((6,), (2,))
+ >>> np.unique(groups[train_indx]), np.unique(groups[test_indx])
+ (array([1, 2, 4]), array([3]))
+
.. _timeseries_cv:
Cross validation of time series data
