basic.py 95.9 KB
Newer Older
wxchan's avatar
wxchan committed
1
# coding: utf-8
2
3
# pylint: disable = invalid-name, C0111, C0301
# pylint: disable = R0912, R0913, R0914, W0105, W0201, W0212
4
"""Wrapper for C API of LightGBM."""
wxchan's avatar
wxchan committed
5
6
from __future__ import absolute_import

7
import copy
wxchan's avatar
wxchan committed
8
import ctypes
9
import os
wxchan's avatar
wxchan committed
10
import warnings
wxchan's avatar
wxchan committed
11
from tempfile import NamedTemporaryFile
wxchan's avatar
wxchan committed
12
13
14
15

import numpy as np
import scipy.sparse

16
17
18
from .compat import (DataFrame, Series,
                     decode_string, string_type,
                     integer_types, numeric_types,
19
                     json, json_default_with_numpy,
20
                     range_, zip_)
wxchan's avatar
wxchan committed
21
22
from .libpath import find_lib_path

wxchan's avatar
wxchan committed
23

wxchan's avatar
wxchan committed
24
def _load_lib():
25
    """Load LightGBM library."""
wxchan's avatar
wxchan committed
26
27
    lib_path = find_lib_path()
    if len(lib_path) == 0:
28
        return None
wxchan's avatar
wxchan committed
29
30
31
32
    lib = ctypes.cdll.LoadLibrary(lib_path[0])
    lib.LGBM_GetLastError.restype = ctypes.c_char_p
    return lib

wxchan's avatar
wxchan committed
33

wxchan's avatar
wxchan committed
34
35
_LIB = _load_lib()

wxchan's avatar
wxchan committed
36

wxchan's avatar
wxchan committed
37
def _safe_call(ret):
38
39
    """Check the return value from C API call.

wxchan's avatar
wxchan committed
40
41
42
    Parameters
    ----------
    ret : int
43
        The return value from C API calls.
wxchan's avatar
wxchan committed
44
45
    """
    if ret != 0:
46
        raise LightGBMError(decode_string(_LIB.LGBM_GetLastError()))
wxchan's avatar
wxchan committed
47

wxchan's avatar
wxchan committed
48

wxchan's avatar
wxchan committed
49
def is_numeric(obj):
50
    """Check whether object is a number or not, include numpy number, etc."""
wxchan's avatar
wxchan committed
51
52
53
    try:
        float(obj)
        return True
wxchan's avatar
wxchan committed
54
55
56
    except (TypeError, ValueError):
        # TypeError: obj is not a string or a number
        # ValueError: invalid literal
wxchan's avatar
wxchan committed
57
58
        return False

wxchan's avatar
wxchan committed
59

wxchan's avatar
wxchan committed
60
def is_numpy_1d_array(data):
61
    """Check whether data is a 1-D numpy array."""
62
    return isinstance(data, np.ndarray) and len(data.shape) == 1
wxchan's avatar
wxchan committed
63

wxchan's avatar
wxchan committed
64

wxchan's avatar
wxchan committed
65
def is_1d_list(data):
66
67
    """Check whether data is a 1-D list."""
    return isinstance(data, list) and (not data or is_numeric(data[0]))
wxchan's avatar
wxchan committed
68

wxchan's avatar
wxchan committed
69

70
def list_to_1d_numpy(data, dtype=np.float32, name='list'):
71
    """Convert data to 1-D numpy array."""
wxchan's avatar
wxchan committed
72
73
74
75
76
77
78
    if is_numpy_1d_array(data):
        if data.dtype == dtype:
            return data
        else:
            return data.astype(dtype=dtype, copy=False)
    elif is_1d_list(data):
        return np.array(data, dtype=dtype, copy=False)
79
80
    elif isinstance(data, Series):
        return data.values.astype(dtype)
wxchan's avatar
wxchan committed
81
    else:
82
83
        raise TypeError("Wrong type({0}) for {1}.\n"
                        "It should be list, numpy 1-D array or pandas Series".format(type(data).__name__, name))
wxchan's avatar
wxchan committed
84

wxchan's avatar
wxchan committed
85

wxchan's avatar
wxchan committed
86
def cfloat32_array_to_numpy(cptr, length):
87
    """Convert a ctypes float pointer array to a numpy array."""
wxchan's avatar
wxchan committed
88
    if isinstance(cptr, ctypes.POINTER(ctypes.c_float)):
89
        return np.fromiter(cptr, dtype=np.float32, count=length)
wxchan's avatar
wxchan committed
90
    else:
91
        raise RuntimeError('Expected float pointer')
wxchan's avatar
wxchan committed
92

Guolin Ke's avatar
Guolin Ke committed
93

Guolin Ke's avatar
Guolin Ke committed
94
def cfloat64_array_to_numpy(cptr, length):
95
    """Convert a ctypes double pointer array to a numpy array."""
Guolin Ke's avatar
Guolin Ke committed
96
97
98
99
100
    if isinstance(cptr, ctypes.POINTER(ctypes.c_double)):
        return np.fromiter(cptr, dtype=np.float64, count=length)
    else:
        raise RuntimeError('Expected double pointer')

wxchan's avatar
wxchan committed
101

wxchan's avatar
wxchan committed
102
def cint32_array_to_numpy(cptr, length):
103
    """Convert a ctypes int pointer array to a numpy array."""
wxchan's avatar
wxchan committed
104
    if isinstance(cptr, ctypes.POINTER(ctypes.c_int32)):
105
        return np.fromiter(cptr, dtype=np.int32, count=length)
wxchan's avatar
wxchan committed
106
    else:
107
        raise RuntimeError('Expected int pointer')
wxchan's avatar
wxchan committed
108

wxchan's avatar
wxchan committed
109

wxchan's avatar
wxchan committed
110
def c_str(string):
111
    """Convert a Python string to C string."""
wxchan's avatar
wxchan committed
112
113
    return ctypes.c_char_p(string.encode('utf-8'))

wxchan's avatar
wxchan committed
114

wxchan's avatar
wxchan committed
115
def c_array(ctype, values):
116
    """Convert a Python array to C array."""
wxchan's avatar
wxchan committed
117
118
    return (ctype * len(values))(*values)

wxchan's avatar
wxchan committed
119

wxchan's avatar
wxchan committed
120
def param_dict_to_str(data):
121
    """Convert Python dictionary to string, which is passed to C API."""
122
    if data is None or not data:
wxchan's avatar
wxchan committed
123
124
125
        return ""
    pairs = []
    for key, val in data.items():
126
        if isinstance(val, (list, tuple, set)) or is_numpy_1d_array(val):
wxchan's avatar
wxchan committed
127
            pairs.append(str(key) + '=' + ','.join(map(str, val)))
wxchan's avatar
wxchan committed
128
        elif isinstance(val, string_type) or isinstance(val, numeric_types) or is_numeric(val):
wxchan's avatar
wxchan committed
129
            pairs.append(str(key) + '=' + str(val))
130
        elif val is not None:
131
            raise TypeError('Unknown type of parameter:%s, got:%s'
wxchan's avatar
wxchan committed
132
133
                            % (key, type(val).__name__))
    return ' '.join(pairs)
134

wxchan's avatar
wxchan committed
135

136
class _TempFile(object):
137
138
139
140
    def __enter__(self):
        with NamedTemporaryFile(prefix="lightgbm_tmp_", delete=True) as f:
            self.name = f.name
        return self
wxchan's avatar
wxchan committed
141

142
143
144
    def __exit__(self, exc_type, exc_val, exc_tb):
        if os.path.isfile(self.name):
            os.remove(self.name)
wxchan's avatar
wxchan committed
145

146
147
148
149
    def readlines(self):
        with open(self.name, "r+") as f:
            ret = f.readlines()
        return ret
wxchan's avatar
wxchan committed
150

151
152
    def writelines(self, lines):
        with open(self.name, "w+") as f:
153
            f.writelines(lines)
154

wxchan's avatar
wxchan committed
155

156
class LightGBMError(Exception):
157
158
    """Error thrown by LightGBM."""

159
160
161
162
163
    pass


MAX_INT32 = (1 << 31) - 1

164
"""Macro definition of data type in C API of LightGBM"""
wxchan's avatar
wxchan committed
165
166
167
168
C_API_DTYPE_FLOAT32 = 0
C_API_DTYPE_FLOAT64 = 1
C_API_DTYPE_INT32 = 2
C_API_DTYPE_INT64 = 3
Guolin Ke's avatar
Guolin Ke committed
169

170
"""Matrix is row major in Python"""
wxchan's avatar
wxchan committed
171
172
C_API_IS_ROW_MAJOR = 1

173
"""Macro definition of prediction type in C API of LightGBM"""
wxchan's avatar
wxchan committed
174
175
176
C_API_PREDICT_NORMAL = 0
C_API_PREDICT_RAW_SCORE = 1
C_API_PREDICT_LEAF_INDEX = 2
177
C_API_PREDICT_CONTRIB = 3
wxchan's avatar
wxchan committed
178

179
"""Data type of data field"""
wxchan's avatar
wxchan committed
180
181
FIELD_TYPE_MAPPER = {"label": C_API_DTYPE_FLOAT32,
                     "weight": C_API_DTYPE_FLOAT32,
Guolin Ke's avatar
Guolin Ke committed
182
                     "init_score": C_API_DTYPE_FLOAT64,
wxchan's avatar
wxchan committed
183
184
                     "group": C_API_DTYPE_INT32}

185
186
PANDAS_DTYPE_MAPPER = {'int8': 'int', 'int16': 'int', 'int32': 'int',
                       'int64': 'int', 'uint8': 'int', 'uint16': 'int',
187
188
                       'uint32': 'int', 'uint64': 'int', 'bool': 'int',
                       'float16': 'float', 'float32': 'float', 'float64': 'float'}
189

wxchan's avatar
wxchan committed
190

191
def convert_from_sliced_object(data):
192
    """Fix the memory of multi-dimensional sliced object."""
193
194
    if data.base is not None and isinstance(data, np.ndarray) and isinstance(data.base, np.ndarray):
        if not data.flags.c_contiguous:
195
196
            warnings.warn("Usage of np.ndarray subset (sliced data) is not recommended "
                          "due to it will double the peak memory cost in LightGBM.")
197
198
199
200
            return np.copy(data)
    return data


wxchan's avatar
wxchan committed
201
def c_float_array(data):
202
    """Get pointer of float numpy array / list."""
wxchan's avatar
wxchan committed
203
204
205
    if is_1d_list(data):
        data = np.array(data, copy=False)
    if is_numpy_1d_array(data):
206
207
        data = convert_from_sliced_object(data)
        assert data.flags.c_contiguous
wxchan's avatar
wxchan committed
208
209
210
211
212
213
214
        if data.dtype == np.float32:
            ptr_data = data.ctypes.data_as(ctypes.POINTER(ctypes.c_float))
            type_data = C_API_DTYPE_FLOAT32
        elif data.dtype == np.float64:
            ptr_data = data.ctypes.data_as(ctypes.POINTER(ctypes.c_double))
            type_data = C_API_DTYPE_FLOAT64
        else:
215
            raise TypeError("Expected np.float32 or np.float64, met type({})"
wxchan's avatar
wxchan committed
216
217
                            .format(data.dtype))
    else:
218
        raise TypeError("Unknown type({})".format(type(data).__name__))
219
    return (ptr_data, type_data, data)  # return `data` to avoid the temporary copy is freed
wxchan's avatar
wxchan committed
220

wxchan's avatar
wxchan committed
221

wxchan's avatar
wxchan committed
222
def c_int_array(data):
223
    """Get pointer of int numpy array / list."""
wxchan's avatar
wxchan committed
224
225
226
    if is_1d_list(data):
        data = np.array(data, copy=False)
    if is_numpy_1d_array(data):
227
228
        data = convert_from_sliced_object(data)
        assert data.flags.c_contiguous
wxchan's avatar
wxchan committed
229
230
231
232
233
234
235
        if data.dtype == np.int32:
            ptr_data = data.ctypes.data_as(ctypes.POINTER(ctypes.c_int32))
            type_data = C_API_DTYPE_INT32
        elif data.dtype == np.int64:
            ptr_data = data.ctypes.data_as(ctypes.POINTER(ctypes.c_int64))
            type_data = C_API_DTYPE_INT64
        else:
236
            raise TypeError("Expected np.int32 or np.int64, met type({})"
wxchan's avatar
wxchan committed
237
238
                            .format(data.dtype))
    else:
239
        raise TypeError("Unknown type({})".format(type(data).__name__))
240
    return (ptr_data, type_data, data)  # return `data` to avoid the temporary copy is freed
wxchan's avatar
wxchan committed
241

wxchan's avatar
wxchan committed
242

243
def _data_from_pandas(data, feature_name, categorical_feature, pandas_categorical):
244
    if isinstance(data, DataFrame):
245
246
        if len(data.shape) != 2 or data.shape[0] < 1:
            raise ValueError('Input data must be 2 dimensional and non empty.')
247
248
249
250
251
252
253
254
        if feature_name == 'auto' or feature_name is None:
            data = data.rename(columns=str)
        cat_cols = data.select_dtypes(include=['category']).columns
        if pandas_categorical is None:  # train dataset
            pandas_categorical = [list(data[col].cat.categories) for col in cat_cols]
        else:
            if len(cat_cols) != len(pandas_categorical):
                raise ValueError('train and valid dataset categorical_feature do not match.')
255
            for col, category in zip_(cat_cols, pandas_categorical):
256
257
258
259
                if list(data[col].cat.categories) != list(category):
                    data[col] = data[col].cat.set_categories(category)
        if len(cat_cols):  # cat_cols is pandas Index object
            data = data.copy()  # not alter origin DataFrame
260
            data[cat_cols] = data[cat_cols].apply(lambda x: x.cat.codes).replace({-1: np.nan})
261
262
263
264
265
266
267
268
269
270
271
272
273
274
        if categorical_feature is not None:
            if feature_name is None:
                feature_name = list(data.columns)
            if categorical_feature == 'auto':
                categorical_feature = list(cat_cols)
            else:
                categorical_feature = list(categorical_feature) + list(cat_cols)
        if feature_name == 'auto':
            feature_name = list(data.columns)
        data_dtypes = data.dtypes
        if not all(dtype.name in PANDAS_DTYPE_MAPPER for dtype in data_dtypes):
            bad_fields = [data.columns[i] for i, dtype in
                          enumerate(data_dtypes) if dtype.name not in PANDAS_DTYPE_MAPPER]

275
276
            msg = ("DataFrame.dtypes for data must be int, float or bool.\n"
                   "Did not expect the data types in fields ")
277
            raise ValueError(msg + ', '.join(bad_fields))
278
        data = data.values.astype('float')
279
280
281
282
283
284
    else:
        if feature_name == 'auto':
            feature_name = None
        if categorical_feature == 'auto':
            categorical_feature = None
    return data, feature_name, categorical_feature, pandas_categorical
285
286
287
288
289
290
291
292
293


def _label_from_pandas(label):
    if isinstance(label, DataFrame):
        if len(label.columns) > 1:
            raise ValueError('DataFrame for label cannot have multiple columns')
        label_dtypes = label.dtypes
        if not all(dtype.name in PANDAS_DTYPE_MAPPER for dtype in label_dtypes):
            raise ValueError('DataFrame.dtypes for label must be int, float or bool')
294
        label = label.values.astype('float').flatten()
295
296
297
    return label


