sklearn.py 35.3 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
9
10
11
12
try:
    import pandas as pd
    _IS_PANDAS_INSTALLED = True
except ImportError:
    _IS_PANDAS_INSTALLED = False
13

wxchan's avatar
wxchan committed
14
from .basic import Dataset, LightGBMError
15
from .compat import (SKLEARN_INSTALLED, _LGBMClassifierBase,
16
17
18
                     LGBMNotFittedError, _LGBMLabelEncoder, _LGBMModelBase,
                     _LGBMRegressorBase, _LGBMCheckXY, _LGBMCheckArray, _LGBMCheckConsistentLength,
                     _LGBMCheckClassificationTargets, argc_, range_)
wxchan's avatar
wxchan committed
19
from .engine import train
20

wxchan's avatar
wxchan committed
21

22
23
24
25
26
# DeprecationWarning is not shown by default, so let's create our own with higher level
class LGBMDeprecationWarning(UserWarning):
    pass


27
def _objective_function_wrapper(func):
wxchan's avatar
wxchan committed
28
    """Decorate an objective function
29
30
31
32
    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
33
34
35
    Parameters
    ----------
    func: callable
36
        Expects a callable with signature ``func(y_true, y_pred)`` or ``func(y_true, y_pred, group):
37
38
39
40
41
42
            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
43
44
45
46
47
48
49

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

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

wxchan's avatar
wxchan committed
86

87
88
def _eval_function_wrapper(func):
    """Decorate an eval function
89
90
91
    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].

92
93
94
    Parameters
    ----------
    func: callable
95
96
97
98
99
        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):
100

101
102
103
104
105
106
107
108
            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.
109
110
111
112
113
114
115

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

116
117
        preds: array-like of shape = [n_samples] or shape = [n_samples * n_classes]
            The predicted values.
118
119
        dataset: ``dataset``
            The training set from which the labels will be extracted using
120
            ``dataset.get_label()``.
121
122
123
124
    """
    def inner(preds, dataset):
        """internal function"""
        labels = dataset.get_label()
wxchan's avatar
wxchan committed
125
        argc = argc_(func)
126
127
128
129
130
131
132
        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
133
            raise TypeError("Self-defined eval function should have 2, 3 or 4 arguments, got %d" % argc)
134
135
    return inner

wxchan's avatar
wxchan committed
136

137
138
class LGBMModel(_LGBMModelBase):
    """Implementation of the scikit-learn API for LightGBM."""
wxchan's avatar
wxchan committed
139

140
    def __init__(self, boosting_type="gbdt", num_leaves=31, max_depth=-1,
wxchan's avatar
wxchan committed
141
                 learning_rate=0.1, n_estimators=10, max_bin=255,
142
143
                 subsample_for_bin=200000, objective=None,
                 min_split_gain=0., min_child_weight=1e-3, min_child_samples=20,
144
                 subsample=1., subsample_freq=1, colsample_bytree=1.,
145
                 reg_alpha=0., reg_lambda=0., random_state=None,
146
                 n_jobs=-1, silent=True, **kwargs):
147
        """Construct a gradient boosting model.
wxchan's avatar
wxchan committed
148
149
150

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

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

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

wxchan's avatar
wxchan committed
223
224
225
226
        Note
        ----
        A custom objective function can be provided for the ``objective``
        parameter. In this case, it should have the signature
227
228
        ``objective(y_true, y_pred) -> grad, hess`` or
        ``objective(y_true, y_pred, group) -> grad, hess``:
wxchan's avatar
wxchan committed
229

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

241
242
243
        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
