sklearn.py 38.6 KB
Newer Older
wxchan's avatar
wxchan committed
1
# coding: utf-8
2
# pylint: disable = invalid-name, W0105, C0111, C0301
wxchan's avatar
wxchan committed
3
4
"""Scikit-Learn Wrapper interface for LightGBM."""
from __future__ import absolute_import
5

wxchan's avatar
wxchan committed
6
import numpy as np
7
import warnings
8

wxchan's avatar
wxchan committed
9
from .basic import Dataset, LightGBMError
10
from .compat import (SKLEARN_INSTALLED, _LGBMClassifierBase,
11
12
                     LGBMNotFittedError, _LGBMLabelEncoder, _LGBMModelBase,
                     _LGBMRegressorBase, _LGBMCheckXY, _LGBMCheckArray, _LGBMCheckConsistentLength,
13
                     _LGBMCheckClassificationTargets, _LGBMComputeSampleWeight,
14
                     argc_, range_, DataFrame, LGBMDeprecationWarning)
wxchan's avatar
wxchan committed
15
from .engine import train
16

wxchan's avatar
wxchan committed
17

18
def _objective_function_wrapper(func):
wxchan's avatar
wxchan committed
19
    """Decorate an objective function
20
21
22
23
    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.

wxchan's avatar
wxchan committed
24
25
26
    Parameters
    ----------
    func: callable
27
        Expects a callable with signature ``func(y_true, y_pred)`` or ``func(y_true, y_pred, group):
28
29
30
31
32
33
            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)
                The predicted values.
            group: array-like
                Group/query data, used for ranking task.
wxchan's avatar
wxchan committed
34
35
36
37
38
39
40

    Returns
    -------
    new_func: callable
        The new objective function as expected by ``lightgbm.engine.train``.
        The signature is ``new_func(preds, dataset)``:

41
42
        preds: array-like of shape = [n_samples] or shape = [n_samples * n_classes]
            The predicted values.
wxchan's avatar
wxchan committed
43
44
        dataset: ``dataset``
            The training set from which the labels will be extracted using
45
            ``dataset.get_label()``.
wxchan's avatar
wxchan committed
46
47
48
49
    """
    def inner(preds, dataset):
        """internal function"""
        labels = dataset.get_label()
wxchan's avatar
wxchan committed
50
        argc = argc_(func)
51
52
53
54
55
        if argc == 2:
            grad, hess = func(labels, preds)
        elif argc == 3:
            grad, hess = func(labels, preds, dataset.get_group())
        else:
wxchan's avatar
wxchan committed
56
            raise TypeError("Self-defined objective function should have 2 or 3 arguments, got %d" % argc)
wxchan's avatar
wxchan committed
57
58
59
60
61
62
63
64
65
66
67
        """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):
68
                    raise ValueError("Length of grad and hess should equal to num_class * num_data")
wxchan's avatar
wxchan committed
69
70
                for k in range_(num_class):
                    for i in range_(num_data):
wxchan's avatar
wxchan committed
71
72
73
74
75
76
                        idx = k * num_data + i
                        grad[idx] *= weight[i]
                        hess[idx] *= weight[i]
        return grad, hess
    return inner

wxchan's avatar
wxchan committed
77

78
79
def _eval_function_wrapper(func):
    """Decorate an eval function
80
81
82
    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].

83
84
85
    Parameters
    ----------
    func: callable
86
87
88
89
90
        Expects a callable with following functions:
            ``func(y_true, y_pred)``,
            ``func(y_true, y_pred, weight)``
         or ``func(y_true, y_pred, weight, group)``
            and return (eval_name->str, eval_result->float, is_bigger_better->Bool):
91

92
93
94
95
96
97
98
99
            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)
                The predicted values.
            weight: array_like of shape = [n_samples]
                The weight of samples.
            group: array-like
                Group/query data, used for ranking task.
100
101
102
103
104
105
106

    Returns
    -------
    new_func: callable
        The new eval function as expected by ``lightgbm.engine.train``.
        The signature is ``new_func(preds, dataset)``:

107
108
        preds: array-like of shape = [n_samples] or shape = [n_samples * n_classes]
            The predicted values.
