Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[python-package] mark EarlyStopException as part of public API #6095

Merged
merged 5 commits into from
Sep 13, 2023
+36 −3
Merged

[python-package] mark EarlyStopException as part of public API #6095

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d0d0174
[python-package] mark EarlyStopException as part of public API
jameslamb Sep 13, 2023
c91fff5
one more thing in __init__.py
jameslamb Sep 13, 2023
3205ef9
add test
jameslamb Sep 13, 2023
85dd414
isort
jameslamb Sep 13, 2023
25471b2
Merge branch 'master' into python/early-stop-exception
jameslamb Sep 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions python-package/lightgbm/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
from pathlib import Path

from .basic import Booster, Dataset, Sequence, register_logger
from .callback import early_stopping, log_evaluation, record_evaluation, reset_parameter
from .callback import EarlyStopException, early_stopping, log_evaluation, record_evaluation, reset_parameter
from .engine import CVBooster, cv, train

try:
Expand All @@ -32,5 +32,5 @@
'train', 'cv',
'LGBMModel', 'LGBMRegressor', 'LGBMClassifier', 'LGBMRanker',
'DaskLGBMRegressor', 'DaskLGBMClassifier', 'DaskLGBMRanker',
'log_evaluation', 'record_evaluation', 'reset_parameter', 'early_stopping',
'log_evaluation', 'record_evaluation', 'reset_parameter', 'early_stopping', 'EarlyStopException',
Copy link
Collaborator Author

@jameslamb jameslamb Sep 13, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This allows for imports like

from lightgbm import EarlyStopException

or

import lightgbm as lgb

def _early_stop(env):
    raise lgb.EarlyStopException(
        best_iteration=6,
        best_score=[("some_validation_set", "some_metric", 0.708, True)]
     )

Every other part of the public API can be imported like this, and I think such imports should be encouraged over those that require knowing the internal sub-module structure like from lightgbm.callback import EarlyStopException

'plot_importance', 'plot_split_value_histogram', 'plot_metric', 'plot_tree', 'create_tree_digraph']
8 changes: 7 additions & 1 deletion python-package/lightgbm/callback.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
from .engine import CVBooster

__all__ = [
'EarlyStopException',
'early_stopping',
'log_evaluation',
'record_evaluation',
Expand All @@ -30,7 +31,11 @@


class EarlyStopException(Exception):
"""Exception of early stopping."""
"""Exception of early stopping.

Raise this from a callback passed in via keyword argument ``callbacks``
in ``cv()`` or ``train()`` to trigger early stopping.
"""

def __init__(self, best_iteration: int, best_score: _ListOfEvalResultTuples) -> None:
"""Create early stopping exception.
Expand All @@ -39,6 +44,7 @@ def __init__(self, best_iteration: int, best_score: _ListOfEvalResultTuples) ->
----------
best_iteration : int
The best iteration stopped.
0-based... pass ``best_iteration=2`` to indicate that the third iteration was the best one.
best_score : list of (eval_name, metric_name, eval_result, is_higher_better) tuple or (eval_name, metric_name, eval_result, is_higher_better, stdv) tuple
Scores for each metric, on each validation set, as of the best iteration.
"""
Expand Down
27 changes: 27 additions & 0 deletions tests/python_package_test/test_engine.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1092,6 +1092,33 @@ def test_early_stopping_min_delta(first_only, single_metric, greater_is_better):
assert np.greater_equal(last_score, best_score - min_delta).any()


def test_early_stopping_can_be_triggered_via_custom_callback():
X, y = make_synthetic_regression()

def _early_stop_after_seventh_iteration(env):
if env.iteration == 6:
exc = lgb.EarlyStopException(
best_iteration=6,
best_score=[("some_validation_set", "some_metric", 0.708, True)]
)
raise exc

bst = lgb.train(
params={
"objective": "regression",
"verbose": -1,
"num_leaves": 2
},
train_set=lgb.Dataset(X, label=y),
num_boost_round=23,
callbacks=[_early_stop_after_seventh_iteration]
)
assert bst.num_trees() == 7
assert bst.best_score["some_validation_set"]["some_metric"] == 0.708
assert bst.best_iteration == 7
assert bst.current_iteration() == 7


def test_continue_train():
X, y = make_synthetic_regression()
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.1, random_state=42)
Expand Down