basic.py 98.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
from .compat import (DataFrame, Series, DataTable,
17
18
                     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

110
111
112
113
114
115
116
117
def cint8_array_to_numpy(cptr, length):
    """Convert a ctypes int pointer array to a numpy array."""
    if isinstance(cptr, ctypes.POINTER(ctypes.c_int8)):
        return np.fromiter(cptr, dtype=np.int8, count=length)
    else:
        raise RuntimeError('Expected int pointer')


wxchan's avatar
wxchan committed
118
def c_str(string):
119
    """Convert a Python string to C string."""
wxchan's avatar
wxchan committed
120
121
    return ctypes.c_char_p(string.encode('utf-8'))

wxchan's avatar
wxchan committed
122

wxchan's avatar
wxchan committed
123
def c_array(ctype, values):
124
    """Convert a Python array to C array."""
wxchan's avatar
wxchan committed
125
126
    return (ctype * len(values))(*values)

wxchan's avatar
wxchan committed
127

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

wxchan's avatar
wxchan committed
143

144
class _TempFile(object):
145
146
147
148
    def __enter__(self):
        with NamedTemporaryFile(prefix="lightgbm_tmp_", delete=True) as f:
            self.name = f.name
        return self
wxchan's avatar
wxchan committed
149

150
151
152
    def __exit__(self, exc_type, exc_val, exc_tb):
        if os.path.isfile(self.name):
            os.remove(self.name)
wxchan's avatar
wxchan committed
153

154
155
156
157
    def readlines(self):
        with open(self.name, "r+") as f:
            ret = f.readlines()
        return ret
wxchan's avatar
wxchan committed
158

159
160
    def writelines(self, lines):
        with open(self.name, "w+") as f:
161
            f.writelines(lines)
162

wxchan's avatar
wxchan committed
163

164
class LightGBMError(Exception):
165
166
    """Error thrown by LightGBM."""

167
168
169
170
171
    pass


MAX_INT32 = (1 << 31) - 1

172
"""Macro definition of data type in C API of LightGBM"""
wxchan's avatar
wxchan committed
173
174
175
176
C_API_DTYPE_FLOAT32 = 0
C_API_DTYPE_FLOAT64 = 1
C_API_DTYPE_INT32 = 2
C_API_DTYPE_INT64 = 3
177
C_API_DTYPE_INT8 = 4
Guolin Ke's avatar
Guolin Ke committed
178

179
"""Matrix is row major in Python"""
wxchan's avatar
wxchan committed
180
181
C_API_IS_ROW_MAJOR = 1

182
"""Macro definition of prediction type in C API of LightGBM"""
wxchan's avatar
wxchan committed
183
184
185
C_API_PREDICT_NORMAL = 0
C_API_PREDICT_RAW_SCORE = 1
C_API_PREDICT_LEAF_INDEX = 2
186
C_API_PREDICT_CONTRIB = 3
wxchan's avatar
wxchan committed
187

188
"""Data type of data field"""
wxchan's avatar
wxchan committed
189
190
FIELD_TYPE_MAPPER = {"label": C_API_DTYPE_FLOAT32,
                     "weight": C_API_DTYPE_FLOAT32,
Guolin Ke's avatar
Guolin Ke committed
191
                     "init_score": C_API_DTYPE_FLOAT64,
192
193
194
                     "group": C_API_DTYPE_INT32,
                     "feature_penalty": C_API_DTYPE_FLOAT64,
                     "monotone_constraints": C_API_DTYPE_INT8}
wxchan's avatar
wxchan committed
195

196
197
PANDAS_DTYPE_MAPPER = {'int8': 'int', 'int16': 'int', 'int32': 'int',
                       'int64': 'int', 'uint8': 'int', 'uint16': 'int',
198
199
                       'uint32': 'int', 'uint64': 'int', 'bool': 'int',
                       'float16': 'float', 'float32': 'float', 'float64': 'float'}
200

wxchan's avatar
wxchan committed
201

202
def convert_from_sliced_object(data):
203
    """Fix the memory of multi-dimensional sliced object."""
204
205
    if data.base is not None and isinstance(data, np.ndarray) and isinstance(data.base, np.ndarray):
        if not data.flags.c_contiguous:
206
207
            warnings.warn("Usage of np.ndarray subset (sliced data) is not recommended "
                          "due to it will double the peak memory cost in LightGBM.")
208
209
210
211
            return np.copy(data)
    return data


wxchan's avatar
wxchan committed
212
def c_float_array(data):
213
    """Get pointer of float numpy array / list."""
wxchan's avatar
wxchan committed
214
215
216
    if is_1d_list(data):
        data = np.array(data, copy=False)
    if is_numpy_1d_array(data):
217
218
        data = convert_from_sliced_object(data)
        assert data.flags.c_contiguous
wxchan's avatar
wxchan committed
219
220
221
222
223
224
225
        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:
226
            raise TypeError("Expected np.float32 or np.float64, met type({})"
wxchan's avatar
wxchan committed
227
228
                            .format(data.dtype))
    else:
229
        raise TypeError("Unknown type({})".format(type(data).__name__))
230
    return (ptr_data, type_data, data)  # return `data` to avoid the temporary copy is freed
wxchan's avatar
wxchan committed
231

wxchan's avatar
wxchan committed
232

wxchan's avatar
wxchan committed
233
def c_int_array(data):
234
    """Get pointer of int numpy array / list."""
wxchan's avatar
wxchan committed
235
236
237
    if is_1d_list(data):
        data = np.array(data, copy=False)
    if is_numpy_1d_array(data):
238
239
        data = convert_from_sliced_object(data)
        assert data.flags.c_contiguous
wxchan's avatar
wxchan committed
240
241
242
243
244
245
246
        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:
247
            raise TypeError("Expected np.int32 or np.int64, met type({})"
wxchan's avatar
wxchan committed
248
249
                            .format(data.dtype))
    else:
250
        raise TypeError("Unknown type({})".format(type(data).__name__))
251
    return (ptr_data, type_data, data)  # return `data` to avoid the temporary copy is freed
wxchan's avatar
wxchan committed
252

wxchan's avatar
wxchan committed
253

254
def _data_from_pandas(data, feature_name, categorical_feature, pandas_categorical):
255
    if isinstance(data, DataFrame):
256
257
        if len(data.shape) != 2 or data.shape[0] < 1:
            raise ValueError('Input data must be 2 dimensional and non empty.')
258
259
260
261
262
263
264
265
        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.')
266
            for col, category in zip_(cat_cols, pandas_categorical):
267
268
269
270
                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
271
            data[cat_cols] = data[cat_cols].apply(lambda x: x.cat.codes).replace({-1: np.nan})
272
273
274
275
276
277
278
279
280
281
282
283
284
285
        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]

286
287
            msg = ("DataFrame.dtypes for data must be int, float or bool.\n"
                   "Did not expect the data types in fields ")
288
            raise ValueError(msg + ', '.join(bad_fields))
289
        data = data.values.astype('float')
290
291
292
293
294
295
    else:
        if feature_name == 'auto':
            feature_name = None
        if categorical_feature == 'auto':
            categorical_feature = None
    return data, feature_name, categorical_feature, pandas_categorical
296
297
298
299
300
301
302
303
304


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')
305
        label = label.values.astype('float').flatten()
306
307
308
    return label


309
310
311
312
313
314
315
316
317
318
319
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):
320
321
    pandas_key = 'pandas_categorical:'
    offset = -len(pandas_key)
322
    if file_name is not None:
323
324
325
326
327
328
329
330
331
332
333
334
335
        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()
336
    elif model_str is not None:
337
338
339
340
341
342
        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
343
344


Guolin Ke's avatar
Guolin Ke committed
345
class _InnerPredictor(object):
346
347
348
349
350
351
352
353
    """_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
354
    """
355

356
    def __init__(self, model_file=None, booster_handle=None, pred_parameter=None):
357
        """Initialize the _InnerPredictor.
wxchan's avatar
wxchan committed
358
359
360

        Parameters
        ----------
361
        model_file : string or None, optional (default=None)
wxchan's avatar
wxchan committed
362
            Path to the model file.
363
364
365
366
        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
367
368
369
370
371
        """
        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
372
            out_num_iterations = ctypes.c_int(0)
wxchan's avatar
wxchan committed
373
374
375
376
            _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
377
            out_num_class = ctypes.c_int(0)
wxchan's avatar
wxchan committed
378
379
380
381
            _safe_call(_LIB.LGBM_BoosterGetNumClasses(
                self.handle,
                ctypes.byref(out_num_class)))
            self.num_class = out_num_class.value
382
            self.num_total_iteration = out_num_iterations.value
383
            self.pandas_categorical = _load_pandas_categorical(file_name=model_file)
wxchan's avatar
wxchan committed
384
        elif booster_handle is not None:
Guolin Ke's avatar
Guolin Ke committed
385
            self.__is_manage_handle = False
wxchan's avatar
wxchan committed
386
            self.handle = booster_handle
Guolin Ke's avatar
Guolin Ke committed
387
            out_num_class = ctypes.c_int(0)
wxchan's avatar
wxchan committed
388
389
390
391
            _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
392
            out_num_iterations = ctypes.c_int(0)
wxchan's avatar
wxchan committed
393
394
395
            _safe_call(_LIB.LGBM_BoosterGetCurrentIteration(
                self.handle,
                ctypes.byref(out_num_iterations)))
396
            self.num_total_iteration = out_num_iterations.value
397
            self.pandas_categorical = None
wxchan's avatar
wxchan committed
398
        else:
Guolin Ke's avatar
Guolin Ke committed
399
            raise TypeError('Need Model file or Booster handle to create a predictor')
wxchan's avatar
wxchan committed
400

401
402
        pred_parameter = {} if pred_parameter is None else pred_parameter
        self.pred_parameter = param_dict_to_str(pred_parameter)
cbecker's avatar
cbecker committed
403

wxchan's avatar
wxchan committed
404
    def __del__(self):
405
406
407
408
409
        try:
            if self.__is_manage_handle:
                _safe_call(_LIB.LGBM_BoosterFree(self.handle))
        except AttributeError:
            pass
wxchan's avatar
wxchan committed
410

411
412
413
414
415
    def __getstate__(self):
        this = self.__dict__.copy()
        this.pop('handle', None)
        return this

wxchan's avatar
wxchan committed
416
    def predict(self, data, num_iteration=-1,
417
                raw_score=False, pred_leaf=False, pred_contrib=False, data_has_header=False,
wxchan's avatar
wxchan committed
418
                is_reshape=True):
