basic.py 61.5 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
wxchan's avatar
wxchan committed
4
5
6
7
"""Wrapper c_api of LightGBM"""
from __future__ import absolute_import

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

import numpy as np
import scipy.sparse

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

wxchan's avatar
wxchan committed
20

wxchan's avatar
wxchan committed
21
22
23
24
25
26
27
28
29
def _load_lib():
    """Load LightGBM Library."""
    lib_path = find_lib_path()
    if len(lib_path) == 0:
        raise Exception("cannot find LightGBM library")
    lib = ctypes.cdll.LoadLibrary(lib_path[0])
    lib.LGBM_GetLastError.restype = ctypes.c_char_p
    return lib

wxchan's avatar
wxchan committed
30

wxchan's avatar
wxchan committed
31
32
_LIB = _load_lib()

wxchan's avatar
wxchan committed
33

wxchan's avatar
wxchan committed
34
35
36
37
class LightGBMError(Exception):
    """Error throwed by LightGBM"""
    pass

wxchan's avatar
wxchan committed
38

wxchan's avatar
wxchan committed
39
40
41
42
43
44
45
46
47
48
def _safe_call(ret):
    """Check the return value of C API call
    Parameters
    ----------
    ret : int
        return value from API calls
    """
    if ret != 0:
        raise LightGBMError(_LIB.LGBM_GetLastError())

wxchan's avatar
wxchan committed
49

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

wxchan's avatar
wxchan committed
60

wxchan's avatar
wxchan committed
61
def is_numpy_1d_array(data):
Guolin Ke's avatar
Guolin Ke committed
62
    """Check is 1d numpy array"""
63
    return isinstance(data, np.ndarray) and len(data.shape) == 1
wxchan's avatar
wxchan committed
64

wxchan's avatar
wxchan committed
65

wxchan's avatar
wxchan committed
66
def is_1d_list(data):
Guolin Ke's avatar
Guolin Ke committed
67
    """Check is 1d list"""
68
    return isinstance(data, list) and \
wxchan's avatar
wxchan committed
69
        (not data or isinstance(data[0], numeric_types))
wxchan's avatar
wxchan committed
70

wxchan's avatar
wxchan committed
71

72
def list_to_1d_numpy(data, dtype=np.float32, name='list'):
Guolin Ke's avatar
Guolin Ke committed
73
    """convert to 1d numpy array"""
wxchan's avatar
wxchan committed
74
75
76
77
78
79
80
    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)
81
82
    elif isinstance(data, Series):
        return data.values.astype(dtype)
wxchan's avatar
wxchan committed
83
    else:
84
        raise TypeError("Wrong type({}) for {}, should be list or numpy array".format(type(data).__name__, name))
wxchan's avatar
wxchan committed
85

wxchan's avatar
wxchan committed
86

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

Guolin Ke's avatar
Guolin Ke committed
95

Guolin Ke's avatar
Guolin Ke committed
96
97
98
99
100
101
102
103
def cfloat64_array_to_numpy(cptr, length):
    """Convert a ctypes double pointer array to a numpy array.
    """
    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
104

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

wxchan's avatar
wxchan committed
113

wxchan's avatar
wxchan committed
114
115
116
117
def c_str(string):
    """Convert a python string to cstring."""
    return ctypes.c_char_p(string.encode('utf-8'))

wxchan's avatar
wxchan committed
118

wxchan's avatar
wxchan committed
119
120
121
122
def c_array(ctype, values):
    """Convert a python array to c array."""
    return (ctype * len(values))(*values)

wxchan's avatar
wxchan committed
123

wxchan's avatar
wxchan committed
124
def param_dict_to_str(data):
125
    if data is None or not data:
wxchan's avatar
wxchan committed
126
127
128
        return ""
    pairs = []
    for key, val in data.items():
129
        if isinstance(val, (list, tuple, set)) or is_numpy_1d_array(val):
wxchan's avatar
wxchan committed
130
            pairs.append(str(key) + '=' + ','.join(map(str, val)))
wxchan's avatar
wxchan committed
131
        elif isinstance(val, string_type) or isinstance(val, numeric_types) or is_numeric(val):
wxchan's avatar
wxchan committed
132
            pairs.append(str(key) + '=' + str(val))
wxchan's avatar
wxchan committed
133
        else:
134
            raise TypeError('Unknown type of parameter:%s, got:%s'
wxchan's avatar
wxchan committed
135
136
                            % (key, type(val).__name__))
    return ' '.join(pairs)
137

wxchan's avatar
wxchan committed
138

139
class _temp_file(object):
140
141
142
143
    def __enter__(self):
        with NamedTemporaryFile(prefix="lightgbm_tmp_", delete=True) as f:
            self.name = f.name
        return self
wxchan's avatar
wxchan committed
144

145
146
147
    def __exit__(self, exc_type, exc_val, exc_tb):
        if os.path.isfile(self.name):
            os.remove(self.name)
wxchan's avatar
wxchan committed
148

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

154
155
    def writelines(self, lines):
        with open(self.name, "w+") as f:
156
            f.writelines(lines)
157

wxchan's avatar
wxchan committed
158

wxchan's avatar
wxchan committed
159
160
161
162
163
"""marco definition of data type in c_api of LightGBM"""
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
164

wxchan's avatar
wxchan committed
165
166
167
"""Matric is row major in python"""
C_API_IS_ROW_MAJOR = 1

Guolin Ke's avatar
Guolin Ke committed
168
"""marco definition of prediction type in c_api of LightGBM"""
wxchan's avatar
wxchan committed
169
170
171
172
C_API_PREDICT_NORMAL = 0
C_API_PREDICT_RAW_SCORE = 1
C_API_PREDICT_LEAF_INDEX = 2

Guolin Ke's avatar
Guolin Ke committed
173
"""data type of data field"""
wxchan's avatar
wxchan committed
174
175
FIELD_TYPE_MAPPER = {"label": C_API_DTYPE_FLOAT32,
                     "weight": C_API_DTYPE_FLOAT32,
Guolin Ke's avatar
Guolin Ke committed
176
                     "init_score": C_API_DTYPE_FLOAT64,
wxchan's avatar
wxchan committed
177
178
                     "group": C_API_DTYPE_INT32}

wxchan's avatar
wxchan committed
179

wxchan's avatar
wxchan committed
180
def c_float_array(data):
Guolin Ke's avatar
Guolin Ke committed
181
    """get pointer of float numpy array / list"""
wxchan's avatar
wxchan committed
182
183
184
185
186
187
188
189
190
191
    if is_1d_list(data):
        data = np.array(data, copy=False)
    if is_numpy_1d_array(data):
        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:
192
            raise TypeError("Expected np.float32 or np.float64, met type({})"
wxchan's avatar
wxchan committed
193
194
                            .format(data.dtype))
    else:
195
        raise TypeError("Unknown type({})".format(type(data).__name__))
wxchan's avatar
wxchan committed
196
197
    return (ptr_data, type_data)

wxchan's avatar
wxchan committed
198

wxchan's avatar
wxchan committed
199
def c_int_array(data):
Guolin Ke's avatar
Guolin Ke committed
200
    """get pointer of int numpy array / list"""
wxchan's avatar
wxchan committed
201
202
203
204
205
206
207
208
209
210
    if is_1d_list(data):
        data = np.array(data, copy=False)
    if is_numpy_1d_array(data):
        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:
211
            raise TypeError("Expected np.int32 or np.int64, met type({})"
wxchan's avatar
wxchan committed
212
213
                            .format(data.dtype))
    else:
214
        raise TypeError("Unknown type({})".format(type(data).__name__))
wxchan's avatar
wxchan committed
215
216
    return (ptr_data, type_data)

wxchan's avatar
wxchan committed
217

218
219
220
221
222
223
PANDAS_DTYPE_MAPPER = {'int8': 'int', 'int16': 'int', 'int32': 'int',
                       'int64': 'int', 'uint8': 'int', 'uint16': 'int',
                       'uint32': 'int', 'uint64': 'int', 'float16': 'float',
                       'float32': 'float', 'float64': 'float', 'bool': 'int'}


Guolin Ke's avatar
Guolin Ke committed
224
def _data_from_pandas(data, feature_name):
225
226
    if isinstance(data, DataFrame):
        if feature_name == 'auto' or feature_name is None:
wxchan's avatar
wxchan committed
227
228
229
230
            if all([isinstance(name, integer_types + (np.integer, )) for name in data.columns]):
                msg = """Using Pandas (default) integer column names, not column indexes. You can use indexes with DataFrame.values."""
                warnings.filterwarnings('once')
                warnings.warn(msg, stacklevel=5)