109
110
        dataset: ``dataset``
            The training set from which the labels will be extracted using
111
            ``dataset.get_label()``.
112
113
114
115
    """
    def inner(preds, dataset):
        """internal function"""
        labels = dataset.get_label()
wxchan's avatar
wxchan committed
116
        argc = argc_(func)
117
118
119
120
121
122
123
        if argc == 2:
            return func(labels, preds)
        elif argc == 3:
            return func(labels, preds, dataset.get_weight())
        elif argc == 4:
            return func(labels, preds, dataset.get_weight(), dataset.get_group())
        else:
wxchan's avatar
wxchan committed
124
            raise TypeError("Self-defined eval function should have 2, 3 or 4 arguments, got %d" % argc)
125
126
    return inner

wxchan's avatar
wxchan committed
127

128
129
class LGBMModel(_LGBMModelBase):
    """Implementation of the scikit-learn API for LightGBM."""
wxchan's avatar
wxchan committed
130

131
    def __init__(self, boosting_type="gbdt", num_leaves=31, max_depth=-1,
132
                 learning_rate=0.1, n_estimators=100,
133
                 subsample_for_bin=200000, objective=None, class_weight=None,
134
                 min_split_gain=0., min_child_weight=1e-3, min_child_samples=20,
135
                 subsample=1., subsample_freq=0, colsample_bytree=1.,
136
                 reg_alpha=0., reg_lambda=0., random_state=None,
137
                 n_jobs=-1, silent=True, importance_type='split', **kwargs):
138
        """Construct a gradient boosting model.
wxchan's avatar
wxchan committed
139
140
141

        Parameters
        ----------
142
143
144
145
146
147
        boosting_type : string, optional (default="gbdt")
            '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
148
            Maximum tree leaves for base learners.
149
        max_depth : int, optional (default=-1)
wxchan's avatar
wxchan committed
150
            Maximum tree depth for base learners, -1 means no limit.
151
        learning_rate : float, optional (default=0.1)
152
            Boosting learning rate.
153
154
155
            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.
156
        n_estimators : int, optional (default=100)
wxchan's avatar
wxchan committed
157
            Number of boosted trees to fit.
158
        subsample_for_bin : int, optional (default=50000)
wxchan's avatar
wxchan committed
159
            Number of samples for constructing bins.
160
        objective : string, callable or None, optional (default=None)
wxchan's avatar
wxchan committed
161
162
            Specify the learning task and the corresponding learning objective or
            a custom objective function to be used (see note below).
163
            default: 'regression' for LGBMRegressor, 'binary' or 'multiclass' for LGBMClassifier, 'lambdarank' for LGBMRanker.
164
165
166
167
168
169
170
171
172
        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.
            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.
            Note that these weights will be multiplied with ``sample_weight`` (passed through the fit method)
            if ``sample_weight`` is specified.
173
        min_split_gain : float, optional (default=0.)
wxchan's avatar
wxchan committed
174
            Minimum loss reduction required to make a further partition on a leaf node of the tree.
175
        min_child_weight : float, optional (default=1e-3)
176
            Minimum sum of instance weight(hessian) needed in a child(leaf).
177
        min_child_samples : int, optional (default=20)
178
            Minimum number of data need in a child(leaf).
179
        subsample : float, optional (default=1.)
wxchan's avatar
wxchan committed
180
            Subsample ratio of the training instance.
181
        subsample_freq : int, optional (default=0)
182
183
            Frequence of subsample, <=0 means no enable.
        colsample_bytree : float, optional (default=1.)
wxchan's avatar
wxchan committed
184
            Subsample ratio of columns when constructing each tree.
185
        reg_alpha : float, optional (default=0.)
186
            L1 regularization term on weights.
187
        reg_lambda : float, optional (default=0.)
188
            L2 regularization term on weights.
189
        random_state : int or None, optional (default=None)
wxchan's avatar
wxchan committed
190
            Random number seed.
191
            If None, default seeds in C++ code will be used.
192
        n_jobs : int, optional (default=-1)
193
            Number of parallel threads.