419
        """Predict logic.
wxchan's avatar
wxchan committed
420
421
422

        Parameters
        ----------
423
        data : string, numpy array, pandas DataFrame, H2O DataTable's Frame or scipy.sparse
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
            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
439
440
441

        Returns
        -------
442
443
        result : numpy array
            Prediction result.
wxchan's avatar
wxchan committed
444
        """
wxchan's avatar
wxchan committed
445
        if isinstance(data, Dataset):
446
            raise TypeError("Cannot use Dataset instance for prediction, please use raw data instead")
447
        data = _data_from_pandas(data, None, None, self.pandas_categorical)[0]
wxchan's avatar
wxchan committed
448
449
450
451
452
        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
453
454
        if pred_contrib:
            predict_type = C_API_PREDICT_CONTRIB
wxchan's avatar
wxchan committed
455
        int_data_has_header = 1 if data_has_header else 0
456
457
        if num_iteration > self.num_total_iteration:
            num_iteration = self.num_total_iteration
cbecker's avatar
cbecker committed
458

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

    def __get_num_preds(self, num_iteration, nrow, predict_type):
505
        """Get size of prediction result."""
506
507
508
509
510
        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
511
512
513
        n_preds = ctypes.c_int64(0)
        _safe_call(_LIB.LGBM_BoosterCalcNumPredict(
            self.handle,
Guolin Ke's avatar
Guolin Ke committed
514
515
516
            ctypes.c_int(nrow),
            ctypes.c_int(predict_type),
            ctypes.c_int(num_iteration),
Guolin Ke's avatar
Guolin Ke committed
517
518
            ctypes.byref(n_preds)))
        return n_preds.value
wxchan's avatar
wxchan committed
519
520

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

525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
        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)
561
562
            for chunk, (start_idx_pred, end_idx_pred) in zip_(np.array_split(mat, sections),
                                                              zip_(n_preds_sections, n_preds_sections[1:])):
563
564
565
                # 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
566
        else:
567
            return inner_predict(mat, num_iteration, predict_type)
wxchan's avatar
wxchan committed
568
569

    def __pred_for_csr(self, csr, num_iteration, predict_type):
570
        """Predict for a CSR data."""
571
572
573
574
575
576
577
578
579
580
581
582
        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)

583
584
585
            assert csr.shape[1] <= MAX_INT32
            csr.indices = csr.indices.astype(np.int32, copy=False)

586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
            _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
604

605
606
607
608
609
610
611
612
613
614
615
616
617
618
        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
619
620

    def __pred_for_csc(self, csc, num_iteration, predict_type):
621
        """Predict for a CSC data."""
Guolin Ke's avatar
Guolin Ke committed
622
        nrow = csc.shape[0]
623
624
        if nrow > MAX_INT32:
            return self.__pred_for_csr(csc.tocsr(), num_iteration, predict_type)
Guolin Ke's avatar
Guolin Ke committed
625
626
627
628
        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)

629
630
        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
631

632
633
634
        assert csc.shape[0] <= MAX_INT32
        csc.indices = csc.indices.astype(np.int32, copy=False)

Guolin Ke's avatar
Guolin Ke committed
635
636
637
        _safe_call(_LIB.LGBM_BoosterPredictForCSC(
            self.handle,
            ptr_indptr,
Guolin Ke's avatar
Guolin Ke committed
638
            ctypes.c_int32(type_ptr_indptr),
Guolin Ke's avatar
Guolin Ke committed
639
640
            csc.indices.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)),
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
641
642
643
644
645
646
            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),
647
            c_str(self.pred_parameter),
Guolin Ke's avatar
Guolin Ke committed
648
            ctypes.byref(out_num_preds),
wxchan's avatar
wxchan committed
649
            preds.ctypes.data_as(ctypes.POINTER(ctypes.c_double))))
wxchan's avatar
wxchan committed
650
        if n_preds != out_num_preds.value:
651
            raise ValueError("Wrong length for predict results")
wxchan's avatar
wxchan committed
652
653
        return preds, nrow

wxchan's avatar
wxchan committed
654

wxchan's avatar
wxchan committed
655
656
class Dataset(object):
    """Dataset in LightGBM."""
657

658
    def __init__(self, data, label=None, reference=None,
659
                 weight=None, group=None, init_score=None, silent=False,
660
                 feature_name='auto', categorical_feature='auto', params=None,
wxchan's avatar
wxchan committed
661
                 free_raw_data=True):
662
        """Initialize Dataset.
663

wxchan's avatar
wxchan committed
664
665
        Parameters
        ----------
666
        data : string, numpy array, pandas DataFrame, H2O DataTable's Frame, scipy.sparse or list of numpy arrays
wxchan's avatar
wxchan committed
667
            Data source of Dataset.
668
            If string, it represents the path to txt file.
669
        label : list, numpy 1-D array, pandas Series / one-column DataFrame or None, optional (default=None)
670
671
672
            Label of the data.
        reference : Dataset or None, optional (default=None)
            If this is Dataset for validation, training data should be used as reference.
673
        weight : list, numpy 1-D array, pandas Series or None, optional (default=None)
wxchan's avatar
wxchan committed
674
            Weight for each instance.
675
        group : list, numpy 1-D array, pandas Series or None, optional (default=None)
676
            Group/query size for Dataset.
677
        init_score : list, numpy 1-D array, pandas Series or None, optional (default=None)
678
            Init score for Dataset.
679
680
681
682
683
684
685
686
687
688
        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.
689
            All values in categorical features should be less than int32 max value (2147483647).
690
            Large values could be memory consuming. Consider using consecutive integers starting from zero.
691
            All negative values in categorical features will be treated as missing values.
Nikita Titov's avatar
Nikita Titov committed
692
        params : dict or None, optional (default=None)
693
            Other parameters for Dataset.
Nikita Titov's avatar
Nikita Titov committed
694
        free_raw_data : bool, optional (default=True)
695
            If True, raw data is freed after constructing inner Dataset.
wxchan's avatar
wxchan committed
696
        """
wxchan's avatar
wxchan committed
697
698
699
700
701
702
        self.handle = None
        self.data = data
        self.label = label
        self.reference = reference
        self.weight = weight
        self.group = group
703
        self.init_score = init_score
wxchan's avatar
wxchan committed
704
705
        self.silent = silent
        self.feature_name = feature_name
706
        self.categorical_feature = categorical_feature
707
        self.params = copy.deepcopy(params)
wxchan's avatar
wxchan committed
708
709
        self.free_raw_data = free_raw_data
        self.used_indices = None
710
        self.need_slice = True
wxchan's avatar
wxchan committed
711
        self._predictor = None
712
        self.pandas_categorical = None
713
        self.params_back_up = None
714
715
        self.feature_penalty = None
        self.monotone_constraints = None
wxchan's avatar
wxchan committed
716
717

    def __del__(self):
718
719
720
721
        try:
            self._free_handle()
        except AttributeError:
            pass
722
723

    def _free_handle(self):
724
        if self.handle is not None:
725
            _safe_call(_LIB.LGBM_DatasetFree(self.handle))
726
            self.handle = None
Nikita Titov's avatar
Nikita Titov committed
727
        return self
wxchan's avatar
wxchan committed
728

729
    def _lazy_init(self, data, label=None, reference=None,
730
                   weight=None, group=None, init_score=None, predictor=None,
wxchan's avatar
wxchan committed
731
                   silent=False, feature_name='auto',
732
                   categorical_feature='auto', params=None):
wxchan's avatar
wxchan committed
733
734
        if data is None:
            self.handle = None
Nikita Titov's avatar
Nikita Titov committed
735
            return self
Guolin Ke's avatar
Guolin Ke committed
736
737
738
        if reference is not None:
            self.pandas_categorical = reference.pandas_categorical
            categorical_feature = reference.categorical_feature
739
740
741
742
        data, feature_name, categorical_feature, self.pandas_categorical = _data_from_pandas(data,
                                                                                             feature_name,
                                                                                             categorical_feature,
                                                                                             self.pandas_categorical)
wxchan's avatar
wxchan committed
743
744
        label = _label_from_pandas(label)
        self.data_has_header = False
745
        # process for args
wxchan's avatar
wxchan committed
746
        params = {} if params is None else params
747
748
749
        args_names = (getattr(self.__class__, '_lazy_init')
                      .__code__
                      .co_varnames[:getattr(self.__class__, '_lazy_init').__code__.co_argcount])
750
751
        for key, _ in params.items():
            if key in args_names:
752
753
754
                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
755
        self.predictor = predictor
756
757
758
        # 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
759
        # get categorical features
760
761
762
763
764
765
766
767
768
769
770
771
772
        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))
773
            if categorical_indices:
774
                if "categorical_feature" in params or "categorical_column" in params:
775
                    warnings.warn('categorical_feature in param dict is overridden.')
776
777
                    params.pop("categorical_feature", None)
                    params.pop("categorical_column", None)
778
                params['categorical_column'] = sorted(categorical_indices)
779

wxchan's avatar
wxchan committed
780
        params_str = param_dict_to_str(params)
781
        # process for reference dataset
wxchan's avatar
wxchan committed
782
        ref_dataset = None
wxchan's avatar
wxchan committed
783
        if isinstance(reference, Dataset):
784
            ref_dataset = reference.construct().handle
wxchan's avatar
wxchan committed
785
786
        elif reference is not None:
            raise TypeError('Reference dataset should be None or dataset instance')
787
        # start construct data
wxchan's avatar
wxchan committed
788
        if isinstance(data, string_type):
789
            # check data has header or not
Guolin Ke's avatar
Guolin Ke committed
790
            if str(params.get("has_header", "")).lower() == "true" \
wxchan's avatar
wxchan committed
791
                    or str(params.get("header", "")).lower() == "true":
792
                self.data_has_header = True
wxchan's avatar
wxchan committed
793
794
795
796
797
798
799
800
            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
801
802
        elif isinstance(data, scipy.sparse.csc_matrix):
            self.__init_from_csc(data, params_str, ref_dataset)
wxchan's avatar
wxchan committed
803
804
        elif isinstance(data, np.ndarray):
            self.__init_from_np2d(data, params_str, ref_dataset)
805
806
        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)
807
808
        elif isinstance(data, DataTable):
            self.__init_from_np2d(data.to_numpy(), params_str, ref_dataset)
wxchan's avatar
wxchan committed
809
810
811
812
        else:
            try:
                csr = scipy.sparse.csr_matrix(data)
                self.__init_from_csr(csr, params_str, ref_dataset)
813
            except BaseException:
wxchan's avatar
wxchan committed
814
                raise TypeError('Cannot initialize Dataset from {}'.format(type(data).__name__))
