sklearn.py 44.3 KB
Newer Older
wxchan's avatar
wxchan committed
1
# coding: utf-8
2
"""Scikit-learn wrapper interface for LightGBM."""
wxchan's avatar
wxchan committed
3
from __future__ import absolute_import
4

wxchan's avatar
wxchan committed
5
import numpy as np
6

7
from .basic import Dataset, LightGBMError, _ConfigAliases
8
from .compat import (SKLEARN_INSTALLED, _LGBMClassifierBase,
9
10
                     LGBMNotFittedError, _LGBMLabelEncoder, _LGBMModelBase,
                     _LGBMRegressorBase, _LGBMCheckXY, _LGBMCheckArray, _LGBMCheckConsistentLength,
11
                     _LGBMAssertAllFinite, _LGBMCheckClassificationTargets, _LGBMComputeSampleWeight,
12
                     argc_, range_, zip_, string_type, DataFrame, DataTable)
wxchan's avatar
wxchan committed
13
from .engine import train
14

wxchan's avatar
wxchan committed
15

16
17
class _ObjectiveFunctionWrapper(object):
    """Proxy class for objective function."""
18

19
20
    def __init__(self, func):
        """Construct a proxy class.
21

22
23
        This class transforms objective function to match objective function with signature ``new_func(preds, dataset)``
        as expected by ``lightgbm.engine.train``.
24

25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
        Parameters
        ----------
        func : callable
            Expects a callable with signature ``func(y_true, y_pred)`` or ``func(y_true, y_pred, group)
            and returns (grad, hess):

                y_true : array-like of shape = [n_samples]
                    The target values.
                y_pred : array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)
                    The predicted values.
                group : array-like
                    Group/query data, used for ranking task.
                grad : array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)
                    The value of the first order derivative (gradient) for each sample point.
                hess : array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)
                    The value of the second order derivative (Hessian) for each sample point.
wxchan's avatar
wxchan committed
41

Nikita Titov's avatar
Nikita Titov committed
42
43
44
45
46
        .. note::

            For multi-class task, the y_pred is group by class_id first, then group by row_id.
            If you want to get i-th row y_pred in j-th class, the access way is y_pred[j * num_data + i]
            and you should group grad and hess in this way as well.
47
48
        """
        self.func = func
wxchan's avatar
wxchan committed
49

50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
    def __call__(self, preds, dataset):
        """Call passed function with appropriate arguments.

        Parameters
        ----------
        preds : array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)
            The predicted values.
        dataset : Dataset
            The training dataset.

        Returns
        -------
        grad : array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)
            The value of the first order derivative (gradient) for each sample point.
        hess : array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)
            The value of the second order derivative (Hessian) for each sample point.
        """
wxchan's avatar
wxchan committed
67
        labels = dataset.get_label()
68
        argc = argc_(self.func)
69
        if argc == 2:
70
            grad, hess = self.func(labels, preds)
71
        elif argc == 3:
72
            grad, hess = self.func(labels, preds, dataset.get_group())
73
        else:
wxchan's avatar
wxchan committed
74
            raise TypeError("Self-defined objective function should have 2 or 3 arguments, got %d" % argc)
wxchan's avatar
wxchan committed
75
76
77
78
79
80
81
82
83
84
85
        """weighted for objective"""
        weight = dataset.get_weight()
        if weight is not None:
            """only one class"""
            if len(weight) == len(grad):
                grad = np.multiply(grad, weight)
                hess = np.multiply(hess, weight)
            else:
                num_data = len(weight)
                num_class = len(grad) // num_data
                if num_class * num_data != len(grad):
86
                    raise ValueError("Length of grad and hess should equal to num_class * num_data")
wxchan's avatar
wxchan committed
87
88
                for k in range_(num_class):
                    for i in range_(num_data):
wxchan's avatar
wxchan committed
89
90
91
92
93
                        idx = k * num_data + i
                        grad[idx] *= weight[i]
                        hess[idx] *= weight[i]
        return grad, hess

wxchan's avatar
wxchan committed
94

95
96
class _EvalFunctionWrapper(object):
    """Proxy class for evaluation function."""
97

98
99
    def __init__(self, func):
        """Construct a proxy class.
100

101
102
        This class transforms evaluation function to match evaluation function with signature ``new_func(preds, dataset)``
        as expected by ``lightgbm.engine.train``.
103

104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
        Parameters
        ----------
        func : callable
            Expects a callable with following signatures:
            ``func(y_true, y_pred)``,
            ``func(y_true, y_pred, weight)``
            or ``func(y_true, y_pred, weight, group)``
            and returns (eval_name, eval_result, is_higher_better) or
            list of (eval_name, eval_result, is_higher_better):

                y_true : array-like of shape = [n_samples]
                    The target values.
                y_pred : array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)
                    The predicted values.
                weight : array-like of shape = [n_samples]
                    The weight of samples.
                group : array-like
                    Group/query data, used for ranking task.
                eval_name : string
123
                    The name of evaluation function (without whitespaces).
124
125
126
127
128
                eval_result : float
                    The eval result.
                is_higher_better : bool
                    Is eval result higher better, e.g. AUC is ``is_higher_better``.

Nikita Titov's avatar
Nikita Titov committed
129
130
131
132
        .. note::

            For multi-class task, the y_pred is group by class_id first, then group by row_id.
            If you want to get i-th row y_pred in j-th class, the access way is y_pred[j * num_data + i].
133
134
        """
        self.func = func
135

136
137
    def __call__(self, preds, dataset):
        """Call passed function with appropriate arguments.
138

139
140
141
142
143
144
145
146
147
148
        Parameters
        ----------
        preds : array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)
            The predicted values.
        dataset : Dataset
            The training dataset.

        Returns
        -------
        eval_name : string
149
            The name of evaluation function (without whitespaces).
150
151
152
153
154
        eval_result : float
            The eval result.
        is_higher_better : bool
            Is eval result higher better, e.g. AUC is ``is_higher_better``.
        """