194
        silent : bool, optional (default=True)
wxchan's avatar
wxchan committed
195
            Whether to print messages while running boosting.
196
        importance_type : string, optional (default='split')
197
198
199
            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.
wxchan's avatar
wxchan committed
200
201
        **kwargs : other parameters
            Check http://lightgbm.readthedocs.io/en/latest/Parameters.html for more parameters.
202
203
204

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

207
208
209
210
211
212
213
214
215
        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
216
            The best score of fitted model.
217
        best_iteration_ : int or None
218
            The best iteration of fitted model if ``early_stopping_rounds`` has been specified.
219
220
221
222
223
        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
224
            The evaluation results if ``early_stopping_rounds`` has been specified.
225
226
227
        feature_importances_ : array of shape = [n_features]
            The feature importances (the higher, the more important the feature).

wxchan's avatar
wxchan committed
228
229
230
231
        Note
        ----
        A custom objective function can be provided for the ``objective``
        parameter. In this case, it should have the signature
232
233
        ``objective(y_true, y_pred) -> grad, hess`` or
        ``objective(y_true, y_pred, group) -> grad, hess``:
wxchan's avatar
wxchan committed
234

235
            y_true: array-like of shape = [n_samples]
236
                The target values.
237
            y_pred: array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)
238
                The predicted values.
239
240
241
            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)
wxchan's avatar
wxchan committed
242
                The value of the gradient for each sample point.
243
            hess: array-like of shape = [n_samples] or shape = [n_samples * n_classes] (for multi-class task)
244
                The value of the second derivative for each sample point.
wxchan's avatar
wxchan committed
245

246
247
248
        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
249
        """
wxchan's avatar
wxchan committed
250
        if not SKLEARN_INSTALLED:
251
            raise LightGBMError('Scikit-learn is required for this module')
wxchan's avatar
wxchan committed
252

253
        self.boosting_type = boosting_type
254
        self.objective = objective
wxchan's avatar
wxchan committed
255
256
257
258
        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
259
        self.subsample_for_bin = subsample_for_bin
wxchan's avatar
wxchan committed
260
261
262
263
264
265
266
267
        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
268
269
        self.random_state = random_state
        self.n_jobs = n_jobs
wxchan's avatar
wxchan committed
270
        self.silent = silent
271
        self.importance_type = importance_type
wxchan's avatar
wxchan committed
272
        self._Booster = None
273
274
275
276
        self._evals_result = None
        self._best_score = None
        self._best_iteration = None
        self._other_params = {}
277
        self._objective = objective
278
        self.class_weight = class_weight
279
280
281
        self._n_features = None
        self._classes = None
        self._n_classes = None
282
        self.set_params(**kwargs)
wxchan's avatar
wxchan committed
283
284
285

    def get_params(self, deep=True):
        params = super(LGBMModel, self).get_params(deep=deep)
286
        params.update(self._other_params)
wxchan's avatar
wxchan committed
287
288
289
290
291
292
        return params

    # minor change to support `**kwargs`
    def set_params(self, **params):
        for key, value in params.items():
            setattr(self, key, value)
293
294
            if hasattr(self, '_' + key):
                setattr(self, '_' + key, value)
295
            self._other_params[key] = value
wxchan's avatar
wxchan committed
296
        return self
wxchan's avatar
wxchan committed
297

Guolin Ke's avatar
Guolin Ke committed
298
    def fit(self, X, y,
299
            sample_weight=None, init_score=None, group=None,
300
            eval_set=None, eval_names=None, eval_sample_weight=None,
301
302
303
            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):
304
        """Build a gradient boosting model from the training set (X, y).
wxchan's avatar
wxchan committed
305
306
307

        Parameters
        ----------
308
309
310
311
312
313
314
315
        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.
316
        group : array-like or None, optional (default=None)
317
318
319
            Group data of training data.
        eval_set : list or None, optional (default=None)
            A list of (X, y) tuple pairs to use as a validation sets for early-stopping.
320
        eval_names : list of strings or None, optional (default=None)
321
322
323
            Names of eval_set.
        eval_sample_weight : list of arrays or None, optional (default=None)
            Weights of eval data.