wxchan's avatar
wxchan committed
815
816
817
        if label is not None:
            self.set_label(label)
        if self.get_label() is None:
818
            raise ValueError("Label should not be None")
wxchan's avatar
wxchan committed
819
820
821
822
823
        if weight is not None:
            self.set_weight(weight)
        if group is not None:
            self.set_group(group)
        # load init score
824
825
826
        if init_score is not None:
            self.set_init_score(init_score)
            if self.predictor is not None:
827
                warnings.warn("The prediction of init_model will be overridden by init_score.")
828
        elif isinstance(self.predictor, _InnerPredictor):
wxchan's avatar
wxchan committed
829
830
831
832
833
834
            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
835
                new_init_score = np.zeros(init_score.size, dtype=np.float32)
wxchan's avatar
wxchan committed
836
                num_data = self.num_data()
wxchan's avatar
wxchan committed
837
838
                for i in range_(num_data):
                    for j in range_(self.predictor.num_class):
wxchan's avatar
wxchan committed
839
840
841
                        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
842
843
        elif self.predictor is not None:
            raise TypeError('wrong predictor type {}'.format(type(self.predictor).__name__))
Guolin Ke's avatar
Guolin Ke committed
844
        # set feature names
Nikita Titov's avatar
Nikita Titov committed
845
        return self.set_feature_name(feature_name)
wxchan's avatar
wxchan committed
846
847

    def __init_from_np2d(self, mat, params_str, ref_dataset):
848
        """Initialize data from a 2-D numpy matrix."""
wxchan's avatar
wxchan committed
849
850
851
852
853
854
855
        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:
856
            # change non-float data to float data, need to copy
wxchan's avatar
wxchan committed
857
858
            data = np.array(mat.reshape(mat.size), dtype=np.float32)

859
        ptr_data, type_ptr_data, _ = c_float_array(data)
wxchan's avatar
wxchan committed
860
861
        _safe_call(_LIB.LGBM_DatasetCreateFromMat(
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
862
863
864
865
            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
866
867
868
            c_str(params_str),
            ref_dataset,
            ctypes.byref(self.handle)))
Nikita Titov's avatar
Nikita Titov committed
869
        return self
wxchan's avatar
wxchan committed
870

871
    def __init_from_list_np2d(self, mats, params_str, ref_dataset):
872
        """Initialize data from a list of 2-D numpy matrices."""
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
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
        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
916
        return self
917

wxchan's avatar
wxchan committed
918
    def __init_from_csr(self, csr, params_str, ref_dataset):
919
        """Initialize data from a CSR matrix."""
wxchan's avatar
wxchan committed
920
        if len(csr.indices) != len(csr.data):
921
            raise ValueError('Length mismatch: {} vs {}'.format(len(csr.indices), len(csr.data)))
wxchan's avatar
wxchan committed
922
923
        self.handle = ctypes.c_void_p()

924
925
        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
926

927
928
929
        assert csr.shape[1] <= MAX_INT32
        csr.indices = csr.indices.astype(np.int32, copy=False)

wxchan's avatar
wxchan committed
930
931
        _safe_call(_LIB.LGBM_DatasetCreateFromCSR(
            ptr_indptr,
Guolin Ke's avatar
Guolin Ke committed
932
            ctypes.c_int(type_ptr_indptr),
wxchan's avatar
wxchan committed
933
934
            csr.indices.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)),
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
935
936
937
938
            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
939
940
941
            c_str(params_str),
            ref_dataset,
            ctypes.byref(self.handle)))
Nikita Titov's avatar
Nikita Titov committed
942
        return self
wxchan's avatar
wxchan committed
943

Guolin Ke's avatar
Guolin Ke committed
944
    def __init_from_csc(self, csc, params_str, ref_dataset):
945
        """Initialize data from a CSC matrix."""
Guolin Ke's avatar
Guolin Ke committed
946
947
948
949
        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()

950
951
        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
952

953
954
955
        assert csc.shape[0] <= MAX_INT32
        csc.indices = csc.indices.astype(np.int32, copy=False)

Guolin Ke's avatar
Guolin Ke committed
956
957
        _safe_call(_LIB.LGBM_DatasetCreateFromCSC(
            ptr_indptr,
Guolin Ke's avatar
Guolin Ke committed
958
            ctypes.c_int(type_ptr_indptr),
Guolin Ke's avatar
Guolin Ke committed
959
960
            csc.indices.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)),
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
961
962
963
964
            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
965
966
967
            c_str(params_str),
            ref_dataset,
            ctypes.byref(self.handle)))
Nikita Titov's avatar
Nikita Titov committed
968
        return self
Guolin Ke's avatar
Guolin Ke committed
969

wxchan's avatar
wxchan committed
970
    def construct(self):
971
972
973
974
975
        """Lazy init.

        Returns
        -------
        self : Dataset
Nikita Titov's avatar
Nikita Titov committed
976
            Constructed Dataset object.
977
        """
978
        if self.handle is None:
wxchan's avatar
wxchan committed
979
980
            if self.reference is not None:
                if self.used_indices is None:
981
                    # create valid
982
                    self._lazy_init(self.data, label=self.label, reference=self.reference,
983
984
                                    weight=self.weight, group=self.group,
                                    init_score=self.init_score, predictor=self._predictor,
985
                                    silent=self.silent, feature_name=self.feature_name, params=self.params)
wxchan's avatar
wxchan committed
986
                else:
987
                    # construct subset
wxchan's avatar
wxchan committed
988
                    used_indices = list_to_1d_numpy(self.used_indices, np.int32, name='used_indices')
989
                    assert used_indices.flags.c_contiguous
Guolin Ke's avatar
Guolin Ke committed
990
991
                    if self.reference.group is not None:
                        group_info = np.array(self.reference.group).astype(int)
992
993
                        _, self.group = np.unique(np.repeat(range_(len(group_info)), repeats=group_info)[self.used_indices],
                                                  return_counts=True)
994
                    self.handle = ctypes.c_void_p()
wxchan's avatar
wxchan committed
995
996
                    params_str = param_dict_to_str(self.params)
                    _safe_call(_LIB.LGBM_DatasetGetSubset(
997
                        self.reference.construct().handle,
wxchan's avatar
wxchan committed
998
                        used_indices.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)),
Guolin Ke's avatar
Guolin Ke committed
999
                        ctypes.c_int(used_indices.shape[0]),
wxchan's avatar
wxchan committed
1000
1001
                        c_str(params_str),
                        ctypes.byref(self.handle)))
1002
1003
                    self.data = self.reference.data
                    self.get_data()
Guolin Ke's avatar
Guolin Ke committed
1004
1005
                    if self.group is not None:
                        self.set_group(self.group)
wxchan's avatar
wxchan committed
1006
1007
1008
                    if self.get_label() is None:
                        raise ValueError("Label should not be None.")
            else:
1009
                # create train
1010
                self._lazy_init(self.data, label=self.label,
1011
1012
1013
                                weight=self.weight, group=self.group,
                                init_score=self.init_score, predictor=self._predictor,
                                silent=self.silent, feature_name=self.feature_name,
1014
                                categorical_feature=self.categorical_feature, params=self.params)
wxchan's avatar
wxchan committed
1015
1016
1017
            if self.free_raw_data:
                self.data = None
        return self
wxchan's avatar
wxchan committed
1018

wxchan's avatar
wxchan committed
1019
    def create_valid(self, data, label=None, weight=None, group=None,
1020
                     init_score=None, silent=False, params=None):
1021
        """Create validation data align with current Dataset.
wxchan's avatar
wxchan committed
1022
1023
1024

        Parameters
        ----------
1025
        data : string, numpy array, pandas DataFrame, H2O DataTable's Frame, scipy.sparse or list of numpy arrays
wxchan's avatar
wxchan committed
1026
            Data source of Dataset.
1027
            If string, it represents the path to txt file.
1028
        label : list, numpy 1-D array, pandas Series / one-column DataFrame or None, optional (default=None)
1029
1030
            Label of the data.
        weight : list, numpy 1-D array, pandas Series or None, optional (default=None)
wxchan's avatar
wxchan committed
1031
            Weight for each instance.
1032
        group : list, numpy 1-D array, pandas Series or None, optional (default=None)
1033
            Group/query size for Dataset.
1034
        init_score : list, numpy 1-D array, pandas Series or None, optional (default=None)
1035
            Init score for Dataset.
1036
1037
        silent : bool, optional (default=False)
            Whether to print messages during construction.
Nikita Titov's avatar
Nikita Titov committed
1038
        params : dict or None, optional (default=None)
1039
            Other parameters for validation Dataset.
1040
1041
1042

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1043
1044
        valid : Dataset
            Validation Dataset with reference to self.
wxchan's avatar
wxchan committed
1045
        """
1046
        ret = Dataset(data, label=label, reference=self,
1047
1048
                      weight=weight, group=group, init_score=init_score,
                      silent=silent, params=params, free_raw_data=self.free_raw_data)
wxchan's avatar
wxchan committed
1049
        ret._predictor = self._predictor
1050
        ret.pandas_categorical = self.pandas_categorical
wxchan's avatar
wxchan committed
1051
        return ret
wxchan's avatar
wxchan committed
1052

wxchan's avatar
wxchan committed
1053
    def subset(self, used_indices, params=None):
1054
        """Get subset of current Dataset.
wxchan's avatar
wxchan committed
1055
1056
1057
1058

        Parameters
        ----------
        used_indices : list of int
1059
            Indices used to create the subset.
Nikita Titov's avatar
Nikita Titov committed
1060
        params : dict or None, optional (default=None)
1061
            These parameters will be passed to Dataset constructor.
1062
1063
1064
1065
1066

        Returns
        -------
        subset : Dataset
            Subset of the current Dataset.
wxchan's avatar
wxchan committed
1067
        """
wxchan's avatar
wxchan committed
1068
1069
        if params is None:
            params = self.params
wxchan's avatar
wxchan committed
1070
        ret = Dataset(None, reference=self, feature_name=self.feature_name,
1071
1072
                      categorical_feature=self.categorical_feature, params=params,
                      free_raw_data=self.free_raw_data)
wxchan's avatar
wxchan committed
1073
        ret._predictor = self._predictor
1074
        ret.pandas_categorical = self.pandas_categorical
wxchan's avatar
wxchan committed
1075
1076
1077
1078
        ret.used_indices = used_indices
        return ret

    def save_binary(self, filename):