244
        """
wxchan's avatar
wxchan committed
245
        if not SKLEARN_INSTALLED:
246
            raise LightGBMError('Scikit-learn is required for this module')
wxchan's avatar
wxchan committed
247

248
        self.boosting_type = boosting_type
249
        self.objective = objective
wxchan's avatar
wxchan committed
250
251
252
253
254
        self.num_leaves = num_leaves
        self.max_depth = max_depth
        self.learning_rate = learning_rate
        self.n_estimators = n_estimators
        self.max_bin = max_bin
wxchan's avatar
wxchan committed
255
        self.subsample_for_bin = subsample_for_bin
wxchan's avatar
wxchan committed
256
257
258
259
260
261
262
263
        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
264
265
        self.random_state = random_state
        self.n_jobs = n_jobs
wxchan's avatar
wxchan committed
266
        self.silent = silent
wxchan's avatar
wxchan committed
267
        self._Booster = None
268
269
270
271
272
273
274
275
        self._evals_result = None
        self._best_score = None
        self._best_iteration = None
        self._other_params = {}
        self._objective = None
        self._n_features = None
        self._classes = None
        self._n_classes = None
276
        self.set_params(**kwargs)
wxchan's avatar
wxchan committed
277
278
279

    def get_params(self, deep=True):
        params = super(LGBMModel, self).get_params(deep=deep)
280
        params.update(self._other_params)
281
282
283
284
285
286
        if 'seed' in params:
            warnings.warn('The `seed` parameter is deprecated and will be removed in next version. '
                          'Please use `random_state` instead.', LGBMDeprecationWarning)
        if 'nthread' in params:
            warnings.warn('The `nthread` parameter is deprecated and will be removed in next version. '
                          'Please use `n_jobs` instead.', LGBMDeprecationWarning)
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
            self._other_params[key] = value
wxchan's avatar
wxchan committed
294
        return self
wxchan's avatar
wxchan committed
295

Guolin Ke's avatar
Guolin Ke committed
296
    def fit(self, X, y,
297
            sample_weight=None, init_score=None, group=None,
298
            eval_set=None, eval_names=None, eval_sample_weight=None,
299
300
301
302
            eval_init_score=None, eval_group=None, eval_metric=None,
            early_stopping_rounds=None, verbose=True, feature_name='auto',
            categorical_feature='auto', callbacks=None):
        """Build a gradient boosting model from the training set (X, y).
wxchan's avatar
wxchan committed
303
304
305

        Parameters
        ----------
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
        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.
        group : array-like of shape = [n_samples] or None, optional (default=None)
            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.
        eval_names: list of strings or None, optional (default=None)
            Names of eval_set.
        eval_sample_weight : list of arrays or None, optional (default=None)
            Weights of eval data.
        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.
        early_stopping_rounds : int or None, optional (default=None)
            Activates early stopping. The model will train until the validation score stops improving.
331
            Validation error needs to decrease at least every ``early_stopping_rounds`` round(s)
332
333
334
335
336
337
338
339
340
            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.
341
            If list of strings, interpreted as feature names (need to specify ``feature_name`` as well).
342
343
            If 'auto' and data is pandas DataFrame, pandas categorical columns are used.
        callbacks : list of callback functions or None, optional (default=None)
344
            List of callback functions that are applied at each iteration.
345
            See Callbacks in Python API for more information.
346

347
348
349
350
351
        Returns
        -------
        self : object
            Returns self.

352
353
        Note
        ----
wxchan's avatar
wxchan committed
354
        Custom eval function expects a callable with following functions:
355
356
357
358
359
360
361
362
363
364
365
366
367
        ``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.
368
            eval_name: str
369
                The name of evaluation.
370
            eval_result: float
371
                The eval result.
372
            is_bigger_better: bool
373
                Is eval result bigger better, e.g. AUC is bigger_better.
374

375
376
        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