298
299
300
301
302
303
304
305
306
307
308
def _dump_pandas_categorical(pandas_categorical, file_name=None):
    pandas_str = ('\npandas_categorical:'
                  + json.dumps(pandas_categorical, default=json_default_with_numpy)
                  + '\n')
    if file_name is not None:
        with open(file_name, 'a') as f:
            f.write(pandas_str)
    return pandas_str


def _load_pandas_categorical(file_name=None, model_str=None):
309
310
    pandas_key = 'pandas_categorical:'
    offset = -len(pandas_key)
311
    if file_name is not None:
312
313
314
315
316
317
318
319
320
321
322
323
324
        max_offset = -os.path.getsize(file_name)
        with open(file_name, 'rb') as f:
            while True:
                if offset < max_offset:
                    offset = max_offset
                f.seek(offset, os.SEEK_END)
                lines = f.readlines()
                if len(lines) >= 2:
                    break
                offset *= 2
        last_line = decode_string(lines[-1]).strip()
        if not last_line.startswith(pandas_key):
            last_line = decode_string(lines[-2]).strip()
325
    elif model_str is not None:
326
327
328
329
330
331
        idx = model_str.rfind('\n', 0, offset)
        last_line = model_str[idx:].strip()
    if last_line.startswith(pandas_key):
        return json.loads(last_line[len(pandas_key):])
    else:
        return None
332
333


Guolin Ke's avatar
Guolin Ke committed
334
class _InnerPredictor(object):
335
336
337
338
339
340
341
342
    """_InnerPredictor of LightGBM.

    Not exposed to user.
    Used only for prediction, usually used for continued training.

    Note
    ----
    Can be converted from Booster, but cannot be converted to Booster.
Guolin Ke's avatar
Guolin Ke committed
343
    """
344

345
    def __init__(self, model_file=None, booster_handle=None, pred_parameter=None):
346
        """Initialize the _InnerPredictor.
wxchan's avatar
wxchan committed
347
348
349

        Parameters
        ----------
350
        model_file : string or None, optional (default=None)
wxchan's avatar
wxchan committed
351
            Path to the model file.
352
353
354
355
        booster_handle : object or None, optional (default=None)
            Handle of Booster.
        pred_parameter: dict or None, optional (default=None)
            Other parameters for the prediciton.
wxchan's avatar
wxchan committed
356
357
358
359
360
        """
        self.handle = ctypes.c_void_p()
        self.__is_manage_handle = True
        if model_file is not None:
            """Prediction task"""
Guolin Ke's avatar
Guolin Ke committed
361
            out_num_iterations = ctypes.c_int(0)
wxchan's avatar
wxchan committed
362
363
364
365
            _safe_call(_LIB.LGBM_BoosterCreateFromModelfile(
                c_str(model_file),
                ctypes.byref(out_num_iterations),
                ctypes.byref(self.handle)))
Guolin Ke's avatar
Guolin Ke committed
366
            out_num_class = ctypes.c_int(0)
wxchan's avatar
wxchan committed
367
368
369
370
            _safe_call(_LIB.LGBM_BoosterGetNumClasses(
                self.handle,
                ctypes.byref(out_num_class)))
            self.num_class = out_num_class.value
371
            self.num_total_iteration = out_num_iterations.value
372
            self.pandas_categorical = _load_pandas_categorical(file_name=model_file)
wxchan's avatar
wxchan committed
373
        elif booster_handle is not None:
Guolin Ke's avatar
Guolin Ke committed
374
            self.__is_manage_handle = False
wxchan's avatar
wxchan committed
375
            self.handle = booster_handle
Guolin Ke's avatar
Guolin Ke committed
376
            out_num_class = ctypes.c_int(0)
wxchan's avatar
wxchan committed
377
378
379
380
            _safe_call(_LIB.LGBM_BoosterGetNumClasses(
                self.handle,
                ctypes.byref(out_num_class)))
            self.num_class = out_num_class.value
Guolin Ke's avatar
Guolin Ke committed
381
            out_num_iterations = ctypes.c_int(0)
wxchan's avatar
wxchan committed
382
383
384
            _safe_call(_LIB.LGBM_BoosterGetCurrentIteration(
                self.handle,
                ctypes.byref(out_num_iterations)))
385
            self.num_total_iteration = out_num_iterations.value
386
            self.pandas_categorical = None
wxchan's avatar
wxchan committed
387
        else:
Guolin Ke's avatar
Guolin Ke committed
388
            raise TypeError('Need Model file or Booster handle to create a predictor')
wxchan's avatar
wxchan committed
389

390
391
        pred_parameter = {} if pred_parameter is None else pred_parameter
        self.pred_parameter = param_dict_to_str(pred_parameter)
cbecker's avatar
cbecker committed
392

wxchan's avatar
wxchan committed
393
    def __del__(self):
394
395
396
397
398
        try:
            if self.__is_manage_handle:
                _safe_call(_LIB.LGBM_BoosterFree(self.handle))
        except AttributeError:
            pass
wxchan's avatar
wxchan committed
399

400
401
402
403
404
    def __getstate__(self):
        this = self.__dict__.copy()
        this.pop('handle', None)
        return this

wxchan's avatar
wxchan committed
405
    def predict(self, data, num_iteration=-1,
406
                raw_score=False, pred_leaf=False, pred_contrib=False, data_has_header=False,
wxchan's avatar
wxchan committed
407
                is_reshape=True):
408
        """Predict logic.
wxchan's avatar
wxchan committed
409
410
411

        Parameters
        ----------
412
        data : string, numpy array, pandas DataFrame or scipy.sparse
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
            Data source for prediction.
            When data type is string, it represents the path of txt file.
        num_iteration : int, optional (default=-1)
            Iteration used for prediction.
        raw_score : bool, optional (default=False)
            Whether to predict raw scores.
        pred_leaf : bool, optional (default=False)
            Whether to predict leaf index.
        pred_contrib : bool, optional (default=False)
            Whether to predict feature contributions.
        data_has_header : bool, optional (default=False)
            Whether data has header.
            Used only for txt data.
        is_reshape : bool, optional (default=True)
            Whether to reshape to (nrow, ncol).
wxchan's avatar
wxchan committed
428
429
430

        Returns
        -------
431
432
        result : numpy array
            Prediction result.
wxchan's avatar
wxchan committed
433
        """
wxchan's avatar
wxchan committed
434
        if isinstance(data, Dataset):
435
            raise TypeError("Cannot use Dataset instance for prediction, please use raw data instead")
436
        data = _data_from_pandas(data, None, None, self.pandas_categorical)[0]
wxchan's avatar
wxchan committed
437
438
439
440
441
        predict_type = C_API_PREDICT_NORMAL
        if raw_score:
            predict_type = C_API_PREDICT_RAW_SCORE
        if pred_leaf:
            predict_type = C_API_PREDICT_LEAF_INDEX
442
443
        if pred_contrib:
            predict_type = C_API_PREDICT_CONTRIB
wxchan's avatar
wxchan committed
444
        int_data_has_header = 1 if data_has_header else 0
445
446
        if num_iteration > self.num_total_iteration:
            num_iteration = self.num_total_iteration
cbecker's avatar
cbecker committed
447

wxchan's avatar
wxchan committed
448
        if isinstance(data, string_type):
449
            with _TempFile() as f:
wxchan's avatar
wxchan committed
450
451
452
                _safe_call(_LIB.LGBM_BoosterPredictForFile(
                    self.handle,
                    c_str(data),
Guolin Ke's avatar
Guolin Ke committed
453
454
455
                    ctypes.c_int(int_data_has_header),
                    ctypes.c_int(predict_type),
                    ctypes.c_int(num_iteration),
456
                    c_str(self.pred_parameter),
wxchan's avatar
wxchan committed
457
458
                    c_str(f.name)))
                lines = f.readlines()
459
460
                nrow = len(lines)
                preds = [float(token) for line in lines for token in line.split('\t')]
Guolin Ke's avatar
Guolin Ke committed
461
                preds = np.array(preds, dtype=np.float64, copy=False)
wxchan's avatar
wxchan committed
462
        elif isinstance(data, scipy.sparse.csr_matrix):
463
            preds, nrow = self.__pred_for_csr(data, num_iteration, predict_type)
Guolin Ke's avatar
Guolin Ke committed
464
        elif isinstance(data, scipy.sparse.csc_matrix):
465
            preds, nrow = self.__pred_for_csc(data, num_iteration, predict_type)
wxchan's avatar
wxchan committed
466
        elif isinstance(data, np.ndarray):
467
            preds, nrow = self.__pred_for_np2d(data, num_iteration, predict_type)
468
469
470
        elif isinstance(data, list):
            try:
                data = np.array(data)
471
            except BaseException:
472
                raise ValueError('Cannot convert data list to numpy array.')
473
            preds, nrow = self.__pred_for_np2d(data, num_iteration, predict_type)
wxchan's avatar
wxchan committed
474
475
        else:
            try:
476
                warnings.warn('Converting data to scipy sparse matrix.')
wxchan's avatar
wxchan committed
477
                csr = scipy.sparse.csr_matrix(data)
478
            except BaseException:
479
                raise TypeError('Cannot predict data for type {}'.format(type(data).__name__))
480
            preds, nrow = self.__pred_for_csr(csr, num_iteration, predict_type)
wxchan's avatar
wxchan committed
481
482
        if pred_leaf:
            preds = preds.astype(np.int32)
483
        if is_reshape and preds.size != nrow:
wxchan's avatar
wxchan committed
484
            if preds.size % nrow == 0:
485
                preds = preds.reshape(nrow, -1)
wxchan's avatar
wxchan committed
486
            else:
487
                raise ValueError('Length of predict result (%d) cannot be divide nrow (%d)'
wxchan's avatar
wxchan committed
488
489
490
491
                                 % (preds.size, nrow))
        return preds

    def __get_num_preds(self, num_iteration, nrow, predict_type):
492
        """Get size of prediction result."""
493
494
495
496
497
        if nrow > MAX_INT32:
            raise LightGBMError('LightGBM cannot perform prediction for data'
                                'with number of rows greater than MAX_INT32 (%d).\n'
                                'You can split your data into chunks'
                                'and then concatenate predictions for them' % MAX_INT32)
Guolin Ke's avatar
Guolin Ke committed
498
499
500
        n_preds = ctypes.c_int64(0)
        _safe_call(_LIB.LGBM_BoosterCalcNumPredict(
            self.handle,
Guolin Ke's avatar
Guolin Ke committed
501
502
503
            ctypes.c_int(nrow),
            ctypes.c_int(predict_type),
            ctypes.c_int(num_iteration),
Guolin Ke's avatar
Guolin Ke committed
504
505
            ctypes.byref(n_preds)))
        return n_preds.value
wxchan's avatar
wxchan committed
506
507

    def __pred_for_np2d(self, mat, num_iteration, predict_type):
508
        """Predict for a 2-D numpy matrix."""
wxchan's avatar
wxchan committed
509
        if len(mat.shape) != 2:
510
            raise ValueError('Input numpy.ndarray or list must be 2 dimensional')
wxchan's avatar
wxchan committed
511

512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
        def inner_predict(mat, num_iteration, predict_type, preds=None):
            if mat.dtype == np.float32 or mat.dtype == np.float64:
                data = np.array(mat.reshape(mat.size), dtype=mat.dtype, copy=False)
            else:
                """change non-float data to float data, need to copy"""
                data = np.array(mat.reshape(mat.size), dtype=np.float32)
            ptr_data, type_ptr_data, _ = c_float_array(data)
            n_preds = self.__get_num_preds(num_iteration, mat.shape[0], predict_type)
            if preds is None:
                preds = np.zeros(n_preds, dtype=np.float64)
            elif len(preds.shape) != 1 or len(preds) != n_preds:
                raise ValueError("Wrong length of pre-allocated predict array")
            out_num_preds = ctypes.c_int64(0)
            _safe_call(_LIB.LGBM_BoosterPredictForMat(
                self.handle,
                ptr_data,
                ctypes.c_int(type_ptr_data),
                ctypes.c_int(mat.shape[0]),
                ctypes.c_int(mat.shape[1]),
                ctypes.c_int(C_API_IS_ROW_MAJOR),
                ctypes.c_int(predict_type),
                ctypes.c_int(num_iteration),
                c_str(self.pred_parameter),
                ctypes.byref(out_num_preds),
                preds.ctypes.data_as(ctypes.POINTER(ctypes.c_double))))
            if n_preds != out_num_preds.value:
                raise ValueError("Wrong length for predict results")
            return preds, mat.shape[0]

        nrow = mat.shape[0]
        if nrow > MAX_INT32:
            sections = np.arange(start=MAX_INT32, stop=nrow, step=MAX_INT32)
            # __get_num_preds() cannot work with nrow > MAX_INT32, so calculate overall number of predictions piecemeal
            n_preds = [self.__get_num_preds(num_iteration, i, predict_type) for i in np.diff([0] + list(sections) + [nrow])]
            n_preds_sections = np.array([0] + n_preds, dtype=np.intp).cumsum()
            preds = np.zeros(sum(n_preds), dtype=np.float64)
548
549
            for chunk, (start_idx_pred, end_idx_pred) in zip_(np.array_split(mat, sections),
                                                              zip_(n_preds_sections, n_preds_sections[1:])):
550
551
552
                # avoid memory consumption by arrays concatenation operations
                inner_predict(chunk, num_iteration, predict_type, preds[start_idx_pred:end_idx_pred])
            return preds, nrow
wxchan's avatar
wxchan committed
553
        else:
554
            return inner_predict(mat, num_iteration, predict_type)
wxchan's avatar
wxchan committed
555
556

    def __pred_for_csr(self, csr, num_iteration, predict_type):
557
        """Predict for a CSR data."""
558
559
560
561
562
563
564
565
566
567
568
569
        def inner_predict(csr, num_iteration, predict_type, preds=None):
            nrow = len(csr.indptr) - 1
            n_preds = self.__get_num_preds(num_iteration, nrow, predict_type)
            if preds is None:
                preds = np.zeros(n_preds, dtype=np.float64)
            elif len(preds.shape) != 1 or len(preds) != n_preds:
                raise ValueError("Wrong length of pre-allocated predict array")
            out_num_preds = ctypes.c_int64(0)

            ptr_indptr, type_ptr_indptr, __ = c_int_array(csr.indptr)
            ptr_data, type_ptr_data, _ = c_float_array(csr.data)

570
571
572
            assert csr.shape[1] <= MAX_INT32
            csr.indices = csr.indices.astype(np.int32, copy=False)

573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
            _safe_call(_LIB.LGBM_BoosterPredictForCSR(
                self.handle,
                ptr_indptr,
                ctypes.c_int32(type_ptr_indptr),
                csr.indices.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)),
                ptr_data,
                ctypes.c_int(type_ptr_data),
                ctypes.c_int64(len(csr.indptr)),
                ctypes.c_int64(len(csr.data)),
                ctypes.c_int64(csr.shape[1]),
                ctypes.c_int(predict_type),
                ctypes.c_int(num_iteration),
                c_str(self.pred_parameter),
                ctypes.byref(out_num_preds),
                preds.ctypes.data_as(ctypes.POINTER(ctypes.c_double))))
            if n_preds != out_num_preds.value:
                raise ValueError("Wrong length for predict results")
            return preds, nrow
wxchan's avatar
wxchan committed
591