1079
        """Save Dataset to a binary file.
wxchan's avatar
wxchan committed
1080
1081
1082
1083
1084

        Parameters
        ----------
        filename : string
            Name of the output file.
Nikita Titov's avatar
Nikita Titov committed
1085
1086
1087
1088
1089

        Returns
        -------
        self : Dataset
            Returns self.
wxchan's avatar
wxchan committed
1090
1091
1092
1093
        """
        _safe_call(_LIB.LGBM_DatasetSaveBinary(
            self.construct().handle,
            c_str(filename)))
Nikita Titov's avatar
Nikita Titov committed
1094
        return self
wxchan's avatar
wxchan committed
1095
1096

    def _update_params(self, params):
1097
1098
        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
1099
1100
        if not self.params:
            self.params = params
wxchan's avatar
wxchan committed
1101
        else:
1102
            self.params_back_up = copy.deepcopy(self.params)
wxchan's avatar
wxchan committed
1103
            self.params.update(params)
Nikita Titov's avatar
Nikita Titov committed
1104
        return self
wxchan's avatar
wxchan committed
1105

1106
1107
1108
    def _reverse_update_params(self):
        self.params = copy.deepcopy(self.params_back_up)
        self.params_back_up = None
1109
1110
        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
1111
        return self
1112

wxchan's avatar
wxchan committed
1113
    def set_field(self, field_name, data):
wxchan's avatar
wxchan committed
1114
        """Set property into the Dataset.
wxchan's avatar
wxchan committed
1115
1116
1117

        Parameters
        ----------
Nikita Titov's avatar
Nikita Titov committed
1118
        field_name : string
1119
            The field name of the information.
1120
        data : list, numpy 1-D array, pandas Series or None
1121
            The array of data to be set.
Nikita Titov's avatar
Nikita Titov committed
1122
1123
1124
1125
1126

        Returns
        -------
        self : Dataset
            Dataset with set property.
wxchan's avatar
wxchan committed
1127
        """
1128
1129
        if self.handle is None:
            raise Exception("Cannot set %s before construct dataset" % field_name)
wxchan's avatar
wxchan committed
1130
        if data is None:
1131
            # set to None
wxchan's avatar
wxchan committed
1132
1133
1134
1135
            _safe_call(_LIB.LGBM_DatasetSetField(
                self.handle,
                c_str(field_name),
                None,
Guolin Ke's avatar
Guolin Ke committed
1136
1137
                ctypes.c_int(0),
                ctypes.c_int(FIELD_TYPE_MAPPER[field_name])))
Nikita Titov's avatar
Nikita Titov committed
1138
            return self
Guolin Ke's avatar
Guolin Ke committed
1139
1140
1141
1142
1143
        dtype = np.float32
        if field_name == 'group':
            dtype = np.int32
        elif field_name == 'init_score':
            dtype = np.float64
1144
        data = list_to_1d_numpy(data, dtype, name=field_name)
1145
1146
        if data.dtype == np.float32 or data.dtype == np.float64:
            ptr_data, type_data, _ = c_float_array(data)
wxchan's avatar
wxchan committed
1147
        elif data.dtype == np.int32:
1148
            ptr_data, type_data, _ = c_int_array(data)
wxchan's avatar
wxchan committed
1149
        else:
Guolin Ke's avatar
Guolin Ke committed
1150
            raise TypeError("Excepted np.float32/64 or np.int32, meet type({})".format(data.dtype))
wxchan's avatar
wxchan committed
1151
        if type_data != FIELD_TYPE_MAPPER[field_name]:
1152
            raise TypeError("Input type error for set_field")
wxchan's avatar
wxchan committed
1153
1154
1155
1156
        _safe_call(_LIB.LGBM_DatasetSetField(
            self.handle,
            c_str(field_name),
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
1157
1158
            ctypes.c_int(len(data)),
            ctypes.c_int(type_data)))
Nikita Titov's avatar
Nikita Titov committed
1159
        return self
wxchan's avatar
wxchan committed
1160

wxchan's avatar
wxchan committed
1161
1162
    def get_field(self, field_name):
        """Get property from the Dataset.
wxchan's avatar
wxchan committed
1163
1164
1165

        Parameters
        ----------
Nikita Titov's avatar
Nikita Titov committed
1166
        field_name : string
1167
            The field name of the information.
wxchan's avatar
wxchan committed
1168
1169
1170

        Returns
        -------
1171
1172
        info : numpy array
            A numpy array with information from the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1173
        """
1174
        if self.handle is None:
1175
            raise Exception("Cannot get %s before construct Dataset" % field_name)
Guolin Ke's avatar
Guolin Ke committed
1176
1177
        tmp_out_len = ctypes.c_int()
        out_type = ctypes.c_int()
wxchan's avatar
wxchan committed
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
        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
1193
1194
        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)
1195
1196
        elif out_type.value == C_API_DTYPE_INT8:
            return cint8_array_to_numpy(ctypes.cast(ret, ctypes.POINTER(ctypes.c_int8)), tmp_out_len.value)
1197
        else:
wxchan's avatar
wxchan committed
1198
            raise TypeError("Unknown type")
Guolin Ke's avatar
Guolin Ke committed
1199

1200
    def set_categorical_feature(self, categorical_feature):
1201
        """Set categorical features.
1202
1203
1204

        Parameters
        ----------
1205
1206
        categorical_feature : list of int or strings
            Names or indices of categorical features.
Nikita Titov's avatar
Nikita Titov committed
1207
1208
1209
1210
1211

        Returns
        -------
        self : Dataset
            Dataset with set categorical features.
1212
1213
        """
        if self.categorical_feature == categorical_feature:
Nikita Titov's avatar
Nikita Titov committed
1214
            return self
1215
        if self.data is not None:
1216
1217
            if self.categorical_feature is None:
                self.categorical_feature = categorical_feature
Nikita Titov's avatar
Nikita Titov committed
1218
                return self._free_handle()
1219
1220
            elif categorical_feature == 'auto':
                warnings.warn('Using categorical_feature in Dataset.')
Nikita Titov's avatar
Nikita Titov committed
1221
                return self
1222
            else:
1223
1224
                warnings.warn('categorical_feature in Dataset is overridden.\n'
                              'New categorical_feature is {}'.format(sorted(list(categorical_feature))))
1225
                self.categorical_feature = categorical_feature
Nikita Titov's avatar
Nikita Titov committed
1226
                return self._free_handle()
1227
        else:
1228
1229
            raise LightGBMError("Cannot set categorical feature after freed raw data, "
                                "set free_raw_data=False when construct Dataset to avoid this.")
1230

Guolin Ke's avatar
Guolin Ke committed
1231
    def _set_predictor(self, predictor):
1232
1233
1234
1235
        """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
1236
1237
        """
        if predictor is self._predictor:
Nikita Titov's avatar
Nikita Titov committed
1238
            return self
Guolin Ke's avatar
Guolin Ke committed
1239
1240
        if self.data is not None:
            self._predictor = predictor
Nikita Titov's avatar
Nikita Titov committed
1241
            return self._free_handle()
Guolin Ke's avatar
Guolin Ke committed
1242
        else:
1243
1244
            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
1245
1246

    def set_reference(self, reference):
1247
        """Set reference Dataset.
Guolin Ke's avatar
Guolin Ke committed
1248
1249
1250
1251

        Parameters
        ----------
        reference : Dataset
1252
            Reference that is used as a template to construct the current Dataset.
Nikita Titov's avatar
Nikita Titov committed
1253
1254
1255
1256
1257

        Returns
        -------
        self : Dataset
            Dataset with set reference.
Guolin Ke's avatar
Guolin Ke committed
1258
        """
1259
1260
1261
        self.set_categorical_feature(reference.categorical_feature) \
            .set_feature_name(reference.feature_name) \
            ._set_predictor(reference._predictor)
1262
1263
        # 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
1264
            return self
Guolin Ke's avatar
Guolin Ke committed
1265
1266
        if self.data is not None:
            self.reference = reference
Nikita Titov's avatar
Nikita Titov committed
1267
            return self._free_handle()
Guolin Ke's avatar
Guolin Ke committed
1268
        else:
1269
1270
            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
1271
1272

    def set_feature_name(self, feature_name):
1273
        """Set feature name.
Guolin Ke's avatar
Guolin Ke committed
1274
1275
1276

        Parameters
        ----------
1277
1278
        feature_name : list of strings
            Feature names.
Nikita Titov's avatar
Nikita Titov committed
1279
1280
1281
1282
1283

        Returns
        -------
        self : Dataset
            Dataset with set feature name.
Guolin Ke's avatar
Guolin Ke committed
1284
        """
1285
1286
        if feature_name != 'auto':
            self.feature_name = feature_name
1287
        if self.handle is not None and feature_name is not None and feature_name != 'auto':
wxchan's avatar
wxchan committed
1288
            if len(feature_name) != self.num_feature():
1289
1290
                raise ValueError("Length of feature_name({}) and num_feature({}) don't match"
                                 .format(len(feature_name), self.num_feature()))
1291
            c_feature_name = [c_str(name) for name in feature_name]
wxchan's avatar
wxchan committed
1292
1293
1294
            _safe_call(_LIB.LGBM_DatasetSetFeatureNames(
                self.handle,
                c_array(ctypes.c_char_p, c_feature_name),
Guolin Ke's avatar
Guolin Ke committed
1295
                ctypes.c_int(len(feature_name))))
Nikita Titov's avatar
Nikita Titov committed
1296
        return self
Guolin Ke's avatar
Guolin Ke committed
1297
1298

    def set_label(self, label):
1299
        """Set label of Dataset.
Guolin Ke's avatar
Guolin Ke committed
1300
1301
1302

        Parameters
        ----------
1303
        label : list, numpy 1-D array, pandas Series / one-column DataFrame or None
1304
            The label information to be set into Dataset.
Nikita Titov's avatar
Nikita Titov committed
1305
1306
1307
1308
1309

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

    def set_weight(self, weight):
1318
        """Set weight of each instance.
Guolin Ke's avatar
Guolin Ke committed
1319
1320
1321

        Parameters
        ----------
1322
        weight : list, numpy 1-D array, pandas Series or None
1323
            Weight to be set for each data point.
Nikita Titov's avatar
Nikita Titov committed
1324
1325
1326
1327
1328

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

    def set_init_score(self, init_score):
1339
        """Set init score of Booster to start from.
Guolin Ke's avatar
Guolin Ke committed
1340
1341
1342

        Parameters
        ----------
1343
        init_score : list, numpy 1-D array, pandas Series or None
1344
            Init score for Booster.
Nikita Titov's avatar
Nikita Titov committed
1345
1346
1347
1348
1349

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

    def set_group(self, group):
1358
        """Set group size of Dataset (used for ranking).