377
        """
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
        if not hasattr(self, '_objective'):
            self._objective = self.objective
        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
393
394
        evals_result = {}
        params = self.get_params()
395
396
397
        # sklearn interface has another naming convention
        params.setdefault('seed', params.pop('random_state'))
        params.setdefault('nthread', params.pop('n_jobs'))
wxchan's avatar
wxchan committed
398
399
400
401
402
        # user can set verbose with kwargs, it has higher priority
        if 'verbose' not in params and self.silent:
            params['verbose'] = -1
        params.pop('silent', None)
        params.pop('n_estimators', None)
403
404
405
406
407
408
        if self._n_classes is not None and self._n_classes > 2:
            params['num_class'] = self._n_classes
        if hasattr(self, '_eval_at'):
            params['ndcg_eval_at'] = self._eval_at
        params['objective'] = self._objective
        if self._fobj:
wxchan's avatar
wxchan committed
409
            params['objective'] = 'None'  # objective = nullptr for unknown objective
wxchan's avatar
wxchan committed
410
411

        if callable(eval_metric):
412
            feval = _eval_function_wrapper(eval_metric)
wxchan's avatar
wxchan committed
413
414
        else:
            feval = None
415
            params['metric'] = eval_metric
wxchan's avatar
wxchan committed
416

417
418
419
420
        if not _IS_PANDAS_INSTALLED or not isinstance(X, pd.DataFrame):
            X, y = _LGBMCheckXY(X, y, accept_sparse=True, force_all_finite=False, ensure_min_samples=2)
            _LGBMCheckConsistentLength(X, y, sample_weight)

421
422
        self._n_features = X.shape[1]

Guolin Ke's avatar
Guolin Ke committed
423
        def _construct_dataset(X, y, sample_weight, init_score, group, params):
Guolin Ke's avatar
Guolin Ke committed
424
            ret = Dataset(X, label=y, max_bin=self.max_bin, weight=sample_weight, group=group, params=params)
Guolin Ke's avatar
Guolin Ke committed
425
426
427
            ret.set_init_score(init_score)
            return ret

Guolin Ke's avatar
Guolin Ke committed
428
        train_set = _construct_dataset(X, y, sample_weight, init_score, group, params)
Guolin Ke's avatar
Guolin Ke committed
429
430
431
432
433
434
435
436
437
438

        valid_sets = []
        if eval_set is not None:
            if isinstance(eval_set, tuple):
                eval_set = [eval_set]
            for i, valid_data in enumerate(eval_set):
                """reduce cost for prediction training data"""
                if valid_data[0] is X and valid_data[1] is y:
                    valid_set = train_set
                else:
Tsukasa OMOTO's avatar
Tsukasa OMOTO committed
439
440
441
442
                    def get_meta_data(collection, i):
                        if collection is None:
                            return None
                        elif isinstance(collection, list):
443
                            return collection[i] if len(collection) > i else None
Tsukasa OMOTO's avatar
Tsukasa OMOTO committed
444
445
446
447
448
449
450
                        elif isinstance(collection, dict):
                            return collection.get(i, None)
                        else:
                            raise TypeError('eval_sample_weight, eval_init_score, and eval_group should be dict or list')
                    valid_weight = get_meta_data(eval_sample_weight, i)
                    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
451
                    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
452
453
454
                valid_sets.append(valid_set)

        self._Booster = train(params, train_set,
455
                              self.n_estimators, valid_sets=valid_sets, valid_names=eval_names,
wxchan's avatar
wxchan committed
456
                              early_stopping_rounds=early_stopping_rounds,
457
                              evals_result=evals_result, fobj=self._fobj, feval=feval,
Guolin Ke's avatar
Guolin Ke committed
458
                              verbose_eval=verbose, feature_name=feature_name,
459
                              categorical_feature=categorical_feature,
460
                              callbacks=callbacks)
wxchan's avatar
wxchan committed
461
462

        if evals_result:
463
            self._evals_result = evals_result
wxchan's avatar
wxchan committed
464
465

        if early_stopping_rounds is not None:
466
            self._best_iteration = self._Booster.best_iteration
467
468

        self._best_score = self._Booster.best_score
wxchan's avatar
wxchan committed
469
470
471
472

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

475
    def predict(self, X, raw_score=False, num_iteration=0):
476
        """Return the predicted value for each sample.
wxchan's avatar
wxchan committed
477
478
479

        Parameters
        ----------
480
        X : array-like or sparse matrix of shape = [n_samples, n_features]
wxchan's avatar
wxchan committed
481
            Input features matrix.