592
593
594
595
596
597
598
599
600
601
602
603
604
605
        nrow = len(csr.indptr) - 1
        if nrow > MAX_INT32:
            sections = [0] + list(np.arange(start=MAX_INT32, stop=nrow, step=MAX_INT32)) + [nrow]
            # __get_num_preds() cannot work with nrow > MAX_INT32, so calculate overall number of predictions piecemeal
            n_preds = [self.__get_num_preds(num_iteration, i, predict_type) for i in np.diff(sections)]
            n_preds_sections = np.array([0] + n_preds, dtype=np.intp).cumsum()
            preds = np.zeros(sum(n_preds), dtype=np.float64)
            for (start_idx, end_idx), (start_idx_pred, end_idx_pred) in zip_(zip_(sections, sections[1:]),
                                                                             zip_(n_preds_sections, n_preds_sections[1:])):
                # avoid memory consumption by arrays concatenation operations
                inner_predict(csr[start_idx:end_idx], num_iteration, predict_type, preds[start_idx_pred:end_idx_pred])
            return preds, nrow
        else:
            return inner_predict(csr, num_iteration, predict_type)
Guolin Ke's avatar
Guolin Ke committed
606
607

    def __pred_for_csc(self, csc, num_iteration, predict_type):
608
        """Predict for a CSC data."""
Guolin Ke's avatar
Guolin Ke committed
609
        nrow = csc.shape[0]
610
611
        if nrow > MAX_INT32:
            return self.__pred_for_csr(csc.tocsr(), num_iteration, predict_type)
Guolin Ke's avatar
Guolin Ke committed
612
613
614
615
        n_preds = self.__get_num_preds(num_iteration, nrow, predict_type)
        preds = np.zeros(n_preds, dtype=np.float64)
        out_num_preds = ctypes.c_int64(0)

616
617
        ptr_indptr, type_ptr_indptr, __ = c_int_array(csc.indptr)
        ptr_data, type_ptr_data, _ = c_float_array(csc.data)
Guolin Ke's avatar
Guolin Ke committed
618

619
620
621
        assert csc.shape[0] <= MAX_INT32
        csc.indices = csc.indices.astype(np.int32, copy=False)

Guolin Ke's avatar
Guolin Ke committed
622
623
624
        _safe_call(_LIB.LGBM_BoosterPredictForCSC(
            self.handle,
            ptr_indptr,
Guolin Ke's avatar
Guolin Ke committed
625
            ctypes.c_int32(type_ptr_indptr),
Guolin Ke's avatar
Guolin Ke committed
626
627
            csc.indices.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)),
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
628
629
630
631
632
633
            ctypes.c_int(type_ptr_data),
            ctypes.c_int64(len(csc.indptr)),
            ctypes.c_int64(len(csc.data)),
            ctypes.c_int64(csc.shape[0]),
            ctypes.c_int(predict_type),
            ctypes.c_int(num_iteration),
634
            c_str(self.pred_parameter),
Guolin Ke's avatar
Guolin Ke committed
635
            ctypes.byref(out_num_preds),
wxchan's avatar
wxchan committed
636
            preds.ctypes.data_as(ctypes.POINTER(ctypes.c_double))))
wxchan's avatar
wxchan committed
637
        if n_preds != out_num_preds.value:
638
            raise ValueError("Wrong length for predict results")
wxchan's avatar
wxchan committed
639
640
        return preds, nrow

wxchan's avatar
wxchan committed
641

wxchan's avatar
wxchan committed
642
643
class Dataset(object):
    """Dataset in LightGBM."""
644

645
    def __init__(self, data, label=None, reference=None,
646
                 weight=None, group=None, init_score=None, silent=False,
647
                 feature_name='auto', categorical_feature='auto', params=None,
wxchan's avatar
wxchan committed
648
                 free_raw_data=True):
649
        """Initialize Dataset.
650

wxchan's avatar
wxchan committed
651
652
        Parameters
        ----------
653
        data : string, numpy array, pandas DataFrame, scipy.sparse or list of numpy arrays
wxchan's avatar
wxchan committed
654
            Data source of Dataset.
655
            If string, it represents the path to txt file.
656
        label : list, numpy 1-D array, pandas Series / one-column DataFrame or None, optional (default=None)
657
658
659
            Label of the data.
        reference : Dataset or None, optional (default=None)
            If this is Dataset for validation, training data should be used as reference.
660
        weight : list, numpy 1-D array, pandas Series or None, optional (default=None)
wxchan's avatar
wxchan committed
661
            Weight for each instance.
662
        group : list, numpy 1-D array, pandas Series or None, optional (default=None)
663
            Group/query size for Dataset.
664
        init_score : list, numpy 1-D array, pandas Series or None, optional (default=None)
665
            Init score for Dataset.
666
667
668
669
670
671
672
673
674
675
        silent : bool, optional (default=False)
            Whether to print messages during construction.
        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.
            If list of strings, interpreted as feature names (need to specify ``feature_name`` as well).
            If 'auto' and data is pandas DataFrame, pandas categorical columns are used.
676
            All values in categorical features should be less than int32 max value (2147483647).
677
            Large values could be memory consuming. Consider using consecutive integers starting from zero.
678
            All negative values in categorical features will be treated as missing values.
Nikita Titov's avatar
Nikita Titov committed
679
        params : dict or None, optional (default=None)
680
            Other parameters for Dataset.
Nikita Titov's avatar
Nikita Titov committed
681
        free_raw_data : bool, optional (default=True)
682
            If True, raw data is freed after constructing inner Dataset.
wxchan's avatar
wxchan committed
683
        """
wxchan's avatar
wxchan committed
684
685
686
687
688
689
        self.handle = None
        self.data = data
        self.label = label
        self.reference = reference
        self.weight = weight
        self.group = group
690
        self.init_score = init_score
wxchan's avatar
wxchan committed
691
692
        self.silent = silent
        self.feature_name = feature_name
693
        self.categorical_feature = categorical_feature
694
        self.params = copy.deepcopy(params)
wxchan's avatar
wxchan committed
695
696
        self.free_raw_data = free_raw_data
        self.used_indices = None
697
        self.need_slice = True
wxchan's avatar
wxchan committed
698
        self._predictor = None
699
        self.pandas_categorical = None
700
        self.params_back_up = None
wxchan's avatar
wxchan committed
701
702

    def __del__(self):
703
704
705
706
        try:
            self._free_handle()
        except AttributeError:
            pass
707
708

    def _free_handle(self):
709
        if self.handle is not None:
710
            _safe_call(_LIB.LGBM_DatasetFree(self.handle))
711
            self.handle = None
Nikita Titov's avatar
Nikita Titov committed
712
        return self
wxchan's avatar
wxchan committed
713

714
    def _lazy_init(self, data, label=None, reference=None,
715
                   weight=None, group=None, init_score=None, predictor=None,
wxchan's avatar
wxchan committed
716
                   silent=False, feature_name='auto',
717
                   categorical_feature='auto', params=None):
wxchan's avatar
wxchan committed
718
719
        if data is None:
            self.handle = None
Nikita Titov's avatar
Nikita Titov committed
720
            return self
Guolin Ke's avatar
Guolin Ke committed
721
722
723
        if reference is not None:
            self.pandas_categorical = reference.pandas_categorical
            categorical_feature = reference.categorical_feature
724
725
726
727
        data, feature_name, categorical_feature, self.pandas_categorical = _data_from_pandas(data,
                                                                                             feature_name,
                                                                                             categorical_feature,
                                                                                             self.pandas_categorical)
wxchan's avatar
wxchan committed
728
729
        label = _label_from_pandas(label)
        self.data_has_header = False
730
        # process for args
wxchan's avatar
wxchan committed
731
        params = {} if params is None else params
732
733
734
        args_names = (getattr(self.__class__, '_lazy_init')
                      .__code__
                      .co_varnames[:getattr(self.__class__, '_lazy_init').__code__.co_argcount])
735
736
        for key, _ in params.items():
            if key in args_names:
737
738
739
                warnings.warn('{0} keyword has been found in `params` and will be ignored.\n'
                              'Please use {0} argument of the Dataset constructor to pass this parameter.'
                              .format(key))
wxchan's avatar
wxchan committed
740
        self.predictor = predictor
741
742
743
        # user can set verbose with params, it has higher priority
        if not any(verbose_alias in params for verbose_alias in ('verbose', 'verbosity')) and silent:
            params["verbose"] = -1
744
        # get categorical features
745
746
747
748
749
750
751
752
753
754
755
756
757
        if categorical_feature is not None:
            categorical_indices = set()
            feature_dict = {}
            if feature_name is not None:
                feature_dict = {name: i for i, name in enumerate(feature_name)}
            for name in categorical_feature:
                if isinstance(name, string_type) and name in feature_dict:
                    categorical_indices.add(feature_dict[name])
                elif isinstance(name, integer_types):
                    categorical_indices.add(name)
                else:
                    raise TypeError("Wrong type({}) or unknown name({}) in categorical_feature"
                                    .format(type(name).__name__, name))
758
            if categorical_indices:
759
                if "categorical_feature" in params or "categorical_column" in params:
760
                    warnings.warn('categorical_feature in param dict is overridden.')
761
762
                    params.pop("categorical_feature", None)
                    params.pop("categorical_column", None)
763
                params['categorical_column'] = sorted(categorical_indices)
764

wxchan's avatar
wxchan committed
765
        params_str = param_dict_to_str(params)
766
        # process for reference dataset
wxchan's avatar
wxchan committed
767
        ref_dataset = None
wxchan's avatar
wxchan committed
768
        if isinstance(reference, Dataset):
769
            ref_dataset = reference.construct().handle
wxchan's avatar
wxchan committed
770
771
        elif reference is not None:
            raise TypeError('Reference dataset should be None or dataset instance')
772
        # start construct data
wxchan's avatar
wxchan committed
773
        if isinstance(data, string_type):
774
            # check data has header or not
Guolin Ke's avatar
Guolin Ke committed
775
            if str(params.get("has_header", "")).lower() == "true" \
wxchan's avatar
wxchan committed
776
                    or str(params.get("header", "")).lower() == "true":
777
                self.data_has_header = True
wxchan's avatar
wxchan committed
778
779
780
781
782
783
784
785
            self.handle = ctypes.c_void_p()
            _safe_call(_LIB.LGBM_DatasetCreateFromFile(
                c_str(data),
                c_str(params_str),
                ref_dataset,
                ctypes.byref(self.handle)))
        elif isinstance(data, scipy.sparse.csr_matrix):
            self.__init_from_csr(data, params_str, ref_dataset)
Guolin Ke's avatar
Guolin Ke committed
786
787
        elif isinstance(data, scipy.sparse.csc_matrix):
            self.__init_from_csc(data, params_str, ref_dataset)
wxchan's avatar
wxchan committed
788
789
        elif isinstance(data, np.ndarray):
            self.__init_from_np2d(data, params_str, ref_dataset)
790
791
        elif isinstance(data, list) and len(data) > 0 and all(isinstance(x, np.ndarray) for x in data):
            self.__init_from_list_np2d(data, params_str, ref_dataset)
wxchan's avatar
wxchan committed
792
793
794
795
        else:
            try:
                csr = scipy.sparse.csr_matrix(data)
                self.__init_from_csr(csr, params_str, ref_dataset)
796
            except BaseException:
wxchan's avatar
wxchan committed
797
                raise TypeError('Cannot initialize Dataset from {}'.format(type(data).__name__))
wxchan's avatar
wxchan committed
798
799
800
        if label is not None:
            self.set_label(label)
        if self.get_label() is None:
801
            raise ValueError("Label should not be None")
wxchan's avatar
wxchan committed
802
803
804
805
806
        if weight is not None:
            self.set_weight(weight)
        if group is not None:
            self.set_group(group)
        # load init score
807
808
809
        if init_score is not None:
            self.set_init_score(init_score)
            if self.predictor is not None:
810
                warnings.warn("The prediction of init_model will be overridden by init_score.")
811
        elif isinstance(self.predictor, _InnerPredictor):
wxchan's avatar
wxchan committed
812
813
814
815
816
817
            init_score = self.predictor.predict(data,
                                                raw_score=True,
                                                data_has_header=self.data_has_header,
                                                is_reshape=False)
            if self.predictor.num_class > 1:
                # need re group init score
wxchan's avatar
wxchan committed
818
                new_init_score = np.zeros(init_score.size, dtype=np.float32)
wxchan's avatar
wxchan committed
819
                num_data = self.num_data()
wxchan's avatar
wxchan committed
820
821
                for i in range_(num_data):
                    for j in range_(self.predictor.num_class):
wxchan's avatar
wxchan committed
822
823
824
                        new_init_score[j * num_data + i] = init_score[i * self.predictor.num_class + j]
                init_score = new_init_score
            self.set_init_score(init_score)
Guolin Ke's avatar
Guolin Ke committed
825
826
        elif self.predictor is not None:
            raise TypeError('wrong predictor type {}'.format(type(self.predictor).__name__))
Guolin Ke's avatar
Guolin Ke committed
827
        # set feature names
Nikita Titov's avatar
Nikita Titov committed
828
        return self.set_feature_name(feature_name)
wxchan's avatar
wxchan committed
829
830

    def __init_from_np2d(self, mat, params_str, ref_dataset):
831
        """Initialize data from a 2-D numpy matrix."""
wxchan's avatar
wxchan committed
832
833
834
835
836
837
838
        if len(mat.shape) != 2:
            raise ValueError('Input numpy.ndarray must be 2 dimensional')

        self.handle = ctypes.c_void_p()
        if mat.dtype == np.float32 or mat.dtype == np.float64:
            data = np.array(mat.reshape(mat.size), dtype=mat.dtype, copy=False)
        else:
839
            # change non-float data to float data, need to copy
wxchan's avatar
wxchan committed
840
841
            data = np.array(mat.reshape(mat.size), dtype=np.float32)

842
        ptr_data, type_ptr_data, _ = c_float_array(data)
wxchan's avatar
wxchan committed
843
844
        _safe_call(_LIB.LGBM_DatasetCreateFromMat(
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
845
846
847
848
            ctypes.c_int(type_ptr_data),
            ctypes.c_int(mat.shape[0]),
            ctypes.c_int(mat.shape[1]),
            ctypes.c_int(C_API_IS_ROW_MAJOR),
wxchan's avatar
wxchan committed
849
850
851
            c_str(params_str),
            ref_dataset,
            ctypes.byref(self.handle)))
Nikita Titov's avatar
Nikita Titov committed
852
        return self
wxchan's avatar
wxchan committed
853

854
    def __init_from_list_np2d(self, mats, params_str, ref_dataset):
855
        """Initialize data from a list of 2-D numpy matrices."""
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
        ncol = mats[0].shape[1]
        nrow = np.zeros((len(mats),), np.int32)
        if mats[0].dtype == np.float64:
            ptr_data = (ctypes.POINTER(ctypes.c_double) * len(mats))()
        else:
            ptr_data = (ctypes.POINTER(ctypes.c_float) * len(mats))()

        holders = []
        type_ptr_data = None

        for i, mat in enumerate(mats):
            if len(mat.shape) != 2:
                raise ValueError('Input numpy.ndarray must be 2 dimensional')

            if mat.shape[1] != ncol:
                raise ValueError('Input arrays must have same number of columns')

            nrow[i] = mat.shape[0]

            if mat.dtype == np.float32 or mat.dtype == np.float64:
                mats[i] = np.array(mat.reshape(mat.size), dtype=mat.dtype, copy=False)
            else:
                # change non-float data to float data, need to copy
                mats[i] = np.array(mat.reshape(mat.size), dtype=np.float32)

            chunk_ptr_data, chunk_type_ptr_data, holder = c_float_array(mats[i])
            if type_ptr_data is not None and chunk_type_ptr_data != type_ptr_data:
                raise ValueError('Input chunks must have same type')
            ptr_data[i] = chunk_ptr_data
            type_ptr_data = chunk_type_ptr_data
            holders.append(holder)

        self.handle = ctypes.c_void_p()
        _safe_call(_LIB.LGBM_DatasetCreateFromMats(
            ctypes.c_int(len(mats)),
            ctypes.cast(ptr_data, ctypes.POINTER(ctypes.POINTER(ctypes.c_double))),
            ctypes.c_int(type_ptr_data),
            nrow.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)),
            ctypes.c_int(ncol),
            ctypes.c_int(C_API_IS_ROW_MAJOR),
            c_str(params_str),
            ref_dataset,
            ctypes.byref(self.handle)))