Guolin Ke's avatar
Guolin Ke committed
1359
1360
1361

        Parameters
        ----------
1362
        group : list, numpy 1-D array, pandas Series or None
1363
            Group size of each group.
Nikita Titov's avatar
Nikita Titov committed
1364
1365
1366
1367
1368

        Returns
        -------
        self : Dataset
            Dataset with set group.
Guolin Ke's avatar
Guolin Ke committed
1369
1370
        """
        self.group = group
1371
        if self.handle is not None and group is not None:
wxchan's avatar
wxchan committed
1372
1373
            group = list_to_1d_numpy(group, np.int32, name='group')
            self.set_field('group', group)
Nikita Titov's avatar
Nikita Titov committed
1374
        return self
Guolin Ke's avatar
Guolin Ke committed
1375
1376

    def get_label(self):
1377
        """Get the label of the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1378
1379
1380

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1381
        label : numpy array or None
1382
            The label information from the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1383
        """
1384
        if self.label is None:
wxchan's avatar
wxchan committed
1385
            self.label = self.get_field('label')
Guolin Ke's avatar
Guolin Ke committed
1386
1387
1388
        return self.label

    def get_weight(self):
1389
        """Get the weight of the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1390
1391
1392

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1393
        weight : numpy array or None
1394
            Weight for each data point from the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1395
        """
1396
        if self.weight is None:
wxchan's avatar
wxchan committed
1397
            self.weight = self.get_field('weight')
Guolin Ke's avatar
Guolin Ke committed
1398
1399
        return self.weight

1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
    def get_feature_penalty(self):
        """Get the feature penalty of the Dataset.

        Returns
        -------
        feature_penalty : numpy array or None
            Feature penalty for each feature in the Dataset.
        """
        if self.feature_penalty is None:
            self.feature_penalty = self.get_field('feature_penalty')
        return self.feature_penalty

    def get_monotone_constraints(self):
        """Get the monotone constraints of the Dataset.

        Returns
        -------
        monotone_constraints : numpy array or None
            Monotone constraints: -1, 0 or 1, for each feature in the Dataset.
        """
        if self.monotone_constraints is None:
            self.monotone_constraints = self.get_field('monotone_constraints')
        return self.monotone_constraints

Guolin Ke's avatar
Guolin Ke committed
1424
    def get_init_score(self):
1425
        """Get the initial score of the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1426
1427
1428

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1429
        init_score : numpy array or None
1430
            Init score of Booster.
Guolin Ke's avatar
Guolin Ke committed
1431
        """
1432
        if self.init_score is None:
wxchan's avatar
wxchan committed
1433
            self.init_score = self.get_field('init_score')
Guolin Ke's avatar
Guolin Ke committed
1434
1435
        return self.init_score

1436
1437
1438
1439
1440
    def get_data(self):
        """Get the raw data of the Dataset.

        Returns
        -------
1441
        data : string, numpy array, pandas DataFrame, H2O DataTable's Frame, scipy.sparse, list of numpy arrays or None
1442
1443
1444
1445
1446
1447
1448
1449
1450
            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()
1451
1452
            elif isinstance(self.data, DataTable):
                self.data = self.data[self.used_indices, :]
1453
1454
1455
1456
1457
1458
            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
1459
    def get_group(self):
1460
        """Get the group of the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1461
1462
1463

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1464
        group : numpy array or None
1465
            Group size of each group.
Guolin Ke's avatar
Guolin Ke committed
1466
        """
1467
        if self.group is None:
wxchan's avatar
wxchan committed
1468
            self.group = self.get_field('group')
Guolin Ke's avatar
Guolin Ke committed
1469
1470
            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
1471
                self.group = np.diff(self.group)
Guolin Ke's avatar
Guolin Ke committed
1472
1473
1474
        return self.group

    def num_data(self):
1475
        """Get the number of rows in the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1476
1477
1478

        Returns
        -------
1479
1480
        number_of_rows : int
            The number of rows in the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1481
        """
1482
        if self.handle is not None:
Guolin Ke's avatar
Guolin Ke committed
1483
            ret = ctypes.c_int()
wxchan's avatar
wxchan committed
1484
1485
1486
            _safe_call(_LIB.LGBM_DatasetGetNumData(self.handle,
                                                   ctypes.byref(ret)))
            return ret.value
Guolin Ke's avatar
Guolin Ke committed
1487
        else:
1488
            raise LightGBMError("Cannot get num_data before construct dataset")
Guolin Ke's avatar
Guolin Ke committed
1489
1490

    def num_feature(self):
1491
        """Get the number of columns (features) in the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1492
1493
1494

        Returns
        -------
1495
1496
        number_of_columns : int
            The number of columns (features) in the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1497
        """
1498
        if self.handle is not None:
Guolin Ke's avatar
Guolin Ke committed
1499
            ret = ctypes.c_int()
wxchan's avatar
wxchan committed
1500
1501
1502
            _safe_call(_LIB.LGBM_DatasetGetNumFeature(self.handle,
                                                      ctypes.byref(ret)))
            return ret.value
Guolin Ke's avatar
Guolin Ke committed
1503
        else:
1504
            raise LightGBMError("Cannot get num_feature before construct dataset")
Guolin Ke's avatar
Guolin Ke committed
1505

1506
    def get_ref_chain(self, ref_limit=100):
1507
1508
1509
1510
1511
        """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.
1512
1513
1514
1515
1516

        Parameters
        ----------
        ref_limit : int, optional (default=100)
            The limit number of references.
1517
1518
1519

        Returns
        -------
1520
1521
1522
        ref_chain : set of Dataset
            Chain of references of the Datasets.
        """
1523
        head = self
1524
        ref_chain = set()
1525
1526
        while len(ref_chain) < ref_limit:
            if isinstance(head, Dataset):
1527
                ref_chain.add(head)
1528
1529
1530
1531
1532
1533
                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
1534
        return ref_chain
1535

1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
    def add_features_from(self, other):
        """Add features from other Dataset to the current Dataset.

        Both Datasets must be constructed before calling this method.

        Parameters
        ----------
        other : Dataset
            The Dataset to take features from.

        Returns
        -------
        self : Dataset
            Dataset with the new features added.
        """
        if self.handle is None or other.handle is None:
            raise ValueError('Both source and target Datasets must be constructed before adding features')
        _safe_call(_LIB.LGBM_DatasetAddFeaturesFrom(self.handle, other.handle))
        return self

    def dump_text(self, filename):
        """Save Dataset to a text file.

        This format cannot be loaded back in by LightGBM, but is useful for debugging purposes.

        Parameters
        ----------
        filename : string
            Name of the output file.

        Returns
        -------
        self : Dataset
            Returns self.
        """
        _safe_call(_LIB.LGBM_DatasetDumpText(
            self.construct().handle,
            c_str(filename)))
        return self

wxchan's avatar
wxchan committed
1576

wxchan's avatar
wxchan committed
1577
class Booster(object):
1578
    """Booster in LightGBM."""
1579

wxchan's avatar
wxchan committed
1580
    def __init__(self, params=None, train_set=None, model_file=None, silent=False):
1581
        """Initialize the Booster.
wxchan's avatar
wxchan committed
1582
1583
1584

        Parameters
        ----------
Nikita Titov's avatar
Nikita Titov committed
1585
        params : dict or None, optional (default=None)
1586
1587
1588
1589
            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
1590
            Path to the model file.
1591
1592
        silent : bool, optional (default=False)
            Whether to print messages during construction.
wxchan's avatar
wxchan committed
1593
        """
1594
        self.handle = None
1595
        self.network = False
wxchan's avatar
wxchan committed
1596
1597
1598
        self.__need_reload_eval_info = True
        self.__train_data_name = "training"
        self.__attr = {}
1599
        self.__set_objective_to_none = False
wxchan's avatar
wxchan committed
1600
        self.best_iteration = -1
wxchan's avatar
wxchan committed
1601
        self.best_score = {}
1602
        params = {} if params is None else copy.deepcopy(params)
1603
1604
1605
        # 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
1606
        if train_set is not None:
1607
            # Training task
wxchan's avatar
wxchan committed
1608
            if not isinstance(train_set, Dataset):
1609
1610
                raise TypeError('Training data should be Dataset instance, met {}'
                                .format(type(train_set).__name__))
wxchan's avatar
wxchan committed
1611
            params_str = param_dict_to_str(params)
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
            # 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
1628
            # construct booster object
1629
            self.handle = ctypes.c_void_p()
wxchan's avatar
wxchan committed
1630
            _safe_call(_LIB.LGBM_BoosterCreate(
wxchan's avatar
wxchan committed
1631
                train_set.construct().handle,
wxchan's avatar
wxchan committed
1632
1633
                c_str(params_str),
                ctypes.byref(self.handle)))
1634
            # save reference to data
wxchan's avatar
wxchan committed
1635
1636
1637
1638
            self.train_set = train_set
            self.valid_sets = []
            self.name_valid_sets = []
            self.__num_dataset = 1
Guolin Ke's avatar
Guolin Ke committed
1639
1640
            self.__init_predictor = train_set._predictor
            if self.__init_predictor is not None:
wxchan's avatar
wxchan committed
1641
1642
                _safe_call(_LIB.LGBM_BoosterMerge(
                    self.handle,
Guolin Ke's avatar
Guolin Ke committed
1643
                    self.__init_predictor.handle))
Guolin Ke's avatar
Guolin Ke committed
1644
            out_num_class = ctypes.c_int(0)
wxchan's avatar
wxchan committed
1645
1646
1647
1648
            _safe_call(_LIB.LGBM_BoosterGetNumClasses(
                self.handle,
                ctypes.byref(out_num_class)))
            self.__num_class = out_num_class.value
1649
            # buffer for inner predict
wxchan's avatar
wxchan committed
1650
1651
1652
            self.__inner_predict_buffer = [None]
            self.__is_predicted_cur_iter = [False]
            self.__get_eval_info()
1653
            self.pandas_categorical = train_set.pandas_categorical
wxchan's avatar
wxchan committed
1654
        elif model_file is not None:
1655
            # Prediction task
Guolin Ke's avatar
Guolin Ke committed
1656
            out_num_iterations = ctypes.c_int(0)
1657
            self.handle = ctypes.c_void_p()
wxchan's avatar
wxchan committed
1658
1659
1660
1661
            _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
1662
            out_num_class = ctypes.c_int(0)
wxchan's avatar
wxchan committed
1663
1664
1665
1666
            _safe_call(_LIB.LGBM_BoosterGetNumClasses(
                self.handle,
                ctypes.byref(out_num_class)))
            self.__num_class = out_num_class.value