324
325
        eval_class_weight : list or None, optional (default=None)
            Class weights of eval data.
326
327
328
329
330
331
332
        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.
            If callable, it should be a custom evaluation metric, see note for more details.
Misha Lisovyi's avatar
Misha Lisovyi committed
333
            In either case, the ``metric`` from the model parameters will be evaluated and used as well.
334
335
        early_stopping_rounds : int or None, optional (default=None)
            Activates early stopping. The model will train until the validation score stops improving.
336
            If there's more than one, will check all of them except the training data.
337
            Validation error needs to decrease at least every ``early_stopping_rounds`` round(s)
338
339
340
341
342
343
344
345
346
            to continue training.
        verbose : bool, optional (default=True)
            If True and an evaluation set is used, writes the evaluation progress.
        feature_name : list of strings or 'auto', optional (default="auto")
            Feature names.
            If 'auto' and data is pandas DataFrame, data columns names are used.
        categorical_feature : list of strings or int, or 'auto', optional (default="auto")
            Categorical features.
            If list of int, interpreted as indices.
347
            If list of strings, interpreted as feature names (need to specify ``feature_name`` as well).
348
            If 'auto' and data is pandas DataFrame, pandas categorical columns are used.
349
            All values should be less than int32 max value (2147483647).
350
        callbacks : list of callback functions or None, optional (default=None)
351
            List of callback functions that are applied at each iteration.
352
            See Callbacks in Python API for more information.
353

354
355
356
357
358
        Returns
        -------
        self : object
            Returns self.

359
360
        Note
        ----
wxchan's avatar
wxchan committed
361
        Custom eval function expects a callable with following functions:
362
363
364
365
366
367
368
369
370
371
372
373
374
        ``func(y_true, y_pred)``, ``func(y_true, y_pred, weight)`` or
        ``func(y_true, y_pred, weight, group)``.
        Returns (eval_name, eval_result, is_bigger_better) or
        list of (eval_name, eval_result, is_bigger_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)
                The predicted values.
            weight: array-like of shape = [n_samples]
                The weight of samples.
            group: array-like
                Group/query data, used for ranking task.
375
            eval_name: string
376
                The name of evaluation.
377
            eval_result: float
378
                The eval result.
379
            is_bigger_better: bool
380
                Is eval result bigger better, e.g. AUC is bigger_better.
381

382
383
        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