155
        labels = dataset.get_label()
156
        argc = argc_(self.func)
157
        if argc == 2:
158
            return self.func(labels, preds)
159
        elif argc == 3:
160
            return self.func(labels, preds, dataset.get_weight())
161
        elif argc == 4:
162
            return self.func(labels, preds, dataset.get_weight(), dataset.get_group())
163
        else:
wxchan's avatar
wxchan committed
164
            raise TypeError("Self-defined eval function should have 2, 3 or 4 arguments, got %d" % argc)
165

wxchan's avatar
wxchan committed
166

167
168
class LGBMModel(_LGBMModelBase):
    """Implementation of the scikit-learn API for LightGBM."""
wxchan's avatar
wxchan committed
169

170
    def __init__(self, boosting_type='gbdt', num_leaves=31, max_depth=-1,
171
                 learning_rate=0.1, n_estimators=100,
172
                 subsample_for_bin=200000, objective=None, class_weight=None,
173
                 min_split_gain=0., min_child_weight=1e-3, min_child_samples=20,
174
                 subsample=1., subsample_freq=0, colsample_bytree=1.,
175
                 reg_alpha=0., reg_lambda=0., random_state=None,
176
                 n_jobs=-1, silent=True, importance_type='split', **kwargs):
177
        r"""Construct a gradient boosting model.
wxchan's avatar
wxchan committed
178
179
180

        Parameters
        ----------
181
        boosting_type : string, optional (default='gbdt')
182
183
184
185
186
            'gbdt', traditional Gradient Boosting Decision Tree.
            'dart', Dropouts meet Multiple Additive Regression Trees.
            'goss', Gradient-based One-Side Sampling.
            'rf', Random Forest.
        num_leaves : int, optional (default=31)
wxchan's avatar
wxchan committed
187
            Maximum tree leaves for base learners.
188
        max_depth : int, optional (default=-1)
189
            Maximum tree depth for base learners, <=0 means no limit.
190
        learning_rate : float, optional (default=0.1)
191
            Boosting learning rate.
192
193
194
            You can use ``callbacks`` parameter of ``fit`` method to shrink/adapt learning rate
            in training using ``reset_parameter`` callback.
            Note, that this will ignore the ``learning_rate`` argument in training.
195
        n_estimators : int, optional (default=100)
wxchan's avatar
wxchan committed
196
            Number of boosted trees to fit.
197
        subsample_for_bin : int, optional (default=200000)
wxchan's avatar
wxchan committed
198
            Number of samples for constructing bins.
199
        objective : string, callable or None, optional (default=None)
wxchan's avatar
wxchan committed
200
201
            Specify the learning task and the corresponding learning objective or
            a custom objective function to be used (see note below).
202
            Default: 'regression' for LGBMRegressor, 'binary' or 'multiclass' for LGBMClassifier, 'lambdarank' for LGBMRanker.
203
204
205
206
        class_weight : dict, 'balanced' or None, optional (default=None)
            Weights associated with classes in the form ``{class_label: weight}``.
            Use this parameter only for multi-class classification task;
            for binary classification task you may use ``is_unbalance`` or ``scale_pos_weight`` parameters.
207
208
209
            Note, that the usage of all these parameters will result in poor estimates of the individual class probabilities.
            You may want to consider performing probability calibration
            (https://scikit-learn.org/stable/modules/calibration.html) of your model.
210
211
212
            The 'balanced' mode uses the values of y to automatically adjust weights
            inversely proportional to class frequencies in the input data as ``n_samples / (n_classes * np.bincount(y))``.
            If None, all classes are supposed to have weight one.
213
            Note, that these weights will be multiplied with ``sample_weight`` (passed through the ``fit`` method)
214
            if ``sample_weight`` is specified.
215
        min_split_gain : float, optional (default=0.)
wxchan's avatar
wxchan committed
216
            Minimum loss reduction required to make a further partition on a leaf node of the tree.
217
        min_child_weight : float, optional (default=1e-3)
218
            Minimum sum of instance weight (hessian) needed in a child (leaf).
219
        min_child_samples : int, optional (default=20)
220
            Minimum number of data needed in a child (leaf).
221
        subsample : float, optional (default=1.)
wxchan's avatar
wxchan committed
222
            Subsample ratio of the training instance.
223
        subsample_freq : int, optional (default=0)
224
225
            Frequence of subsample, <=0 means no enable.
        colsample_bytree : float, optional (default=1.)
wxchan's avatar
wxchan committed
226
            Subsample ratio of columns when constructing each tree.
227
        reg_alpha : float, optional (default=0.)
228
            L1 regularization term on weights.
229
        reg_lambda : float, optional (default=0.)
230
            L2 regularization term on weights.
231
        random_state : int or None, optional (default=None)
wxchan's avatar
wxchan committed
232
            Random number seed.
233
            If None, default seeds in C++ code will be used.
234
        n_jobs : int, optional (default=-1)
235
            Number of parallel threads.
236
        silent : bool, optional (default=True)
wxchan's avatar
wxchan committed
237
            Whether to print messages while running boosting.
238
        importance_type : string, optional (default='split')
239
            The type of feature importance to be filled into ``feature_importances_``.
240
241
242
243
            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.
        **kwargs
            Other parameters for the model.
wxchan's avatar
wxchan committed
244
            Check http://lightgbm.readthedocs.io/en/latest/Parameters.html for more parameters.
245

Nikita Titov's avatar
Nikita Titov committed
246
247
248
            .. warning::

                \*\*kwargs is not supported in sklearn, it may cause unexpected issues.
wxchan's avatar
wxchan committed
249

250
251
252
253
254
255
256
257
258
        Attributes
        ----------
        n_features_ : int
            The number of features of fitted model.
        classes_ : array of shape = [n_classes]
            The class label array (only for classification problem).
        n_classes_ : int
            The number of classes (only for classification problem).
        best_score_ : dict or None
259
            The best score of fitted model.
260
        best_iteration_ : int or None
261
            The best iteration of fitted model if ``early_stopping_rounds`` has been specified.
262
263
264
265
266
        objective_ : string or callable
            The concrete objective used while fitting this model.
        booster_ : Booster
            The underlying Booster of this model.
        evals_result_ : dict or None
267
            The evaluation results if ``early_stopping_rounds`` has been specified.
268
269
270
        feature_importances_ : array of shape = [n_features]
            The feature importances (the higher, the more important the feature).

wxchan's avatar
wxchan committed
271
272
        Note
        ----
273
274
        A custom objective function can be provided for the ``objective`` parameter.
        In this case, it should have the signature
275
276
        ``objective(y_true, y_pred) -> grad, hess`` or
        ``objective(y_true, y_pred, group) -> grad, hess``:
wxchan's avatar
wxchan committed
277

Nikita Titov's avatar
Nikita Titov committed
278
            y_true : array-like of shape = [n_samples]
279
                The target values.
Nikita Titov's avatar
Nikita Titov committed
280
            y_pred : array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)
281
                The predicted values.
Nikita Titov's avatar
Nikita Titov committed
282
            group : array-like
283
                Group/query data, used for ranking task.
Nikita Titov's avatar
Nikita Titov committed
284
            grad : array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)
285
                The value of the first order derivative (gradient) for each sample point.
Nikita Titov's avatar
Nikita Titov committed
286
            hess : array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)
287
                The value of the second order derivative (Hessian) for each sample point.
wxchan's avatar
wxchan committed
288

289
290
291
        For multi-class task, the y_pred is group by class_id first, then group by row_id.
        If you want to get i-th row y_pred in j-th class, the access way is y_pred[j * num_data + i]
        and you should group grad and hess in this way as well.
wxchan's avatar
wxchan committed
292
        """