wxchan's avatar
wxchan committed
231
            data = data.rename(columns=str)
232
233
234
235
236
237
238
239
240
241
242
243
244
        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]

            msg = """DataFrame.dtypes for data must be int, float or bool. Did not expect the data types in fields """
            raise ValueError(msg + ', '.join(bad_fields))
        data = data.values.astype('float')
    else:
        if feature_name == 'auto':
            feature_name = None
Guolin Ke's avatar
Guolin Ke committed
245
    return data, feature_name
246
247
248
249
250
251
252
253
254
255
256
257
258


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')
        label = label.values.astype('float')
    return label


Guolin Ke's avatar
Guolin Ke committed
259
260
class _InnerPredictor(object):
    """
261
262
    A _InnerPredictor of LightGBM.
    Only used for prediction, usually used for continued-train
Guolin Ke's avatar
Guolin Ke committed
263
    Note: Can convert from Booster, but cannot convert to Booster
wxchan's avatar
wxchan committed
264
    """
Guolin Ke's avatar
Guolin Ke committed
265
266
    def __init__(self, model_file=None, booster_handle=None):
        """Initialize the _InnerPredictor. Not expose to user
wxchan's avatar
wxchan committed
267
268
269
270
271

        Parameters
        ----------
        model_file : string
            Path to the model file.
Guolin Ke's avatar
Guolin Ke committed
272
273
        booster_handle : Handle of Booster
            use handle to init
wxchan's avatar
wxchan committed
274
275
276
277
278
        """
        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
279
            out_num_iterations = ctypes.c_int(0)
wxchan's avatar
wxchan committed
280
281
282
283
            _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
284
            out_num_class = ctypes.c_int(0)
wxchan's avatar
wxchan committed
285
286
287
288
            _safe_call(_LIB.LGBM_BoosterGetNumClasses(
                self.handle,
                ctypes.byref(out_num_class)))
            self.num_class = out_num_class.value
289
            self.num_total_iteration = out_num_iterations.value
wxchan's avatar
wxchan committed
290
        elif booster_handle is not None:
Guolin Ke's avatar
Guolin Ke committed
291
            self.__is_manage_handle = False
wxchan's avatar
wxchan committed
292
            self.handle = booster_handle
Guolin Ke's avatar
Guolin Ke committed
293
            out_num_class = ctypes.c_int(0)
wxchan's avatar
wxchan committed
294
295
296
297
            _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
298
            out_num_iterations = ctypes.c_int(0)
wxchan's avatar
wxchan committed
299
300
301
            _safe_call(_LIB.LGBM_BoosterGetCurrentIteration(
                self.handle,
                ctypes.byref(out_num_iterations)))
302
            self.num_total_iteration = out_num_iterations.value
wxchan's avatar
wxchan committed
303
        else:
Guolin Ke's avatar
Guolin Ke committed
304
            raise TypeError('Need Model file or Booster handle to create a predictor')
wxchan's avatar
wxchan committed
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319

    def __del__(self):
        if self.__is_manage_handle:
            _safe_call(_LIB.LGBM_BoosterFree(self.handle))

    def predict(self, data, num_iteration=-1,
                raw_score=False, pred_leaf=False, data_has_header=False,
                is_reshape=True):
        """
        Predict logic

        Parameters
        ----------
        data : string/numpy array/scipy.sparse
            Data source for prediction
320
            When data type is string, it represents the path of txt file
wxchan's avatar
wxchan committed
321
        num_iteration : int
322
            Used iteration for prediction
wxchan's avatar
wxchan committed
323
324
325
326
327
        raw_score : bool
            True for predict raw score
        pred_leaf : bool
            True for predict leaf index
        data_has_header : bool
Guolin Ke's avatar
Guolin Ke committed
328
            Used for txt data, True if txt data has header
wxchan's avatar
wxchan committed
329
        is_reshape : bool
330
            Reshape to (nrow, ncol) if true
wxchan's avatar
wxchan committed
331
332
333
334
335

        Returns
        -------
        Prediction result
        """
wxchan's avatar
wxchan committed
336
        if isinstance(data, Dataset):
337
            raise TypeError("Cannot use Dataset instance for prediction, please use raw data instead")
Guolin Ke's avatar
Guolin Ke committed
338
        data = _data_from_pandas(data, None)[0]
wxchan's avatar
wxchan committed
339
340
341
342
343
344
        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
        int_data_has_header = 1 if data_has_header else 0
345
346
        if num_iteration > self.num_total_iteration:
            num_iteration = self.num_total_iteration
wxchan's avatar
wxchan committed
347
        if isinstance(data, string_type):
348
            with _temp_file() as f:
wxchan's avatar
wxchan committed
349
350
351
                _safe_call(_LIB.LGBM_BoosterPredictForFile(
                    self.handle,
                    c_str(data),
Guolin Ke's avatar
Guolin Ke committed
352
353
354
                    ctypes.c_int(int_data_has_header),
                    ctypes.c_int(predict_type),
                    ctypes.c_int(num_iteration),
wxchan's avatar
wxchan committed
355
356
                    c_str(f.name)))
                lines = f.readlines()
357
358
                nrow = len(lines)
                preds = [float(token) for line in lines for token in line.split('\t')]
Guolin Ke's avatar
Guolin Ke committed
359
                preds = np.array(preds, dtype=np.float64, copy=False)
wxchan's avatar
wxchan committed
360
361
362
        elif isinstance(data, scipy.sparse.csr_matrix):
            preds, nrow = self.__pred_for_csr(data, num_iteration,
                                              predict_type)
Guolin Ke's avatar
Guolin Ke committed
363
364
365
        elif isinstance(data, scipy.sparse.csc_matrix):
            preds, nrow = self.__pred_for_csc(data, num_iteration,
                                              predict_type)
wxchan's avatar
wxchan committed
366
367
368
        elif isinstance(data, np.ndarray):
            preds, nrow = self.__pred_for_np2d(data, num_iteration,
                                               predict_type)
369
        elif isinstance(data, DataFrame):
370
371
            preds, nrow = self.__pred_for_np2d(data.values, num_iteration,
                                               predict_type)
wxchan's avatar
wxchan committed
372
373
374
375
376
377
        else:
            try:
                csr = scipy.sparse.csr_matrix(data)
                preds, nrow = self.__pred_for_csr(csr, num_iteration,
                                                  predict_type)
            except:
378
                raise TypeError('Cannot predict data for type {}'.format(type(data).__name__))
wxchan's avatar
wxchan committed
379
380
        if pred_leaf:
            preds = preds.astype(np.int32)
381
        if is_reshape and preds.size != nrow:
wxchan's avatar
wxchan committed
382
            if preds.size % nrow == 0:
383
                preds = preds.reshape(nrow, -1)
wxchan's avatar
wxchan committed
384
            else:
385
                raise ValueError('Length of predict result (%d) cannot be divide nrow (%d)'
wxchan's avatar
wxchan committed
386
387
388
389
                                 % (preds.size, nrow))
        return preds

    def __get_num_preds(self, num_iteration, nrow, predict_type):
Guolin Ke's avatar
Guolin Ke committed
390
391
392
        """
        Get size of prediction result
        """
Guolin Ke's avatar
Guolin Ke committed
393
394
395
        n_preds = ctypes.c_int64(0)
        _safe_call(_LIB.LGBM_BoosterCalcNumPredict(
            self.handle,
Guolin Ke's avatar
Guolin Ke committed
396
397
398
            ctypes.c_int(nrow),
            ctypes.c_int(predict_type),
            ctypes.c_int(num_iteration),
Guolin Ke's avatar
Guolin Ke committed
399
400
            ctypes.byref(n_preds)))
        return n_preds.value
wxchan's avatar
wxchan committed
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416

    def __pred_for_np2d(self, mat, num_iteration, predict_type):
        """
        Predict for a 2-D numpy matrix.
        """
        if len(mat.shape) != 2:
            raise ValueError('Input numpy.ndarray must be 2 dimensional')

        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)
Guolin Ke's avatar
Guolin Ke committed
417
        preds = np.zeros(n_preds, dtype=np.float64)
wxchan's avatar
wxchan committed
418
419
420
421
        out_num_preds = ctypes.c_int64(0)
        _safe_call(_LIB.LGBM_BoosterPredictForMat(
            self.handle,
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
422
423
424
425
426
427
            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),
wxchan's avatar
wxchan committed
428
            ctypes.byref(out_num_preds),
wxchan's avatar
wxchan committed
429
            preds.ctypes.data_as(ctypes.POINTER(ctypes.c_double))))