384
        """
385
386
387
388
389
390
391
392
393
394
395
396
397
        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):
            self._fobj = _objective_function_wrapper(self._objective)
        else:
            self._fobj = None
wxchan's avatar
wxchan committed
398
399
        evals_result = {}
        params = self.get_params()
wxchan's avatar
wxchan committed
400
        # user can set verbose with kwargs, it has higher priority
401
        if not any(verbose_alias in params for verbose_alias in ('verbose', 'verbosity')) and self.silent:
402
            params['verbose'] = 0
wxchan's avatar
wxchan committed
403
        params.pop('silent', None)
404
        params.pop('importance_type', None)
wxchan's avatar
wxchan committed
405
        params.pop('n_estimators', None)
406
        params.pop('class_weight', None)
407
408
409
        if self._n_classes is not None and self._n_classes > 2:
            params['num_class'] = self._n_classes
        if hasattr(self, '_eval_at'):
410
            params['eval_at'] = self._eval_at
411
412
        params['objective'] = self._objective
        if self._fobj:
wxchan's avatar
wxchan committed
413
            params['objective'] = 'None'  # objective = nullptr for unknown objective
wxchan's avatar
wxchan committed
414
415

        if callable(eval_metric):
416
            feval = _eval_function_wrapper(eval_metric)
wxchan's avatar
wxchan committed
417
418
        else:
            feval = None
419
            params['metric'] = eval_metric
wxchan's avatar
wxchan committed
420

Nikita Titov's avatar
Nikita Titov committed
421
        if not isinstance(X, DataFrame):
422
423
424
            X, y = _LGBMCheckXY(X, y, accept_sparse=True, force_all_finite=False, ensure_min_samples=2)
            _LGBMCheckConsistentLength(X, y, sample_weight)

425
426
427
428
429
430
        if self.class_weight is not None:
            class_sample_weight = _LGBMComputeSampleWeight(self.class_weight, y)
            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)
431

432
433
        self._n_features = X.shape[1]

Guolin Ke's avatar
Guolin Ke committed
434
        def _construct_dataset(X, y, sample_weight, init_score, group, params):
435
            ret = Dataset(X, label=y, weight=sample_weight, group=group, params=params)
Guolin Ke's avatar
Guolin Ke committed
436
437
438
            ret.set_init_score(init_score)
            return ret

Guolin Ke's avatar
Guolin Ke committed
439
        train_set = _construct_dataset(X, y, sample_weight, init_score, group, params)
Guolin Ke's avatar
Guolin Ke committed
440
441
442

        valid_sets = []
        if eval_set is not None:
443
444
445
446
447
448
449
450
451
452
453

            def _get_meta_data(collection, i):
                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:
                    raise TypeError('eval_sample_weight, eval_class_weight, eval_init_score, and eval_group should be dict or list')

Guolin Ke's avatar
Guolin Ke committed
454
455
456
            if isinstance(eval_set, tuple):
                eval_set = [eval_set]
            for i, valid_data in enumerate(eval_set):
457
                # reduce cost for prediction training data
Guolin Ke's avatar
Guolin Ke committed
458
459
460
                if valid_data[0] is X and valid_data[1] is y:
                    valid_set = train_set
                else:
461
462
463
                    valid_weight = _get_meta_data(eval_sample_weight, i)
                    if _get_meta_data(eval_class_weight, i) is not None:
                        valid_class_sample_weight = _LGBMComputeSampleWeight(_get_meta_data(eval_class_weight, i), valid_data[1])
464
465
466
467
                        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)
468
469
                    valid_init_score = _get_meta_data(eval_init_score, i)
                    valid_group = _get_meta_data(eval_group, i)
Guolin Ke's avatar
Guolin Ke committed
470
                    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
471
472
473
                valid_sets.append(valid_set)

        self._Booster = train(params, train_set,
474
                              self.n_estimators, valid_sets=valid_sets, valid_names=eval_names,
wxchan's avatar
wxchan committed
475
                              early_stopping_rounds=early_stopping_rounds,
476
                              evals_result=evals_result, fobj=self._fobj, feval=feval,
Guolin Ke's avatar
Guolin Ke committed
477
                              verbose_eval=verbose, feature_name=feature_name,
478
                              categorical_feature=categorical_feature,
479
                              callbacks=callbacks)
wxchan's avatar
wxchan committed
480
481

        if evals_result:
482
            self._evals_result = evals_result
wxchan's avatar
wxchan committed
483
484

        if early_stopping_rounds is not None:
485
            self._best_iteration = self._Booster.best_iteration
486
487

        self._best_score = self._Booster.best_score
wxchan's avatar
wxchan committed
488
489
490
491

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

494
495
    def predict(self, X, raw_score=False, num_iteration=-1,
                pred_leaf=False, pred_contrib=False, **kwargs):
496
        """Return the predicted value for each sample.
wxchan's avatar
wxchan committed
497
498
499

        Parameters
        ----------
500
        X : array-like or sparse matrix of shape = [n_samples, n_features]
wxchan's avatar
wxchan committed
501
            Input features matrix.
502
503
        raw_score : bool, optional (default=False)
            Whether to predict raw scores.
504
505
506
507
508
509
510
511
        num_iteration : int, optional (default=-1)
            Limit number of iterations in the prediction.
            If <= 0, uses all trees (no limits).
        pred_leaf : bool, optional (default=False)
            Whether to predict leaf index.
        pred_contrib : bool, optional (default=False)
            Whether to predict feature contributions.
        **kwargs : other parameters for the prediction
wxchan's avatar
wxchan committed
512
513
514

        Returns
        -------
515
516
        predicted_result : array-like of shape = [n_samples] or shape = [n_samples, n_classes]
            The predicted values.