wxchan's avatar
wxchan committed
293
        if not SKLEARN_INSTALLED:
294
            raise LightGBMError('Scikit-learn is required for this module')
wxchan's avatar
wxchan committed
295

296
        self.boosting_type = boosting_type
297
        self.objective = objective
wxchan's avatar
wxchan committed
298
299
300
301
        self.num_leaves = num_leaves
        self.max_depth = max_depth
        self.learning_rate = learning_rate
        self.n_estimators = n_estimators
wxchan's avatar
wxchan committed
302
        self.subsample_for_bin = subsample_for_bin
wxchan's avatar
wxchan committed
303
304
305
306
307
308
309
310
        self.min_split_gain = min_split_gain
        self.min_child_weight = min_child_weight
        self.min_child_samples = min_child_samples
        self.subsample = subsample
        self.subsample_freq = subsample_freq
        self.colsample_bytree = colsample_bytree
        self.reg_alpha = reg_alpha
        self.reg_lambda = reg_lambda
311
312
        self.random_state = random_state
        self.n_jobs = n_jobs
wxchan's avatar
wxchan committed
313
        self.silent = silent
314
        self.importance_type = importance_type
wxchan's avatar
wxchan committed
315
        self._Booster = None
316
317
318
319
        self._evals_result = None
        self._best_score = None
        self._best_iteration = None
        self._other_params = {}
320
        self._objective = objective
321
        self.class_weight = class_weight
322
323
        self._class_weight = None
        self._class_map = None
324
325
326
        self._n_features = None
        self._classes = None
        self._n_classes = None
327
        self.set_params(**kwargs)
wxchan's avatar
wxchan committed
328

Nikita Titov's avatar
Nikita Titov committed
329
330
331
332
    def _more_tags(self):
        return {'allow_nan': True,
                'X_types': ['2darray', 'sparse', '1dlabels']}

wxchan's avatar
wxchan committed
333
    def get_params(self, deep=True):
334
335
336
337
338
339
340
341
342
343
344
345
346
        """Get parameters for this estimator.

        Parameters
        ----------
        deep : bool, optional (default=True)
            If True, will return the parameters for this estimator and
            contained subobjects that are estimators.

        Returns
        -------
        params : dict
            Parameter names mapped to their values.
        """
wxchan's avatar
wxchan committed
347
        params = super(LGBMModel, self).get_params(deep=deep)
348
        params.update(self._other_params)
wxchan's avatar
wxchan committed
349
350
351
352
        return params

    # minor change to support `**kwargs`
    def set_params(self, **params):
353
354
355
356
357
358
359
360
361
362
363
364
        """Set the parameters of this estimator.

        Parameters
        ----------
        **params
            Parameter names with their new values.

        Returns
        -------
        self : object
            Returns self.
        """
wxchan's avatar
wxchan committed
365
366
        for key, value in params.items():
            setattr(self, key, value)
367
368
            if hasattr(self, '_' + key):
                setattr(self, '_' + key, value)
369
            self._other_params[key] = value
wxchan's avatar
wxchan committed
370
        return self
wxchan's avatar
wxchan committed
371

Guolin Ke's avatar
Guolin Ke committed
372
    def fit(self, X, y,
373
            sample_weight=None, init_score=None, group=None,
374
            eval_set=None, eval_names=None, eval_sample_weight=None,
375
376
377
            eval_class_weight=None, eval_init_score=None, eval_group=None,
            eval_metric=None, early_stopping_rounds=None, verbose=True,
            feature_name='auto', categorical_feature='auto', callbacks=None):