wxchan's avatar
wxchan committed
430
        if n_preds != out_num_preds.value:
431
            raise ValueError("Wrong length for predict results")
wxchan's avatar
wxchan committed
432
433
434
435
436
437
438
439
        return preds, mat.shape[0]

    def __pred_for_csr(self, csr, num_iteration, predict_type):
        """
        Predict for a csr data
        """
        nrow = len(csr.indptr) - 1
        n_preds = self.__get_num_preds(num_iteration, nrow, predict_type)
Guolin Ke's avatar
Guolin Ke committed
440
        preds = np.zeros(n_preds, dtype=np.float64)
wxchan's avatar
wxchan committed
441
442
443
444
445
446
447
448
        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)

        _safe_call(_LIB.LGBM_BoosterPredictForCSR(
            self.handle,
            ptr_indptr,
Guolin Ke's avatar
Guolin Ke committed
449
            ctypes.c_int32(type_ptr_indptr),
wxchan's avatar
wxchan committed
450
451
            csr.indices.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)),
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
452
453
454
455
456
457
            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),
wxchan's avatar
wxchan committed
458
            ctypes.byref(out_num_preds),
wxchan's avatar
wxchan committed
459
            preds.ctypes.data_as(ctypes.POINTER(ctypes.c_double))))
Guolin Ke's avatar
Guolin Ke committed
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
        if n_preds != out_num_preds.value:
            raise ValueError("Wrong length for predict results")
        return preds, nrow

    def __pred_for_csc(self, csc, num_iteration, predict_type):
        """
        Predict for a csc data
        """
        nrow = csc.shape[0]
        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)

        ptr_indptr, type_ptr_indptr = c_int_array(csc.indptr)
        ptr_data, type_ptr_data = c_float_array(csc.data)

        _safe_call(_LIB.LGBM_BoosterPredictForCSC(
            self.handle,
            ptr_indptr,
Guolin Ke's avatar
Guolin Ke committed
479
            ctypes.c_int32(type_ptr_indptr),
Guolin Ke's avatar
Guolin Ke committed
480
481
            csc.indices.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)),
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
482
483
484
485
486
487
            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),
Guolin Ke's avatar
Guolin Ke committed
488
            ctypes.byref(out_num_preds),
wxchan's avatar
wxchan committed
489
            preds.ctypes.data_as(ctypes.POINTER(ctypes.c_double))))
wxchan's avatar
wxchan committed
490
        if n_preds != out_num_preds.value:
491
            raise ValueError("Wrong length for predict results")
wxchan's avatar
wxchan committed
492
493
        return preds, nrow

wxchan's avatar
wxchan committed
494

wxchan's avatar
wxchan committed
495
496
class Dataset(object):
    """Dataset in LightGBM."""
wxchan's avatar
wxchan committed
497
    def __init__(self, data, label=None, max_bin=255, reference=None,
wxchan's avatar
wxchan committed
498
                 weight=None, group=None, silent=False,
Guolin Ke's avatar
Guolin Ke committed
499
                 feature_name='auto', params=None,
wxchan's avatar
wxchan committed
500
                 free_raw_data=True):
wxchan's avatar
wxchan committed
501
502
503
504
        """
        Parameters
        ----------
        data : string/numpy array/scipy.sparse
wxchan's avatar
wxchan committed
505
            Data source of Dataset.
506
            When data type is string, it represents the path of txt file
wxchan's avatar
wxchan committed
507
508
509
        label : list or numpy 1-D array, optional
            Label of the data
        max_bin : int, required
510
            Max number of discrete bin for features
wxchan's avatar
wxchan committed
511
        reference : Other Dataset, optional
wxchan's avatar
wxchan committed
512
513
514
515
            If this dataset validation, need to use training data as reference
        weight : list or numpy 1-D array , optional
            Weight for each instance.
        group : list or numpy 1-D array , optional
516
            Group/query size for dataset
wxchan's avatar
wxchan committed
517
518
        silent : boolean, optional
            Whether print messages during construction
wxchan's avatar
wxchan committed
519
        feature_name : list of str, or 'auto'
520
            Feature names
wxchan's avatar
wxchan committed
521
            If 'auto' and data is pandas DataFrame, use data columns name
wxchan's avatar
wxchan committed
522
        params: dict, optional
523
            Other parameters
wxchan's avatar
wxchan committed
524
525
        free_raw_data: Bool
            True if need to free raw data after construct inner dataset
wxchan's avatar
wxchan committed
526
        """
wxchan's avatar
wxchan committed
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
        self.handle = None
        self.data = data
        self.label = label
        self.max_bin = max_bin
        self.reference = reference
        self.weight = weight
        self.group = group
        self.silent = silent
        self.feature_name = feature_name
        self.params = params
        self.free_raw_data = free_raw_data
        self.used_indices = None
        self._predictor = None

    def __del__(self):
542
543
544
        self._free_handle()

    def _free_handle(self):
545
        if self.handle is not None:
546
            _safe_call(_LIB.LGBM_DatasetFree(self.handle))
547
            self.handle = None
wxchan's avatar
wxchan committed
548
549
550

    def _lazy_init(self, data, label=None, max_bin=255, reference=None,
                   weight=None, group=None, predictor=None,
wxchan's avatar
wxchan committed
551
                   silent=False, feature_name='auto',
Guolin Ke's avatar
Guolin Ke committed
552
                   params=None):
wxchan's avatar
wxchan committed
553
554
555
        if data is None:
            self.handle = None
            return
Guolin Ke's avatar
Guolin Ke committed
556
        data, feature_name, = _data_from_pandas(data, feature_name)
wxchan's avatar
wxchan committed
557
558
559
560
561
562
563
564
565
566
567
568
569
570
        label = _label_from_pandas(label)
        self.data_has_header = False
        """process for args"""
        params = {} if params is None else params
        self.max_bin = max_bin
        self.predictor = predictor
        params["max_bin"] = max_bin
        if silent:
            params["verbose"] = 0
        elif "verbose" not in params:
            params["verbose"] = 1
        params_str = param_dict_to_str(params)
        """process for reference dataset"""
        ref_dataset = None
wxchan's avatar
wxchan committed
571
        if isinstance(reference, Dataset):
572
            ref_dataset = reference.construct().handle
wxchan's avatar
wxchan committed
573
574
575
        elif reference is not None:
            raise TypeError('Reference dataset should be None or dataset instance')
        """start construct data"""
wxchan's avatar
wxchan committed
576
        if isinstance(data, string_type):
wxchan's avatar
wxchan committed
577
            """check data has header or not"""
Guolin Ke's avatar
Guolin Ke committed
578
            if str(params.get("has_header", "")).lower() == "true" \
wxchan's avatar
wxchan committed
579
                    or str(params.get("header", "")).lower() == "true":
580
                self.data_has_header = True
wxchan's avatar
wxchan committed
581
582
583
584
585
586
587
588
            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
589
590
        elif isinstance(data, scipy.sparse.csc_matrix):
            self.__init_from_csc(data, params_str, ref_dataset)
wxchan's avatar
wxchan committed
591
592
593
594
595
596
597
        elif isinstance(data, np.ndarray):
            self.__init_from_np2d(data, params_str, ref_dataset)
        else:
            try:
                csr = scipy.sparse.csr_matrix(data)
                self.__init_from_csr(csr, params_str, ref_dataset)
            except:
wxchan's avatar
wxchan committed
598
                raise TypeError('Cannot initialize Dataset from {}'.format(type(data).__name__))
wxchan's avatar
wxchan committed
599
600
601
        if label is not None:
            self.set_label(label)
        if self.get_label() is None:
602
            raise ValueError("Label should not be None")
wxchan's avatar
wxchan committed
603
604
605
606
607
        if weight is not None:
            self.set_weight(weight)
        if group is not None:
            self.set_group(group)
        # load init score
Guolin Ke's avatar
Guolin Ke committed
608
        if isinstance(self.predictor, _InnerPredictor):
wxchan's avatar
wxchan committed
609
610
611
612
613
614
            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
615
                new_init_score = np.zeros(init_score.size, dtype=np.float32)
wxchan's avatar
wxchan committed
616
                num_data = self.num_data()
wxchan's avatar
wxchan committed
617
618
                for i in range_(num_data):
                    for j in range_(self.predictor.num_class):
wxchan's avatar
wxchan committed
619
620
621
                        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
622
623
        elif self.predictor is not None:
            raise TypeError('wrong predictor type {}'.format(type(self.predictor).__name__))
Guolin Ke's avatar
Guolin Ke committed
624
625
        # set feature names
        self.set_feature_name(feature_name)
