[python-package] add scikit-learn-style API for early stopping

docs/Python-Intro.rst

@@ -244,6 +244,11 @@ This works with both metrics to minimize (L2, log loss, etc.) and to maximize (N
 Note that if you specify more than one evaluation metric, all of them will be used for early stopping.
 However, you can change this behavior and make LightGBM check only the first metric for early stopping by passing ``first_metric_only=True`` in ``early_stopping`` callback constructor.
 
+In the scikit-learn API of lightgbm, early stopping can also be enabled by setting the parameter ``early_stopping`` to ``True``
+or by setting the parameter ``early_stopping_round`` to an integer greater than 0.
+When early stopping is enabled and no validation set is provided, a portion of the training data will be used as validation set.
+The amount of data to use for validation is controlled by the parameter ``validation_fraction`` and defaults to 0.1.
+
 Prediction
 ----------
 

python-package/lightgbm/dask.py

@@ -1134,6 +1134,7 @@ def __init__(
         random_state: Optional[Union[int, np.random.RandomState, "np.random.Generator"]] = None,
         n_jobs: Optional[int] = None,
         importance_type: str = "split",
+        validation_fraction: Optional[float] = 0.1,
         client: Optional[Client] = None,
         **kwargs: Any,
     ):
@@ -1337,6 +1338,7 @@ def __init__(
         random_state: Optional[Union[int, np.random.RandomState, "np.random.Generator"]] = None,
         n_jobs: Optional[int] = None,
         importance_type: str = "split",
+        validation_fraction: Optional[float] = 0.1,
         client: Optional[Client] = None,
         **kwargs: Any,
     ):
@@ -1504,6 +1506,7 @@ def __init__(
         random_state: Optional[Union[int, np.random.RandomState, "np.random.Generator"]] = None,
         n_jobs: Optional[int] = None,
         importance_type: str = "split",
+        validation_fraction: Optional[float] = 0.1,
         client: Optional[Client] = None,
         **kwargs: Any,
     ):

python-package/lightgbm/engine.py

@@ -510,11 +510,9 @@ def _make_n_folds(
     nfold: int,
     params: Dict[str, Any],
     seed: int,
-    fpreproc: Optional[_LGBM_PreprocFunction],
     stratified: bool,
     shuffle: bool,
-    eval_train_metric: bool,
-) -> CVBooster:
+) -> Iterable[Tuple[np.ndarray, np.ndarray]]:
     """Make a n-fold list of Booster from random indices."""
     full_data = full_data.construct()
     num_data = full_data.num_data()