378
        """Build a gradient boosting model from the training set (X, y).
wxchan's avatar
wxchan committed
379
380
381

        Parameters
        ----------
382
383
384
385
386
387
388
389
        X : array-like or sparse matrix of shape = [n_samples, n_features]
            Input feature matrix.
        y : array-like of shape = [n_samples]
            The target values (class labels in classification, real numbers in regression).
        sample_weight : array-like of shape = [n_samples] or None, optional (default=None)
            Weights of training data.
        init_score : array-like of shape = [n_samples] or None, optional (default=None)
            Init score of training data.
390
        group : array-like or None, optional (default=None)
391
392
            Group data of training data.
        eval_set : list or None, optional (default=None)
393
            A list of (X, y) tuple pairs to use as validation sets.
394
        eval_names : list of strings or None, optional (default=None)
395
396
397
            Names of eval_set.
        eval_sample_weight : list of arrays or None, optional (default=None)
            Weights of eval data.
398
399
        eval_class_weight : list or None, optional (default=None)
            Class weights of eval data.
400
401
402
403
404
405
        eval_init_score : list of arrays or None, optional (default=None)
            Init score of eval data.
        eval_group : list of arrays or None, optional (default=None)
            Group data of eval data.
        eval_metric : string, list of strings, callable or None, optional (default=None)
            If string, it should be a built-in evaluation metric to use.
406
            If callable, it should be a custom evaluation metric, see note below for more details.
Misha Lisovyi's avatar
Misha Lisovyi committed
407
            In either case, the ``metric`` from the model parameters will be evaluated and used as well.
408
            Default: 'l2' for LGBMRegressor, 'logloss' for LGBMClassifier, 'ndcg' for LGBMRanker.
409
410
        early_stopping_rounds : int or None, optional (default=None)
            Activates early stopping. The model will train until the validation score stops improving.
411
            Validation score needs to improve at least every ``early_stopping_rounds`` round(s)
412
            to continue training.
413
414
            Requires at least one validation data and one metric.
            If there's more than one, will check all of them. But the training data is ignored anyway.
415
416
            To check only the first metric, set the ``first_metric_only`` parameter to ``True``
            in additional parameters ``**kwargs`` of the model constructor.
417
418
419
420
421
422
        verbose : bool or int, optional (default=True)
            Requires at least one evaluation data.
            If True, the eval metric on the eval set is printed at each boosting stage.
            If int, the eval metric on the eval set is printed at every ``verbose`` boosting stage.
            The last boosting stage or the boosting stage found by using ``early_stopping_rounds`` is also printed.

Nikita Titov's avatar
Nikita Titov committed
423
424
            .. rubric:: Example

425
426
427
            With ``verbose`` = 4 and at least one item in ``eval_set``,
            an evaluation metric is printed every 4 (instead of 1) boosting stages.

428
        feature_name : list of strings or 'auto', optional (default='auto')
429
430
            Feature names.
            If 'auto' and data is pandas DataFrame, data columns names are used.
431
        categorical_feature : list of strings or int, or 'auto', optional (default='auto')
432
433
            Categorical features.
            If list of int, interpreted as indices.
434
            If list of strings, interpreted as feature names (need to specify ``feature_name`` as well).
435
            If 'auto' and data is pandas DataFrame, pandas unordered categorical columns are used.
436
            All values in categorical features should be less than int32 max value (2147483647).
437
            Large values could be memory consuming. Consider using consecutive integers starting from zero.
438
            All negative values in categorical features will be treated as missing values.
439
            The output cannot be monotonically constrained with respect to a categorical feature.
440
        callbacks : list of callback functions or None, optional (default=None)
441
            List of callback functions that are applied at each iteration.
442
            See Callbacks in Python API for more information.
443

444
445
446
447
448
        Returns
        -------
        self : object
            Returns self.

449
450
        Note
        ----
451
        Custom eval function expects a callable with following signatures:
452
        ``func(y_true, y_pred)``, ``func(y_true, y_pred, weight)`` or
453
        ``func(y_true, y_pred, weight, group)``
454
455
        and returns (eval_name, eval_result, is_higher_better) or
        list of (eval_name, eval_result, is_higher_better):
456

Nikita Titov's avatar
Nikita Titov committed
457
            y_true : array-like of shape = [n_samples]
458
                The target values.
459
            y_pred : array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)
460
                The predicted values.
Nikita Titov's avatar
Nikita Titov committed
461
            weight : array-like of shape = [n_samples]
462
                The weight of samples.
Nikita Titov's avatar
Nikita Titov committed
463
            group : array-like
464
                Group/query data, used for ranking task.
Nikita Titov's avatar
Nikita Titov committed
465
            eval_name : string
466
                The name of evaluation function (without whitespaces).
Nikita Titov's avatar
Nikita Titov committed
467
            eval_result : float
468
                The eval result.
469
470
            is_higher_better : bool
                Is eval result higher better, e.g. AUC is ``is_higher_better``.
471

472
473
        For multi-class task, the y_pred is group by class_id first, then group by row_id.
        If you want to get i-th row y_pred in j-th class, the access way is y_pred[j * num_data + i].
wxchan's avatar
wxchan committed
474
        """
475
476
477
478
479
480
481
482
483
484
        if self._objective is None:
            if isinstance(self, LGBMRegressor):
                self._objective = "regression"
            elif isinstance(self, LGBMClassifier):
                self._objective = "binary"
            elif isinstance(self, LGBMRanker):
                self._objective = "lambdarank"
            else:
                raise ValueError("Unknown LGBMModel type.")
        if callable(self._objective):
485
            self._fobj = _ObjectiveFunctionWrapper(self._objective)
486
487
        else:
            self._fobj = None