Nikita Titov's avatar
Nikita Titov committed
899
        return self
900

wxchan's avatar
wxchan committed
901
    def __init_from_csr(self, csr, params_str, ref_dataset):
902
        """Initialize data from a CSR matrix."""
wxchan's avatar
wxchan committed
903
        if len(csr.indices) != len(csr.data):
904
            raise ValueError('Length mismatch: {} vs {}'.format(len(csr.indices), len(csr.data)))
wxchan's avatar
wxchan committed
905
906
        self.handle = ctypes.c_void_p()

907
908
        ptr_indptr, type_ptr_indptr, __ = c_int_array(csr.indptr)
        ptr_data, type_ptr_data, _ = c_float_array(csr.data)
wxchan's avatar
wxchan committed
909

910
911
912
        assert csr.shape[1] <= MAX_INT32
        csr.indices = csr.indices.astype(np.int32, copy=False)

wxchan's avatar
wxchan committed
913
914
        _safe_call(_LIB.LGBM_DatasetCreateFromCSR(
            ptr_indptr,
Guolin Ke's avatar
Guolin Ke committed
915
            ctypes.c_int(type_ptr_indptr),
wxchan's avatar
wxchan committed
916
917
            csr.indices.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)),
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
918
919
920
921
            ctypes.c_int(type_ptr_data),
            ctypes.c_int64(len(csr.indptr)),
            ctypes.c_int64(len(csr.data)),
            ctypes.c_int64(csr.shape[1]),
wxchan's avatar
wxchan committed
922
923
924
            c_str(params_str),
            ref_dataset,
            ctypes.byref(self.handle)))
Nikita Titov's avatar
Nikita Titov committed
925
        return self
wxchan's avatar
wxchan committed
926

Guolin Ke's avatar
Guolin Ke committed
927
    def __init_from_csc(self, csc, params_str, ref_dataset):
928
        """Initialize data from a CSC matrix."""
Guolin Ke's avatar
Guolin Ke committed
929
930
931
932
        if len(csc.indices) != len(csc.data):
            raise ValueError('Length mismatch: {} vs {}'.format(len(csc.indices), len(csc.data)))
        self.handle = ctypes.c_void_p()

933
934
        ptr_indptr, type_ptr_indptr, __ = c_int_array(csc.indptr)
        ptr_data, type_ptr_data, _ = c_float_array(csc.data)
Guolin Ke's avatar
Guolin Ke committed
935

936
937
938
        assert csc.shape[0] <= MAX_INT32
        csc.indices = csc.indices.astype(np.int32, copy=False)

Guolin Ke's avatar
Guolin Ke committed
939
940
        _safe_call(_LIB.LGBM_DatasetCreateFromCSC(
            ptr_indptr,
Guolin Ke's avatar
Guolin Ke committed
941
            ctypes.c_int(type_ptr_indptr),
Guolin Ke's avatar
Guolin Ke committed
942
943
            csc.indices.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)),
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
944
945
946
947
            ctypes.c_int(type_ptr_data),
            ctypes.c_int64(len(csc.indptr)),
            ctypes.c_int64(len(csc.data)),
            ctypes.c_int64(csc.shape[0]),
Guolin Ke's avatar
Guolin Ke committed
948
949
950
            c_str(params_str),
            ref_dataset,
            ctypes.byref(self.handle)))
Nikita Titov's avatar
Nikita Titov committed
951
        return self
Guolin Ke's avatar
Guolin Ke committed
952

wxchan's avatar
wxchan committed
953
    def construct(self):
954
955
956
957
958
        """Lazy init.

        Returns
        -------
        self : Dataset
Nikita Titov's avatar
Nikita Titov committed
959
            Constructed Dataset object.
960
        """
961
        if self.handle is None:
wxchan's avatar
wxchan committed
962
963
            if self.reference is not None:
                if self.used_indices is None:
964
                    # create valid
965
                    self._lazy_init(self.data, label=self.label, reference=self.reference,
966
967
                                    weight=self.weight, group=self.group,
                                    init_score=self.init_score, predictor=self._predictor,
968
                                    silent=self.silent, feature_name=self.feature_name, params=self.params)
wxchan's avatar
wxchan committed
969
                else:
970
                    # construct subset
wxchan's avatar
wxchan committed
971
                    used_indices = list_to_1d_numpy(self.used_indices, np.int32, name='used_indices')
972
                    assert used_indices.flags.c_contiguous
Guolin Ke's avatar
Guolin Ke committed
973
974
                    if self.reference.group is not None:
                        group_info = np.array(self.reference.group).astype(int)
975
976
                        _, self.group = np.unique(np.repeat(range_(len(group_info)), repeats=group_info)[self.used_indices],
                                                  return_counts=True)
977
                    self.handle = ctypes.c_void_p()
wxchan's avatar
wxchan committed
978
979
                    params_str = param_dict_to_str(self.params)
                    _safe_call(_LIB.LGBM_DatasetGetSubset(
980
                        self.reference.construct().handle,
wxchan's avatar
wxchan committed
981
                        used_indices.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)),
Guolin Ke's avatar
Guolin Ke committed
982
                        ctypes.c_int(used_indices.shape[0]),
wxchan's avatar
wxchan committed
983
984
                        c_str(params_str),
                        ctypes.byref(self.handle)))
985
986
                    self.data = self.reference.data
                    self.get_data()
Guolin Ke's avatar
Guolin Ke committed
987
988
                    if self.group is not None:
                        self.set_group(self.group)
wxchan's avatar
wxchan committed
989
990
991
                    if self.get_label() is None:
                        raise ValueError("Label should not be None.")
            else:
992
                # create train
993
                self._lazy_init(self.data, label=self.label,
994
995
996
                                weight=self.weight, group=self.group,
                                init_score=self.init_score, predictor=self._predictor,
                                silent=self.silent, feature_name=self.feature_name,
997
                                categorical_feature=self.categorical_feature, params=self.params)
wxchan's avatar
wxchan committed
998
999
1000
            if self.free_raw_data:
                self.data = None
        return self
wxchan's avatar
wxchan committed
1001

wxchan's avatar
wxchan committed
1002
    def create_valid(self, data, label=None, weight=None, group=None,
1003
                     init_score=None, silent=False, params=None):
1004
        """Create validation data align with current Dataset.
wxchan's avatar
wxchan committed
1005
1006
1007

        Parameters
        ----------
1008
        data : string, numpy array, pandas DataFrame, scipy.sparse or list of numpy arrays
wxchan's avatar
wxchan committed
1009
            Data source of Dataset.
1010
            If string, it represents the path to txt file.
1011
        label : list, numpy 1-D array, pandas Series / one-column DataFrame or None, optional (default=None)
1012
1013
            Label of the data.
        weight : list, numpy 1-D array, pandas Series or None, optional (default=None)
wxchan's avatar
wxchan committed
1014
            Weight for each instance.
1015
        group : list, numpy 1-D array, pandas Series or None, optional (default=None)
1016
            Group/query size for Dataset.
1017
        init_score : list, numpy 1-D array, pandas Series or None, optional (default=None)
1018
            Init score for Dataset.
1019
1020
        silent : bool, optional (default=False)
            Whether to print messages during construction.
Nikita Titov's avatar
Nikita Titov committed
1021
        params : dict or None, optional (default=None)
1022
            Other parameters for validation Dataset.
1023
1024
1025

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1026
1027
        valid : Dataset
            Validation Dataset with reference to self.
wxchan's avatar
wxchan committed
1028
        """
1029
        ret = Dataset(data, label=label, reference=self,
1030
1031
                      weight=weight, group=group, init_score=init_score,
                      silent=silent, params=params, free_raw_data=self.free_raw_data)
wxchan's avatar
wxchan committed
1032
        ret._predictor = self._predictor
1033
        ret.pandas_categorical = self.pandas_categorical
wxchan's avatar
wxchan committed
1034
        return ret
wxchan's avatar
wxchan committed
1035

wxchan's avatar
wxchan committed
1036
    def subset(self, used_indices, params=None):
1037
        """Get subset of current Dataset.
wxchan's avatar
wxchan committed
1038
1039
1040
1041

        Parameters
        ----------
        used_indices : list of int
1042
            Indices used to create the subset.
Nikita Titov's avatar
Nikita Titov committed
1043
        params : dict or None, optional (default=None)
1044
            These parameters will be passed to Dataset constructor.
1045
1046
1047
1048
1049

        Returns
        -------
        subset : Dataset
            Subset of the current Dataset.
wxchan's avatar
wxchan committed
1050
        """
wxchan's avatar
wxchan committed
1051
1052
        if params is None:
            params = self.params
wxchan's avatar
wxchan committed
1053
        ret = Dataset(None, reference=self, feature_name=self.feature_name,
1054
1055
                      categorical_feature=self.categorical_feature, params=params,
                      free_raw_data=self.free_raw_data)
wxchan's avatar
wxchan committed
1056
        ret._predictor = self._predictor
1057
        ret.pandas_categorical = self.pandas_categorical
wxchan's avatar
wxchan committed
1058
1059
1060
1061
        ret.used_indices = used_indices
        return ret

    def save_binary(self, filename):
1062
        """Save Dataset to a binary file.
wxchan's avatar
wxchan committed
1063
1064
1065
1066
1067

        Parameters
        ----------
        filename : string
            Name of the output file.
Nikita Titov's avatar
Nikita Titov committed
1068
1069
1070
1071
1072

        Returns
        -------
        self : Dataset
            Returns self.
wxchan's avatar
wxchan committed
1073
1074
1075
1076
        """
        _safe_call(_LIB.LGBM_DatasetSaveBinary(
            self.construct().handle,
            c_str(filename)))
Nikita Titov's avatar
Nikita Titov committed
1077
        return self
wxchan's avatar
wxchan committed
1078
1079

    def _update_params(self, params):
1080
1081
        if self.handle is not None and params is not None:
            _safe_call(_LIB.LGBM_DatasetUpdateParam(self.handle, c_str(param_dict_to_str(params))))
wxchan's avatar
wxchan committed
1082
1083
        if not self.params:
            self.params = params
wxchan's avatar
wxchan committed
1084
        else:
1085
            self.params_back_up = copy.deepcopy(self.params)
wxchan's avatar
wxchan committed
1086
            self.params.update(params)
Nikita Titov's avatar
Nikita Titov committed
1087
        return self
wxchan's avatar
wxchan committed
1088

1089
1090
1091
    def _reverse_update_params(self):
        self.params = copy.deepcopy(self.params_back_up)
        self.params_back_up = None
1092
1093
        if self.handle is not None and self.params is not None:
            _safe_call(_LIB.LGBM_DatasetUpdateParam(self.handle, c_str(param_dict_to_str(self.params))))
Nikita Titov's avatar
Nikita Titov committed
1094
        return self
1095

wxchan's avatar
wxchan committed
1096
    def set_field(self, field_name, data):
wxchan's avatar
wxchan committed
1097
        """Set property into the Dataset.
wxchan's avatar
wxchan committed
1098
1099
1100

        Parameters
        ----------
Nikita Titov's avatar
Nikita Titov committed
1101
        field_name : string
1102
            The field name of the information.
1103
        data : list, numpy 1-D array, pandas Series or None
1104
            The array of data to be set.
Nikita Titov's avatar
Nikita Titov committed
1105
1106
1107
1108
1109

        Returns
        -------
        self : Dataset
            Dataset with set property.
wxchan's avatar
wxchan committed
1110
        """
1111
1112
        if self.handle is None:
            raise Exception("Cannot set %s before construct dataset" % field_name)
wxchan's avatar
wxchan committed
1113
        if data is None:
1114
            # set to None
wxchan's avatar
wxchan committed
1115
1116
1117
1118
            _safe_call(_LIB.LGBM_DatasetSetField(
                self.handle,
                c_str(field_name),
                None,
Guolin Ke's avatar
Guolin Ke committed
1119
1120
                ctypes.c_int(0),
                ctypes.c_int(FIELD_TYPE_MAPPER[field_name])))
Nikita Titov's avatar
Nikita Titov committed
1121
            return self
Guolin Ke's avatar
Guolin Ke committed
1122
1123
1124
1125
1126
        dtype = np.float32
        if field_name == 'group':
            dtype = np.int32
        elif field_name == 'init_score':
            dtype = np.float64
1127
        data = list_to_1d_numpy(data, dtype, name=field_name)
1128
1129
        if data.dtype == np.float32 or data.dtype == np.float64:
            ptr_data, type_data, _ = c_float_array(data)
wxchan's avatar
wxchan committed
1130
        elif data.dtype == np.int32:
1131
            ptr_data, type_data, _ = c_int_array(data)
wxchan's avatar
wxchan committed
1132
        else:
Guolin Ke's avatar
Guolin Ke committed
1133
            raise TypeError("Excepted np.float32/64 or np.int32, meet type({})".format(data.dtype))
wxchan's avatar
wxchan committed
1134
        if type_data != FIELD_TYPE_MAPPER[field_name]:
1135
            raise TypeError("Input type error for set_field")
wxchan's avatar
wxchan committed
1136
1137
1138
1139
        _safe_call(_LIB.LGBM_DatasetSetField(
            self.handle,
            c_str(field_name),
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
1140
1141
            ctypes.c_int(len(data)),
            ctypes.c_int(type_data)))
Nikita Titov's avatar
Nikita Titov committed
1142
        return self
wxchan's avatar
wxchan committed
1143

wxchan's avatar
wxchan committed
1144
1145
    def get_field(self, field_name):
        """Get property from the Dataset.
wxchan's avatar
wxchan committed
1146
1147
1148

        Parameters
        ----------
Nikita Titov's avatar
Nikita Titov committed
1149
        field_name : string
1150
            The field name of the information.
wxchan's avatar
wxchan committed
1151
1152
1153

        Returns
        -------
1154
1155
        info : numpy array
            A numpy array with information from the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1156
        """
1157
        if self.handle is None:
1158
            raise Exception("Cannot get %s before construct Dataset" % field_name)
Guolin Ke's avatar
Guolin Ke committed
1159
1160
        tmp_out_len = ctypes.c_int()
        out_type = ctypes.c_int()
wxchan's avatar
wxchan committed
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
        ret = ctypes.POINTER(ctypes.c_void_p)()
        _safe_call(_LIB.LGBM_DatasetGetField(
            self.handle,
            c_str(field_name),
            ctypes.byref(tmp_out_len),
            ctypes.byref(ret),
            ctypes.byref(out_type)))
        if out_type.value != FIELD_TYPE_MAPPER[field_name]:
            raise TypeError("Return type error for get_field")
        if tmp_out_len.value == 0:
            return None
        if out_type.value == C_API_DTYPE_INT32:
            return cint32_array_to_numpy(ctypes.cast(ret, ctypes.POINTER(ctypes.c_int32)), tmp_out_len.value)
        elif out_type.value == C_API_DTYPE_FLOAT32:
            return cfloat32_array_to_numpy(ctypes.cast(ret, ctypes.POINTER(ctypes.c_float)), tmp_out_len.value)