@@ -559,7 +557,16 @@ def _make_n_folds(
             test_id = [randidx[i : i + kstep] for i in range(0, num_data, kstep)]
             train_id = [np.concatenate([test_id[i] for i in range(nfold) if k != i]) for k in range(nfold)]
             folds = zip(train_id, test_id)
+    return folds
 
+
+def _make_cvbooster(
+    full_data: Dataset,
+    params: Dict[str, Any],
+    folds: Iterable[Tuple[np.ndarray, np.ndarray]],
+    fpreproc: Optional[_LGBM_PreprocFunction],
+    eval_train_metric: bool,
+) -> CVBooster:
     ret = CVBooster()
     for train_idx, test_idx in folds:
         train_set = full_data.subset(sorted(train_idx))
@@ -764,10 +771,11 @@ def cv(
         nfold=nfold,
         params=params,
         seed=seed,
-        fpreproc=fpreproc,
         stratified=stratified,
         shuffle=shuffle,
-        eval_train_metric=eval_train_metric,
+    )
+    cvbooster = _make_cvbooster(
+        full_data=train_set, params=params, folds=cvfolds, fpreproc=fpreproc, eval_train_metric=eval_train_metric
     )
 
     # setup callbacks
@@ -802,24 +810,24 @@ def cv(
         for cb in callbacks_before_iter:
             cb(
                 callback.CallbackEnv(
-                    model=cvfolds,
+                    model=cvbooster,
                     params=params,
                     iteration=i,
                     begin_iteration=0,
                     end_iteration=num_boost_round,
                     evaluation_result_list=None,
                 )
             )
-        cvfolds.update(fobj=fobj)  # type: ignore[call-arg]
-        res = _agg_cv_result(cvfolds.eval_valid(feval))  # type: ignore[call-arg]
+        cvbooster.update(fobj=fobj)  # type: ignore[call-arg]
+        res = _agg_cv_result(cvbooster.eval_valid(feval))  # type: ignore[call-arg]
         for _, key, mean, _, std in res:
             results[f"{key}-mean"].append(mean)
             results[f"{key}-stdv"].append(std)
         try:
             for cb in callbacks_after_iter:
                 cb(
                     callback.CallbackEnv(
-                        model=cvfolds,
+                        model=cvbooster,
                         params=params,
                         iteration=i,
                         begin_iteration=0,
@@ -828,14 +836,14 @@ def cv(
                     )
                 )
         except callback.EarlyStopException as earlyStopException:
-            cvfolds.best_iteration = earlyStopException.best_iteration + 1
-            for bst in cvfolds.boosters:
-                bst.best_iteration = cvfolds.best_iteration
+            cvbooster.best_iteration = earlyStopException.best_iteration + 1
+            for bst in cvbooster.boosters:
+                bst.best_iteration = cvbooster.best_iteration
             for k in results:
-                results[k] = results[k][: cvfolds.best_iteration]
+                results[k] = results[k][: cvbooster.best_iteration]
             break
 
     if return_cvbooster:
-        results["cvbooster"] = cvfolds  # type: ignore[assignment]
+        results["cvbooster"] = cvbooster  # type: ignore[assignment]
 
     return dict(results)

python-package/lightgbm/sklearn.py

@@ -46,7 +46,7 @@
     dt_DataTable,
     pd_DataFrame,
 )
-from .engine import train
+from .engine import _make_n_folds, train
 
 if TYPE_CHECKING:
     from .compat import _sklearn_Tags
@@ -509,7 +509,8 @@ def __init__(
         random_state: Optional[Union[int, np.random.RandomState, np.random.Generator]] = None,
         n_jobs: Optional[int] = None,
         importance_type: str = "split",
-        **kwargs: Any,
+        validation_fraction: Optional[float] = 0.1,
+        **kwargs,
     ):
         r"""Construct a gradient boosting model.
 
@@ -589,6 +590,10 @@ def __init__(
             The type of feature importance to be filled into ``feature_importances_``.
             If 'split', result contains numbers of times the feature is used in a model.
             If 'gain', result contains total gains of splits which use the feature.
+        validation_fraction : float or None, optional (default=0.1)
+            Proportion of training data to set aside as
+            validation data for early stopping. If None, early stopping is done on
+            the training data. Only used if early stopping is performed.
         **kwargs
             Other parameters for the model.
             Check http://lightgbm.readthedocs.io/en/latest/Parameters.html for more parameters.
@@ -653,6 +658,7 @@ def __init__(
         self.random_state = random_state
         self.n_jobs = n_jobs
         self.importance_type = importance_type
+        self.validation_fraction = validation_fraction
         self._Booster: Optional[Booster] = None
         self._evals_result: _EvalResultDict = {}
         self._best_score: _LGBM_BoosterBestScoreType = {}
@@ -812,11 +818,29 @@ def _process_params(self, stage: str) -> Dict[str, Any]:
         params.pop("importance_type", None)
         params.pop("n_estimators", None)
         params.pop("class_weight", None)
+        params.pop("validation_fraction", None)
 
         if isinstance(params["random_state"], np.random.RandomState):
             params["random_state"] = params["random_state"].randint(np.iinfo(np.int32).max)
         elif isinstance(params["random_state"], np.random.Generator):
             params["random_state"] = int(params["random_state"].integers(np.iinfo(np.int32).max))
+
+        params = _choose_param_value(
+            main_param_name="early_stopping_round",
+            params=params,
+            default_value="auto",
+        )
+        if params["early_stopping_round"] == "auto":
+            if hasattr(self, "_n_rows_train") and self._n_rows_train > 10_000:
+                params["early_stopping_round"] = 10
+            else:
+                params["early_stopping_round"] = None
+
+        if params["early_stopping_round"] is True:
+            params["early_stopping_round"] = 10
+        elif params["early_stopping_round"] is False:
+            params["early_stopping_round"] = None
+
         if self._n_classes > 2:
             for alias in _ConfigAliases.get("num_class"):
                 params.pop(alias, None)
@@ -891,27 +915,6 @@ def fit(
         init_model: Optional[Union[str, Path, Booster, "LGBMModel"]] = None,
     ) -> "LGBMModel":
         """Docstring is set after definition, using a template."""
-        params = self._process_params(stage="fit")
-
-        # Do not modify original args in fit function
-        # Refer to https://github.com/microsoft/LightGBM/pull/2619
-        eval_metric_list: List[Union[str, _LGBM_ScikitCustomEvalFunction]]
-        if eval_metric is None:
-            eval_metric_list = []
-        elif isinstance(eval_metric, list):
-            eval_metric_list = copy.deepcopy(eval_metric)
-        else:
-            eval_metric_list = [copy.deepcopy(eval_metric)]
-
-        # Separate built-in from callable evaluation metrics
-        eval_metrics_callable = [_EvalFunctionWrapper(f) for f in eval_metric_list if callable(f)]
-        eval_metrics_builtin = [m for m in eval_metric_list if isinstance(m, str)]
-
-        # concatenate metric from params (or default if not provided in params) and eval_metric
-        params["metric"] = [params["metric"]] if isinstance(params["metric"], (str, type(None))) else params["metric"]
-        params["metric"] = [e for e in eval_metrics_builtin if e not in params["metric"]] + params["metric"]
-        params["metric"] = [metric for metric in params["metric"] if metric is not None]
-
         if not isinstance(X, (pd_DataFrame, dt_DataTable)):
             _X, _y = _LGBMValidateData(
                 self,
@@ -933,6 +936,33 @@ def fit(
             # for other data types, setting n_features_in_ is handled by _LGBMValidateData() in the branch above
             self.n_features_in_ = _X.shape[1]
 
+        self._n_features = _X.shape[1]
+        # copy for consistency
+        self._n_features_in = self._n_features
+
+        self._n_rows_train = _X.shape[0]
+
+        params = self._process_params(stage="fit")
+
+        # Do not modify original args in fit function
+        # Refer to https://github.com/microsoft/LightGBM/pull/2619
+        eval_metric_list: List[Union[str, _LGBM_ScikitCustomEvalFunction]]
+        if eval_metric is None:
+            eval_metric_list = []
+        elif isinstance(eval_metric, list):
+            eval_metric_list = copy.deepcopy(eval_metric)
+        else:
+            eval_metric_list = [copy.deepcopy(eval_metric)]
+
+        # Separate built-in from callable evaluation metrics
+        eval_metrics_callable = [_EvalFunctionWrapper(f) for f in eval_metric_list if callable(f)]
+        eval_metrics_builtin = [m for m in eval_metric_list if isinstance(m, str)]
+
+        # concatenate metric from params (or default if not provided in params) and eval_metric
+        params["metric"] = [params["metric"]] if isinstance(params["metric"], (str, type(None))) else params["metric"]
+        params["metric"] = [e for e in eval_metrics_builtin if e not in params["metric"]] + params["metric"]
+        params["metric"] = [metric for metric in params["metric"] if metric is not None]
+
         if self._class_weight is None:
             self._class_weight = self.class_weight
         if self._class_weight is not None:
@@ -953,54 +983,75 @@ def fit(
             params=params,
         )
 
-        valid_sets: List[Dataset] = []
-        if eval_set is not None:
-            if isinstance(eval_set, tuple):
-                eval_set = [eval_set]
-            for i, valid_data in enumerate(eval_set):
-                # reduce cost for prediction training data
-                if valid_data[0] is X and valid_data[1] is y:
-                    valid_set = train_set
-                else:
-                    valid_weight = _extract_evaluation_meta_data(
-                        collection=eval_sample_weight,
-                        name="eval_sample_weight",
-                        i=i,
-                    )
-                    valid_class_weight = _extract_evaluation_meta_data(
-                        collection=eval_class_weight,
-                        name="eval_class_weight",
-                        i=i,
-                    )
-                    if valid_class_weight is not None:
-                        if isinstance(valid_class_weight, dict) and self._class_map is not None:
-                            valid_class_weight = {self._class_map[k]: v for k, v in valid_class_weight.items()}
-                        valid_class_sample_weight = _LGBMComputeSampleWeight(valid_class_weight, valid_data[1])
-                        if valid_weight is None or len(valid_weight) == 0:
-                            valid_weight = valid_class_sample_weight
-                        else:
-                            valid_weight = np.multiply(valid_weight, valid_class_sample_weight)
-                    valid_init_score = _extract_evaluation_meta_data(
-                        collection=eval_init_score,
-                        name="eval_init_score",
-                        i=i,
-                    )
-                    valid_group = _extract_evaluation_meta_data(
-                        collection=eval_group,
-                        name="eval_group",
-                        i=i,
-                    )
-                    valid_set = Dataset(
-                        data=valid_data[0],
-                        label=valid_data[1],
-                        weight=valid_weight,
-                        group=valid_group,
-                        init_score=valid_init_score,
-                        categorical_feature="auto",
-                        params=params,
-                    )
-
-                valid_sets.append(valid_set)
+        if params["early_stopping_round"] is not None and eval_set is None:
+            if self.validation_fraction is not None:
+                n_splits = max(int(np.ceil(1 / self.validation_fraction)), 2)
+                stratified = isinstance(self, LGBMClassifier)
+                cvfolds = _make_n_folds(
+                    full_data=train_set,
+                    folds=None,
+                    nfold=n_splits,
+                    params=params,
+                    seed=self.random_state,
+                    stratified=stratified,
+                    shuffle=True,
+                )
+                train_idx, val_idx = next(cvfolds)
+                valid_set = train_set.subset(sorted(val_idx))
+                train_set = train_set.subset(sorted(train_idx))
+            else:
+                valid_set = train_set
+            valid_set = valid_set.construct()
+            valid_sets = [valid_set]
+        else:
+            valid_sets: List[Dataset] = []
+            if eval_set is not None:
+                if isinstance(eval_set, tuple):
+                    eval_set = [eval_set]
+                for i, valid_data in enumerate(eval_set):
+                    # reduce cost for prediction training data
+                    if valid_data[0] is X and valid_data[1] is y:
+                        valid_set = train_set
+                    else:
+                        valid_weight = _extract_evaluation_meta_data(
+                            collection=eval_sample_weight,
+                            name="eval_sample_weight",
+                            i=i,
+                        )
+                        valid_class_weight = _extract_evaluation_meta_data(
+                            collection=eval_class_weight,
+                            name="eval_class_weight",
+                            i=i,
+                        )
+                        if valid_class_weight is not None:
+                            if isinstance(valid_class_weight, dict) and self._class_map is not None:
+                                valid_class_weight = {self._class_map[k]: v for k, v in valid_class_weight.items()}
+                            valid_class_sample_weight = _LGBMComputeSampleWeight(valid_class_weight, valid_data[1])
+                            if valid_weight is None or len(valid_weight) == 0:
+                                valid_weight = valid_class_sample_weight
+                            else:
+                                valid_weight = np.multiply(valid_weight, valid_class_sample_weight)
+                        valid_init_score = _extract_evaluation_meta_data(
+                            collection=eval_init_score,
+                            name="eval_init_score",
+                            i=i,
+                        )
+                        valid_group = _extract_evaluation_meta_data(
+                            collection=eval_group,
+                            name="eval_group",
+                            i=i,
+                        )
+                        valid_set = Dataset(
+                            data=valid_data[0],
+                            label=valid_data[1],
+                            weight=valid_weight,
+                            group=valid_group,
+                            init_score=valid_init_score,
+                            categorical_feature="auto",
+                            params=params,
+                        )
+
+                    valid_sets.append(valid_set)
 
         if isinstance(init_model, LGBMModel):
             init_model = init_model.booster_