wxchan's avatar
wxchan committed
488
489
        evals_result = {}
        params = self.get_params()
wxchan's avatar
wxchan committed
490
        # user can set verbose with kwargs, it has higher priority
491
        if not any(verbose_alias in params for verbose_alias in _ConfigAliases.get("verbosity")) and self.silent:
492
            params['verbose'] = -1
wxchan's avatar
wxchan committed
493
        params.pop('silent', None)
494
        params.pop('importance_type', None)
wxchan's avatar
wxchan committed
495
        params.pop('n_estimators', None)
496
        params.pop('class_weight', None)
497
498
        for alias in _ConfigAliases.get('objective'):
            params.pop(alias, None)
499
        if self._n_classes is not None and self._n_classes > 2:
500
501
            for alias in _ConfigAliases.get('num_class'):
                params.pop(alias, None)
502
503
            params['num_class'] = self._n_classes
        if hasattr(self, '_eval_at'):
504
505
            for alias in _ConfigAliases.get('eval_at'):
                params.pop(alias, None)
506
            params['eval_at'] = self._eval_at
507
508
        params['objective'] = self._objective
        if self._fobj:
wxchan's avatar
wxchan committed
509
            params['objective'] = 'None'  # objective = nullptr for unknown objective
wxchan's avatar
wxchan committed
510
511

        if callable(eval_metric):
512
            feval = _EvalFunctionWrapper(eval_metric)
wxchan's avatar
wxchan committed
513
514
        else:
            feval = None
515
516
517
518
519
520
521
522
523
524
525
            # register default metric for consistency with callable eval_metric case
            original_metric = self._objective if isinstance(self._objective, string_type) else None
            if original_metric is None:
                # try to deduce from class instance
                if isinstance(self, LGBMRegressor):
                    original_metric = "l2"
                elif isinstance(self, LGBMClassifier):
                    original_metric = "multi_logloss" if self._n_classes > 2 else "binary_logloss"
                elif isinstance(self, LGBMRanker):
                    original_metric = "ndcg"
            # overwrite default metric by explicitly set metric
526
            for metric_alias in _ConfigAliases.get("metric"):
527
528
529
530
531
                if metric_alias in params:
                    original_metric = params.pop(metric_alias)
            # concatenate metric from params (or default if not provided in params) and eval_metric
            original_metric = [original_metric] if isinstance(original_metric, (string_type, type(None))) else original_metric
            eval_metric = [eval_metric] if isinstance(eval_metric, (string_type, type(None))) else eval_metric
532
533
            params['metric'] = [e for e in eval_metric if e not in original_metric] + original_metric
            params['metric'] = [metric for metric in params['metric'] if metric is not None]
wxchan's avatar
wxchan committed
534

535
        if not isinstance(X, (DataFrame, DataTable)):
536
537
538
539
            _X, _y = _LGBMCheckXY(X, y, accept_sparse=True, force_all_finite=False, ensure_min_samples=2)
            _LGBMCheckConsistentLength(_X, _y, sample_weight)
        else:
            _X, _y = X, y
540

541
542
543
544
        if self._class_weight is None:
            self._class_weight = self.class_weight
        if self._class_weight is not None:
            class_sample_weight = _LGBMComputeSampleWeight(self._class_weight, y)
545
546
547
548
            if sample_weight is None or len(sample_weight) == 0:
                sample_weight = class_sample_weight
            else:
                sample_weight = np.multiply(sample_weight, class_sample_weight)
549

550
        self._n_features = _X.shape[1]
551

Guolin Ke's avatar
Guolin Ke committed
552
        def _construct_dataset(X, y, sample_weight, init_score, group, params):
553
            ret = Dataset(X, label=y, weight=sample_weight, group=group, params=params)
Nikita Titov's avatar
Nikita Titov committed
554
            return ret.set_init_score(init_score)
Guolin Ke's avatar
Guolin Ke committed
555

556
        train_set = _construct_dataset(_X, _y, sample_weight, init_score, group, params)
Guolin Ke's avatar
Guolin Ke committed
557
558
559

        valid_sets = []
        if eval_set is not None:
560

561
            def _get_meta_data(collection, name, i):
562
563
564
565
566
567
568
                if collection is None:
                    return None
                elif isinstance(collection, list):
                    return collection[i] if len(collection) > i else None
                elif isinstance(collection, dict):
                    return collection.get(i, None)
                else:
569
                    raise TypeError('{} should be dict or list'.format(name))
570

Guolin Ke's avatar
Guolin Ke committed
571
572
573
            if isinstance(eval_set, tuple):
                eval_set = [eval_set]
            for i, valid_data in enumerate(eval_set):
574
                # reduce cost for prediction training data
Guolin Ke's avatar
Guolin Ke committed
575
576
577
                if valid_data[0] is X and valid_data[1] is y:
                    valid_set = train_set
                else:
578
579
580
581
582
583
                    valid_weight = _get_meta_data(eval_sample_weight, 'eval_sample_weight', i)
                    valid_class_weight = _get_meta_data(eval_class_weight, 'eval_class_weight', 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])
584
585
586
587
                        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)
588
589
                    valid_init_score = _get_meta_data(eval_init_score, 'eval_init_score', i)
                    valid_group = _get_meta_data(eval_group, 'eval_group', i)
590
591
                    valid_set = _construct_dataset(valid_data[0], valid_data[1],
                                                   valid_weight, valid_init_score, valid_group, params)