1667
            self.pandas_categorical = _load_pandas_categorical(file_name=model_file)
1668
        elif 'model_str' in params:
1669
            self.model_from_string(params['model_str'], False)
wxchan's avatar
wxchan committed
1670
        else:
1671
            raise TypeError('Need at least one training dataset or model file to create booster instance')
1672
        self.params = params
wxchan's avatar
wxchan committed
1673
1674

    def __del__(self):
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
        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
1685

wxchan's avatar
wxchan committed
1686
1687
1688
1689
    def __copy__(self):
        return self.__deepcopy__(None)

    def __deepcopy__(self, _):
1690
        model_str = self.model_to_string(num_iteration=-1)
1691
1692
        booster = Booster({'model_str': model_str})
        return booster
wxchan's avatar
wxchan committed
1693
1694
1695
1696
1697
1698
1699

    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:
1700
            this["handle"] = self.model_to_string(num_iteration=-1)
wxchan's avatar
wxchan committed
1701
1702
1703
        return this

    def __setstate__(self, state):
1704
1705
        model_str = state.get('handle', None)
        if model_str is not None:
wxchan's avatar
wxchan committed
1706
            handle = ctypes.c_void_p()
Guolin Ke's avatar
Guolin Ke committed
1707
            out_num_iterations = ctypes.c_int(0)
1708
1709
1710
1711
            _safe_call(_LIB.LGBM_BoosterLoadModelFromString(
                c_str(model_str),
                ctypes.byref(out_num_iterations),
                ctypes.byref(handle)))
wxchan's avatar
wxchan committed
1712
1713
1714
            state['handle'] = handle
        self.__dict__.update(state)

wxchan's avatar
wxchan committed
1715
    def free_dataset(self):
Nikita Titov's avatar
Nikita Titov committed
1716
1717
1718
1719
1720
1721
1722
        """Free Booster's Datasets.

        Returns
        -------
        self : Booster
            Booster without Datasets.
        """
wxchan's avatar
wxchan committed
1723
1724
        self.__dict__.pop('train_set', None)
        self.__dict__.pop('valid_sets', None)
1725
        self.__num_dataset = 0
Nikita Titov's avatar
Nikita Titov committed
1726
        return self
wxchan's avatar
wxchan committed
1727

1728
1729
1730
    def _free_buffer(self):
        self.__inner_predict_buffer = []
        self.__is_predicted_cur_iter = []
Nikita Titov's avatar
Nikita Titov committed
1731
        return self
1732

1733
1734
1735
1736
1737
1738
    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
1739
        machines : list, set or string
1740
            Names of machines.
Nikita Titov's avatar
Nikita Titov committed
1741
        local_listen_port : int, optional (default=12400)
1742
            TCP listen port for local machines.
Nikita Titov's avatar
Nikita Titov committed
1743
        listen_time_out : int, optional (default=120)
1744
            Socket time-out in minutes.
Nikita Titov's avatar
Nikita Titov committed
1745
        num_machines : int, optional (default=1)
1746
            The number of machines for parallel learning application.
Nikita Titov's avatar
Nikita Titov committed
1747
1748
1749
1750
1751

        Returns
        -------
        self : Booster
            Booster with set network.
1752
1753
1754
1755
1756
1757
        """
        _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
1758
        return self
1759
1760

    def free_network(self):
Nikita Titov's avatar
Nikita Titov committed
1761
1762
1763
1764
1765
1766
1767
        """Free Booster's network.

        Returns
        -------
        self : Booster
            Booster with freed network.
        """
1768
1769
        _safe_call(_LIB.LGBM_NetworkFree())
        self.network = False
Nikita Titov's avatar
Nikita Titov committed
1770
        return self
1771

wxchan's avatar
wxchan committed
1772
    def set_train_data_name(self, name):
1773
1774
1775
1776
        """Set the name to the training Dataset.

        Parameters
        ----------
Nikita Titov's avatar
Nikita Titov committed
1777
1778
1779
1780
1781
1782
1783
        name : string
            Name for the training Dataset.

        Returns
        -------
        self : Booster
            Booster with set training Dataset name.
1784
        """
wxchan's avatar
wxchan committed
1785
        self.__train_data_name = name
Nikita Titov's avatar
Nikita Titov committed
1786
        return self
wxchan's avatar
wxchan committed
1787
1788

    def add_valid(self, data, name):
1789
        """Add validation data.
wxchan's avatar
wxchan committed
1790
1791
1792
1793

        Parameters
        ----------
        data : Dataset
1794
1795
1796
            Validation data.
        name : string
            Name of validation data.
Nikita Titov's avatar
Nikita Titov committed
1797
1798
1799
1800
1801

        Returns
        -------
        self : Booster
            Booster with set validation data.
wxchan's avatar
wxchan committed
1802
        """
Guolin Ke's avatar
Guolin Ke committed
1803
        if not isinstance(data, Dataset):
1804
1805
            raise TypeError('Validation data should be Dataset instance, met {}'
                            .format(type(data).__name__))
Guolin Ke's avatar
Guolin Ke committed
1806
        if data._predictor is not self.__init_predictor:
1807
1808
            raise LightGBMError("Add validation data failed, "
                                "you should use same predictor for these data")
wxchan's avatar
wxchan committed
1809
1810
        _safe_call(_LIB.LGBM_BoosterAddValidData(
            self.handle,
wxchan's avatar
wxchan committed
1811
            data.construct().handle))
wxchan's avatar
wxchan committed
1812
1813
1814
1815
1816
        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
1817
        return self
wxchan's avatar
wxchan committed
1818
1819

    def reset_parameter(self, params):
1820
        """Reset parameters of Booster.
wxchan's avatar
wxchan committed
1821
1822
1823
1824

        Parameters
        ----------
        params : dict
1825
            New parameters for Booster.
Nikita Titov's avatar
Nikita Titov committed
1826
1827
1828
1829
1830

        Returns
        -------
        self : Booster
            Booster with new parameters.
wxchan's avatar
wxchan committed
1831
        """
1832
        if any(metric_alias in params for metric_alias in ('metric', 'metrics', 'metric_types')):
wxchan's avatar
wxchan committed
1833
1834
1835
1836
1837
1838
            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
1839
        self.params.update(params)
Nikita Titov's avatar
Nikita Titov committed
1840
        return self
wxchan's avatar
wxchan committed
1841
1842

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

wxchan's avatar
wxchan committed
1845
1846
        Parameters
        ----------
1847
1848
1849
1850
        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
1851
1852
            Customized objective function.

1853
1854
1855
1856
            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
1857
1858
        Returns
        -------
1859
1860
        is_finished : bool
            Whether the update was successfully finished.
wxchan's avatar
wxchan committed
1861
        """
1862
        # need reset training data
wxchan's avatar
wxchan committed
1863
        if train_set is not None and train_set is not self.train_set:
Guolin Ke's avatar
Guolin Ke committed
1864
            if not isinstance(train_set, Dataset):
1865
1866
                raise TypeError('Training data should be Dataset instance, met {}'
                                .format(type(train_set).__name__))
Guolin Ke's avatar
Guolin Ke committed
1867
            if train_set._predictor is not self.__init_predictor:
1868
1869
                raise LightGBMError("Replace training data failed, "
                                    "you should use same predictor for these data")
wxchan's avatar
wxchan committed
1870
1871
1872
            self.train_set = train_set
            _safe_call(_LIB.LGBM_BoosterResetTrainingData(
                self.handle,
wxchan's avatar
wxchan committed
1873
                self.train_set.construct().handle))
wxchan's avatar
wxchan committed
1874
1875
1876
            self.__inner_predict_buffer[0] = None
        is_finished = ctypes.c_int(0)
        if fobj is None:
1877
            if self.__set_objective_to_none:
1878
                raise LightGBMError('Cannot update due to null objective function.')
wxchan's avatar
wxchan committed
1879
1880
1881
            _safe_call(_LIB.LGBM_BoosterUpdateOneIter(
                self.handle,
                ctypes.byref(is_finished)))
wxchan's avatar
wxchan committed
1882
            self.__is_predicted_cur_iter = [False for _ in range_(self.__num_dataset)]
wxchan's avatar
wxchan committed
1883
1884
            return is_finished.value == 1
        else:
1885
            if not self.__set_objective_to_none:
Nikita Titov's avatar
Nikita Titov committed
1886
                self.reset_parameter({"objective": "none"}).__set_objective_to_none = True
wxchan's avatar
wxchan committed
1887
1888
1889
1890
            grad, hess = fobj(self.__inner_predict(0), self.train_set)
            return self.__boost(grad, hess)

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

1893
1894
1895
1896
1897
        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.
1898

wxchan's avatar
wxchan committed
1899
1900
        Parameters
        ----------
1901
        grad : 1-D numpy array or 1-D list
Nikita Titov's avatar
Nikita Titov committed
1902
            The first order derivative (gradient).
1903
        hess : 1-D numpy array or 1-D list
Nikita Titov's avatar
Nikita Titov committed
1904
            The second order derivative (Hessian).
wxchan's avatar
wxchan committed
1905
1906
1907

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1908
1909
        is_finished : bool
            Whether the boost was successfully finished.
wxchan's avatar
wxchan committed
1910
        """
1911
1912
        grad = list_to_1d_numpy(grad, name='gradient')
        hess = list_to_1d_numpy(hess, name='hessian')
1913
1914
        assert grad.flags.c_contiguous
        assert hess.flags.c_contiguous
wxchan's avatar
wxchan committed
1915
        if len(grad) != len(hess):
1916
1917
            raise ValueError("Lengths of gradient({}) and hessian({}) don't match"
                             .format(len(grad), len(hess)))
wxchan's avatar
wxchan committed
1918
1919
1920
1921
1922
1923
        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
1924
        self.__is_predicted_cur_iter = [False for _ in range_(self.__num_dataset)]
wxchan's avatar
wxchan committed
1925
1926
1927
        return is_finished.value == 1

    def rollback_one_iter(self):
Nikita Titov's avatar
Nikita Titov committed
1928
1929
1930
1931
1932
1933
1934
        """Rollback one iteration.

        Returns
        -------
        self : Booster
            Booster with rolled back one iteration.
        """
wxchan's avatar
wxchan committed
1935
1936
        _safe_call(_LIB.LGBM_BoosterRollbackOneIter(
            self.handle))
wxchan's avatar
wxchan committed
1937
        self.__is_predicted_cur_iter = [False for _ in range_(self.__num_dataset)]
Nikita Titov's avatar
Nikita Titov committed
1938
        return self
wxchan's avatar
wxchan committed
1939
1940

    def current_iteration(self):
1941
1942
1943
1944
1945
1946
1947
        """Get the index of the current iteration.

        Returns
        -------
        cur_iter : int
            The index of the current iteration.
        """
Guolin Ke's avatar
Guolin Ke committed
1948
        out_cur_iter = ctypes.c_int(0)
wxchan's avatar
wxchan committed
1949
1950
1951
1952
1953
        _safe_call(_LIB.LGBM_BoosterGetCurrentIteration(
            self.handle,
            ctypes.byref(out_cur_iter)))
        return out_cur_iter.value

1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
    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
1982
    def eval(self, data, name, feval=None):
1983
        """Evaluate for data.