wxchan's avatar
wxchan committed
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643

    def __init_from_np2d(self, mat, params_str, ref_dataset):
        """
        Initialize data from a 2-D numpy matrix.
        """
        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:
            """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)
        _safe_call(_LIB.LGBM_DatasetCreateFromMat(
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
644
645
646
647
            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
648
649
650
651
652
653
654
655
656
            c_str(params_str),
            ref_dataset,
            ctypes.byref(self.handle)))

    def __init_from_csr(self, csr, params_str, ref_dataset):
        """
        Initialize data from a CSR matrix.
        """
        if len(csr.indices) != len(csr.data):
657
            raise ValueError('Length mismatch: {} vs {}'.format(len(csr.indices), len(csr.data)))
wxchan's avatar
wxchan committed
658
659
660
661
662
663
664
        self.handle = ctypes.c_void_p()

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

        _safe_call(_LIB.LGBM_DatasetCreateFromCSR(
            ptr_indptr,
Guolin Ke's avatar
Guolin Ke committed
665
            ctypes.c_int(type_ptr_indptr),
wxchan's avatar
wxchan committed
666
667
            csr.indices.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)),
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
668
669
670
671
            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
672
673
674
675
            c_str(params_str),
            ref_dataset,
            ctypes.byref(self.handle)))

Guolin Ke's avatar
Guolin Ke committed
676
677
678
679
680
681
682
683
684
685
686
687
688
    def __init_from_csc(self, csc, params_str, ref_dataset):
        """
        Initialize data from a csc matrix.
        """
        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()

        ptr_indptr, type_ptr_indptr = c_int_array(csc.indptr)
        ptr_data, type_ptr_data = c_float_array(csc.data)

        _safe_call(_LIB.LGBM_DatasetCreateFromCSC(
            ptr_indptr,
Guolin Ke's avatar
Guolin Ke committed
689
            ctypes.c_int(type_ptr_indptr),
Guolin Ke's avatar
Guolin Ke committed
690
691
            csc.indices.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)),
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
692
693
694
695
            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
696
697
698
699
            c_str(params_str),
            ref_dataset,
            ctypes.byref(self.handle)))

wxchan's avatar
wxchan committed
700
701
    def construct(self):
        """Lazy init"""
702
        if self.handle is None:
wxchan's avatar
wxchan committed
703
704
705
706
707
708
709
710
711
            if self.reference is not None:
                if self.used_indices is None:
                    """create valid"""
                    self._lazy_init(self.data, label=self.label, max_bin=self.max_bin, reference=self.reference,
                                    weight=self.weight, group=self.group, predictor=self._predictor,
                                    silent=self.silent, params=self.params)
                else:
                    """construct subset"""
                    used_indices = list_to_1d_numpy(self.used_indices, np.int32, name='used_indices')
712
                    self.handle = ctypes.c_void_p()
wxchan's avatar
wxchan committed
713
714
                    params_str = param_dict_to_str(self.params)
                    _safe_call(_LIB.LGBM_DatasetGetSubset(
715
                        self.reference.construct().handle,
wxchan's avatar
wxchan committed
716
                        used_indices.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)),
Guolin Ke's avatar
Guolin Ke committed
717
                        ctypes.c_int(used_indices.shape[0]),
wxchan's avatar
wxchan committed
718
719
720
721
722
723
724
725
726
                        c_str(params_str),
                        ctypes.byref(self.handle)))
                    if self.get_label() is None:
                        raise ValueError("Label should not be None.")
            else:
                """create train"""
                self._lazy_init(self.data, label=self.label, max_bin=self.max_bin,
                                weight=self.weight, group=self.group, predictor=self._predictor,
                                silent=self.silent, feature_name=self.feature_name,
Guolin Ke's avatar
Guolin Ke committed
727
                                params=self.params)
wxchan's avatar
wxchan committed
728
729
730
            if self.free_raw_data:
                self.data = None
        return self
wxchan's avatar
wxchan committed
731

wxchan's avatar
wxchan committed
732
733
734
735
    def create_valid(self, data, label=None, weight=None, group=None,
                     silent=False, params=None):
        """
        Create validation data align with current dataset
wxchan's avatar
wxchan committed
736
737
738

        Parameters
        ----------
wxchan's avatar
wxchan committed
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
        data : string/numpy array/scipy.sparse
            Data source of Dataset.
            When data type is string, it represents the path of txt file
        label : list or numpy 1-D array, optional
            Label of the training data.
        weight : list or numpy 1-D array , optional
            Weight for each instance.
        group : list or numpy 1-D array , optional
            Group/query size for dataset
        silent : boolean, optional
            Whether print messages during construction
        params: dict, optional
            Other parameters
        """
        ret = Dataset(data, label=label, max_bin=self.max_bin, reference=self,
                      weight=weight, group=group, silent=silent, params=params,
                      free_raw_data=self.free_raw_data)
wxchan's avatar
wxchan committed
756
        ret._predictor = self._predictor
wxchan's avatar
wxchan committed
757
        return ret
wxchan's avatar
wxchan committed
758

wxchan's avatar
wxchan committed
759
    def subset(self, used_indices, params=None):
wxchan's avatar
wxchan committed
760
        """
wxchan's avatar
wxchan committed
761
762
763
764
765
766
767
768
769
770
        Get subset of current dataset

        Parameters
        ----------
        used_indices : list of int
            Used indices of this subset
        params : dict
            Other parameters
        """
        ret = Dataset(None, reference=self, feature_name=self.feature_name,
Guolin Ke's avatar
Guolin Ke committed
771
                      params=params)
wxchan's avatar
wxchan committed
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
        ret._predictor = self._predictor
        ret.used_indices = used_indices
        return ret

    def save_binary(self, filename):
        """
        Save Dataset to binary file

        Parameters
        ----------
        filename : string
            Name of the output file.
        """
        _safe_call(_LIB.LGBM_DatasetSaveBinary(
            self.construct().handle,
            c_str(filename)))

    def _update_params(self, params):
        if not self.params:
            self.params = params
wxchan's avatar
wxchan committed
792
        else:
wxchan's avatar
wxchan committed
793
            self.params.update(params)
wxchan's avatar
wxchan committed
794
795

    def set_field(self, field_name, data):
wxchan's avatar
wxchan committed
796
        """Set property into the Dataset.
wxchan's avatar
wxchan committed
797
798
799
800
801
802
803
804
805

        Parameters
        ----------
        field_name: str
            The field name of the information

        data: numpy array or list or None
            The array ofdata to be set
        """
806
807
        if self.handle is None:
            raise Exception("Cannot set %s before construct dataset" % field_name)
wxchan's avatar
wxchan committed
808
809
810
811
812
813
        if data is None:
            """set to None"""
            _safe_call(_LIB.LGBM_DatasetSetField(
                self.handle,
                c_str(field_name),
                None,
Guolin Ke's avatar
Guolin Ke committed
814
815
                ctypes.c_int(0),
                ctypes.c_int(FIELD_TYPE_MAPPER[field_name])))
wxchan's avatar
wxchan committed
816
            return
Guolin Ke's avatar
Guolin Ke committed
817
818
819
820
821
        dtype = np.float32
        if field_name == 'group':
            dtype = np.int32
        elif field_name == 'init_score':
            dtype = np.float64
822
        data = list_to_1d_numpy(data, dtype, name=field_name)
wxchan's avatar
wxchan committed
823
824
825
        if data.dtype == np.float32:
            ptr_data = data.ctypes.data_as(ctypes.POINTER(ctypes.c_float))
            type_data = C_API_DTYPE_FLOAT32
Guolin Ke's avatar
Guolin Ke committed
826
827
828
        elif data.dtype == np.float64:
            ptr_data = data.ctypes.data_as(ctypes.POINTER(ctypes.c_double))
            type_data = C_API_DTYPE_FLOAT64
wxchan's avatar
wxchan committed
829
830
831
832
        elif data.dtype == np.int32:
            ptr_data = data.ctypes.data_as(ctypes.POINTER(ctypes.c_int32))
            type_data = C_API_DTYPE_INT32
        else:
Guolin Ke's avatar
Guolin Ke committed
833
            raise TypeError("Excepted np.float32/64 or np.int32, meet type({})".format(data.dtype))
wxchan's avatar
wxchan committed
834
        if type_data != FIELD_TYPE_MAPPER[field_name]:
835
            raise TypeError("Input type error for set_field")
wxchan's avatar
wxchan committed
836
837
838
839
        _safe_call(_LIB.LGBM_DatasetSetField(
            self.handle,
            c_str(field_name),
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
840
841
            ctypes.c_int(len(data)),
            ctypes.c_int(type_data)))
wxchan's avatar
wxchan committed
842

wxchan's avatar
wxchan committed
843
844
    def get_field(self, field_name):
        """Get property from the Dataset.