Guolin Ke's avatar
Guolin Ke committed
592
593
594
                valid_sets.append(valid_set)

        self._Booster = train(params, train_set,
595
                              self.n_estimators, valid_sets=valid_sets, valid_names=eval_names,
wxchan's avatar
wxchan committed
596
                              early_stopping_rounds=early_stopping_rounds,
597
                              evals_result=evals_result, fobj=self._fobj, feval=feval,
Guolin Ke's avatar
Guolin Ke committed
598
                              verbose_eval=verbose, feature_name=feature_name,
599
                              categorical_feature=categorical_feature,
600
                              callbacks=callbacks)
wxchan's avatar
wxchan committed
601
602

        if evals_result:
603
            self._evals_result = evals_result
wxchan's avatar
wxchan committed
604
605

        if early_stopping_rounds is not None:
606
            self._best_iteration = self._Booster.best_iteration
607
608

        self._best_score = self._Booster.best_score
wxchan's avatar
wxchan committed
609
610
611
612

        # free dataset
        self.booster_.free_dataset()
        del train_set, valid_sets
wxchan's avatar
wxchan committed
613
614
        return self

615
    def predict(self, X, raw_score=False, num_iteration=None,
616
                pred_leaf=False, pred_contrib=False, **kwargs):
617
        """Return the predicted value for each sample.
wxchan's avatar
wxchan committed
618
619
620

        Parameters
        ----------
621
        X : array-like or sparse matrix of shape = [n_samples, n_features]
wxchan's avatar
wxchan committed
622
            Input features matrix.
623
624
        raw_score : bool, optional (default=False)
            Whether to predict raw scores.
625
        num_iteration : int or None, optional (default=None)
626
            Limit number of iterations in the prediction.
627
628
            If None, if the best iteration exists, it is used; otherwise, all trees are used.
            If <= 0, all trees are used (no limits).
629
630
631
632
        pred_leaf : bool, optional (default=False)
            Whether to predict leaf index.
        pred_contrib : bool, optional (default=False)
            Whether to predict feature contributions.
633

Nikita Titov's avatar
Nikita Titov committed
634
635
636
637
638
639
640
            .. note::

                If you want to get more explanations for your model's predictions using SHAP values,
                like SHAP interaction values,
                you can install the shap package (https://github.com/slundberg/shap).
                Note that unlike the shap package, with ``pred_contrib`` we return a matrix with an extra
                column, where the last column is the expected value.
641

642
643
        **kwargs
            Other parameters for the prediction.
wxchan's avatar
wxchan committed
644
645
646

        Returns
        -------
647
648
        predicted_result : array-like of shape = [n_samples] or shape = [n_samples, n_classes]
            The predicted values.
649
        X_leaves : array-like of shape = [n_samples, n_trees] or shape = [n_samples, n_trees * n_classes]
Nikita Titov's avatar
Nikita Titov committed
650
            If ``pred_leaf=True``, the predicted leaf of every tree for each sample.
651
652
        X_SHAP_values : array-like of shape = [n_samples, n_features + 1] or shape = [n_samples, (n_features + 1) * n_classes]
            If ``pred_contrib=True``, the feature contributions for each sample.
wxchan's avatar
wxchan committed
653
        """
654
655
        if self._n_features is None:
            raise LGBMNotFittedError("Estimator not fitted, call `fit` before exploiting the model.")
656
        if not isinstance(X, (DataFrame, DataTable)):
657
            X = _LGBMCheckArray(X, accept_sparse=True, force_all_finite=False)
658
659
660
661
662
663
        n_features = X.shape[1]
        if self._n_features != n_features:
            raise ValueError("Number of features of the model must "
                             "match the input. Model n_features_ is %s and "
                             "input n_features is %s "
                             % (self._n_features, n_features))
664
665
        return self.booster_.predict(X, raw_score=raw_score, num_iteration=num_iteration,
                                     pred_leaf=pred_leaf, pred_contrib=pred_contrib, **kwargs)
wxchan's avatar
wxchan committed
666

667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
    @property
    def n_features_(self):
        """Get the number of features of fitted model."""
        if self._n_features is None:
            raise LGBMNotFittedError('No n_features found. Need to call fit beforehand.')
        return self._n_features

    @property
    def best_score_(self):
        """Get the best score of fitted model."""
        if self._n_features is None:
            raise LGBMNotFittedError('No best_score found. Need to call fit beforehand.')
        return self._best_score

    @property
    def best_iteration_(self):
        """Get the best iteration of fitted model."""
        if self._n_features is None:
            raise LGBMNotFittedError('No best_iteration found. Need to call fit with early_stopping_rounds beforehand.')
        return self._best_iteration

    @property
    def objective_(self):
        """Get the concrete objective used while fitting this model."""
        if self._n_features is None:
            raise LGBMNotFittedError('No objective found. Need to call fit beforehand.')
        return self._objective

695
696
697
698
    @property
    def booster_(self):
        """Get the underlying lightgbm Booster of this model."""
        if self._Booster is None:
699
            raise LGBMNotFittedError('No booster found. Need to call fit beforehand.')
700
        return self._Booster
wxchan's avatar
wxchan committed
701

702
703
704
    @property
    def evals_result_(self):
        """Get the evaluation results."""
705
706
707
        if self._n_features is None:
            raise LGBMNotFittedError('No results found. Need to call fit with eval_set beforehand.')
        return self._evals_result
708
709

    @property
710
    def feature_importances_(self):
711
        """Get feature importances.
712

Nikita Titov's avatar
Nikita Titov committed
713
714
715
716
717
718
        .. note::

            Feature importance in sklearn interface used to normalize to 1,
            it's deprecated after 2.0.4 and is the same as Booster.feature_importance() now.
            ``importance_type`` attribute is passed to the function
            to configure the type of importance values to be extracted.
719
        """
720
721
        if self._n_features is None:
            raise LGBMNotFittedError('No feature_importances found. Need to call fit beforehand.')
722
        return self.booster_.feature_importance(importance_type=self.importance_type)