482
483
484
        raw_score : bool, optional (default=False)
            Whether to predict raw scores.
        num_iteration : int, optional (default=0)
wxchan's avatar
wxchan committed
485
486
487
488
            Limit number of iterations in the prediction; defaults to 0 (use all trees).

        Returns
        -------
489
490
        predicted_result : array-like of shape = [n_samples] or shape = [n_samples, n_classes]
            The predicted values.
wxchan's avatar
wxchan committed
491
        """
492
493
        if self._n_features is None:
            raise LGBMNotFittedError("Estimator not fitted, call `fit` before exploiting the model.")
494
495
        if not _IS_PANDAS_INSTALLED or not isinstance(X, pd.DataFrame):
            X = _LGBMCheckArray(X, accept_sparse=True, force_all_finite=False)
496
497
498
499
500
501
        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))
502
        return self.booster_.predict(X, raw_score=raw_score, num_iteration=num_iteration)
wxchan's avatar
wxchan committed
503
504

    def apply(self, X, num_iteration=0):
505
        """Return the predicted leaf every tree for each sample.
wxchan's avatar
wxchan committed
506
507
508

        Parameters
        ----------
509
        X : array-like or sparse matrix of shape = [n_samples, n_features]
wxchan's avatar
wxchan committed
510
            Input features matrix.
511
        num_iteration : int, optional (default=0)
wxchan's avatar
wxchan committed
512
            Limit number of iterations in the prediction; defaults to 0 (use all trees).
wxchan's avatar
wxchan committed
513
514
515

        Returns
        -------
516
517
        X_leaves : array-like of shape = [n_samples, n_trees]
            The predicted leaf every tree for each sample.
wxchan's avatar
wxchan committed
518
        """
519
520
        if self._n_features is None:
            raise LGBMNotFittedError("Estimator not fitted, call `fit` before exploiting the model.")
521
522
        if not _IS_PANDAS_INSTALLED or not isinstance(X, pd.DataFrame):
            X = _LGBMCheckArray(X, accept_sparse=True, force_all_finite=False)
523
524
525
526
527
528
        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))
529
        return self.booster_.predict(X, pred_leaf=True, num_iteration=num_iteration)
wxchan's avatar
wxchan committed
530

531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
    @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

559
560
561
562
    @property
    def booster_(self):
        """Get the underlying lightgbm Booster of this model."""
        if self._Booster is None:
563
            raise LGBMNotFittedError('No booster found. Need to call fit beforehand.')
564
        return self._Booster
wxchan's avatar
wxchan committed
565

566
567
568
    @property
    def evals_result_(self):
        """Get the evaluation results."""
569
570
571
        if self._n_features is None:
            raise LGBMNotFittedError('No results found. Need to call fit with eval_set beforehand.')
        return self._evals_result
572
573

    @property
574
    def feature_importances_(self):
575
        """Get feature importances.
576

577
578
579
        Note
        ----
        Feature importance in sklearn interface used to normalize to 1,
580
        it's deprecated after 2.0.4 and same as Booster.feature_importance() now.