Guolin Ke's avatar
Guolin Ke committed
1176
1177
        elif out_type.value == C_API_DTYPE_FLOAT64:
            return cfloat64_array_to_numpy(ctypes.cast(ret, ctypes.POINTER(ctypes.c_double)), tmp_out_len.value)
1178
        else:
wxchan's avatar
wxchan committed
1179
            raise TypeError("Unknown type")
Guolin Ke's avatar
Guolin Ke committed
1180

1181
    def set_categorical_feature(self, categorical_feature):
1182
        """Set categorical features.
1183
1184
1185

        Parameters
        ----------
1186
1187
        categorical_feature : list of int or strings
            Names or indices of categorical features.
Nikita Titov's avatar
Nikita Titov committed
1188
1189
1190
1191
1192

        Returns
        -------
        self : Dataset
            Dataset with set categorical features.
1193
1194
        """
        if self.categorical_feature == categorical_feature:
Nikita Titov's avatar
Nikita Titov committed
1195
            return self
1196
        if self.data is not None:
1197
1198
            if self.categorical_feature is None:
                self.categorical_feature = categorical_feature
Nikita Titov's avatar
Nikita Titov committed
1199
                return self._free_handle()
1200
1201
            elif categorical_feature == 'auto':
                warnings.warn('Using categorical_feature in Dataset.')
Nikita Titov's avatar
Nikita Titov committed
1202
                return self
1203
            else:
1204
1205
                warnings.warn('categorical_feature in Dataset is overridden.\n'
                              'New categorical_feature is {}'.format(sorted(list(categorical_feature))))
1206
                self.categorical_feature = categorical_feature
Nikita Titov's avatar
Nikita Titov committed
1207
                return self._free_handle()
1208
        else:
1209
1210
            raise LightGBMError("Cannot set categorical feature after freed raw data, "
                                "set free_raw_data=False when construct Dataset to avoid this.")
1211

Guolin Ke's avatar
Guolin Ke committed
1212
    def _set_predictor(self, predictor):
1213
1214
1215
1216
        """Set predictor for continued training.

        It is not recommended for user to call this function.
        Please use init_model argument in engine.train() or engine.cv() instead.
Guolin Ke's avatar
Guolin Ke committed
1217
1218
        """
        if predictor is self._predictor:
Nikita Titov's avatar
Nikita Titov committed
1219
            return self
Guolin Ke's avatar
Guolin Ke committed
1220
1221
        if self.data is not None:
            self._predictor = predictor
Nikita Titov's avatar
Nikita Titov committed
1222
            return self._free_handle()
Guolin Ke's avatar
Guolin Ke committed
1223
        else:
1224
1225
            raise LightGBMError("Cannot set predictor after freed raw data, "
                                "set free_raw_data=False when construct Dataset to avoid this.")
Guolin Ke's avatar
Guolin Ke committed
1226
1227

    def set_reference(self, reference):
1228
        """Set reference Dataset.
Guolin Ke's avatar
Guolin Ke committed
1229
1230
1231
1232

        Parameters
        ----------
        reference : Dataset
1233
            Reference that is used as a template to construct the current Dataset.
Nikita Titov's avatar
Nikita Titov committed
1234
1235
1236
1237
1238

        Returns
        -------
        self : Dataset
            Dataset with set reference.
Guolin Ke's avatar
Guolin Ke committed
1239
        """
1240
1241
1242
        self.set_categorical_feature(reference.categorical_feature) \
            .set_feature_name(reference.feature_name) \
            ._set_predictor(reference._predictor)
1243
1244
        # we're done if self and reference share a common upstrem reference
        if self.get_ref_chain().intersection(reference.get_ref_chain()):
Nikita Titov's avatar
Nikita Titov committed
1245
            return self
Guolin Ke's avatar
Guolin Ke committed
1246
1247
        if self.data is not None:
            self.reference = reference
Nikita Titov's avatar
Nikita Titov committed
1248
            return self._free_handle()
Guolin Ke's avatar
Guolin Ke committed
1249
        else:
1250
1251
            raise LightGBMError("Cannot set reference after freed raw data, "
                                "set free_raw_data=False when construct Dataset to avoid this.")
Guolin Ke's avatar
Guolin Ke committed
1252
1253

    def set_feature_name(self, feature_name):
1254
        """Set feature name.
Guolin Ke's avatar
Guolin Ke committed
1255
1256
1257

        Parameters
        ----------
1258
1259
        feature_name : list of strings
            Feature names.
Nikita Titov's avatar
Nikita Titov committed
1260
1261
1262
1263
1264

        Returns
        -------
        self : Dataset
            Dataset with set feature name.
Guolin Ke's avatar
Guolin Ke committed
1265
        """
1266
1267
        if feature_name != 'auto':
            self.feature_name = feature_name
1268
        if self.handle is not None and feature_name is not None and feature_name != 'auto':
wxchan's avatar
wxchan committed
1269
            if len(feature_name) != self.num_feature():
1270
1271
                raise ValueError("Length of feature_name({}) and num_feature({}) don't match"
                                 .format(len(feature_name), self.num_feature()))
1272
            c_feature_name = [c_str(name) for name in feature_name]
wxchan's avatar
wxchan committed
1273
1274
1275
            _safe_call(_LIB.LGBM_DatasetSetFeatureNames(
                self.handle,
                c_array(ctypes.c_char_p, c_feature_name),
Guolin Ke's avatar
Guolin Ke committed
1276
                ctypes.c_int(len(feature_name))))
Nikita Titov's avatar
Nikita Titov committed
1277
        return self
Guolin Ke's avatar
Guolin Ke committed
1278
1279

    def set_label(self, label):
1280
        """Set label of Dataset.
Guolin Ke's avatar
Guolin Ke committed
1281
1282
1283

        Parameters
        ----------
1284
        label : list, numpy 1-D array, pandas Series / one-column DataFrame or None
1285
            The label information to be set into Dataset.
Nikita Titov's avatar
Nikita Titov committed
1286
1287
1288
1289
1290

        Returns
        -------
        self : Dataset
            Dataset with set label.
Guolin Ke's avatar
Guolin Ke committed
1291
1292
        """
        self.label = label
1293
        if self.handle is not None:
1294
            label = list_to_1d_numpy(_label_from_pandas(label), name='label')
wxchan's avatar
wxchan committed
1295
            self.set_field('label', label)
Nikita Titov's avatar
Nikita Titov committed
1296
        return self
Guolin Ke's avatar
Guolin Ke committed
1297
1298

    def set_weight(self, weight):
1299
        """Set weight of each instance.
Guolin Ke's avatar
Guolin Ke committed
1300
1301
1302

        Parameters
        ----------
1303
        weight : list, numpy 1-D array, pandas Series or None
1304
            Weight to be set for each data point.
Nikita Titov's avatar
Nikita Titov committed
1305
1306
1307
1308
1309

        Returns
        -------
        self : Dataset
            Dataset with set weight.
Guolin Ke's avatar
Guolin Ke committed
1310
        """
1311
1312
        if weight is not None and np.all(weight == 1):
            weight = None
Guolin Ke's avatar
Guolin Ke committed
1313
        self.weight = weight
1314
        if self.handle is not None and weight is not None:
wxchan's avatar
wxchan committed
1315
1316
            weight = list_to_1d_numpy(weight, name='weight')
            self.set_field('weight', weight)
Nikita Titov's avatar
Nikita Titov committed
1317
        return self
Guolin Ke's avatar
Guolin Ke committed
1318
1319

    def set_init_score(self, init_score):
1320
        """Set init score of Booster to start from.
Guolin Ke's avatar
Guolin Ke committed
1321
1322
1323

        Parameters
        ----------
1324
        init_score : list, numpy 1-D array, pandas Series or None
1325
            Init score for Booster.
Nikita Titov's avatar
Nikita Titov committed
1326
1327
1328
1329
1330

        Returns
        -------
        self : Dataset
            Dataset with set init score.
Guolin Ke's avatar
Guolin Ke committed
1331
1332
        """
        self.init_score = init_score
1333
        if self.handle is not None and init_score is not None:
Guolin Ke's avatar
Guolin Ke committed
1334
            init_score = list_to_1d_numpy(init_score, np.float64, name='init_score')
wxchan's avatar
wxchan committed
1335
            self.set_field('init_score', init_score)
Nikita Titov's avatar
Nikita Titov committed
1336
        return self
Guolin Ke's avatar
Guolin Ke committed
1337
1338

    def set_group(self, group):
1339
        """Set group size of Dataset (used for ranking).
Guolin Ke's avatar
Guolin Ke committed
1340
1341
1342

        Parameters
        ----------
1343
        group : list, numpy 1-D array, pandas Series or None
1344
            Group size of each group.
Nikita Titov's avatar
Nikita Titov committed
1345
1346
1347
1348
1349

        Returns
        -------
        self : Dataset
            Dataset with set group.
Guolin Ke's avatar
Guolin Ke committed
1350
1351
        """
        self.group = group
1352
        if self.handle is not None and group is not None:
wxchan's avatar
wxchan committed
1353
1354
            group = list_to_1d_numpy(group, np.int32, name='group')
            self.set_field('group', group)
Nikita Titov's avatar
Nikita Titov committed
1355
        return self
Guolin Ke's avatar
Guolin Ke committed
1356
1357

    def get_label(self):
1358
        """Get the label of the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1359
1360
1361

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1362
        label : numpy array or None
1363
            The label information from the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1364
        """
1365
        if self.label is None:
wxchan's avatar
wxchan committed
1366
            self.label = self.get_field('label')
Guolin Ke's avatar
Guolin Ke committed
1367
1368
1369
        return self.label

    def get_weight(self):
1370
        """Get the weight of the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1371
1372
1373

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1374
        weight : numpy array or None
1375
            Weight for each data point from the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1376
        """
1377
        if self.weight is None:
wxchan's avatar
wxchan committed
1378
            self.weight = self.get_field('weight')
Guolin Ke's avatar
Guolin Ke committed
1379
1380
1381
        return self.weight

    def get_init_score(self):
1382
        """Get the initial score of the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1383
1384
1385

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1386
        init_score : numpy array or None
1387
            Init score of Booster.
Guolin Ke's avatar
Guolin Ke committed
1388
        """
1389
        if self.init_score is None:
wxchan's avatar
wxchan committed
1390
            self.init_score = self.get_field('init_score')
Guolin Ke's avatar
Guolin Ke committed
1391
1392
        return self.init_score

1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
    def get_data(self):
        """Get the raw data of the Dataset.

        Returns
        -------
        data : string, numpy array, pandas DataFrame, scipy.sparse, list of numpy arrays or None
            Raw data used in the Dataset construction.
        """
        if self.handle is None:
            raise Exception("Cannot get data before construct Dataset")
        if self.data is not None and self.used_indices is not None and self.need_slice:
            if isinstance(self.data, np.ndarray) or scipy.sparse.issparse(self.data):
                self.data = self.data[self.used_indices, :]
            elif isinstance(self.data, DataFrame):
                self.data = self.data.iloc[self.used_indices].copy()
            else:
                warnings.warn("Cannot subset {} type of raw data.\n"
                              "Returning original raw data".format(type(self.data).__name__))
            self.need_slice = False
        return self.data

Guolin Ke's avatar
Guolin Ke committed
1414
    def get_group(self):
1415
        """Get the group of the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1416
1417
1418

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1419
        group : numpy array or None
1420
            Group size of each group.
Guolin Ke's avatar
Guolin Ke committed
1421
        """
1422
        if self.group is None:
wxchan's avatar
wxchan committed
1423
            self.group = self.get_field('group')
Guolin Ke's avatar
Guolin Ke committed
1424
1425
            if self.group is not None:
                # group data from LightGBM is boundaries data, need to convert to group size
Nikita Titov's avatar
Nikita Titov committed
1426
                self.group = np.diff(self.group)
Guolin Ke's avatar
Guolin Ke committed
1427
1428
1429
        return self.group

    def num_data(self):
1430
        """Get the number of rows in the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1431
1432
1433

        Returns
        -------
1434
1435
        number_of_rows : int
            The number of rows in the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1436
        """
1437
        if self.handle is not None:
Guolin Ke's avatar
Guolin Ke committed
1438
            ret = ctypes.c_int()
wxchan's avatar
wxchan committed
1439
1440
1441
            _safe_call(_LIB.LGBM_DatasetGetNumData(self.handle,
                                                   ctypes.byref(ret)))
            return ret.value
Guolin Ke's avatar
Guolin Ke committed
1442
        else:
1443
            raise LightGBMError("Cannot get num_data before construct dataset")
Guolin Ke's avatar
Guolin Ke committed
1444
1445

    def num_feature(self):
1446
        """Get the number of columns (features) in the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1447
1448
1449

        Returns
        -------
1450
1451
        number_of_columns : int
            The number of columns (features) in the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1452
        """
1453
        if self.handle is not None:
Guolin Ke's avatar
Guolin Ke committed
1454
            ret = ctypes.c_int()
wxchan's avatar
wxchan committed
1455
1456
1457
            _safe_call(_LIB.LGBM_DatasetGetNumFeature(self.handle,
                                                      ctypes.byref(ret)))
            return ret.value
Guolin Ke's avatar
Guolin Ke committed
1458
        else:
1459
            raise LightGBMError("Cannot get num_feature before construct dataset")
Guolin Ke's avatar
Guolin Ke committed
1460

1461
    def get_ref_chain(self, ref_limit=100):
1462
1463
1464
1465
1466
        """Get a chain of Dataset objects.

        Starts with r, then goes to r.reference (if exists),
        then to r.reference.reference, etc.
        until we hit ``ref_limit`` or a reference loop.
1467
1468
1469
1470
1471

        Parameters
        ----------
        ref_limit : int, optional (default=100)
            The limit number of references.
1472
1473
1474

        Returns
        -------
1475
1476
1477
        ref_chain : set of Dataset
            Chain of references of the Datasets.
        """
1478
        head = self
1479
        ref_chain = set()
1480
1481
        while len(ref_chain) < ref_limit:
            if isinstance(head, Dataset):
1482
                ref_chain.add(head)
1483
1484
1485
1486
1487
1488
                if (head.reference is not None) and (head.reference not in ref_chain):
                    head = head.reference
                else:
                    break
            else:
                break
Nikita Titov's avatar
Nikita Titov committed
1489
        return ref_chain
1490

wxchan's avatar
wxchan committed
1491

wxchan's avatar
wxchan committed
1492
class Booster(object):
1493
    """Booster in LightGBM."""
1494

wxchan's avatar
wxchan committed
1495
    def __init__(self, params=None, train_set=None, model_file=None, silent=False):
1496
        """Initialize the Booster.
wxchan's avatar
wxchan committed
1497
1498
1499

        Parameters
        ----------
Nikita Titov's avatar
Nikita Titov committed
1500
        params : dict or None, optional (default=None)
1501
1502
1503
1504
            Parameters for Booster.
        train_set : Dataset or None, optional (default=None)
            Training dataset.
        model_file : string or None, optional (default=None)
wxchan's avatar
wxchan committed
1505
            Path to the model file.
1506
1507
        silent : bool, optional (default=False)
            Whether to print messages during construction.
wxchan's avatar
wxchan committed
1508
        """