wxchan's avatar
wxchan committed
845
846
847

        Parameters
        ----------
wxchan's avatar
wxchan committed
848
849
        field_name: str
            The field name of the information
wxchan's avatar
wxchan committed
850
851
852

        Returns
        -------
wxchan's avatar
wxchan committed
853
854
        info : array
            A numpy array of information of the data
Guolin Ke's avatar
Guolin Ke committed
855
        """
856
857
        if self.handle is None:
            raise Exception("Cannot get %s before construct dataset" % field_name)
Guolin Ke's avatar
Guolin Ke committed
858
859
        tmp_out_len = ctypes.c_int()
        out_type = ctypes.c_int()
wxchan's avatar
wxchan committed
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
        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
875
876
        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)
877
        else:
wxchan's avatar
wxchan committed
878
            raise TypeError("Unknown type")
Guolin Ke's avatar
Guolin Ke committed
879
880
881
882
883
884
885
886
887
888

    def _set_predictor(self, predictor):
        """
        Set predictor for continued training, not recommand for user to call this function.
        Please set init_model in engine.train or engine.cv
        """
        if predictor is self._predictor:
            return
        if self.data is not None:
            self._predictor = predictor
889
            self._free_handle()
Guolin Ke's avatar
Guolin Ke committed
890
        else:
891
            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
892
893
894
895
896
897
898
899

    def set_reference(self, reference):
        """
        Set reference dataset

        Parameters
        ----------
        reference : Dataset
900
            Will use reference as template to consturct current dataset
Guolin Ke's avatar
Guolin Ke committed
901
902
903
904
905
906
907
        """
        self.set_feature_name(reference.feature_name)
        self._set_predictor(reference._predictor)
        if self.reference is reference:
            return
        if self.data is not None:
            self.reference = reference
908
            self._free_handle()
Guolin Ke's avatar
Guolin Ke committed
909
        else:
910
            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
911
912
913
914
915
916
917
918

    def set_feature_name(self, feature_name):
        """
        Set feature name

        Parameters
        ----------
        feature_name : list of str
919
            Feature names
Guolin Ke's avatar
Guolin Ke committed
920
921
        """
        self.feature_name = feature_name
922
        if self.handle is not None and feature_name is not None and feature_name != 'auto':
wxchan's avatar
wxchan committed
923
924
            if len(feature_name) != self.num_feature():
                raise ValueError("Length of feature_name({}) and num_feature({}) don't match".format(len(feature_name), self.num_feature()))
925
            c_feature_name = [c_str(name) for name in feature_name]
wxchan's avatar
wxchan committed
926
927
928
            _safe_call(_LIB.LGBM_DatasetSetFeatureNames(
                self.handle,
                c_array(ctypes.c_char_p, c_feature_name),
Guolin Ke's avatar
Guolin Ke committed
929
                ctypes.c_int(len(feature_name))))
Guolin Ke's avatar
Guolin Ke committed
930
931

    def set_label(self, label):
wxchan's avatar
wxchan committed
932
933
        """
        Set label of Dataset
Guolin Ke's avatar
Guolin Ke committed
934
935
936
937
938
939
940

        Parameters
        ----------
        label: numpy array or list or None
            The label information to be set into Dataset
        """
        self.label = label
941
        if self.handle is not None:
wxchan's avatar
wxchan committed
942
943
            label = list_to_1d_numpy(label, name='label')
            self.set_field('label', label)
Guolin Ke's avatar
Guolin Ke committed
944
945

    def set_weight(self, weight):
wxchan's avatar
wxchan committed
946
947
        """
        Set weight of each instance.
Guolin Ke's avatar
Guolin Ke committed
948
949
950
951
952
953
954

        Parameters
        ----------
        weight : numpy array or list or None
            Weight for each data point
        """
        self.weight = weight
955
        if self.handle is not None and weight is not None:
wxchan's avatar
wxchan committed
956
957
            weight = list_to_1d_numpy(weight, name='weight')
            self.set_field('weight', weight)
Guolin Ke's avatar
Guolin Ke committed
958
959

    def set_init_score(self, init_score):
wxchan's avatar
wxchan committed
960
961
        """
        Set init score of booster to start from.
Guolin Ke's avatar
Guolin Ke committed
962
963
964
965
966
967
968

        Parameters
        ----------
        init_score: numpy array or list or None
            Init score for booster
        """
        self.init_score = init_score
969
        if self.handle is not None and init_score is not None:
Guolin Ke's avatar
Guolin Ke committed
970
            init_score = list_to_1d_numpy(init_score, np.float64, name='init_score')
wxchan's avatar
wxchan committed
971
            self.set_field('init_score', init_score)
Guolin Ke's avatar
Guolin Ke committed
972
973

    def set_group(self, group):
wxchan's avatar
wxchan committed
974
975
        """
        Set group size of Dataset (used for ranking).
Guolin Ke's avatar
Guolin Ke committed
976
977
978
979
980
981
982

        Parameters
        ----------
        group : numpy array or list or None
            Group size of each group
        """
        self.group = group
983
        if self.handle is not None and group is not None:
wxchan's avatar
wxchan committed
984
985
            group = list_to_1d_numpy(group, np.int32, name='group')
            self.set_field('group', group)
Guolin Ke's avatar
Guolin Ke committed
986
987

    def get_label(self):
wxchan's avatar
wxchan committed
988
989
        """
        Get the label of the Dataset.
Guolin Ke's avatar
Guolin Ke committed
990
991
992
993
994

        Returns
        -------
        label : array
        """
995
        if self.label is None and self.handle is not None:
wxchan's avatar
wxchan committed
996
            self.label = self.get_field('label')
Guolin Ke's avatar
Guolin Ke committed
997
998
999
        return self.label

    def get_weight(self):
wxchan's avatar
wxchan committed
1000
1001
        """
        Get the weight of the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1002
1003
1004
1005
1006

        Returns
        -------
        weight : array
        """
1007
        if self.weight is None and self.handle is not None:
wxchan's avatar
wxchan committed
1008
            self.weight = self.get_field('weight')
Guolin Ke's avatar
Guolin Ke committed
1009
1010
1011
        return self.weight

    def get_init_score(self):
wxchan's avatar
wxchan committed
1012
1013
        """
        Get the initial score of the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1014
1015
1016
1017
1018

        Returns
        -------
        init_score : array
        """
1019
        if self.init_score is None and self.handle is not None:
wxchan's avatar
wxchan committed
1020
            self.init_score = self.get_field('init_score')
Guolin Ke's avatar
Guolin Ke committed
1021
1022
1023
        return self.init_score

    def get_group(self):
wxchan's avatar
wxchan committed
1024
1025
        """
        Get the initial score of the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1026
1027
1028
1029
1030

        Returns
        -------
        init_score : array
        """
1031
        if self.group is None and self.handle is not None:
wxchan's avatar
wxchan committed
1032
            self.group = self.get_field('group')
Guolin Ke's avatar
Guolin Ke committed
1033
1034
1035
            if self.group is not None:
                # group data from LightGBM is boundaries data, need to convert to group size
                new_group = []
wxchan's avatar
wxchan committed
1036
                for i in range_(len(self.group) - 1):
Guolin Ke's avatar
Guolin Ke committed
1037
1038
                    new_group.append(self.group[i + 1] - self.group[i])
                self.group = new_group
Guolin Ke's avatar
Guolin Ke committed
1039
1040
1041
        return self.group

    def num_data(self):
wxchan's avatar
wxchan committed
1042
1043
        """
        Get the number of rows in the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1044
1045
1046
1047
1048

        Returns
        -------
        number of rows : int
        """
1049
        if self.handle is not None:
Guolin Ke's avatar
Guolin Ke committed
1050
            ret = ctypes.c_int()
wxchan's avatar
wxchan committed
1051
1052
1053
            _safe_call(_LIB.LGBM_DatasetGetNumData(self.handle,
                                                   ctypes.byref(ret)))
            return ret.value
Guolin Ke's avatar
Guolin Ke committed
1054
        else:
1055
            raise LightGBMError("Cannot get num_data before construct dataset")
Guolin Ke's avatar
Guolin Ke committed
1056
1057

    def num_feature(self):
wxchan's avatar
wxchan committed
1058
1059
        """
        Get the number of columns (features) in the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1060