wxchan's avatar
wxchan committed
1984
1985
1986

        Parameters
        ----------
1987
1988
1989
1990
1991
        data : Dataset
            Data for the evaluating.
        name : string
            Name of the data.
        feval : callable or None, optional (default=None)
1992
            Customized evaluation function.
1993
1994
            Should accept two parameters: preds, train_data,
            and return (eval_name, eval_result, is_higher_better) or list of such tuples.
1995
1996
            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].
1997

wxchan's avatar
wxchan committed
1998
1999
        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
2000
        result : list
2001
            List with evaluation results.
wxchan's avatar
wxchan committed
2002
        """
Guolin Ke's avatar
Guolin Ke committed
2003
2004
        if not isinstance(data, Dataset):
            raise TypeError("Can only eval for Dataset instance")
wxchan's avatar
wxchan committed
2005
2006
2007
2008
        data_idx = -1
        if data is self.train_set:
            data_idx = 0
        else:
wxchan's avatar
wxchan committed
2009
            for i in range_(len(self.valid_sets)):
wxchan's avatar
wxchan committed
2010
2011
2012
                if data is self.valid_sets[i]:
                    data_idx = i + 1
                    break
2013
        # need to push new valid data
wxchan's avatar
wxchan committed
2014
2015
2016
2017
2018
2019
2020
        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):
2021
        """Evaluate for training data.
wxchan's avatar
wxchan committed
2022
2023
2024

        Parameters
        ----------
2025
        feval : callable or None, optional (default=None)
2026
            Customized evaluation function.
2027
2028
            Should accept two parameters: preds, train_data,
            and return (eval_name, eval_result, is_higher_better) or list of such tuples.
2029
2030
            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
2031
2032
2033

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
2034
        result : list
2035
            List with evaluation results.
wxchan's avatar
wxchan committed
2036
2037
2038
2039
        """
        return self.__inner_eval(self.__train_data_name, 0, feval)

    def eval_valid(self, feval=None):
2040
        """Evaluate for validation data.
wxchan's avatar
wxchan committed
2041
2042
2043

        Parameters
        ----------
2044
        feval : callable or None, optional (default=None)
2045
            Customized evaluation function.
2046
2047
            Should accept two parameters: preds, train_data,
            and return (eval_name, eval_result, is_higher_better) or list of such tuples.
2048
2049
            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
2050
2051
2052

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
2053
        result : list
2054
            List with evaluation results.
wxchan's avatar
wxchan committed
2055
        """
wxchan's avatar
wxchan committed
2056
        return [item for i in range_(1, self.__num_dataset)
wxchan's avatar
wxchan committed
2057
                for item in self.__inner_eval(self.name_valid_sets[i - 1], i, feval)]
wxchan's avatar
wxchan committed
2058

2059
    def save_model(self, filename, num_iteration=None, start_iteration=0):
2060
        """Save Booster to file.
wxchan's avatar
wxchan committed
2061
2062
2063

        Parameters
        ----------
2064
2065
        filename : string
            Filename to save Booster.
2066
2067
2068
2069
        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
2070
        start_iteration : int, optional (default=0)
2071
            Start index of the iteration that should be saved.
Nikita Titov's avatar
Nikita Titov committed
2072
2073
2074
2075
2076

        Returns
        -------
        self : Booster
            Returns self.
wxchan's avatar
wxchan committed
2077
        """
2078
        if num_iteration is None:
2079
            num_iteration = self.best_iteration
wxchan's avatar
wxchan committed
2080
2081
        _safe_call(_LIB.LGBM_BoosterSaveModel(
            self.handle,
2082
            ctypes.c_int(start_iteration),
Guolin Ke's avatar
Guolin Ke committed
2083
            ctypes.c_int(num_iteration),
wxchan's avatar
wxchan committed
2084
            c_str(filename)))
2085
        _dump_pandas_categorical(self.pandas_categorical, filename)
Nikita Titov's avatar
Nikita Titov committed
2086
        return self
wxchan's avatar
wxchan committed
2087

2088
    def shuffle_models(self, start_iteration=0, end_iteration=-1):
2089
        """Shuffle models.
Nikita Titov's avatar
Nikita Titov committed
2090

2091
2092
2093
        Parameters
        ----------
        start_iteration : int, optional (default=0)
2094
            The first iteration that will be shuffled.
2095
2096
        end_iteration : int, optional (default=-1)
            The last iteration that will be shuffled.
2097
            If <= 0, means the last available iteration.
2098

Nikita Titov's avatar
Nikita Titov committed
2099
2100
2101
2102
        Returns
        -------
        self : Booster
            Booster with shuffled models.
2103
        """
2104
2105
        _safe_call(_LIB.LGBM_BoosterShuffleModels(
            self.handle,
Guolin Ke's avatar
Guolin Ke committed
2106
2107
            ctypes.c_int(start_iteration),
            ctypes.c_int(end_iteration)))
Nikita Titov's avatar
Nikita Titov committed
2108
        return self
2109
2110
2111
2112
2113
2114

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

        Parameters
        ----------
Nikita Titov's avatar
Nikita Titov committed
2115
        model_str : string
2116
            Model will be loaded from this string.
Nikita Titov's avatar
Nikita Titov committed
2117
2118
        verbose : bool, optional (default=True)
            Whether to print messages while loading model.
2119
2120
2121

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
2122
        self : Booster
2123
2124
            Loaded Booster object.
        """
2125
2126
2127
2128
        if self.handle is not None:
            _safe_call(_LIB.LGBM_BoosterFree(self.handle))
        self._free_buffer()
        self.handle = ctypes.c_void_p()
2129
2130
2131
2132
2133
2134
2135
2136
2137
        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)))
2138
        if verbose:
Nikita Titov's avatar
Nikita Titov committed
2139
            print('Finished loading model, total used %d iterations' % int(out_num_iterations.value))
2140
        self.__num_class = out_num_class.value
2141
        self.pandas_categorical = _load_pandas_categorical(model_str=model_str)
2142
2143
2144
2145
        return self

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

2147
2148
2149
2150
2151
2152
        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
2153
        start_iteration : int, optional (default=0)
2154
2155
2156
2157
            Start index of the iteration that should be saved.

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
2158
        str_repr : string
2159
2160
            String representation of Booster.
        """
2161
        if num_iteration is None:
2162
2163
            num_iteration = self.best_iteration
        buffer_len = 1 << 20
2164
        tmp_out_len = ctypes.c_int64(0)
2165
2166
2167
2168
        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,
2169
            ctypes.c_int(start_iteration),
2170
            ctypes.c_int(num_iteration),
2171
            ctypes.c_int64(buffer_len),
2172
2173
2174
            ctypes.byref(tmp_out_len),
            ptr_string_buffer))
        actual_len = tmp_out_len.value
2175
        # if buffer length is not long enough, re-allocate a buffer
2176
2177
2178
2179
2180
        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,
2181
                ctypes.c_int(start_iteration),
2182
                ctypes.c_int(num_iteration),
2183
                ctypes.c_int64(actual_len),
2184
2185
                ctypes.byref(tmp_out_len),
                ptr_string_buffer))
2186
2187
2188
        ret = string_buffer.value.decode()
        ret += _dump_pandas_categorical(self.pandas_categorical)
        return ret
2189

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

2193
2194
        Parameters
        ----------
2195
2196
2197
2198
        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
2199
        start_iteration : int, optional (default=0)
2200
            Start index of the iteration that should be dumped.
2201

wxchan's avatar
wxchan committed
2202
2203
        Returns
        -------
2204
        json_repr : dict
Nikita Titov's avatar
Nikita Titov committed
2205
            JSON format of Booster.
wxchan's avatar
wxchan committed
2206
        """
2207
        if num_iteration is None:
2208
            num_iteration = self.best_iteration
wxchan's avatar
wxchan committed
2209
        buffer_len = 1 << 20
2210
        tmp_out_len = ctypes.c_int64(0)
wxchan's avatar
wxchan committed
2211
2212
2213
2214
        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,
2215
            ctypes.c_int(start_iteration),
Guolin Ke's avatar
Guolin Ke committed
2216
            ctypes.c_int(num_iteration),
2217
            ctypes.c_int64(buffer_len),
wxchan's avatar
wxchan committed
2218
            ctypes.byref(tmp_out_len),
Guolin Ke's avatar
Guolin Ke committed
2219
            ptr_string_buffer))
wxchan's avatar
wxchan committed
2220
        actual_len = tmp_out_len.value
2221
        # if buffer length is not long enough, reallocate a buffer
wxchan's avatar
wxchan committed
2222
2223
2224
2225
2226
        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,
2227
                ctypes.c_int(start_iteration),
Guolin Ke's avatar
Guolin Ke committed
2228
                ctypes.c_int(num_iteration),
2229
                ctypes.c_int64(actual_len),
wxchan's avatar
wxchan committed
2230
                ctypes.byref(tmp_out_len),
Guolin Ke's avatar
Guolin Ke committed
2231
                ptr_string_buffer))
2232
2233
2234
2235
        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
2236

2237
2238
    def predict(self, data, num_iteration=None,
                raw_score=False, pred_leaf=False, pred_contrib=False,
2239
                data_has_header=False, is_reshape=True, **kwargs):
2240
        """Make a prediction.
wxchan's avatar
wxchan committed
2241
2242
2243

        Parameters
        ----------
2244
        data : string, numpy array, pandas DataFrame, H2O DataTable's Frame or scipy.sparse
2245
2246
            Data source for prediction.
            If string, it represents the path to txt file.
2247
2248
2249
2250
        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).
2251
2252
2253
2254
        raw_score : bool, optional (default=False)
            Whether to predict raw scores.
        pred_leaf : bool, optional (default=False)
            Whether to predict leaf index.
2255
2256
        pred_contrib : bool, optional (default=False)
            Whether to predict feature contributions.
2257
2258
2259
2260
2261
2262
2263

            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).

2264
2265
2266
2267
2268
        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].
2269
2270
        **kwargs
            Other parameters for the prediction.
wxchan's avatar
wxchan committed
2271
2272
2273

        Returns
        -------
2274
2275
        result : numpy array
            Prediction result.
wxchan's avatar
wxchan committed
2276
        """