1509
        self.handle = None
1510
        self.network = False
wxchan's avatar
wxchan committed
1511
1512
1513
        self.__need_reload_eval_info = True
        self.__train_data_name = "training"
        self.__attr = {}
1514
        self.__set_objective_to_none = False
wxchan's avatar
wxchan committed
1515
        self.best_iteration = -1
wxchan's avatar
wxchan committed
1516
        self.best_score = {}
1517
        params = {} if params is None else copy.deepcopy(params)
1518
1519
1520
        # user can set verbose with params, it has higher priority
        if not any(verbose_alias in params for verbose_alias in ('verbose', 'verbosity')) and silent:
            params["verbose"] = -1
wxchan's avatar
wxchan committed
1521
        if train_set is not None:
1522
            # Training task
wxchan's avatar
wxchan committed
1523
            if not isinstance(train_set, Dataset):
1524
1525
                raise TypeError('Training data should be Dataset instance, met {}'
                                .format(type(train_set).__name__))
wxchan's avatar
wxchan committed
1526
            params_str = param_dict_to_str(params)
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
            # set network if necessary
            for alias in ["machines", "workers", "nodes"]:
                if alias in params:
                    machines = params[alias]
                    if isinstance(machines, string_type):
                        num_machines = len(machines.split(','))
                    elif isinstance(machines, (list, set)):
                        num_machines = len(machines)
                        machines = ','.join(machines)
                    else:
                        raise ValueError("Invalid machines in params.")
                    self.set_network(machines,
                                     local_listen_port=params.get("local_listen_port", 12400),
                                     listen_time_out=params.get("listen_time_out", 120),
                                     num_machines=params.get("num_machines", num_machines))
                    break
1543
            # construct booster object
1544
            self.handle = ctypes.c_void_p()
wxchan's avatar
wxchan committed
1545
            _safe_call(_LIB.LGBM_BoosterCreate(
wxchan's avatar
wxchan committed
1546
                train_set.construct().handle,
wxchan's avatar
wxchan committed
1547
1548
                c_str(params_str),
                ctypes.byref(self.handle)))
1549
            # save reference to data
wxchan's avatar
wxchan committed
1550
1551
1552
1553
            self.train_set = train_set
            self.valid_sets = []
            self.name_valid_sets = []
            self.__num_dataset = 1
Guolin Ke's avatar
Guolin Ke committed
1554
1555
            self.__init_predictor = train_set._predictor
            if self.__init_predictor is not None:
wxchan's avatar
wxchan committed
1556
1557
                _safe_call(_LIB.LGBM_BoosterMerge(
                    self.handle,
Guolin Ke's avatar
Guolin Ke committed
1558
                    self.__init_predictor.handle))
Guolin Ke's avatar
Guolin Ke committed
1559
            out_num_class = ctypes.c_int(0)
wxchan's avatar
wxchan committed
1560
1561
1562
1563
            _safe_call(_LIB.LGBM_BoosterGetNumClasses(
                self.handle,
                ctypes.byref(out_num_class)))
            self.__num_class = out_num_class.value
1564
            # buffer for inner predict
wxchan's avatar
wxchan committed
1565
1566
1567
            self.__inner_predict_buffer = [None]
            self.__is_predicted_cur_iter = [False]
            self.__get_eval_info()
1568
            self.pandas_categorical = train_set.pandas_categorical
wxchan's avatar
wxchan committed
1569
        elif model_file is not None:
1570
            # Prediction task
Guolin Ke's avatar
Guolin Ke committed
1571
            out_num_iterations = ctypes.c_int(0)
1572
            self.handle = ctypes.c_void_p()
wxchan's avatar
wxchan committed
1573
1574
1575
1576
            _safe_call(_LIB.LGBM_BoosterCreateFromModelfile(
                c_str(model_file),
                ctypes.byref(out_num_iterations),
                ctypes.byref(self.handle)))
Guolin Ke's avatar
Guolin Ke committed
1577
            out_num_class = ctypes.c_int(0)
wxchan's avatar
wxchan committed
1578
1579
1580
1581
            _safe_call(_LIB.LGBM_BoosterGetNumClasses(
                self.handle,
                ctypes.byref(out_num_class)))
            self.__num_class = out_num_class.value
1582
            self.pandas_categorical = _load_pandas_categorical(file_name=model_file)
1583
        elif 'model_str' in params:
1584
            self.model_from_string(params['model_str'], False)
wxchan's avatar
wxchan committed
1585
        else:
1586
            raise TypeError('Need at least one training dataset or model file to create booster instance')
1587
        self.params = params
wxchan's avatar
wxchan committed
1588
1589

    def __del__(self):
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
        try:
            if self.network:
                self.free_network()
        except AttributeError:
            pass
        try:
            if self.handle is not None:
                _safe_call(_LIB.LGBM_BoosterFree(self.handle))
        except AttributeError:
            pass
wxchan's avatar
wxchan committed
1600

wxchan's avatar
wxchan committed
1601
1602
1603
1604
    def __copy__(self):
        return self.__deepcopy__(None)

    def __deepcopy__(self, _):
1605
        model_str = self.model_to_string(num_iteration=-1)
1606
1607
        booster = Booster({'model_str': model_str})
        return booster
wxchan's avatar
wxchan committed
1608
1609
1610
1611
1612
1613
1614

    def __getstate__(self):
        this = self.__dict__.copy()
        handle = this['handle']
        this.pop('train_set', None)
        this.pop('valid_sets', None)
        if handle is not None:
1615
            this["handle"] = self.model_to_string(num_iteration=-1)
wxchan's avatar
wxchan committed
1616
1617
1618
        return this

    def __setstate__(self, state):
1619
1620
        model_str = state.get('handle', None)
        if model_str is not None:
wxchan's avatar
wxchan committed
1621
            handle = ctypes.c_void_p()
Guolin Ke's avatar
Guolin Ke committed
1622
            out_num_iterations = ctypes.c_int(0)
1623
1624
1625
1626
            _safe_call(_LIB.LGBM_BoosterLoadModelFromString(
                c_str(model_str),
                ctypes.byref(out_num_iterations),
                ctypes.byref(handle)))
wxchan's avatar
wxchan committed
1627
1628
1629
            state['handle'] = handle
        self.__dict__.update(state)

wxchan's avatar
wxchan committed
1630
    def free_dataset(self):
Nikita Titov's avatar
Nikita Titov committed
1631
1632
1633
1634
1635
1636
1637
        """Free Booster's Datasets.

        Returns
        -------
        self : Booster
            Booster without Datasets.
        """
wxchan's avatar
wxchan committed
1638
1639
        self.__dict__.pop('train_set', None)
        self.__dict__.pop('valid_sets', None)
1640
        self.__num_dataset = 0
Nikita Titov's avatar
Nikita Titov committed
1641
        return self
wxchan's avatar
wxchan committed
1642

1643
1644
1645
    def _free_buffer(self):
        self.__inner_predict_buffer = []
        self.__is_predicted_cur_iter = []
Nikita Titov's avatar
Nikita Titov committed
1646
        return self
1647

1648
1649
1650
1651
1652
1653
    def set_network(self, machines, local_listen_port=12400,
                    listen_time_out=120, num_machines=1):
        """Set the network configuration.

        Parameters
        ----------
Nikita Titov's avatar
Nikita Titov committed
1654
        machines : list, set or string
1655
            Names of machines.
Nikita Titov's avatar
Nikita Titov committed
1656
        local_listen_port : int, optional (default=12400)
1657
            TCP listen port for local machines.
Nikita Titov's avatar
Nikita Titov committed
1658
        listen_time_out : int, optional (default=120)
1659
            Socket time-out in minutes.
Nikita Titov's avatar
Nikita Titov committed
1660
        num_machines : int, optional (default=1)
1661
            The number of machines for parallel learning application.
Nikita Titov's avatar
Nikita Titov committed
1662
1663
1664
1665
1666

        Returns
        -------
        self : Booster
            Booster with set network.
1667
1668
1669
1670
1671
1672
        """
        _safe_call(_LIB.LGBM_NetworkInit(c_str(machines),
                                         ctypes.c_int(local_listen_port),
                                         ctypes.c_int(listen_time_out),
                                         ctypes.c_int(num_machines)))
        self.network = True
Nikita Titov's avatar
Nikita Titov committed
1673
        return self
1674
1675

    def free_network(self):
Nikita Titov's avatar
Nikita Titov committed
1676
1677
1678
1679
1680
1681
1682
        """Free Booster's network.

        Returns
        -------
        self : Booster
            Booster with freed network.
        """
1683
1684
        _safe_call(_LIB.LGBM_NetworkFree())
        self.network = False
Nikita Titov's avatar
Nikita Titov committed
1685
        return self
1686

wxchan's avatar
wxchan committed
1687
    def set_train_data_name(self, name):
1688
1689
1690
1691
        """Set the name to the training Dataset.

        Parameters
        ----------
Nikita Titov's avatar
Nikita Titov committed
1692
1693
1694
1695
1696
1697
1698
        name : string
            Name for the training Dataset.

        Returns
        -------
        self : Booster
            Booster with set training Dataset name.
1699
        """
wxchan's avatar
wxchan committed
1700
        self.__train_data_name = name
Nikita Titov's avatar
Nikita Titov committed
1701
        return self
wxchan's avatar
wxchan committed
1702
1703

    def add_valid(self, data, name):
1704
        """Add validation data.
wxchan's avatar
wxchan committed
1705
1706
1707
1708

        Parameters
        ----------
        data : Dataset
1709
1710
1711
            Validation data.
        name : string
            Name of validation data.
Nikita Titov's avatar
Nikita Titov committed
1712
1713
1714
1715
1716

        Returns
        -------
        self : Booster
            Booster with set validation data.
wxchan's avatar
wxchan committed
1717
        """
Guolin Ke's avatar
Guolin Ke committed
1718
        if not isinstance(data, Dataset):
1719
1720
            raise TypeError('Validation data should be Dataset instance, met {}'
                            .format(type(data).__name__))
Guolin Ke's avatar
Guolin Ke committed
1721
        if data._predictor is not self.__init_predictor:
1722
1723
            raise LightGBMError("Add validation data failed, "
                                "you should use same predictor for these data")
wxchan's avatar
wxchan committed
1724
1725
        _safe_call(_LIB.LGBM_BoosterAddValidData(
            self.handle,
wxchan's avatar
wxchan committed
1726
            data.construct().handle))
wxchan's avatar
wxchan committed
1727
1728
1729
1730
1731
        self.valid_sets.append(data)
        self.name_valid_sets.append(name)
        self.__num_dataset += 1
        self.__inner_predict_buffer.append(None)
        self.__is_predicted_cur_iter.append(False)
Nikita Titov's avatar
Nikita Titov committed
1732
        return self
wxchan's avatar
wxchan committed
1733
1734

    def reset_parameter(self, params):
1735
        """Reset parameters of Booster.
wxchan's avatar
wxchan committed
1736
1737
1738
1739

        Parameters
        ----------
        params : dict
1740
            New parameters for Booster.
Nikita Titov's avatar
Nikita Titov committed
1741
1742
1743
1744
1745

        Returns
        -------
        self : Booster
            Booster with new parameters.
wxchan's avatar
wxchan committed
1746
        """
1747
        if any(metric_alias in params for metric_alias in ('metric', 'metrics', 'metric_types')):
wxchan's avatar
wxchan committed
1748
1749
1750
1751
1752
1753
            self.__need_reload_eval_info = True
        params_str = param_dict_to_str(params)
        if params_str:
            _safe_call(_LIB.LGBM_BoosterResetParameter(
                self.handle,
                c_str(params_str)))
Guolin Ke's avatar
Guolin Ke committed
1754
        self.params.update(params)
Nikita Titov's avatar
Nikita Titov committed
1755
        return self
wxchan's avatar
wxchan committed
1756
1757

    def update(self, train_set=None, fobj=None):
Nikita Titov's avatar
Nikita Titov committed
1758
        """Update Booster for one iteration.
1759

wxchan's avatar
wxchan committed
1760
1761
        Parameters
        ----------
1762
1763
1764
1765
        train_set : Dataset or None, optional (default=None)
            Training data.
            If None, last training data is used.
        fobj : callable or None, optional (default=None)
wxchan's avatar
wxchan committed
1766
1767
            Customized objective function.

1768
1769
1770
1771
            For multi-class task, the score is group by class_id first, then group by row_id.
            If you want to get i-th row score in j-th class, the access way is score[j * num_data + i]
            and you should group grad and hess in this way as well.

wxchan's avatar
wxchan committed
1772
1773
        Returns
        -------
1774
1775
        is_finished : bool
            Whether the update was successfully finished.
wxchan's avatar
wxchan committed
1776
        """
1777
        # need reset training data
wxchan's avatar
wxchan committed
1778
        if train_set is not None and train_set is not self.train_set:
Guolin Ke's avatar
Guolin Ke committed
1779
            if not isinstance(train_set, Dataset):
1780
1781
                raise TypeError('Training data should be Dataset instance, met {}'
                                .format(type(train_set).__name__))
Guolin Ke's avatar
Guolin Ke committed
1782
            if train_set._predictor is not self.__init_predictor:
1783
1784
                raise LightGBMError("Replace training data failed, "
                                    "you should use same predictor for these data")
wxchan's avatar
wxchan committed
1785
1786
1787
            self.train_set = train_set
            _safe_call(_LIB.LGBM_BoosterResetTrainingData(
                self.handle,
wxchan's avatar
wxchan committed
1788
                self.train_set.construct().handle))
wxchan's avatar
wxchan committed
1789
1790
1791
            self.__inner_predict_buffer[0] = None
        is_finished = ctypes.c_int(0)
        if fobj is None:
1792
            if self.__set_objective_to_none:
1793
                raise LightGBMError('Cannot update due to null objective function.')
wxchan's avatar
wxchan committed
1794
1795
1796
            _safe_call(_LIB.LGBM_BoosterUpdateOneIter(
                self.handle,
                ctypes.byref(is_finished)))
wxchan's avatar
wxchan committed
1797
            self.__is_predicted_cur_iter = [False for _ in range_(self.__num_dataset)]
wxchan's avatar
wxchan committed
1798
1799
            return is_finished.value == 1
        else:
1800
            if not self.__set_objective_to_none:
Nikita Titov's avatar
Nikita Titov committed
1801
                self.reset_parameter({"objective": "none"}).__set_objective_to_none = True
wxchan's avatar
wxchan committed
1802
1803
1804
1805
            grad, hess = fobj(self.__inner_predict(0), self.train_set)
            return self.__boost(grad, hess)

    def __boost(self, grad, hess):
1806
        """Boost Booster for one iteration with customized gradient statistics.
Nikita Titov's avatar
Nikita Titov committed
1807

1808
1809
1810
1811
1812
        Note
        ----
        For multi-class task, the score is group by class_id first, then group by row_id.
        If you want to get i-th row score in j-th class, the access way is score[j * num_data + i]
        and you should group grad and hess in this way as well.
1813

wxchan's avatar
wxchan committed
1814
1815
        Parameters
        ----------
1816
        grad : 1-D numpy array or 1-D list
Nikita Titov's avatar
Nikita Titov committed
1817
            The first order derivative (gradient).
1818
        hess : 1-D numpy array or 1-D list
Nikita Titov's avatar
Nikita Titov committed
1819
            The second order derivative (Hessian).
wxchan's avatar
wxchan committed
1820
1821
1822

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1823
1824
        is_finished : bool
            Whether the boost was successfully finished.
wxchan's avatar
wxchan committed
1825
        """