1061
1062
1063
1064

        Returns
        -------
        number of columns : int
        """
1065
        if self.handle is not None:
Guolin Ke's avatar
Guolin Ke committed
1066
            ret = ctypes.c_int()
wxchan's avatar
wxchan committed
1067
1068
1069
            _safe_call(_LIB.LGBM_DatasetGetNumFeature(self.handle,
                                                      ctypes.byref(ret)))
            return ret.value
Guolin Ke's avatar
Guolin Ke committed
1070
        else:
1071
            raise LightGBMError("Cannot get num_feature before construct dataset")
Guolin Ke's avatar
Guolin Ke committed
1072

wxchan's avatar
wxchan committed
1073

wxchan's avatar
wxchan committed
1074
class Booster(object):
wxchan's avatar
wxchan committed
1075
    """"Booster in LightGBM."""
wxchan's avatar
wxchan committed
1076
    def __init__(self, params=None, train_set=None, model_file=None, silent=False):
wxchan's avatar
wxchan committed
1077
1078
        """
        Initialize the Booster.
wxchan's avatar
wxchan committed
1079
1080
1081
1082
1083
1084

        Parameters
        ----------
        params : dict
            Parameters for boosters.
        train_set : Dataset
1085
            Training dataset
wxchan's avatar
wxchan committed
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
        model_file : string
            Path to the model file.
        silent : boolean, optional
            Whether print messages during construction
        """
        self.handle = ctypes.c_void_p()
        self.__need_reload_eval_info = True
        self.__train_data_name = "training"
        self.__attr = {}
        self.best_iteration = -1
        params = {} if params is None else params
        if silent:
            params["verbose"] = 0
        elif "verbose" not in params:
            params["verbose"] = 1
        if train_set is not None:
            """Training task"""
            if not isinstance(train_set, Dataset):
1104
                raise TypeError('Training data should be Dataset instance, met {}'.format(type(train_set).__name__))
wxchan's avatar
wxchan committed
1105
1106
1107
            params_str = param_dict_to_str(params)
            """construct booster object"""
            _safe_call(_LIB.LGBM_BoosterCreate(
wxchan's avatar
wxchan committed
1108
                train_set.construct().handle,
wxchan's avatar
wxchan committed
1109
1110
1111
1112
1113
1114
1115
                c_str(params_str),
                ctypes.byref(self.handle)))
            """save reference to data"""
            self.train_set = train_set
            self.valid_sets = []
            self.name_valid_sets = []
            self.__num_dataset = 1
Guolin Ke's avatar
Guolin Ke committed
1116
1117
            self.__init_predictor = train_set._predictor
            if self.__init_predictor is not None:
wxchan's avatar
wxchan committed
1118
1119
                _safe_call(_LIB.LGBM_BoosterMerge(
                    self.handle,
Guolin Ke's avatar
Guolin Ke committed
1120
                    self.__init_predictor.handle))
Guolin Ke's avatar
Guolin Ke committed
1121
            out_num_class = ctypes.c_int(0)
wxchan's avatar
wxchan committed
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
            _safe_call(_LIB.LGBM_BoosterGetNumClasses(
                self.handle,
                ctypes.byref(out_num_class)))
            self.__num_class = out_num_class.value
            """buffer for inner predict"""
            self.__inner_predict_buffer = [None]
            self.__is_predicted_cur_iter = [False]
            self.__get_eval_info()
        elif model_file is not None:
            """Prediction task"""
Guolin Ke's avatar
Guolin Ke committed
1132
            out_num_iterations = ctypes.c_int(0)
wxchan's avatar
wxchan committed
1133
1134
1135
1136
            _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
1137
            out_num_class = ctypes.c_int(0)
wxchan's avatar
wxchan committed
1138
1139
1140
1141
            _safe_call(_LIB.LGBM_BoosterGetNumClasses(
                self.handle,
                ctypes.byref(out_num_class)))
            self.__num_class = out_num_class.value
1142
1143
        elif 'model_str' in params:
            self.__load_model_from_string(params['model_str'])
wxchan's avatar
wxchan committed
1144
        else:
1145
            raise TypeError('Need at least one training dataset or model file to create booster instance')
wxchan's avatar
wxchan committed
1146
1147

    def __del__(self):
Guolin Ke's avatar
Guolin Ke committed
1148
        if self.handle is not None:
wxchan's avatar
wxchan committed
1149
1150
            _safe_call(_LIB.LGBM_BoosterFree(self.handle))

wxchan's avatar
wxchan committed
1151
1152
1153
1154
    def __copy__(self):
        return self.__deepcopy__(None)

    def __deepcopy__(self, _):
1155
1156
1157
        model_str = self.__save_model_to_string()
        booster = Booster({'model_str': model_str})
        return booster
wxchan's avatar
wxchan committed
1158
1159
1160
1161
1162
1163
1164

    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:
1165
            this["handle"] = self.__save_model_to_string()
wxchan's avatar
wxchan committed
1166
1167
1168
        return this

    def __setstate__(self, state):
1169
1170
        model_str = state.get('handle', None)
        if model_str is not None:
wxchan's avatar
wxchan committed
1171
            handle = ctypes.c_void_p()
Guolin Ke's avatar
Guolin Ke committed
1172
            out_num_iterations = ctypes.c_int(0)
1173
1174
1175
1176
            _safe_call(_LIB.LGBM_BoosterLoadModelFromString(
                c_str(model_str),
                ctypes.byref(out_num_iterations),
                ctypes.byref(handle)))
wxchan's avatar
wxchan committed
1177
1178
1179
            state['handle'] = handle
        self.__dict__.update(state)

wxchan's avatar
wxchan committed
1180
1181
1182
1183
    def set_train_data_name(self, name):
        self.__train_data_name = name

    def add_valid(self, data, name):
wxchan's avatar
wxchan committed
1184
1185
        """
        Add an validation data
wxchan's avatar
wxchan committed
1186
1187
1188
1189

        Parameters
        ----------
        data : Dataset
1190
            Validation data
wxchan's avatar
wxchan committed
1191
        name : String
1192
            Name of validation data
wxchan's avatar
wxchan committed
1193
        """
Guolin Ke's avatar
Guolin Ke committed
1194
        if not isinstance(data, Dataset):
wxchan's avatar
wxchan committed
1195
            raise TypeError('valid data should be Dataset instance, met {}'.format(type(data).__name__))
Guolin Ke's avatar
Guolin Ke committed
1196
1197
        if data._predictor is not self.__init_predictor:
            raise LightGBMError("Add validation data failed, you should use same predictor for these data")
wxchan's avatar
wxchan committed
1198
1199
        _safe_call(_LIB.LGBM_BoosterAddValidData(
            self.handle,
wxchan's avatar
wxchan committed
1200
            data.construct().handle))
wxchan's avatar
wxchan committed
1201
1202
1203
1204
1205
1206
1207
        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)

    def reset_parameter(self, params):
wxchan's avatar
wxchan committed
1208
1209
        """
        Reset parameters for booster
wxchan's avatar
wxchan committed
1210
1211
1212
1213

        Parameters
        ----------
        params : dict
1214
            New parameters for boosters
wxchan's avatar
wxchan committed
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
        silent : boolean, optional
            Whether print messages during construction
        """
        if 'metric' in params:
            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)))

    def update(self, train_set=None, fobj=None):
        """
        Update for one iteration
        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
1232

wxchan's avatar
wxchan committed
1233
1234
        Parameters
        ----------
1235
1236
        train_set :
            Training data, None means use last training data
wxchan's avatar
wxchan committed
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
        fobj : function
            Customized objective function.

        Returns
        -------
        is_finished, bool
        """

        """need reset training data"""
        if train_set is not None and train_set is not self.train_set:
Guolin Ke's avatar
Guolin Ke committed
1247
1248
            if not isinstance(train_set, Dataset):
                raise TypeError('Training data should be Dataset instance, met {}'.format(type(train_set).__name__))
Guolin Ke's avatar
Guolin Ke committed
1249
1250
            if train_set._predictor is not self.__init_predictor:
                raise LightGBMError("Replace training data failed, you should use same predictor for these data")
wxchan's avatar
wxchan committed
1251
1252
1253
            self.train_set = train_set
            _safe_call(_LIB.LGBM_BoosterResetTrainingData(
                self.handle,
wxchan's avatar
wxchan committed
1254
                self.train_set.construct().handle))
wxchan's avatar
wxchan committed
1255
1256
1257
1258
1259
1260
            self.__inner_predict_buffer[0] = None
        is_finished = ctypes.c_int(0)
        if fobj is None:
            _safe_call(_LIB.LGBM_BoosterUpdateOneIter(
                self.handle,
                ctypes.byref(is_finished)))