581
        """
582
583
        if self._n_features is None:
            raise LGBMNotFittedError('No feature_importances found. Need to call fit beforehand.')
584
        return self.booster_.feature_importance()
wxchan's avatar
wxchan committed
585

586
    def booster(self):
587
588
        warnings.warn('The `booster()` method is deprecated and will be removed in next version. '
                      'Please use attribute `booster_` instead.', LGBMDeprecationWarning)
589
        return self.booster_
wxchan's avatar
wxchan committed
590

591
    def feature_importance(self):
592
593
        warnings.warn('The `feature_importance()` method is deprecated and will be removed in next version. '
                      'Please use attribute `feature_importances_` instead.', LGBMDeprecationWarning)
594
        return self.feature_importances_
wxchan's avatar
wxchan committed
595

wxchan's avatar
wxchan committed
596

597
598
class LGBMRegressor(LGBMModel, _LGBMRegressorBase):
    """LightGBM regressor."""
wxchan's avatar
wxchan committed
599

Guolin Ke's avatar
Guolin Ke committed
600
601
    def fit(self, X, y,
            sample_weight=None, init_score=None,
602
            eval_set=None, eval_names=None, eval_sample_weight=None,
603
604
            eval_init_score=None, eval_metric="l2", early_stopping_rounds=None,
            verbose=True, feature_name='auto', categorical_feature='auto', callbacks=None):
605
606
607

        super(LGBMRegressor, self).fit(X, y, sample_weight=sample_weight,
                                       init_score=init_score, eval_set=eval_set,
608
                                       eval_names=eval_names,
609
610
611
612
613
                                       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,
614
                                       categorical_feature=categorical_feature,
Guolin Ke's avatar
Guolin Ke committed
615
                                       callbacks=callbacks)
Guolin Ke's avatar
Guolin Ke committed
616
617
        return self

618
619
620
621
    base_doc = LGBMModel.fit.__doc__
    fit.__doc__ = (base_doc[:base_doc.find('eval_metric :')] +
                   'eval_metric : string, list of strings, callable or None, optional (default="l2")\n' +
                   base_doc[base_doc.find('            If string, it should be a built-in evaluation metric to use.'):])
wxchan's avatar
wxchan committed
622

623
624
625

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

Guolin Ke's avatar
Guolin Ke committed
627
628
    def fit(self, X, y,
            sample_weight=None, init_score=None,
629
            eval_set=None, eval_names=None, eval_sample_weight=None,
630
            eval_init_score=None, eval_metric="logloss",
wxchan's avatar
wxchan committed
631
            early_stopping_rounds=None, verbose=True,
632
633
634
            feature_name='auto', categorical_feature='auto', callbacks=None):
        _LGBMCheckClassificationTargets(y)
        self._le = _LGBMLabelEncoder().fit(y)
635
        _y = self._le.transform(y)
636

637
638
639
        self._classes = self._le.classes_
        self._n_classes = len(self._classes)
        if self._n_classes > 2:
wxchan's avatar
wxchan committed
640
            # Switch to using a multiclass objective in the underlying LGBM instance
641
            self._objective = "multiclass"
wxchan's avatar
wxchan committed
642
            if eval_metric == 'logloss' or eval_metric == 'binary_logloss':
wxchan's avatar
wxchan committed
643
                eval_metric = "multi_logloss"
wxchan's avatar
wxchan committed
644
645
646
647
648
649
650
            elif eval_metric == 'error' or eval_metric == 'binary_error':
                eval_metric = "multi_error"
        else:
            if eval_metric == 'logloss' or eval_metric == 'multi_logloss':
                eval_metric = 'binary_logloss'
            elif eval_metric == 'error' or eval_metric == 'multi_error':
                eval_metric = 'binary_error'
wxchan's avatar
wxchan committed
651
652

        if eval_set is not None:
653
654
655
656
657
658
659
            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))
660

661
        super(LGBMClassifier, self).fit(X, _y, sample_weight=sample_weight,
662
                                        init_score=init_score, eval_set=eval_set,
663
                                        eval_names=eval_names,
664
665
666
667
668
                                        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,
669
                                        categorical_feature=categorical_feature,
670
                                        callbacks=callbacks)
wxchan's avatar
wxchan committed
671
672
        return self

673
674
675
676
677
    base_doc = LGBMModel.fit.__doc__
    fit.__doc__ = (base_doc[:base_doc.find('eval_metric :')] +
                   'eval_metric : string, list of strings, callable or None, optional (default="logloss")\n' +
                   base_doc[base_doc.find('            If string, it should be a built-in evaluation metric to use.'):])

678
679
680
681
    def predict(self, X, raw_score=False, num_iteration=0):
        class_probs = self.predict_proba(X, raw_score, num_iteration)
        class_index = np.argmax(class_probs, axis=1)
        return self._le.inverse_transform(class_index)
wxchan's avatar
wxchan committed
682

683
    def predict_proba(self, X, raw_score=False, num_iteration=0):
684
        """Return the predicted probability for each class for each sample.