517
518
519
520
        X_leaves : array-like of shape = [n_samples, n_trees] or shape [n_samples, n_trees * n_classes]
            If ``pred_leaf=True``, the predicted leaf every tree for each sample.
        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 each feature contributions for each sample.
wxchan's avatar
wxchan committed
521
        """
522
523
        if self._n_features is None:
            raise LGBMNotFittedError("Estimator not fitted, call `fit` before exploiting the model.")
Nikita Titov's avatar
Nikita Titov committed
524
        if not isinstance(X, DataFrame):
525
            X = _LGBMCheckArray(X, accept_sparse=True, force_all_finite=False)
526
527
528
529
530
531
        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))
532
533
        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
534
535

    def apply(self, X, num_iteration=0):
536
        """Return the predicted leaf every tree for each sample.
wxchan's avatar
wxchan committed
537
538
539

        Parameters
        ----------
540
        X : array-like or sparse matrix of shape = [n_samples, n_features]
wxchan's avatar
wxchan committed
541
            Input features matrix.
542
        num_iteration : int, optional (default=0)
wxchan's avatar
wxchan committed
543
            Limit number of iterations in the prediction; defaults to 0 (use all trees).
wxchan's avatar
wxchan committed
544
545
546

        Returns
        -------
547
548
        X_leaves : array-like of shape = [n_samples, n_trees]
            The predicted leaf every tree for each sample.
wxchan's avatar
wxchan committed
549
        """
550
551
552
        warnings.warn('apply method is deprecated and will be removed in 2.2 version.\n'
                      'Please use pred_leaf parameter of predict method instead.',
                      LGBMDeprecationWarning)
553
554
        if self._n_features is None:
            raise LGBMNotFittedError("Estimator not fitted, call `fit` before exploiting the model.")
Nikita Titov's avatar
Nikita Titov committed
555
        if not isinstance(X, DataFrame):
556
            X = _LGBMCheckArray(X, accept_sparse=True, force_all_finite=False)
557
558
559
560
561
562
        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))
563
        return self.booster_.predict(X, pred_leaf=True, num_iteration=num_iteration)
wxchan's avatar
wxchan committed
564

565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
    @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

593
594
595
596
    @property
    def booster_(self):
        """Get the underlying lightgbm Booster of this model."""
        if self._Booster is None:
597
            raise LGBMNotFittedError('No booster found. Need to call fit beforehand.')
598
        return self._Booster
wxchan's avatar
wxchan committed
599

600
601
602
    @property
    def evals_result_(self):
        """Get the evaluation results."""
603
604
605
        if self._n_features is None:
            raise LGBMNotFittedError('No results found. Need to call fit with eval_set beforehand.')
        return self._evals_result
606
607

    @property
608
    def feature_importances_(self):
609
        """Get feature importances.
610

611
612
613
        Note
        ----
        Feature importance in sklearn interface used to normalize to 1,
614
615
616
        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.