wxchan's avatar
wxchan committed
1261
            self.__is_predicted_cur_iter = [False for _ in range_(self.__num_dataset)]
wxchan's avatar
wxchan committed
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
            return is_finished.value == 1
        else:
            grad, hess = fobj(self.__inner_predict(0), self.train_set)
            return self.__boost(grad, hess)

    def __boost(self, grad, hess):
        """
        Boost the booster for one iteration, with customized gradient statistics.
        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
1273

wxchan's avatar
wxchan committed
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
        Parameters
        ----------
        grad : 1d numpy or 1d list
            The first order of gradient.
        hess : 1d numpy or 1d list
            The second order of gradient.

        Returns
        -------
        is_finished, bool
        """
1285
1286
        grad = list_to_1d_numpy(grad, name='gradient')
        hess = list_to_1d_numpy(hess, name='hessian')
wxchan's avatar
wxchan committed
1287
        if len(grad) != len(hess):
1288
            raise ValueError("Lengths of gradient({}) and hessian({}) don't match".format(len(grad), len(hess)))
wxchan's avatar
wxchan committed
1289
1290
1291
1292
1293
1294
        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
1295
        self.__is_predicted_cur_iter = [False for _ in range_(self.__num_dataset)]
wxchan's avatar
wxchan committed
1296
1297
1298
1299
1300
1301
1302
1303
        return is_finished.value == 1

    def rollback_one_iter(self):
        """
        Rollback one iteration
        """
        _safe_call(_LIB.LGBM_BoosterRollbackOneIter(
            self.handle))
wxchan's avatar
wxchan committed
1304
        self.__is_predicted_cur_iter = [False for _ in range_(self.__num_dataset)]
wxchan's avatar
wxchan committed
1305
1306

    def current_iteration(self):
Guolin Ke's avatar
Guolin Ke committed
1307
        out_cur_iter = ctypes.c_int(0)
wxchan's avatar
wxchan committed
1308
1309
1310
1311
1312
1313
        _safe_call(_LIB.LGBM_BoosterGetCurrentIteration(
            self.handle,
            ctypes.byref(out_cur_iter)))
        return out_cur_iter.value

    def eval(self, data, name, feval=None):
wxchan's avatar
wxchan committed
1314
1315
        """
        Evaluate for data
wxchan's avatar
wxchan committed
1316
1317
1318

        Parameters
        ----------
Guolin Ke's avatar
Guolin Ke committed
1319
        data : Dataset object
1320
1321
        name :
            Name of data
wxchan's avatar
wxchan committed
1322
1323
1324
1325
1326
1327
1328
        feval : function
            Custom evaluation function.
        Returns
        -------
        result: list
            Evaluation result list.
        """
Guolin Ke's avatar
Guolin Ke committed
1329
1330
        if not isinstance(data, Dataset):
            raise TypeError("Can only eval for Dataset instance")
wxchan's avatar
wxchan committed
1331
1332
1333
1334
        data_idx = -1
        if data is self.train_set:
            data_idx = 0
        else:
wxchan's avatar
wxchan committed
1335
            for i in range_(len(self.valid_sets)):
wxchan's avatar
wxchan committed
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
                if data is self.valid_sets[i]:
                    data_idx = i + 1
                    break
        """need to push new valid data"""
        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):
wxchan's avatar
wxchan committed
1347
1348
        """
        Evaluate for training data
wxchan's avatar
wxchan committed
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362

        Parameters
        ----------
        feval : function
            Custom evaluation function.

        Returns
        -------
        result: str
            Evaluation result list.
        """
        return self.__inner_eval(self.__train_data_name, 0, feval)

    def eval_valid(self, feval=None):
wxchan's avatar
wxchan committed
1363
1364
        """
        Evaluate for validation data
wxchan's avatar
wxchan committed
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375

        Parameters
        ----------
        feval : function
            Custom evaluation function.

        Returns
        -------
        result: str
            Evaluation result list.
        """
wxchan's avatar
wxchan committed
1376
        return [item for i in range_(1, self.__num_dataset)
wxchan's avatar
wxchan committed
1377
                for item in self.__inner_eval(self.name_valid_sets[i - 1], i, feval)]
wxchan's avatar
wxchan committed
1378
1379

    def save_model(self, filename, num_iteration=-1):
wxchan's avatar
wxchan committed
1380
1381
        """
        Save model of booster to file
wxchan's avatar
wxchan committed
1382
1383
1384
1385

        Parameters
        ----------
        filename : str
1386
            Filename to save
wxchan's avatar
wxchan committed
1387
        num_iteration: int
1388
            Number of iteration that want to save. < 0 means save the best iteration(if have)
wxchan's avatar
wxchan committed
1389
        """
1390
1391
        if num_iteration <= 0:
            num_iteration = self.best_iteration
wxchan's avatar
wxchan committed
1392
1393
        _safe_call(_LIB.LGBM_BoosterSaveModel(
            self.handle,
Guolin Ke's avatar
Guolin Ke committed
1394
            ctypes.c_int(num_iteration),
wxchan's avatar
wxchan committed
1395
1396
            c_str(filename)))

1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
    def __load_model_from_string(self, model_str):
        """[Private] Load model from string"""
        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)))
        self.__num_class = out_num_class.value

    def __save_model_to_string(self, num_iteration=-1):
        """[Private] Save model to string"""
        if num_iteration <= 0:
            num_iteration = self.best_iteration
        buffer_len = 1 << 20
        tmp_out_len = ctypes.c_int(0)
        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,
            ctypes.c_int(num_iteration),
            ctypes.c_int(buffer_len),
            ctypes.byref(tmp_out_len),
            ptr_string_buffer))
        actual_len = tmp_out_len.value
        '''if buffer length is not long enough, re-allocate a buffer'''
        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,
                ctypes.c_int(num_iteration),
                ctypes.c_int(actual_len),
                ctypes.byref(tmp_out_len),
                ptr_string_buffer))
        return string_buffer.value.decode()

1437
    def dump_model(self, num_iteration=-1):
wxchan's avatar
wxchan committed
1438
1439
        """
        Dump model to json format
wxchan's avatar
wxchan committed
1440

1441
1442
1443
1444
1445
        Parameters
        ----------
        num_iteration: int
            Number of iteration that want to dump. < 0 means dump to best iteration(if have)

wxchan's avatar
wxchan committed
1446
1447
1448
1449
        Returns
        -------
        Json format of model
        """
1450
1451
        if num_iteration <= 0:
            num_iteration = self.best_iteration
wxchan's avatar
wxchan committed
1452
        buffer_len = 1 << 20
Guolin Ke's avatar
Guolin Ke committed
1453
        tmp_out_len = ctypes.c_int(0)
wxchan's avatar
wxchan committed
1454
1455
1456
1457
        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,
Guolin Ke's avatar
Guolin Ke committed
1458
1459
            ctypes.c_int(num_iteration),
            ctypes.c_int(buffer_len),
wxchan's avatar
wxchan committed
1460
            ctypes.byref(tmp_out_len),
Guolin Ke's avatar
Guolin Ke committed
1461
            ptr_string_buffer))
wxchan's avatar
wxchan committed
1462
        actual_len = tmp_out_len.value
1463
        '''if buffer length is not long enough, reallocate a buffer'''
wxchan's avatar
wxchan committed
1464
1465
1466
1467
1468
        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,
Guolin Ke's avatar
Guolin Ke committed
1469
1470
                ctypes.c_int(num_iteration),
                ctypes.c_int(actual_len),
wxchan's avatar
wxchan committed
1471
                ctypes.byref(tmp_out_len),
Guolin Ke's avatar
Guolin Ke committed
1472
                ptr_string_buffer))
wxchan's avatar
wxchan committed
1473
1474
1475
        return json.loads(string_buffer.value.decode())

    def predict(self, data, num_iteration=-1, raw_score=False, pred_leaf=False, data_has_header=False, is_reshape=True):
wxchan's avatar
wxchan committed
1476
1477
        """
        Predict logic
wxchan's avatar
wxchan committed
1478
1479
1480
1481
1482

        Parameters
        ----------
        data : string/numpy array/scipy.sparse
            Data source for prediction
1483
            When data type is string, it represents the path of txt file
wxchan's avatar
wxchan committed
1484
        num_iteration : int
1485
            Used iteration for prediction, < 0 means predict for best iteration(if have)
wxchan's avatar
wxchan committed
1486
1487
1488
1489
1490
1491
1492
        raw_score : bool
            True for predict raw score
        pred_leaf : bool
            True for predict leaf index
        data_has_header : bool
            Used for txt data
        is_reshape : bool
1493
            Reshape to (nrow, ncol) if true
wxchan's avatar
wxchan committed
1494
1495
1496
1497
1498

        Returns
        -------
        Prediction result
        """