wxchan's avatar
wxchan committed
685
686
687

        Parameters
        ----------
688
        X : array-like or sparse matrix of shape = [n_samples, n_features]
wxchan's avatar
wxchan committed
689
            Input features matrix.
690
691
692
        raw_score : bool, optional (default=False)
            Whether to predict raw scores.
        num_iteration : int, optional (default=0)
wxchan's avatar
wxchan committed
693
694
695
696
            Limit number of iterations in the prediction; defaults to 0 (use all trees).

        Returns
        -------
697
698
        predicted_probability : array-like of shape = [n_samples, n_classes]
            The predicted probability for each class for each sample.
wxchan's avatar
wxchan committed
699
        """
700
701
        if self._n_features is None:
            raise LGBMNotFittedError("Estimator not fitted, call `fit` before exploiting the model.")
702
703
        if not _IS_PANDAS_INSTALLED or not isinstance(X, pd.DataFrame):
            X = _LGBMCheckArray(X, accept_sparse=True, force_all_finite=False)
704
705
706
707
708
709
        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))
710
        class_probs = self.booster_.predict(X, raw_score=raw_score, num_iteration=num_iteration)
711
        if self._n_classes > 2:
wxchan's avatar
wxchan committed
712
713
            return class_probs
        else:
714
715
716
717
            return np.vstack((1. - class_probs, class_probs)).transpose()

    @property
    def classes_(self):
718
719
720
721
        """Get the class label array."""
        if self._classes is None:
            raise LGBMNotFittedError('No classes found. Need to call fit beforehand.')
        return self._classes
722
723
724

    @property
    def n_classes_(self):
725
726
727
728
        """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
729

wxchan's avatar
wxchan committed
730

wxchan's avatar
wxchan committed
731
class LGBMRanker(LGBMModel):
732
    """LightGBM ranker."""
wxchan's avatar
wxchan committed
733

Guolin Ke's avatar
Guolin Ke committed
734
    def fit(self, X, y,
735
            sample_weight=None, init_score=None, group=None,
736
            eval_set=None, eval_names=None, eval_sample_weight=None,
737
738
739
740
            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
741
        if group is None:
742
            raise ValueError("Should set group for ranking task")
wxchan's avatar
wxchan committed
743
744

        if eval_set is not None:
Guolin Ke's avatar
Guolin Ke committed
745
            if eval_group is None:
746
                raise ValueError("Eval_group cannot be None when eval_set is not None")
Guolin Ke's avatar
Guolin Ke committed
747
            elif len(eval_group) != len(eval_set):
748
                raise ValueError("Length of eval_group should be equal to eval_set")
wxchan's avatar
wxchan committed
749
            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
750
                    or (isinstance(eval_group, list) and any(group is None for group in eval_group)):
751
752
                raise ValueError("Should set group for all eval datasets for ranking task; "
                                 "if you use dict, the index should start from 0")
753

754
        self._eval_at = eval_at
755
756
        super(LGBMRanker, self).fit(X, y, sample_weight=sample_weight,
                                    init_score=init_score, group=group,
757
758
                                    eval_set=eval_set, eval_names=eval_names,
                                    eval_sample_weight=eval_sample_weight,
759
760
761
762
                                    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,
763
                                    categorical_feature=categorical_feature,
764
                                    callbacks=callbacks)
wxchan's avatar
wxchan committed
765
        return self
766
767
768
769
770
771
772
773

    base_doc = LGBMModel.fit.__doc__
    fit.__doc__ = (base_doc[:base_doc.find('eval_metric :')] +
                   'eval_metric : string, list of strings, callable or None, optional (default="ndcg")\n' +
                   base_doc[base_doc.find('            If string, it should be a built-in evaluation metric to use.'):base_doc.find('early_stopping_rounds :')] +
                   'eval_at : list of int, optional (default=[1])\n'
                   '            The evaluation positions of NDCG.\n' +
                   base_doc[base_doc.find('        early_stopping_rounds :'):])