1826
1827
        grad = list_to_1d_numpy(grad, name='gradient')
        hess = list_to_1d_numpy(hess, name='hessian')
1828
1829
        assert grad.flags.c_contiguous
        assert hess.flags.c_contiguous
wxchan's avatar
wxchan committed
1830
        if len(grad) != len(hess):
1831
1832
            raise ValueError("Lengths of gradient({}) and hessian({}) don't match"
                             .format(len(grad), len(hess)))
wxchan's avatar
wxchan committed
1833
1834
1835
1836
1837
1838
        is_finished = ctypes.c_int(0)
        _safe_call(_LIB.LGBM_BoosterUpdateOneIterCustom(
            self.handle,
            grad.ctypes.data_as(ctypes.POINTER(ctypes.c_float)),
            hess.ctypes.data_as(ctypes.POINTER(ctypes.c_float)),
            ctypes.byref(is_finished)))
wxchan's avatar
wxchan committed
1839
        self.__is_predicted_cur_iter = [False for _ in range_(self.__num_dataset)]
wxchan's avatar
wxchan committed
1840
1841
1842
        return is_finished.value == 1

    def rollback_one_iter(self):
Nikita Titov's avatar
Nikita Titov committed
1843
1844
1845
1846
1847
1848
1849
        """Rollback one iteration.

        Returns
        -------
        self : Booster
            Booster with rolled back one iteration.
        """
wxchan's avatar
wxchan committed
1850
1851
        _safe_call(_LIB.LGBM_BoosterRollbackOneIter(
            self.handle))
wxchan's avatar
wxchan committed
1852
        self.__is_predicted_cur_iter = [False for _ in range_(self.__num_dataset)]
Nikita Titov's avatar
Nikita Titov committed
1853
        return self
wxchan's avatar
wxchan committed
1854
1855

    def current_iteration(self):
1856
1857
1858
1859
1860
1861
1862
        """Get the index of the current iteration.

        Returns
        -------
        cur_iter : int
            The index of the current iteration.
        """
Guolin Ke's avatar
Guolin Ke committed
1863
        out_cur_iter = ctypes.c_int(0)
wxchan's avatar
wxchan committed
1864
1865
1866
1867
1868
        _safe_call(_LIB.LGBM_BoosterGetCurrentIteration(
            self.handle,
            ctypes.byref(out_cur_iter)))
        return out_cur_iter.value

1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
    def num_model_per_iteration(self):
        """Get number of models per iteration.

        Returns
        -------
        model_per_iter : int
            The number of models per iteration.
        """
        model_per_iter = ctypes.c_int(0)
        _safe_call(_LIB.LGBM_BoosterNumModelPerIteration(
            self.handle,
            ctypes.byref(model_per_iter)))
        return model_per_iter.value

    def num_trees(self):
        """Get number of weak sub-models.

        Returns
        -------
        num_trees : int
            The number of weak sub-models.
        """
        num_trees = ctypes.c_int(0)
        _safe_call(_LIB.LGBM_BoosterNumberOfTotalModel(
            self.handle,
            ctypes.byref(num_trees)))
        return num_trees.value

wxchan's avatar
wxchan committed
1897
    def eval(self, data, name, feval=None):
1898
        """Evaluate for data.
wxchan's avatar
wxchan committed
1899
1900
1901

        Parameters
        ----------
1902
1903
1904
1905
1906
        data : Dataset
            Data for the evaluating.
        name : string
            Name of the data.
        feval : callable or None, optional (default=None)
1907
            Customized evaluation function.
1908
1909
            Should accept two parameters: preds, train_data,
            and return (eval_name, eval_result, is_higher_better) or list of such tuples.
1910
1911
            For multi-class task, the preds is group by class_id first, then group by row_id.
            If you want to get i-th row preds in j-th class, the access way is preds[j * num_data + i].
1912

wxchan's avatar
wxchan committed
1913
1914
        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1915
        result : list
1916
            List with evaluation results.
wxchan's avatar
wxchan committed
1917
        """
Guolin Ke's avatar
Guolin Ke committed
1918
1919
        if not isinstance(data, Dataset):
            raise TypeError("Can only eval for Dataset instance")
wxchan's avatar
wxchan committed
1920
1921
1922
1923
        data_idx = -1
        if data is self.train_set:
            data_idx = 0
        else:
wxchan's avatar
wxchan committed
1924
            for i in range_(len(self.valid_sets)):
wxchan's avatar
wxchan committed
1925
1926
1927
                if data is self.valid_sets[i]:
                    data_idx = i + 1
                    break
1928
        # need to push new valid data
wxchan's avatar
wxchan committed
1929
1930
1931
1932
1933
1934
1935
        if data_idx == -1:
            self.add_valid(data, name)
            data_idx = self.__num_dataset - 1

        return self.__inner_eval(name, data_idx, feval)

    def eval_train(self, feval=None):
1936
        """Evaluate for training data.
wxchan's avatar
wxchan committed
1937
1938
1939

        Parameters
        ----------
1940
        feval : callable or None, optional (default=None)
1941
            Customized evaluation function.
1942
1943
            Should accept two parameters: preds, train_data,
            and return (eval_name, eval_result, is_higher_better) or list of such tuples.
1944
1945
            For multi-class task, the preds is group by class_id first, then group by row_id.
            If you want to get i-th row preds in j-th class, the access way is preds[j * num_data + i].
wxchan's avatar
wxchan committed
1946
1947
1948

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1949
        result : list
1950
            List with evaluation results.
wxchan's avatar
wxchan committed
1951
1952
1953
1954
        """
        return self.__inner_eval(self.__train_data_name, 0, feval)

    def eval_valid(self, feval=None):
1955
        """Evaluate for validation data.
wxchan's avatar
wxchan committed
1956
1957
1958

        Parameters
        ----------
1959
        feval : callable or None, optional (default=None)
1960
            Customized evaluation function.
1961
1962
            Should accept two parameters: preds, train_data,
            and return (eval_name, eval_result, is_higher_better) or list of such tuples.
1963
1964
            For multi-class task, the preds is group by class_id first, then group by row_id.
            If you want to get i-th row preds in j-th class, the access way is preds[j * num_data + i].
wxchan's avatar
wxchan committed
1965
1966
1967

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1968
        result : list
1969
            List with evaluation results.
wxchan's avatar
wxchan committed
1970
        """
wxchan's avatar
wxchan committed
1971
        return [item for i in range_(1, self.__num_dataset)
wxchan's avatar
wxchan committed
1972
                for item in self.__inner_eval(self.name_valid_sets[i - 1], i, feval)]
wxchan's avatar
wxchan committed
1973

1974
    def save_model(self, filename, num_iteration=None, start_iteration=0):
1975
        """Save Booster to file.
wxchan's avatar
wxchan committed
1976
1977
1978

        Parameters
        ----------
1979
1980
        filename : string
            Filename to save Booster.
1981
1982
1983
1984
        num_iteration : int or None, optional (default=None)
            Index of the iteration that should be saved.
            If None, if the best iteration exists, it is saved; otherwise, all iterations are saved.
            If <= 0, all iterations are saved.
Nikita Titov's avatar
Nikita Titov committed
1985
        start_iteration : int, optional (default=0)
1986
            Start index of the iteration that should be saved.
Nikita Titov's avatar
Nikita Titov committed
1987
1988
1989
1990
1991

        Returns
        -------
        self : Booster
            Returns self.
wxchan's avatar
wxchan committed
1992
        """
1993
        if num_iteration is None:
1994
            num_iteration = self.best_iteration
wxchan's avatar
wxchan committed
1995
1996
        _safe_call(_LIB.LGBM_BoosterSaveModel(
            self.handle,
1997
            ctypes.c_int(start_iteration),
Guolin Ke's avatar
Guolin Ke committed
1998
            ctypes.c_int(num_iteration),
wxchan's avatar
wxchan committed
1999
            c_str(filename)))
2000
        _dump_pandas_categorical(self.pandas_categorical, filename)
Nikita Titov's avatar
Nikita Titov committed
2001
        return self
wxchan's avatar
wxchan committed
2002

2003
    def shuffle_models(self, start_iteration=0, end_iteration=-1):
2004
        """Shuffle models.
Nikita Titov's avatar
Nikita Titov committed
2005

2006
2007
2008
        Parameters
        ----------
        start_iteration : int, optional (default=0)
2009
            The first iteration that will be shuffled.
2010
2011
        end_iteration : int, optional (default=-1)
            The last iteration that will be shuffled.
2012
            If <= 0, means the last available iteration.
2013

Nikita Titov's avatar
Nikita Titov committed
2014
2015
2016
2017
        Returns
        -------
        self : Booster
            Booster with shuffled models.
2018
        """
2019
2020
        _safe_call(_LIB.LGBM_BoosterShuffleModels(
            self.handle,
Guolin Ke's avatar
Guolin Ke committed
2021
2022
            ctypes.c_int(start_iteration),
            ctypes.c_int(end_iteration)))
Nikita Titov's avatar
Nikita Titov committed
2023
        return self
2024
2025
2026
2027
2028
2029

    def model_from_string(self, model_str, verbose=True):
        """Load Booster from a string.

        Parameters
        ----------
Nikita Titov's avatar
Nikita Titov committed
2030
        model_str : string
2031
            Model will be loaded from this string.
Nikita Titov's avatar
Nikita Titov committed
2032
2033
        verbose : bool, optional (default=True)
            Whether to print messages while loading model.
2034
2035
2036

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
2037
        self : Booster
2038
2039
            Loaded Booster object.
        """
2040
2041
2042
2043
        if self.handle is not None:
            _safe_call(_LIB.LGBM_BoosterFree(self.handle))
        self._free_buffer()
        self.handle = ctypes.c_void_p()
2044
2045
2046
2047
2048
2049
2050
2051
2052
        out_num_iterations = ctypes.c_int(0)
        _safe_call(_LIB.LGBM_BoosterLoadModelFromString(
            c_str(model_str),
            ctypes.byref(out_num_iterations),
            ctypes.byref(self.handle)))
        out_num_class = ctypes.c_int(0)
        _safe_call(_LIB.LGBM_BoosterGetNumClasses(
            self.handle,
            ctypes.byref(out_num_class)))
2053
        if verbose:
Nikita Titov's avatar
Nikita Titov committed
2054
            print('Finished loading model, total used %d iterations' % int(out_num_iterations.value))
2055
        self.__num_class = out_num_class.value
2056
        self.pandas_categorical = _load_pandas_categorical(model_str=model_str)
2057
2058
2059
2060
        return self

    def model_to_string(self, num_iteration=None, start_iteration=0):
        """Save Booster to string.
2061

2062
2063
2064
2065
2066
2067
        Parameters
        ----------
        num_iteration : int or None, optional (default=None)
            Index of the iteration that should be saved.
            If None, if the best iteration exists, it is saved; otherwise, all iterations are saved.
            If <= 0, all iterations are saved.
Nikita Titov's avatar
Nikita Titov committed
2068
        start_iteration : int, optional (default=0)
2069
2070
2071
2072
            Start index of the iteration that should be saved.

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
2073
        str_repr : string
2074
2075
            String representation of Booster.
        """
2076
        if num_iteration is None:
2077
2078
            num_iteration = self.best_iteration
        buffer_len = 1 << 20
2079
        tmp_out_len = ctypes.c_int64(0)
2080
2081
2082
2083
        string_buffer = ctypes.create_string_buffer(buffer_len)
        ptr_string_buffer = ctypes.c_char_p(*[ctypes.addressof(string_buffer)])
        _safe_call(_LIB.LGBM_BoosterSaveModelToString(
            self.handle,
2084
            ctypes.c_int(start_iteration),
2085
            ctypes.c_int(num_iteration),
2086
            ctypes.c_int64(buffer_len),
2087
2088
2089
            ctypes.byref(tmp_out_len),
            ptr_string_buffer))
        actual_len = tmp_out_len.value
2090
        # if buffer length is not long enough, re-allocate a buffer
2091
2092
2093
2094
2095
        if actual_len > buffer_len:
            string_buffer = ctypes.create_string_buffer(actual_len)
            ptr_string_buffer = ctypes.c_char_p(*[ctypes.addressof(string_buffer)])
            _safe_call(_LIB.LGBM_BoosterSaveModelToString(
                self.handle,
2096
                ctypes.c_int(start_iteration),
2097
                ctypes.c_int(num_iteration),
2098
                ctypes.c_int64(actual_len),
2099
2100
                ctypes.byref(tmp_out_len),
                ptr_string_buffer))
2101
2102
2103
        ret = string_buffer.value.decode()
        ret += _dump_pandas_categorical(self.pandas_categorical)
        return ret
2104

2105
    def dump_model(self, num_iteration=None, start_iteration=0):
Nikita Titov's avatar
Nikita Titov committed
2106
        """Dump Booster to JSON format.
wxchan's avatar
wxchan committed
2107

2108
2109
        Parameters
        ----------
2110
2111
2112
2113
        num_iteration : int or None, optional (default=None)
            Index of the iteration that should be dumped.
            If None, if the best iteration exists, it is dumped; otherwise, all iterations are dumped.
            If <= 0, all iterations are dumped.
Nikita Titov's avatar
Nikita Titov committed
2114
        start_iteration : int, optional (default=0)
2115
            Start index of the iteration that should be dumped.
2116

wxchan's avatar
wxchan committed
2117
2118
        Returns
        -------
2119
        json_repr : dict
Nikita Titov's avatar
Nikita Titov committed
2120
            JSON format of Booster.
wxchan's avatar
wxchan committed
2121
        """
2122
        if num_iteration is None:
2123
            num_iteration = self.best_iteration
wxchan's avatar
wxchan committed
2124
        buffer_len = 1 << 20
2125
        tmp_out_len = ctypes.c_int64(0)
wxchan's avatar
wxchan committed
2126
2127
2128
2129
        string_buffer = ctypes.create_string_buffer(buffer_len)
        ptr_string_buffer = ctypes.c_char_p(*[ctypes.addressof(string_buffer)])
        _safe_call(_LIB.LGBM_BoosterDumpModel(
            self.handle,
2130
            ctypes.c_int(start_iteration),
Guolin Ke's avatar
Guolin Ke committed
2131
            ctypes.c_int(num_iteration),
2132
            ctypes.c_int64(buffer_len),
wxchan's avatar
wxchan committed
2133
            ctypes.byref(tmp_out_len),
Guolin Ke's avatar
Guolin Ke committed
2134
            ptr_string_buffer))
wxchan's avatar
wxchan committed
2135
        actual_len = tmp_out_len.value
2136
        # if buffer length is not long enough, reallocate a buffer
wxchan's avatar
wxchan committed
2137
2138
2139
2140
2141
        if actual_len > buffer_len:
            string_buffer = ctypes.create_string_buffer(actual_len)
            ptr_string_buffer = ctypes.c_char_p(*[ctypes.addressof(string_buffer)])
            _safe_call(_LIB.LGBM_BoosterDumpModel(
                self.handle,
2142
                ctypes.c_int(start_iteration),
Guolin Ke's avatar
Guolin Ke committed
2143
                ctypes.c_int(num_iteration),
2144
                ctypes.c_int64(actual_len),
wxchan's avatar
wxchan committed
2145
                ctypes.byref(tmp_out_len),
Guolin Ke's avatar
Guolin Ke committed
2146
                ptr_string_buffer))
2147
2148
2149
2150
        ret = json.loads(string_buffer.value.decode())
        ret['pandas_categorical'] = json.loads(json.dumps(self.pandas_categorical,
                                                          default=json_default_with_numpy))
        return ret