1499
        predictor = self._to_predictor()
1500
1501
        if num_iteration <= 0:
            num_iteration = self.best_iteration
wxchan's avatar
wxchan committed
1502
1503
        return predictor.predict(data, num_iteration, raw_score, pred_leaf, data_has_header, is_reshape)

Guolin Ke's avatar
Guolin Ke committed
1504
    def _to_predictor(self):
wxchan's avatar
wxchan committed
1505
        """Convert to predictor"""
Guolin Ke's avatar
Guolin Ke committed
1506
        predictor = _InnerPredictor(booster_handle=self.handle)
wxchan's avatar
wxchan committed
1507
1508
        return predictor

wxchan's avatar
wxchan committed
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
    def feature_name(self):
        """
        Get feature names.

        Returns
        -------
        result : array
            Array of feature names.
        """
        out_num_feature = ctypes.c_int(0)
        """Get num of features"""
        _safe_call(_LIB.LGBM_BoosterGetNumFeature(
            self.handle,
            ctypes.byref(out_num_feature)))
        num_feature = out_num_feature.value
        """Get name of features"""
        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)]

1536
    def feature_importance(self, importance_type='split'):
wxchan's avatar
wxchan committed
1537
        """
wxchan's avatar
wxchan committed
1538
        Get feature importances
1539

1540
1541
1542
1543
1544
1545
1546
        Parameters
        ----------
        importance_type : str, default "split"
        How the importance is calculated: "split" or "gain"
        "split" is the number of times a feature is used in a model
        "gain" is the total gain of splits which use the feature

1547
1548
        Returns
        -------
wxchan's avatar
wxchan committed
1549
1550
        result : array
            Array of feature importances.
1551
1552
1553
1554
1555
        """
        if importance_type not in ["split", "gain"]:
            raise KeyError("importance_type must be split or gain")
        dump_model = self.dump_model()
        ret = [0] * (dump_model["max_feature_idx"] + 1)
wxchan's avatar
wxchan committed
1556

1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
        def dfs(root):
            if "split_feature" in root:
                if importance_type == 'split':
                    ret[root["split_feature"]] += 1
                elif importance_type == 'gain':
                    ret[root["split_feature"]] += root["split_gain"]
                dfs(root["left_child"])
                dfs(root["right_child"])
        for tree in dump_model["tree_info"]:
            dfs(tree["tree_structure"])
        return np.array(ret)

wxchan's avatar
wxchan committed
1569
1570
    def __inner_eval(self, data_name, data_idx, feval=None):
        """
1571
        Evaulate training or validation data
wxchan's avatar
wxchan committed
1572
1573
        """
        if data_idx >= self.__num_dataset:
1574
            raise ValueError("Data_idx should be smaller than number of dataset")
wxchan's avatar
wxchan committed
1575
1576
1577
        self.__get_eval_info()
        ret = []
        if self.__num_inner_eval > 0:
wxchan's avatar
wxchan committed
1578
            result = np.array([0.0 for _ in range_(self.__num_inner_eval)], dtype=np.float64)
Guolin Ke's avatar
Guolin Ke committed
1579
            tmp_out_len = ctypes.c_int(0)
wxchan's avatar
wxchan committed
1580
1581
            _safe_call(_LIB.LGBM_BoosterGetEval(
                self.handle,
Guolin Ke's avatar
Guolin Ke committed
1582
                ctypes.c_int(data_idx),
wxchan's avatar
wxchan committed
1583
                ctypes.byref(tmp_out_len),
Guolin Ke's avatar
Guolin Ke committed
1584
                result.ctypes.data_as(ctypes.POINTER(ctypes.c_double))))
wxchan's avatar
wxchan committed
1585
            if tmp_out_len.value != self.__num_inner_eval:
1586
                raise ValueError("Wrong length of eval results")
wxchan's avatar
wxchan committed
1587
            for i in range_(self.__num_inner_eval):
wxchan's avatar
wxchan committed
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
                ret.append((data_name, self.__name_inner_eval[i], result[i], self.__higher_better_inner_eval[i]))
        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):
        """
        Predict for training and validation dataset
        """
        if data_idx >= self.__num_dataset:
1608
            raise ValueError("Data_idx should be smaller than number of dataset")
wxchan's avatar
wxchan committed
1609
1610
1611
1612
1613
1614
        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
            self.__inner_predict_buffer[data_idx] = \
wxchan's avatar
wxchan committed
1615
                np.array([0.0 for _ in range_(n_preds)], dtype=np.float64, copy=False)
wxchan's avatar
wxchan committed
1616
1617
1618
        """avoid to predict many time in one iteration"""
        if not self.__is_predicted_cur_iter[data_idx]:
            tmp_out_len = ctypes.c_int64(0)
Guolin Ke's avatar
Guolin Ke committed
1619
            data_ptr = self.__inner_predict_buffer[data_idx].ctypes.data_as(ctypes.POINTER(ctypes.c_double))
wxchan's avatar
wxchan committed
1620
1621
            _safe_call(_LIB.LGBM_BoosterGetPredict(
                self.handle,
Guolin Ke's avatar
Guolin Ke committed
1622
                ctypes.c_int(data_idx),
wxchan's avatar
wxchan committed
1623
1624
1625
                ctypes.byref(tmp_out_len),
                data_ptr))
            if tmp_out_len.value != len(self.__inner_predict_buffer[data_idx]):
1626
                raise ValueError("Wrong length of predict results for data %d" % (data_idx))
wxchan's avatar
wxchan committed
1627
1628
1629
1630
1631
1632
1633
1634
1635
            self.__is_predicted_cur_iter[data_idx] = True
        return self.__inner_predict_buffer[data_idx]

    def __get_eval_info(self):
        """
        Get inner evaluation count and names
        """
        if self.__need_reload_eval_info:
            self.__need_reload_eval_info = False
Guolin Ke's avatar
Guolin Ke committed
1636
            out_num_eval = ctypes.c_int(0)
wxchan's avatar
wxchan committed
1637
1638
1639
1640
1641
1642
1643
            """Get num of inner evals"""
            _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:
                """Get name of evals"""
Guolin Ke's avatar
Guolin Ke committed
1644
                tmp_out_len = ctypes.c_int(0)
wxchan's avatar
wxchan committed
1645
                string_buffers = [ctypes.create_string_buffer(255) for i in range_(self.__num_inner_eval)]
wxchan's avatar
wxchan committed
1646
                ptr_string_buffers = (ctypes.c_char_p * self.__num_inner_eval)(*map(ctypes.addressof, string_buffers))
wxchan's avatar
wxchan committed
1647
1648
1649
1650
1651
                _safe_call(_LIB.LGBM_BoosterGetEvalNames(
                    self.handle,
                    ctypes.byref(tmp_out_len),
                    ptr_string_buffers))
                if self.__num_inner_eval != tmp_out_len.value:
1652
                    raise ValueError("Length of eval names doesn't equal with num_evals")
1653
                self.__name_inner_eval = \
wxchan's avatar
wxchan committed
1654
                    [string_buffers[i].value.decode() for i in range_(self.__num_inner_eval)]
1655
1656
1657
                self.__higher_better_inner_eval = \
                    [name.startswith(('auc', 'ndcg')) for name in self.__name_inner_eval]

wxchan's avatar
wxchan committed
1658
    def attr(self, key):
wxchan's avatar
wxchan committed
1659
1660
        """
        Get attribute string from the Booster.
wxchan's avatar
wxchan committed
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671

        Parameters
        ----------
        key : str
            The key to get attribute from.

        Returns
        -------
        value : str
            The attribute value of the key, returns None if attribute do not exist.
        """
1672
        return self.__attr.get(key, None)
wxchan's avatar
wxchan committed
1673
1674

    def set_attr(self, **kwargs):
wxchan's avatar
wxchan committed
1675
1676
        """
        Set the attribute of the Booster.
wxchan's avatar
wxchan committed
1677
1678
1679
1680
1681
1682
1683
1684

        Parameters
        ----------
        **kwargs
            The attributes to set. Setting a value to None deletes an attribute.
        """
        for key, value in kwargs.items():
            if value is not None:
wxchan's avatar
wxchan committed
1685
                if not isinstance(value, string_type):
1686
                    raise ValueError("Set attr only accepts strings")
wxchan's avatar
wxchan committed
1687
1688
1689
                self.__attr[key] = value
            else:
                self.__attr.pop(key, None)