wxchan's avatar
wxchan committed
723

wxchan's avatar
wxchan committed
724

725
726
class LGBMRegressor(LGBMModel, _LGBMRegressorBase):
    """LightGBM regressor."""
wxchan's avatar
wxchan committed
727

Guolin Ke's avatar
Guolin Ke committed
728
729
    def fit(self, X, y,
            sample_weight=None, init_score=None,
730
            eval_set=None, eval_names=None, eval_sample_weight=None,
731
            eval_init_score=None, eval_metric=None, early_stopping_rounds=None,
732
            verbose=True, feature_name='auto', categorical_feature='auto', callbacks=None):
733
        """Docstring is inherited from the LGBMModel."""
734
735
        super(LGBMRegressor, self).fit(X, y, sample_weight=sample_weight,
                                       init_score=init_score, eval_set=eval_set,
736
                                       eval_names=eval_names,
737
738
739
740
741
                                       eval_sample_weight=eval_sample_weight,
                                       eval_init_score=eval_init_score,
                                       eval_metric=eval_metric,
                                       early_stopping_rounds=early_stopping_rounds,
                                       verbose=verbose, feature_name=feature_name,
742
                                       categorical_feature=categorical_feature,
Guolin Ke's avatar
Guolin Ke committed
743
                                       callbacks=callbacks)
Guolin Ke's avatar
Guolin Ke committed
744
745
        return self

746
747
748
    _base_doc = LGBMModel.fit.__doc__
    fit.__doc__ = (_base_doc[:_base_doc.find('eval_class_weight :')]
                   + _base_doc[_base_doc.find('eval_init_score :'):])
wxchan's avatar
wxchan committed
749

750
751
752

class LGBMClassifier(LGBMModel, _LGBMClassifierBase):
    """LightGBM classifier."""
wxchan's avatar
wxchan committed
753

Guolin Ke's avatar
Guolin Ke committed
754
755
    def fit(self, X, y,
            sample_weight=None, init_score=None,
756
            eval_set=None, eval_names=None, eval_sample_weight=None,
757
            eval_class_weight=None, eval_init_score=None, eval_metric=None,
wxchan's avatar
wxchan committed
758
            early_stopping_rounds=None, verbose=True,
759
            feature_name='auto', categorical_feature='auto', callbacks=None):
760
        """Docstring is inherited from the LGBMModel."""
761
        _LGBMAssertAllFinite(y)
762
763
        _LGBMCheckClassificationTargets(y)
        self._le = _LGBMLabelEncoder().fit(y)
764
        _y = self._le.transform(y)
765
766
767
        self._class_map = dict(zip_(self._le.classes_, self._le.transform(self._le.classes_)))
        if isinstance(self.class_weight, dict):
            self._class_weight = {self._class_map[k]: v for k, v in self.class_weight.items()}
768

769
770
771
        self._classes = self._le.classes_
        self._n_classes = len(self._classes)
        if self._n_classes > 2:
wxchan's avatar
wxchan committed
772
            # Switch to using a multiclass objective in the underlying LGBM instance
773
774
            ova_aliases = ("multiclassova", "multiclass_ova", "ova", "ovr")
            if self._objective not in ova_aliases and not callable(self._objective):
775
                self._objective = "multiclass"
776
            if eval_metric in ('logloss', 'binary_logloss'):
wxchan's avatar
wxchan committed
777
                eval_metric = "multi_logloss"
778
            elif eval_metric in ('error', 'binary_error'):
wxchan's avatar
wxchan committed
779
780
                eval_metric = "multi_error"
        else:
781
            if eval_metric in ('logloss', 'multi_logloss'):
wxchan's avatar
wxchan committed
782
                eval_metric = 'binary_logloss'
783
            elif eval_metric in ('error', 'multi_error'):
wxchan's avatar
wxchan committed
784
                eval_metric = 'binary_error'
wxchan's avatar
wxchan committed
785
786

        if eval_set is not None:
787
788
789
790
791
792
793
            if isinstance(eval_set, tuple):
                eval_set = [eval_set]
            for i, (valid_x, valid_y) in enumerate(eval_set):
                if valid_x is X and valid_y is y:
                    eval_set[i] = (valid_x, _y)
                else:
                    eval_set[i] = (valid_x, self._le.transform(valid_y))
794

795
        super(LGBMClassifier, self).fit(X, _y, sample_weight=sample_weight,
796
                                        init_score=init_score, eval_set=eval_set,
797
                                        eval_names=eval_names,
798
                                        eval_sample_weight=eval_sample_weight,
799
                                        eval_class_weight=eval_class_weight,
800
801
802
803
                                        eval_init_score=eval_init_score,
                                        eval_metric=eval_metric,
                                        early_stopping_rounds=early_stopping_rounds,
                                        verbose=verbose, feature_name=feature_name,
804
                                        categorical_feature=categorical_feature,
805
                                        callbacks=callbacks)
wxchan's avatar
wxchan committed
806
807
        return self

808
    fit.__doc__ = LGBMModel.fit.__doc__
809

810
    def predict(self, X, raw_score=False, num_iteration=None,
811
                pred_leaf=False, pred_contrib=False, **kwargs):
812
        """Docstring is inherited from the LGBMModel."""
813
814
815
816
817
818
819
        result = self.predict_proba(X, raw_score, num_iteration,
                                    pred_leaf, pred_contrib, **kwargs)
        if raw_score or pred_leaf or pred_contrib:
            return result
        else:
            class_index = np.argmax(result, axis=1)
            return self._le.inverse_transform(class_index)
wxchan's avatar
wxchan committed
820

821
822
    predict.__doc__ = LGBMModel.predict.__doc__

823
    def predict_proba(self, X, raw_score=False, num_iteration=None,
824
                      pred_leaf=False, pred_contrib=False, **kwargs):