2277
        predictor = self._to_predictor(copy.deepcopy(kwargs))
2278
        if num_iteration is None:
2279
            num_iteration = self.best_iteration
2280
2281
2282
        return predictor.predict(data, num_iteration,
                                 raw_score, pred_leaf, pred_contrib,
                                 data_has_header, is_reshape)
wxchan's avatar
wxchan committed
2283

2284
    def refit(self, data, label, decay_rate=0.9, **kwargs):
Guolin Ke's avatar
Guolin Ke committed
2285
2286
2287
2288
        """Refit the existing Booster by new data.

        Parameters
        ----------
2289
        data : string, numpy array, pandas DataFrame, H2O DataTable's Frame or scipy.sparse
Guolin Ke's avatar
Guolin Ke committed
2290
2291
            Data source for refit.
            If string, it represents the path to txt file.
2292
        label : list, numpy 1-D array or pandas Series / one-column DataFrame
Guolin Ke's avatar
Guolin Ke committed
2293
2294
            Label for refit.
        decay_rate : float, optional (default=0.9)
2295
2296
            Decay rate of refit,
            will use ``leaf_output = decay_rate * old_leaf_output + (1.0 - decay_rate) * new_leaf_output`` to refit trees.
2297
2298
        **kwargs
            Other parameters for refit.
2299
            These parameters will be passed to ``predict`` method.
Guolin Ke's avatar
Guolin Ke committed
2300
2301
2302
2303
2304
2305

        Returns
        -------
        result : Booster
            Refitted Booster.
        """
2306
2307
        if self.__set_objective_to_none:
            raise LightGBMError('Cannot refit due to null objective function.')
2308
        predictor = self._to_predictor(copy.deepcopy(kwargs))
2309
        leaf_preds = predictor.predict(data, -1, pred_leaf=True)
2310
        nrow, ncol = leaf_preds.shape
2311
        train_set = Dataset(data, label, silent=True)
Guolin Ke's avatar
Guolin Ke committed
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
        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)))
2324
2325
        new_booster.network = self.network
        new_booster.__attr = self.__attr.copy()
Guolin Ke's avatar
Guolin Ke committed
2326
2327
        return new_booster

2328
    def get_leaf_output(self, tree_id, leaf_id):
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
        """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.
        """
2343
2344
2345
2346
2347
2348
2349
2350
        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

2351
    def _to_predictor(self, pred_parameter=None):
2352
        """Convert to predictor."""
2353
        predictor = _InnerPredictor(booster_handle=self.handle, pred_parameter=pred_parameter)
2354
        predictor.pandas_categorical = self.pandas_categorical
wxchan's avatar
wxchan committed
2355
2356
        return predictor

2357
    def num_feature(self):
2358
2359
2360
2361
2362
2363
2364
        """Get number of features.

        Returns
        -------
        num_feature : int
            The number of features.
        """
2365
2366
2367
2368
2369
2370
        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
2371
    def feature_name(self):
2372
        """Get names of features.
wxchan's avatar
wxchan committed
2373
2374
2375

        Returns
        -------
2376
2377
        result : list
            List with names of features.
wxchan's avatar
wxchan committed
2378
        """
2379
        num_feature = self.num_feature()
2380
        # Get name of features
wxchan's avatar
wxchan committed
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
        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)]

2392
    def feature_importance(self, importance_type='split', iteration=None):
2393
        """Get feature importances.
2394

2395
2396
        Parameters
        ----------
2397
2398
2399
2400
        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.
2401
2402
2403
2404
        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).
2405

2406
2407
        Returns
        -------
2408
2409
        result : numpy array
            Array with feature importances.
2410
        """
2411
2412
        if iteration is None:
            iteration = self.best_iteration
2413
2414
2415
2416
2417
2418
        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
2419
        result = np.zeros(self.num_feature(), dtype=np.float64)
2420
2421
2422
2423
2424
2425
2426
2427
2428
        _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
2429

wxchan's avatar
wxchan committed
2430
    def __inner_eval(self, data_name, data_idx, feval=None):
2431
        """Evaluate training or validation data."""
wxchan's avatar
wxchan committed
2432
        if data_idx >= self.__num_dataset:
2433
            raise ValueError("Data_idx should be smaller than number of dataset")
wxchan's avatar
wxchan committed
2434
2435
2436
        self.__get_eval_info()
        ret = []
        if self.__num_inner_eval > 0:
2437
            result = np.zeros(self.__num_inner_eval, dtype=np.float64)
Guolin Ke's avatar
Guolin Ke committed
2438
            tmp_out_len = ctypes.c_int(0)
wxchan's avatar
wxchan committed
2439
2440
            _safe_call(_LIB.LGBM_BoosterGetEval(
                self.handle,
Guolin Ke's avatar
Guolin Ke committed
2441
                ctypes.c_int(data_idx),
wxchan's avatar
wxchan committed
2442
                ctypes.byref(tmp_out_len),
Guolin Ke's avatar
Guolin Ke committed
2443
                result.ctypes.data_as(ctypes.POINTER(ctypes.c_double))))
wxchan's avatar
wxchan committed
2444
            if tmp_out_len.value != self.__num_inner_eval:
2445
                raise ValueError("Wrong length of eval results")
wxchan's avatar
wxchan committed
2446
            for i in range_(self.__num_inner_eval):
2447
2448
                ret.append((data_name, self.__name_inner_eval[i],
                            result[i], self.__higher_better_inner_eval[i]))
wxchan's avatar
wxchan committed
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
        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):
2464
        """Predict for training and validation dataset."""
wxchan's avatar
wxchan committed
2465
        if data_idx >= self.__num_dataset:
2466
            raise ValueError("Data_idx should be smaller than number of dataset")
wxchan's avatar
wxchan committed
2467
2468
2469
2470
2471
        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
2472
            self.__inner_predict_buffer[data_idx] = np.zeros(n_preds, dtype=np.float64)
2473
        # avoid to predict many time in one iteration
wxchan's avatar
wxchan committed
2474
2475
        if not self.__is_predicted_cur_iter[data_idx]:
            tmp_out_len = ctypes.c_int64(0)
Guolin Ke's avatar
Guolin Ke committed
2476
            data_ptr = self.__inner_predict_buffer[data_idx].ctypes.data_as(ctypes.POINTER(ctypes.c_double))
wxchan's avatar
wxchan committed
2477
2478
            _safe_call(_LIB.LGBM_BoosterGetPredict(
                self.handle,
Guolin Ke's avatar
Guolin Ke committed
2479
                ctypes.c_int(data_idx),
wxchan's avatar
wxchan committed
2480
2481
2482
                ctypes.byref(tmp_out_len),
                data_ptr))
            if tmp_out_len.value != len(self.__inner_predict_buffer[data_idx]):
2483
                raise ValueError("Wrong length of predict results for data %d" % (data_idx))
wxchan's avatar
wxchan committed
2484
2485
2486
2487
            self.__is_predicted_cur_iter[data_idx] = True
        return self.__inner_predict_buffer[data_idx]

    def __get_eval_info(self):
2488
        """Get inner evaluation count and names."""
wxchan's avatar
wxchan committed
2489
2490
        if self.__need_reload_eval_info:
            self.__need_reload_eval_info = False
Guolin Ke's avatar
Guolin Ke committed
2491
            out_num_eval = ctypes.c_int(0)
2492
            # Get num of inner evals
wxchan's avatar
wxchan committed
2493
2494
2495
2496
2497
            _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:
2498
                # Get name of evals
Guolin Ke's avatar
Guolin Ke committed
2499
                tmp_out_len = ctypes.c_int(0)
wxchan's avatar
wxchan committed
2500
                string_buffers = [ctypes.create_string_buffer(255) for i in range_(self.__num_inner_eval)]
wxchan's avatar
wxchan committed
2501
                ptr_string_buffers = (ctypes.c_char_p * self.__num_inner_eval)(*map(ctypes.addressof, string_buffers))
wxchan's avatar
wxchan committed
2502
2503
2504
2505
2506
                _safe_call(_LIB.LGBM_BoosterGetEvalNames(
                    self.handle,
                    ctypes.byref(tmp_out_len),
                    ptr_string_buffers))
                if self.__num_inner_eval != tmp_out_len.value:
2507
                    raise ValueError("Length of eval names doesn't equal with num_evals")
2508
                self.__name_inner_eval = \
wxchan's avatar
wxchan committed
2509
                    [string_buffers[i].value.decode() for i in range_(self.__num_inner_eval)]
2510
                self.__higher_better_inner_eval = \
2511
                    [name.startswith(('auc', 'ndcg@', 'map@')) for name in self.__name_inner_eval]
2512

wxchan's avatar
wxchan committed
2513
    def attr(self, key):
2514
        """Get attribute string from the Booster.
wxchan's avatar
wxchan committed
2515
2516
2517

        Parameters
        ----------
2518
2519
        key : string
            The name of the attribute.
wxchan's avatar
wxchan committed
2520
2521
2522

        Returns
        -------
2523
2524
        value : string or None
            The attribute value.
Nikita Titov's avatar
Nikita Titov committed
2525
            Returns None if attribute does not exist.
wxchan's avatar
wxchan committed
2526
        """
2527
        return self.__attr.get(key, None)
wxchan's avatar
wxchan committed
2528
2529

    def set_attr(self, **kwargs):
2530
        """Set attributes to the Booster.
wxchan's avatar
wxchan committed
2531
2532
2533
2534

        Parameters
        ----------
        **kwargs
2535
2536
            The attributes to set.
            Setting a value to None deletes an attribute.
Nikita Titov's avatar
Nikita Titov committed
2537
2538
2539
2540

        Returns
        -------
        self : Booster
2541
            Booster with set attributes.
wxchan's avatar
wxchan committed
2542
2543
2544
        """
        for key, value in kwargs.items():
            if value is not None:
wxchan's avatar
wxchan committed
2545
                if not isinstance(value, string_type):
Nikita Titov's avatar
Nikita Titov committed
2546
                    raise ValueError("Only string values are accepted")
wxchan's avatar
wxchan committed
2547
2548
2549
                self.__attr[key] = value
            else:
                self.__attr.pop(key, None)
Nikita Titov's avatar
Nikita Titov committed
2550
        return self