617
        """
618
619
        if self._n_features is None:
            raise LGBMNotFittedError('No feature_importances found. Need to call fit beforehand.')
620
        return self.booster_.feature_importance(importance_type=self.importance_type)
wxchan's avatar
wxchan committed
621

wxchan's avatar
wxchan committed
622

623
624
class LGBMRegressor(LGBMModel, _LGBMRegressorBase):
    """LightGBM regressor."""
wxchan's avatar
wxchan committed
625

Guolin Ke's avatar
Guolin Ke committed
626
627
    def fit(self, X, y,
            sample_weight=None, init_score=None,
628
            eval_set=None, eval_names=None, eval_sample_weight=None,
629
630
            eval_init_score=None, eval_metric="l2", early_stopping_rounds=None,
            verbose=True, feature_name='auto', categorical_feature='auto', callbacks=None):
631
632
633

        super(LGBMRegressor, self).fit(X, y, sample_weight=sample_weight,
                                       init_score=init_score, eval_set=eval_set,
634
                                       eval_names=eval_names,
635
636
637
638
639
                                       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,
640
                                       categorical_feature=categorical_feature,
Guolin Ke's avatar
Guolin Ke committed
641
                                       callbacks=callbacks)
Guolin Ke's avatar
Guolin Ke committed
642
643
        return self

644
645
646
647
648
    _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__
    fit.__doc__ = (_base_doc[:_base_doc.find('eval_metric :')]
649
                   + 'eval_metric : string, list of strings, callable or None, optional (default="l2")\n'
650
                   + _base_doc[_base_doc.find('            If string, it should be a built-in evaluation metric to use.'):])
wxchan's avatar
wxchan committed
651

652
653
654

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

Guolin Ke's avatar
Guolin Ke committed
656
657
    def fit(self, X, y,
            sample_weight=None, init_score=None,
658
            eval_set=None, eval_names=None, eval_sample_weight=None,
659
            eval_class_weight=None, eval_init_score=None, eval_metric="logloss",
wxchan's avatar
wxchan committed
660
            early_stopping_rounds=None, verbose=True,
661
662
663
            feature_name='auto', categorical_feature='auto', callbacks=None):
        _LGBMCheckClassificationTargets(y)
        self._le = _LGBMLabelEncoder().fit(y)
664
        _y = self._le.transform(y)
665

666
667
668
        self._classes = self._le.classes_
        self._n_classes = len(self._classes)
        if self._n_classes > 2:
wxchan's avatar
wxchan committed
669
            # Switch to using a multiclass objective in the underlying LGBM instance
670
671
            ova_aliases = ("multiclassova", "multiclass_ova", "ova", "ovr")
            if self._objective not in ova_aliases and not callable(self._objective):
672
                self._objective = "multiclass"
673
            if eval_metric in ('logloss', 'binary_logloss'):
wxchan's avatar
wxchan committed
674
                eval_metric = "multi_logloss"
675
            elif eval_metric in ('error', 'binary_error'):
wxchan's avatar
wxchan committed
676
677
                eval_metric = "multi_error"
        else:
678
            if eval_metric in ('logloss', 'multi_logloss'):
wxchan's avatar
wxchan committed
679
                eval_metric = 'binary_logloss'
680
            elif eval_metric in ('error', 'multi_error'):
wxchan's avatar
wxchan committed
681
                eval_metric = 'binary_error'
wxchan's avatar
wxchan committed
682
683

        if eval_set is not None:
684
685
686
687
688
689
690
            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))
691

692
        super(LGBMClassifier, self).fit(X, _y, sample_weight=sample_weight,
693
                                        init_score=init_score, eval_set=eval_set,
694
                                        eval_names=eval_names,
695
                                        eval_sample_weight=eval_sample_weight,
696
                                        eval_class_weight=eval_class_weight,
697
698
699
700
                                        eval_init_score=eval_init_score,
                                        eval_metric=eval_metric,
                                        early_stopping_rounds=early_stopping_rounds,
                                        verbose=verbose, feature_name=feature_name,
701
                                        categorical_feature=categorical_feature,
702
                                        callbacks=callbacks)
wxchan's avatar
wxchan committed
703
704
        return self

705
706
    _base_doc = LGBMModel.fit.__doc__
    fit.__doc__ = (_base_doc[:_base_doc.find('eval_metric :')]
707
                   + 'eval_metric : string, list of strings, callable or None, optional (default="logloss")\n'
708
709
710
711
712
713
714
715
716
717
718
                   + _base_doc[_base_doc.find('            If string, it should be a built-in evaluation metric to use.'):])

    def predict(self, X, raw_score=False, num_iteration=-1,
                pred_leaf=False, pred_contrib=False, **kwargs):
        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
719

720
721
    def predict_proba(self, X, raw_score=False, num_iteration=-1,
                      pred_leaf=False, pred_contrib=False, **kwargs):
722
        """Return the predicted probability for each class for each sample.
wxchan's avatar
wxchan committed
723
724
725

        Parameters
        ----------
726
        X : array-like or sparse matrix of shape = [n_samples, n_features]
wxchan's avatar
wxchan committed
727
            Input features matrix.
728
729
        raw_score : bool, optional (default=False)
            Whether to predict raw scores.