825
        """Return the predicted probability for each class for each sample.
wxchan's avatar
wxchan committed
826
827
828

        Parameters
        ----------
829
        X : array-like or sparse matrix of shape = [n_samples, n_features]
wxchan's avatar
wxchan committed
830
            Input features matrix.
831
832
        raw_score : bool, optional (default=False)
            Whether to predict raw scores.
833
        num_iteration : int or None, optional (default=None)
834
            Limit number of iterations in the prediction.
835
836
            If None, if the best iteration exists, it is used; otherwise, all trees are used.
            If <= 0, all trees are used (no limits).
837
838
839
840
        pred_leaf : bool, optional (default=False)
            Whether to predict leaf index.
        pred_contrib : bool, optional (default=False)
            Whether to predict feature contributions.
841

Nikita Titov's avatar
Nikita Titov committed
842
843
844
845
846
847
848
            .. note::

                If you want to get more explanations for your model's predictions using SHAP values,
                like SHAP interaction values,
                you can install the shap package (https://github.com/slundberg/shap).
                Note that unlike the shap package, with ``pred_contrib`` we return a matrix with an extra
                column, where the last column is the expected value.
849

850
851
        **kwargs
            Other parameters for the prediction.
wxchan's avatar
wxchan committed
852
853
854

        Returns
        -------
855
856
        predicted_probability : array-like of shape = [n_samples, n_classes]
            The predicted probability for each class for each sample.
857
        X_leaves : array-like of shape = [n_samples, n_trees * n_classes]
858
            If ``pred_leaf=True``, the predicted leaf of every tree for each sample.
859
        X_SHAP_values : array-like of shape = [n_samples, (n_features + 1) * n_classes]
860
            If ``pred_contrib=True``, the feature contributions for each sample.
wxchan's avatar
wxchan committed
861
        """
862
863
        result = super(LGBMClassifier, self).predict(X, raw_score, num_iteration,
                                                     pred_leaf, pred_contrib, **kwargs)
864
        if self._n_classes > 2 or raw_score or pred_leaf or pred_contrib:
865
            return result
wxchan's avatar
wxchan committed
866
        else:
867
            return np.vstack((1. - result, result)).transpose()
868
869
870

    @property
    def classes_(self):
871
872
873
874
        """Get the class label array."""
        if self._classes is None:
            raise LGBMNotFittedError('No classes found. Need to call fit beforehand.')
        return self._classes
875
876
877

    @property
    def n_classes_(self):
878
879
880
881
        """Get the number of classes."""
        if self._n_classes is None:
            raise LGBMNotFittedError('No classes found. Need to call fit beforehand.')
        return self._n_classes
wxchan's avatar
wxchan committed
882

wxchan's avatar
wxchan committed
883

wxchan's avatar
wxchan committed
884
class LGBMRanker(LGBMModel):
885
    """LightGBM ranker."""
wxchan's avatar
wxchan committed
886

Guolin Ke's avatar
Guolin Ke committed
887
    def fit(self, X, y,
888
            sample_weight=None, init_score=None, group=None,
889
            eval_set=None, eval_names=None, eval_sample_weight=None,
890
            eval_init_score=None, eval_group=None, eval_metric=None,
891
892
            eval_at=[1], early_stopping_rounds=None, verbose=True,
            feature_name='auto', categorical_feature='auto', callbacks=None):
893
        """Docstring is inherited from the LGBMModel."""
894
        # check group data
Guolin Ke's avatar
Guolin Ke committed
895
        if group is None:
896
            raise ValueError("Should set group for ranking task")
wxchan's avatar
wxchan committed
897
898

        if eval_set is not None:
Guolin Ke's avatar
Guolin Ke committed
899
            if eval_group is None:
900
                raise ValueError("Eval_group cannot be None when eval_set is not None")
Guolin Ke's avatar
Guolin Ke committed
901
            elif len(eval_group) != len(eval_set):
902
                raise ValueError("Length of eval_group should be equal to eval_set")
903
904
905
906
            elif (isinstance(eval_group, dict)
                  and any(i not in eval_group or eval_group[i] is None for i in range_(len(eval_group)))
                  or isinstance(eval_group, list)
                  and any(group is None for group in eval_group)):
907
908
                raise ValueError("Should set group for all eval datasets for ranking task; "
                                 "if you use dict, the index should start from 0")
909

910
        self._eval_at = eval_at
911
912
        super(LGBMRanker, self).fit(X, y, sample_weight=sample_weight,
                                    init_score=init_score, group=group,
913
914
                                    eval_set=eval_set, eval_names=eval_names,
                                    eval_sample_weight=eval_sample_weight,
915
916
917
918
                                    eval_init_score=eval_init_score, eval_group=eval_group,
                                    eval_metric=eval_metric,
                                    early_stopping_rounds=early_stopping_rounds,
                                    verbose=verbose, feature_name=feature_name,
919
                                    categorical_feature=categorical_feature,
920
                                    callbacks=callbacks)
wxchan's avatar
wxchan committed
921
        return self
922

923
924
925
926
    _base_doc = LGBMModel.fit.__doc__
    fit.__doc__ = (_base_doc[:_base_doc.find('eval_class_weight :')]
                   + _base_doc[_base_doc.find('eval_init_score :'):])
    _base_doc = fit.__doc__
927
928
    _before_early_stop, _early_stop, _after_early_stop = _base_doc.partition('early_stopping_rounds :')
    fit.__doc__ = (_before_early_stop
929
                   + 'eval_at : list of int, optional (default=[1])\n'
930
931
                   + ' ' * 12 + 'The evaluation positions of the specified metric.\n'
                   + ' ' * 8 + _early_stop + _after_early_stop)