wxchan's avatar
wxchan committed
2151

2152
2153
    def predict(self, data, num_iteration=None,
                raw_score=False, pred_leaf=False, pred_contrib=False,
2154
                data_has_header=False, is_reshape=True, **kwargs):
2155
        """Make a prediction.
wxchan's avatar
wxchan committed
2156
2157
2158

        Parameters
        ----------
2159
        data : string, numpy array, pandas DataFrame or scipy.sparse
2160
2161
            Data source for prediction.
            If string, it represents the path to txt file.
2162
2163
2164
2165
        num_iteration : int or None, optional (default=None)
            Limit number of iterations in the prediction.
            If None, if the best iteration exists, it is used; otherwise, all iterations are used.
            If <= 0, all iterations are used (no limits).
2166
2167
2168
2169
        raw_score : bool, optional (default=False)
            Whether to predict raw scores.
        pred_leaf : bool, optional (default=False)
            Whether to predict leaf index.
2170
2171
        pred_contrib : bool, optional (default=False)
            Whether to predict feature contributions.
2172
2173
2174
2175
2176
2177
2178

            Note
            ----
            If you want to get more explanation for your model's predictions using SHAP values
            like SHAP interaction values,
            you can install shap package (https://github.com/slundberg/shap).

2179
2180
2181
2182
2183
        data_has_header : bool, optional (default=False)
            Whether the data has header.
            Used only if data is string.
        is_reshape : bool, optional (default=True)
            If True, result is reshaped to [nrow, ncol].
2184
2185
        **kwargs
            Other parameters for the prediction.
wxchan's avatar
wxchan committed
2186
2187
2188

        Returns
        -------
2189
2190
        result : numpy array
            Prediction result.
wxchan's avatar
wxchan committed
2191
        """
2192
        predictor = self._to_predictor(copy.deepcopy(kwargs))
2193
        if num_iteration is None:
2194
            num_iteration = self.best_iteration
2195
2196
2197
        return predictor.predict(data, num_iteration,
                                 raw_score, pred_leaf, pred_contrib,
                                 data_has_header, is_reshape)
wxchan's avatar
wxchan committed
2198

2199
    def refit(self, data, label, decay_rate=0.9, **kwargs):
Guolin Ke's avatar
Guolin Ke committed
2200
2201
2202
2203
        """Refit the existing Booster by new data.

        Parameters
        ----------
2204
        data : string, numpy array, pandas DataFrame or scipy.sparse
Guolin Ke's avatar
Guolin Ke committed
2205
2206
            Data source for refit.
            If string, it represents the path to txt file.
2207
        label : list, numpy 1-D array or pandas Series / one-column DataFrame
Guolin Ke's avatar
Guolin Ke committed
2208
2209
            Label for refit.
        decay_rate : float, optional (default=0.9)
2210
2211
            Decay rate of refit,
            will use ``leaf_output = decay_rate * old_leaf_output + (1.0 - decay_rate) * new_leaf_output`` to refit trees.
2212
2213
        **kwargs
            Other parameters for refit.
2214
            These parameters will be passed to ``predict`` method.
Guolin Ke's avatar
Guolin Ke committed
2215
2216
2217
2218
2219
2220

        Returns
        -------
        result : Booster
            Refitted Booster.
        """
2221
2222
        if self.__set_objective_to_none:
            raise LightGBMError('Cannot refit due to null objective function.')
2223
        predictor = self._to_predictor(copy.deepcopy(kwargs))
2224
        leaf_preds = predictor.predict(data, -1, pred_leaf=True)
2225
        nrow, ncol = leaf_preds.shape
2226
        train_set = Dataset(data, label, silent=True)
Guolin Ke's avatar
Guolin Ke committed
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
        new_booster = Booster(self.params, train_set, silent=True)
        # Copy models
        _safe_call(_LIB.LGBM_BoosterMerge(
            new_booster.handle,
            predictor.handle))
        leaf_preds = leaf_preds.reshape(-1)
        ptr_data, type_ptr_data, _ = c_int_array(leaf_preds)
        _safe_call(_LIB.LGBM_BoosterRefit(
            new_booster.handle,
            ptr_data,
            ctypes.c_int(nrow),
            ctypes.c_int(ncol)))
2239
2240
        new_booster.network = self.network
        new_booster.__attr = self.__attr.copy()
Guolin Ke's avatar
Guolin Ke committed
2241
2242
        return new_booster

2243
    def get_leaf_output(self, tree_id, leaf_id):
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
        """Get the output of a leaf.

        Parameters
        ----------
        tree_id : int
            The index of the tree.
        leaf_id : int
            The index of the leaf in the tree.

        Returns
        -------
        result : float
            The output of the leaf.
        """
2258
2259
2260
2261
2262
2263
2264
2265
        ret = ctypes.c_double(0)
        _safe_call(_LIB.LGBM_BoosterGetLeafValue(
            self.handle,
            ctypes.c_int(tree_id),
            ctypes.c_int(leaf_id),
            ctypes.byref(ret)))
        return ret.value

2266
    def _to_predictor(self, pred_parameter=None):
2267
        """Convert to predictor."""
2268
        predictor = _InnerPredictor(booster_handle=self.handle, pred_parameter=pred_parameter)
2269
        predictor.pandas_categorical = self.pandas_categorical
wxchan's avatar
wxchan committed
2270
2271
        return predictor

2272
    def num_feature(self):
2273
2274
2275
2276
2277
2278
2279
        """Get number of features.

        Returns
        -------
        num_feature : int
            The number of features.
        """
2280
2281
2282
2283
2284
2285
        out_num_feature = ctypes.c_int(0)
        _safe_call(_LIB.LGBM_BoosterGetNumFeature(
            self.handle,
            ctypes.byref(out_num_feature)))
        return out_num_feature.value

wxchan's avatar
wxchan committed
2286
    def feature_name(self):
2287
        """Get names of features.
wxchan's avatar
wxchan committed
2288
2289
2290

        Returns
        -------
2291
2292
        result : list
            List with names of features.
wxchan's avatar
wxchan committed
2293
        """
2294
        num_feature = self.num_feature()
2295
        # Get name of features
wxchan's avatar
wxchan committed
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
        tmp_out_len = ctypes.c_int(0)
        string_buffers = [ctypes.create_string_buffer(255) for i in range_(num_feature)]
        ptr_string_buffers = (ctypes.c_char_p * num_feature)(*map(ctypes.addressof, string_buffers))
        _safe_call(_LIB.LGBM_BoosterGetFeatureNames(
            self.handle,
            ctypes.byref(tmp_out_len),
            ptr_string_buffers))
        if num_feature != tmp_out_len.value:
            raise ValueError("Length of feature names doesn't equal with num_feature")
        return [string_buffers[i].value.decode() for i in range_(num_feature)]

2307
    def feature_importance(self, importance_type='split', iteration=None):
2308
        """Get feature importances.
2309

2310
2311
        Parameters
        ----------
2312
2313
2314
2315
        importance_type : string, optional (default="split")
            How the importance is calculated.
            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.
2316
2317
2318
2319
        iteration : int or None, optional (default=None)
            Limit number of iterations in the feature importance calculation.
            If None, if the best iteration exists, it is used; otherwise, all trees are used.
            If <= 0, all trees are used (no limits).
2320

2321
2322
        Returns
        -------
2323
2324
        result : numpy array
            Array with feature importances.
2325
        """
2326
2327
        if iteration is None:
            iteration = self.best_iteration
2328
2329
2330
2331
2332
2333
        if importance_type == "split":
            importance_type_int = 0
        elif importance_type == "gain":
            importance_type_int = 1
        else:
            importance_type_int = -1
Nikita Titov's avatar
Nikita Titov committed
2334
        result = np.zeros(self.num_feature(), dtype=np.float64)
2335
2336
2337
2338
2339
2340
2341
2342
2343
        _safe_call(_LIB.LGBM_BoosterFeatureImportance(
            self.handle,
            ctypes.c_int(iteration),
            ctypes.c_int(importance_type_int),
            result.ctypes.data_as(ctypes.POINTER(ctypes.c_double))))
        if importance_type_int == 0:
            return result.astype(int)
        else:
            return result
2344

wxchan's avatar
wxchan committed
2345
    def __inner_eval(self, data_name, data_idx, feval=None):
2346
        """Evaluate training or validation data."""
wxchan's avatar
wxchan committed
2347
        if data_idx >= self.__num_dataset:
2348
            raise ValueError("Data_idx should be smaller than number of dataset")
wxchan's avatar
wxchan committed
2349
2350
2351
        self.__get_eval_info()
        ret = []
        if self.__num_inner_eval > 0:
2352
            result = np.zeros(self.__num_inner_eval, dtype=np.float64)
Guolin Ke's avatar
Guolin Ke committed
2353
            tmp_out_len = ctypes.c_int(0)
wxchan's avatar
wxchan committed
2354
2355
            _safe_call(_LIB.LGBM_BoosterGetEval(
                self.handle,
Guolin Ke's avatar
Guolin Ke committed
2356
                ctypes.c_int(data_idx),
wxchan's avatar
wxchan committed
2357
                ctypes.byref(tmp_out_len),
Guolin Ke's avatar
Guolin Ke committed
2358
                result.ctypes.data_as(ctypes.POINTER(ctypes.c_double))))
wxchan's avatar
wxchan committed
2359
            if tmp_out_len.value != self.__num_inner_eval:
2360
                raise ValueError("Wrong length of eval results")
wxchan's avatar
wxchan committed
2361
            for i in range_(self.__num_inner_eval):
2362
2363
                ret.append((data_name, self.__name_inner_eval[i],
                            result[i], self.__higher_better_inner_eval[i]))
wxchan's avatar
wxchan committed
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
        if feval is not None:
            if data_idx == 0:
                cur_data = self.train_set
            else:
                cur_data = self.valid_sets[data_idx - 1]
            feval_ret = feval(self.__inner_predict(data_idx), cur_data)
            if isinstance(feval_ret, list):
                for eval_name, val, is_higher_better in feval_ret:
                    ret.append((data_name, eval_name, val, is_higher_better))
            else:
                eval_name, val, is_higher_better = feval_ret
                ret.append((data_name, eval_name, val, is_higher_better))
        return ret

    def __inner_predict(self, data_idx):
2379
        """Predict for training and validation dataset."""
wxchan's avatar
wxchan committed
2380
        if data_idx >= self.__num_dataset:
2381
            raise ValueError("Data_idx should be smaller than number of dataset")
wxchan's avatar
wxchan committed
2382
2383
2384
2385
2386
        if self.__inner_predict_buffer[data_idx] is None:
            if data_idx == 0:
                n_preds = self.train_set.num_data() * self.__num_class
            else:
                n_preds = self.valid_sets[data_idx - 1].num_data() * self.__num_class
2387
            self.__inner_predict_buffer[data_idx] = np.zeros(n_preds, dtype=np.float64)
2388
        # avoid to predict many time in one iteration
wxchan's avatar
wxchan committed
2389
2390
        if not self.__is_predicted_cur_iter[data_idx]:
            tmp_out_len = ctypes.c_int64(0)
Guolin Ke's avatar
Guolin Ke committed
2391
            data_ptr = self.__inner_predict_buffer[data_idx].ctypes.data_as(ctypes.POINTER(ctypes.c_double))
wxchan's avatar
wxchan committed
2392
2393
            _safe_call(_LIB.LGBM_BoosterGetPredict(
                self.handle,
Guolin Ke's avatar
Guolin Ke committed
2394
                ctypes.c_int(data_idx),
wxchan's avatar
wxchan committed
2395
2396
2397
                ctypes.byref(tmp_out_len),
                data_ptr))
            if tmp_out_len.value != len(self.__inner_predict_buffer[data_idx]):
2398
                raise ValueError("Wrong length of predict results for data %d" % (data_idx))
wxchan's avatar
wxchan committed
2399
2400
2401
2402
            self.__is_predicted_cur_iter[data_idx] = True
        return self.__inner_predict_buffer[data_idx]

    def __get_eval_info(self):
2403
        """Get inner evaluation count and names."""
wxchan's avatar
wxchan committed
2404
2405
        if self.__need_reload_eval_info:
            self.__need_reload_eval_info = False
Guolin Ke's avatar
Guolin Ke committed
2406
            out_num_eval = ctypes.c_int(0)
2407
            # Get num of inner evals
wxchan's avatar
wxchan committed
2408
2409
2410
2411
2412
            _safe_call(_LIB.LGBM_BoosterGetEvalCounts(
                self.handle,
                ctypes.byref(out_num_eval)))
            self.__num_inner_eval = out_num_eval.value
            if self.__num_inner_eval > 0:
2413
                # Get name of evals
Guolin Ke's avatar
Guolin Ke committed
2414
                tmp_out_len = ctypes.c_int(0)
wxchan's avatar
wxchan committed
2415
                string_buffers = [ctypes.create_string_buffer(255) for i in range_(self.__num_inner_eval)]
wxchan's avatar
wxchan committed
2416
                ptr_string_buffers = (ctypes.c_char_p * self.__num_inner_eval)(*map(ctypes.addressof, string_buffers))
wxchan's avatar
wxchan committed
2417
2418
2419
2420
2421
                _safe_call(_LIB.LGBM_BoosterGetEvalNames(
                    self.handle,
                    ctypes.byref(tmp_out_len),
                    ptr_string_buffers))
                if self.__num_inner_eval != tmp_out_len.value:
2422
                    raise ValueError("Length of eval names doesn't equal with num_evals")
2423
                self.__name_inner_eval = \
wxchan's avatar
wxchan committed
2424
                    [string_buffers[i].value.decode() for i in range_(self.__num_inner_eval)]
2425
                self.__higher_better_inner_eval = \
2426
                    [name.startswith(('auc', 'ndcg@', 'map@')) for name in self.__name_inner_eval]
2427

wxchan's avatar
wxchan committed
2428
    def attr(self, key):
2429
        """Get attribute string from the Booster.
wxchan's avatar
wxchan committed
2430
2431
2432

        Parameters
        ----------
2433
2434
        key : string
            The name of the attribute.
wxchan's avatar
wxchan committed
2435
2436
2437

        Returns
        -------
2438
2439
        value : string or None
            The attribute value.
Nikita Titov's avatar
Nikita Titov committed
2440
            Returns None if attribute does not exist.
wxchan's avatar
wxchan committed
2441
        """
2442
        return self.__attr.get(key, None)
wxchan's avatar
wxchan committed
2443
2444

    def set_attr(self, **kwargs):
2445
        """Set attributes to the Booster.
wxchan's avatar
wxchan committed
2446
2447
2448
2449

        Parameters
        ----------
        **kwargs
2450
2451
            The attributes to set.
            Setting a value to None deletes an attribute.
Nikita Titov's avatar
Nikita Titov committed
2452
2453
2454
2455

        Returns
        -------
        self : Booster
2456
            Booster with set attributes.
wxchan's avatar
wxchan committed
2457
2458
2459
        """
        for key, value in kwargs.items():
            if value is not None:
wxchan's avatar
wxchan committed
2460
                if not isinstance(value, string_type):
Nikita Titov's avatar
Nikita Titov committed
2461
                    raise ValueError("Only string values are accepted")
wxchan's avatar
wxchan committed
2462
2463
2464
                self.__attr[key] = value
            else:
                self.__attr.pop(key, None)
Nikita Titov's avatar
Nikita Titov committed
2465
        return self