730
731
732
733
734
735
736
737
        num_iteration : int, optional (default=-1)
            Limit number of iterations in the prediction.
            If <= 0, uses all trees (no limits).
        pred_leaf : bool, optional (default=False)
            Whether to predict leaf index.
        pred_contrib : bool, optional (default=False)
            Whether to predict feature contributions.
        **kwargs : other parameters for the prediction
wxchan's avatar
wxchan committed
738
739
740

        Returns
        -------
741
742
        predicted_probability : array-like of shape = [n_samples, n_classes]
            The predicted probability for each class for each sample.
743
744
745
746
        X_leaves : array-like of shape = [n_samples, n_trees * n_classes]
            If ``pred_leaf=True``, the predicted leaf every tree for each sample.
        X_SHAP_values : array-like of shape = [n_samples, (n_features + 1) * n_classes]
            If ``pred_contrib=True``, the each feature contributions for each sample.
wxchan's avatar
wxchan committed
747
        """
748
749
750
751
        result = super(LGBMClassifier, self).predict(X, raw_score, num_iteration,
                                                     pred_leaf, pred_contrib, **kwargs)
        if self._n_classes > 2 or pred_leaf or pred_contrib:
            return result
wxchan's avatar
wxchan committed
752
        else:
753
            return np.vstack((1. - result, result)).transpose()
754
755
756

    @property
    def classes_(self):
757
758
759
760
        """Get the class label array."""
        if self._classes is None:
            raise LGBMNotFittedError('No classes found. Need to call fit beforehand.')
        return self._classes
761
762
763

    @property
    def n_classes_(self):
764
765
766
767
        """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
768

wxchan's avatar
wxchan committed
769

wxchan's avatar
wxchan committed
770
class LGBMRanker(LGBMModel):
771
    """LightGBM ranker."""
wxchan's avatar
wxchan committed
772

Guolin Ke's avatar
Guolin Ke committed
773
    def fit(self, X, y,
774
            sample_weight=None, init_score=None, group=None,
775
            eval_set=None, eval_names=None, eval_sample_weight=None,
776
777
778
779
            eval_init_score=None, eval_group=None, eval_metric='ndcg',
            eval_at=[1], early_stopping_rounds=None, verbose=True,
            feature_name='auto', categorical_feature='auto', callbacks=None):
        # check group data
Guolin Ke's avatar
Guolin Ke committed
780
        if group is None:
781
            raise ValueError("Should set group for ranking task")
wxchan's avatar
wxchan committed
782
783

        if eval_set is not None:
Guolin Ke's avatar
Guolin Ke committed
784
            if eval_group is None:
785
                raise ValueError("Eval_group cannot be None when eval_set is not None")
Guolin Ke's avatar
Guolin Ke committed
786
            elif len(eval_group) != len(eval_set):
787
                raise ValueError("Length of eval_group should be equal to eval_set")
wxchan's avatar
wxchan committed
788
            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)))) \
wxchan's avatar
wxchan committed
789
                    or (isinstance(eval_group, list) and any(group is None for group in eval_group)):
790
791
                raise ValueError("Should set group for all eval datasets for ranking task; "
                                 "if you use dict, the index should start from 0")
792

793
        self._eval_at = eval_at
794
795
        super(LGBMRanker, self).fit(X, y, sample_weight=sample_weight,
                                    init_score=init_score, group=group,
796
797
                                    eval_set=eval_set, eval_names=eval_names,
                                    eval_sample_weight=eval_sample_weight,
798
799
800
801
                                    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,
802
                                    categorical_feature=categorical_feature,
803
                                    callbacks=callbacks)
wxchan's avatar
wxchan committed
804
        return self
805

806
807
808
809
810
    _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__
    fit.__doc__ = (_base_doc[:_base_doc.find('eval_metric :')]
811
                   + 'eval_metric : string, list of strings, callable or None, optional (default="ndcg")\n'
812
                   + _base_doc[_base_doc.find('            If string, it should be a built-in evaluation metric to use.'):_base_doc.find('early_stopping_rounds :')]
813
                   + 'eval_at : list of int, optional (default=[1])\n'
814
                     '            The evaluation positions of the specified metric.\n'
815
                   + _base_doc[_base_doc.find('        early_stopping_rounds :'):])