basic.py 106 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 (PANDAS_INSTALLED, DataFrame, Series, is_dtype_sparse,
17
                     DataTable,
18
19
                     decode_string, string_type,
                     integer_types, numeric_types,
20
                     json, json_default_with_numpy,
21
                     range_, zip_)
wxchan's avatar
wxchan committed
22
23
from .libpath import find_lib_path

wxchan's avatar
wxchan committed
24

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

wxchan's avatar
wxchan committed
34

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

wxchan's avatar
wxchan committed
37

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

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

wxchan's avatar
wxchan committed
49

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

wxchan's avatar
wxchan committed
60

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

wxchan's avatar
wxchan committed
65

wxchan's avatar
wxchan committed
66
def is_1d_list(data):
67
68
    """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
69

wxchan's avatar
wxchan committed
70

71
def list_to_1d_numpy(data, dtype=np.float32, name='list'):
72
    """Convert data to numpy 1-D array."""
wxchan's avatar
wxchan committed
73
74
75
76
77
78
79
    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)
80
    elif isinstance(data, Series):
81
82
83
84
85
86
        if _get_bad_pandas_dtypes([data.dtypes]):
            raise ValueError('Series.dtypes must be int, float or bool')
        if hasattr(data.values, 'values'):  # SparseArray
            return data.values.values.astype(dtype)
        else:
            return data.values.astype(dtype)
wxchan's avatar
wxchan committed
87
    else:
88
89
        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
90

wxchan's avatar
wxchan committed
91

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

Guolin Ke's avatar
Guolin Ke committed
99

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

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

wxchan's avatar
wxchan committed
115

116
117
118
119
120
121
122
123
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
124
def c_str(string):
125
    """Convert a Python string to C string."""
wxchan's avatar
wxchan committed
126
127
    return ctypes.c_char_p(string.encode('utf-8'))

wxchan's avatar
wxchan committed
128

wxchan's avatar
wxchan committed
129
def c_array(ctype, values):
130
    """Convert a Python array to C array."""
wxchan's avatar
wxchan committed
131
132
    return (ctype * len(values))(*values)

wxchan's avatar
wxchan committed
133

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

wxchan's avatar
wxchan committed
149

150
class _TempFile(object):
151
152
153
154
    def __enter__(self):
        with NamedTemporaryFile(prefix="lightgbm_tmp_", delete=True) as f:
            self.name = f.name
        return self
wxchan's avatar
wxchan committed
155

156
157
158
    def __exit__(self, exc_type, exc_val, exc_tb):
        if os.path.isfile(self.name):
            os.remove(self.name)
wxchan's avatar
wxchan committed
159

160
161
162
163
    def readlines(self):
        with open(self.name, "r+") as f:
            ret = f.readlines()
        return ret
wxchan's avatar
wxchan committed
164

165
166
    def writelines(self, lines):
        with open(self.name, "w+") as f:
167
            f.writelines(lines)
168

wxchan's avatar
wxchan committed
169

170
class LightGBMError(Exception):
171
172
    """Error thrown by LightGBM."""

173
174
175
176
177
    pass


MAX_INT32 = (1 << 31) - 1

178
"""Macro definition of data type in C API of LightGBM"""
wxchan's avatar
wxchan committed
179
180
181
182
C_API_DTYPE_FLOAT32 = 0
C_API_DTYPE_FLOAT64 = 1
C_API_DTYPE_INT32 = 2
C_API_DTYPE_INT64 = 3
183
C_API_DTYPE_INT8 = 4
Guolin Ke's avatar
Guolin Ke committed
184

185
"""Matrix is row major in Python"""
wxchan's avatar
wxchan committed
186
187
C_API_IS_ROW_MAJOR = 1

188
"""Macro definition of prediction type in C API of LightGBM"""
wxchan's avatar
wxchan committed
189
190
191
C_API_PREDICT_NORMAL = 0
C_API_PREDICT_RAW_SCORE = 1
C_API_PREDICT_LEAF_INDEX = 2
192
C_API_PREDICT_CONTRIB = 3
wxchan's avatar
wxchan committed
193

194
"""Data type of data field"""
wxchan's avatar
wxchan committed
195
196
FIELD_TYPE_MAPPER = {"label": C_API_DTYPE_FLOAT32,
                     "weight": C_API_DTYPE_FLOAT32,
Guolin Ke's avatar
Guolin Ke committed
197
                     "init_score": C_API_DTYPE_FLOAT64,
198
199
200
                     "group": C_API_DTYPE_INT32,
                     "feature_penalty": C_API_DTYPE_FLOAT64,
                     "monotone_constraints": C_API_DTYPE_INT8}
wxchan's avatar
wxchan committed
201

wxchan's avatar
wxchan committed
202

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


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

wxchan's avatar
wxchan committed
233

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

wxchan's avatar
wxchan committed
254

255
256
257
258
259
260
261
262
263
264
265
def _get_bad_pandas_dtypes(dtypes):
    pandas_dtype_mapper = {'int8': 'int', 'int16': 'int', 'int32': 'int',
                           'int64': 'int', 'uint8': 'int', 'uint16': 'int',
                           'uint32': 'int', 'uint64': 'int', 'bool': 'int',
                           'float16': 'float', 'float32': 'float', 'float64': 'float'}
    bad_indices = [i for i, dtype in enumerate(dtypes) if (dtype.name not in pandas_dtype_mapper
                                                           and (not is_dtype_sparse(dtype)
                                                                or dtype.subtype.name not in pandas_dtype_mapper))]
    return bad_indices


266
def _data_from_pandas(data, feature_name, categorical_feature, pandas_categorical):
267
    if isinstance(data, DataFrame):
268
269
        if len(data.shape) != 2 or data.shape[0] < 1:
            raise ValueError('Input data must be 2 dimensional and non empty.')
270
271
        if feature_name == 'auto' or feature_name is None:
            data = data.rename(columns=str)
272
273
        cat_cols = list(data.select_dtypes(include=['category']).columns)
        cat_cols_not_ordered = [col for col in cat_cols if not data[col].cat.ordered]
274
275
276
277
278
        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.')
279
            for col, category in zip_(cat_cols, pandas_categorical):
280
281
                if list(data[col].cat.categories) != list(category):
                    data[col] = data[col].cat.set_categories(category)
282
        if len(cat_cols):  # cat_cols is list
283
            data = data.copy()  # not alter origin DataFrame
284
            data[cat_cols] = data[cat_cols].apply(lambda x: x.cat.codes).replace({-1: np.nan})
285
286
287
        if categorical_feature is not None:
            if feature_name is None:
                feature_name = list(data.columns)
288
            if categorical_feature == 'auto':  # use cat cols from DataFrame
289
                categorical_feature = cat_cols_not_ordered
290
291
            else:  # use cat cols specified by user
                categorical_feature = list(categorical_feature)
292
293
        if feature_name == 'auto':
            feature_name = list(data.columns)
294
295
        bad_indices = _get_bad_pandas_dtypes(data.dtypes)
        if bad_indices:
296
            raise ValueError("DataFrame.dtypes for data must be int, float or bool.\n"
297
                             "Did not expect the data types in the following fields: "
298
                             + ', '.join(data.columns[bad_indices]))
299
        data = data.values.astype('float')
300
301
302
303
304
305
    else:
        if feature_name == 'auto':
            feature_name = None
        if categorical_feature == 'auto':
            categorical_feature = None
    return data, feature_name, categorical_feature, pandas_categorical
306
307
308
309
310
311


def _label_from_pandas(label):
    if isinstance(label, DataFrame):
        if len(label.columns) > 1:
            raise ValueError('DataFrame for label cannot have multiple columns')
312
        if _get_bad_pandas_dtypes(label.dtypes):
313
            raise ValueError('DataFrame.dtypes for label must be int, float or bool')
314
        label = label.values.astype('float').flatten()
315
316
317
    return label


318
319
320
321
322
323
324
325
326
327
328
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):
329
330
    pandas_key = 'pandas_categorical:'
    offset = -len(pandas_key)
331
    if file_name is not None:
332
333
334
335
336
337
338
339
340
341
342
343
344
        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()
345
    elif model_str is not None:
346
347
348
349
350
351
        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
352
353


Guolin Ke's avatar
Guolin Ke committed
354
class _InnerPredictor(object):
355
356
357
358
359
360
361
362
    """_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
363
    """
364

365
    def __init__(self, model_file=None, booster_handle=None, pred_parameter=None):
366
        """Initialize the _InnerPredictor.
wxchan's avatar
wxchan committed
367
368
369

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

410
411
        pred_parameter = {} if pred_parameter is None else pred_parameter
        self.pred_parameter = param_dict_to_str(pred_parameter)
cbecker's avatar
cbecker committed
412

wxchan's avatar
wxchan committed
413
    def __del__(self):
414
415
416
417
418
        try:
            if self.__is_manage_handle:
                _safe_call(_LIB.LGBM_BoosterFree(self.handle))
        except AttributeError:
            pass
wxchan's avatar
wxchan committed
419

420
421
422
423
424
    def __getstate__(self):
        this = self.__dict__.copy()
        this.pop('handle', None)
        return this

wxchan's avatar
wxchan committed
425
    def predict(self, data, num_iteration=-1,
426
                raw_score=False, pred_leaf=False, pred_contrib=False, data_has_header=False,
wxchan's avatar
wxchan committed
427
                is_reshape=True):
428
        """Predict logic.
wxchan's avatar
wxchan committed
429
430
431

        Parameters
        ----------
432
        data : string, numpy array, pandas DataFrame, H2O DataTable's Frame or scipy.sparse
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
            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
448
449
450

        Returns
        -------
451
452
        result : numpy array
            Prediction result.
wxchan's avatar
wxchan committed
453
        """
wxchan's avatar
wxchan committed
454
        if isinstance(data, Dataset):
455
            raise TypeError("Cannot use Dataset instance for prediction, please use raw data instead")
456
        data = _data_from_pandas(data, None, None, self.pandas_categorical)[0]
wxchan's avatar
wxchan committed
457
458
459
460
461
        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
462
463
        if pred_contrib:
            predict_type = C_API_PREDICT_CONTRIB
wxchan's avatar
wxchan committed
464
        int_data_has_header = 1 if data_has_header else 0
465
466
        if num_iteration > self.num_total_iteration:
            num_iteration = self.num_total_iteration
cbecker's avatar
cbecker committed
467

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

    def __get_num_preds(self, num_iteration, nrow, predict_type):
514
        """Get size of prediction result."""
515
516
517
518
519
        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
520
521
522
        n_preds = ctypes.c_int64(0)
        _safe_call(_LIB.LGBM_BoosterCalcNumPredict(
            self.handle,
Guolin Ke's avatar
Guolin Ke committed
523
524
525
            ctypes.c_int(nrow),
            ctypes.c_int(predict_type),
            ctypes.c_int(num_iteration),
Guolin Ke's avatar
Guolin Ke committed
526
527
            ctypes.byref(n_preds)))
        return n_preds.value
wxchan's avatar
wxchan committed
528
529

    def __pred_for_np2d(self, mat, num_iteration, predict_type):
530
        """Predict for a 2-D numpy matrix."""
wxchan's avatar
wxchan committed
531
        if len(mat.shape) != 2:
532
            raise ValueError('Input numpy.ndarray or list must be 2 dimensional')
wxchan's avatar
wxchan committed
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
561
562
563
564
565
566
567
568
569
        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)
570
571
            for chunk, (start_idx_pred, end_idx_pred) in zip_(np.array_split(mat, sections),
                                                              zip_(n_preds_sections, n_preds_sections[1:])):
572
573
574
                # 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
575
        else:
576
            return inner_predict(mat, num_iteration, predict_type)
wxchan's avatar
wxchan committed
577
578

    def __pred_for_csr(self, csr, num_iteration, predict_type):
579
        """Predict for a CSR data."""
580
581
582
583
584
585
586
587
588
589
590
591
        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)

592
593
594
            assert csr.shape[1] <= MAX_INT32
            csr.indices = csr.indices.astype(np.int32, copy=False)

595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
            _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
613

614
615
616
617
618
619
620
621
622
623
624
625
626
627
        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
628
629

    def __pred_for_csc(self, csc, num_iteration, predict_type):
630
        """Predict for a CSC data."""
Guolin Ke's avatar
Guolin Ke committed
631
        nrow = csc.shape[0]
632
633
        if nrow > MAX_INT32:
            return self.__pred_for_csr(csc.tocsr(), num_iteration, predict_type)
Guolin Ke's avatar
Guolin Ke committed
634
635
636
637
        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)

638
639
        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
640

641
642
643
        assert csc.shape[0] <= MAX_INT32
        csc.indices = csc.indices.astype(np.int32, copy=False)

Guolin Ke's avatar
Guolin Ke committed
644
645
646
        _safe_call(_LIB.LGBM_BoosterPredictForCSC(
            self.handle,
            ptr_indptr,
Guolin Ke's avatar
Guolin Ke committed
647
            ctypes.c_int32(type_ptr_indptr),
Guolin Ke's avatar
Guolin Ke committed
648
649
            csc.indices.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)),
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
650
651
652
653
654
655
            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),
656
            c_str(self.pred_parameter),
Guolin Ke's avatar
Guolin Ke committed
657
            ctypes.byref(out_num_preds),
wxchan's avatar
wxchan committed
658
            preds.ctypes.data_as(ctypes.POINTER(ctypes.c_double))))
wxchan's avatar
wxchan committed
659
        if n_preds != out_num_preds.value:
660
            raise ValueError("Wrong length for predict results")
wxchan's avatar
wxchan committed
661
662
        return preds, nrow

wxchan's avatar
wxchan committed
663

wxchan's avatar
wxchan committed
664
665
class Dataset(object):
    """Dataset in LightGBM."""
666

667
    def __init__(self, data, label=None, reference=None,
668
                 weight=None, group=None, init_score=None, silent=False,
669
                 feature_name='auto', categorical_feature='auto', params=None,
wxchan's avatar
wxchan committed
670
                 free_raw_data=True):
671
        """Initialize Dataset.
672

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

    def __del__(self):
728
729
730
731
        try:
            self._free_handle()
        except AttributeError:
            pass
732
733

    def _free_handle(self):
734
        if self.handle is not None:
735
            _safe_call(_LIB.LGBM_DatasetFree(self.handle))
736
            self.handle = None
Guolin Ke's avatar
Guolin Ke committed
737
738
739
        self.need_slice = True
        if self.used_indices is not None:
            self.data = None
Nikita Titov's avatar
Nikita Titov committed
740
        return self
wxchan's avatar
wxchan committed
741

Guolin Ke's avatar
Guolin Ke committed
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
    def _set_init_score_by_predictor(self, predictor, data, used_indices=None):
        data_has_header = False
        if isinstance(data, string_type):
            # check data has header or not
            if self.params.get("has_header", False) or self.params.get("header", False):
                data_has_header = True
        init_score = predictor.predict(data,
                                       raw_score=True,
                                       data_has_header=data_has_header,
                                       is_reshape=False)
        num_data = self.num_data()
        if used_indices is not None:
            assert not self.need_slice
            if isinstance(data, string_type):
                sub_init_score = np.zeros(num_data * predictor.num_class, dtype=np.float32)
                assert num_data == len(used_indices)
                for i in range_(len(used_indices)):
                    for j in range_(predictor.num_class):
                        sub_init_score[i * redictor.num_class + j] = init_score[used_indices[i] * redictor.num_class + j]
                init_score = sub_init_score
        if predictor.num_class > 1:
            # need to regroup init_score
            new_init_score = np.zeros(init_score.size, dtype=np.float32)
            for i in range_(num_data):
                for j in range_(predictor.num_class):
                    new_init_score[j * num_data + i] = init_score[i * predictor.num_class + j]
            init_score = new_init_score
        self.set_init_score(init_score)

771
    def _lazy_init(self, data, label=None, reference=None,
772
                   weight=None, group=None, init_score=None, predictor=None,
wxchan's avatar
wxchan committed
773
                   silent=False, feature_name='auto',
774
                   categorical_feature='auto', params=None):
wxchan's avatar
wxchan committed
775
776
        if data is None:
            self.handle = None
Nikita Titov's avatar
Nikita Titov committed
777
            return self
Guolin Ke's avatar
Guolin Ke committed
778
779
780
        if reference is not None:
            self.pandas_categorical = reference.pandas_categorical
            categorical_feature = reference.categorical_feature
781
782
783
784
        data, feature_name, categorical_feature, self.pandas_categorical = _data_from_pandas(data,
                                                                                             feature_name,
                                                                                             categorical_feature,
                                                                                             self.pandas_categorical)
wxchan's avatar
wxchan committed
785
        label = _label_from_pandas(label)
Guolin Ke's avatar
Guolin Ke committed
786

787
        # process for args
wxchan's avatar
wxchan committed
788
        params = {} if params is None else params
789
790
791
        args_names = (getattr(self.__class__, '_lazy_init')
                      .__code__
                      .co_varnames[:getattr(self.__class__, '_lazy_init').__code__.co_argcount])
792
793
        for key, _ in params.items():
            if key in args_names:
794
795
796
                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))
797
798
799
        # 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
800
        # get categorical features
801
802
803
804
805
806
807
808
809
810
811
812
813
        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))
814
            if categorical_indices:
815
                if "categorical_feature" in params or "categorical_column" in params:
816
                    warnings.warn('categorical_feature in param dict is overridden.')
817
818
                    params.pop("categorical_feature", None)
                    params.pop("categorical_column", None)
819
                params['categorical_column'] = sorted(categorical_indices)
820

wxchan's avatar
wxchan committed
821
        params_str = param_dict_to_str(params)
822
        # process for reference dataset
wxchan's avatar
wxchan committed
823
        ref_dataset = None
wxchan's avatar
wxchan committed
824
        if isinstance(reference, Dataset):
825
            ref_dataset = reference.construct().handle
wxchan's avatar
wxchan committed
826
827
        elif reference is not None:
            raise TypeError('Reference dataset should be None or dataset instance')
828
        # start construct data
wxchan's avatar
wxchan committed
829
        if isinstance(data, string_type):
wxchan's avatar
wxchan committed
830
831
832
833
834
835
836
837
            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
838
839
        elif isinstance(data, scipy.sparse.csc_matrix):
            self.__init_from_csc(data, params_str, ref_dataset)
wxchan's avatar
wxchan committed
840
841
        elif isinstance(data, np.ndarray):
            self.__init_from_np2d(data, params_str, ref_dataset)
842
843
        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)
844
845
        elif isinstance(data, DataTable):
            self.__init_from_np2d(data.to_numpy(), params_str, ref_dataset)
wxchan's avatar
wxchan committed
846
847
848
849
        else:
            try:
                csr = scipy.sparse.csr_matrix(data)
                self.__init_from_csr(csr, params_str, ref_dataset)
850
            except BaseException:
wxchan's avatar
wxchan committed
851
                raise TypeError('Cannot initialize Dataset from {}'.format(type(data).__name__))
wxchan's avatar
wxchan committed
852
853
854
        if label is not None:
            self.set_label(label)
        if self.get_label() is None:
855
            raise ValueError("Label should not be None")
wxchan's avatar
wxchan committed
856
857
858
859
        if weight is not None:
            self.set_weight(weight)
        if group is not None:
            self.set_group(group)
860
861
862
        if isinstance(predictor, _InnerPredictor):
            if self._predictor is None and init_score is not None:
                warnings.warn("The init_score will be overridden by the prediction of init_model.")
Guolin Ke's avatar
Guolin Ke committed
863
            self._set_init_score_by_predictor(predictor, data)
864
865
        elif init_score is not None:
            self.set_init_score(init_score)
Guolin Ke's avatar
Guolin Ke committed
866
867
        elif predictor is not None:
            raise TypeError('Wrong predictor type {}'.format(type(predictor).__name__))
Guolin Ke's avatar
Guolin Ke committed
868
        # set feature names
Nikita Titov's avatar
Nikita Titov committed
869
        return self.set_feature_name(feature_name)
wxchan's avatar
wxchan committed
870
871

    def __init_from_np2d(self, mat, params_str, ref_dataset):
872
        """Initialize data from a 2-D numpy matrix."""
wxchan's avatar
wxchan committed
873
874
875
876
877
878
879
        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:
880
            # change non-float data to float data, need to copy
wxchan's avatar
wxchan committed
881
882
            data = np.array(mat.reshape(mat.size), dtype=np.float32)

883
        ptr_data, type_ptr_data, _ = c_float_array(data)
wxchan's avatar
wxchan committed
884
885
        _safe_call(_LIB.LGBM_DatasetCreateFromMat(
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
886
887
888
889
            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
890
891
892
            c_str(params_str),
            ref_dataset,
            ctypes.byref(self.handle)))
Nikita Titov's avatar
Nikita Titov committed
893
        return self
wxchan's avatar
wxchan committed
894

895
    def __init_from_list_np2d(self, mats, params_str, ref_dataset):
896
        """Initialize data from a list of 2-D numpy matrices."""
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
        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
940
        return self
941

wxchan's avatar
wxchan committed
942
    def __init_from_csr(self, csr, params_str, ref_dataset):
943
        """Initialize data from a CSR matrix."""
wxchan's avatar
wxchan committed
944
        if len(csr.indices) != len(csr.data):
945
            raise ValueError('Length mismatch: {} vs {}'.format(len(csr.indices), len(csr.data)))
wxchan's avatar
wxchan committed
946
947
        self.handle = ctypes.c_void_p()

948
949
        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
950

951
952
953
        assert csr.shape[1] <= MAX_INT32
        csr.indices = csr.indices.astype(np.int32, copy=False)

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

Guolin Ke's avatar
Guolin Ke committed
968
    def __init_from_csc(self, csc, params_str, ref_dataset):
969
        """Initialize data from a CSC matrix."""
Guolin Ke's avatar
Guolin Ke committed
970
971
972
973
        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()

974
975
        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
976

977
978
979
        assert csc.shape[0] <= MAX_INT32
        csc.indices = csc.indices.astype(np.int32, copy=False)

Guolin Ke's avatar
Guolin Ke committed
980
981
        _safe_call(_LIB.LGBM_DatasetCreateFromCSC(
            ptr_indptr,
Guolin Ke's avatar
Guolin Ke committed
982
            ctypes.c_int(type_ptr_indptr),
Guolin Ke's avatar
Guolin Ke committed
983
984
            csc.indices.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)),
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
985
986
987
988
            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
989
990
991
            c_str(params_str),
            ref_dataset,
            ctypes.byref(self.handle)))
Nikita Titov's avatar
Nikita Titov committed
992
        return self
Guolin Ke's avatar
Guolin Ke committed
993

wxchan's avatar
wxchan committed
994
    def construct(self):
995
996
997
998
999
        """Lazy init.

        Returns
        -------
        self : Dataset
Nikita Titov's avatar
Nikita Titov committed
1000
            Constructed Dataset object.
1001
        """
1002
        if self.handle is None:
wxchan's avatar
wxchan committed
1003
1004
            if self.reference is not None:
                if self.used_indices is None:
1005
                    # create valid
1006
                    self._lazy_init(self.data, label=self.label, reference=self.reference,
1007
1008
                                    weight=self.weight, group=self.group,
                                    init_score=self.init_score, predictor=self._predictor,
1009
                                    silent=self.silent, feature_name=self.feature_name, params=self.params)
wxchan's avatar
wxchan committed
1010
                else:
1011
                    # construct subset
wxchan's avatar
wxchan committed
1012
                    used_indices = list_to_1d_numpy(self.used_indices, np.int32, name='used_indices')
1013
                    assert used_indices.flags.c_contiguous
Guolin Ke's avatar
Guolin Ke committed
1014
1015
                    if self.reference.group is not None:
                        group_info = np.array(self.reference.group).astype(int)
1016
1017
                        _, self.group = np.unique(np.repeat(range_(len(group_info)), repeats=group_info)[self.used_indices],
                                                  return_counts=True)
1018
                    self.handle = ctypes.c_void_p()
wxchan's avatar
wxchan committed
1019
1020
                    params_str = param_dict_to_str(self.params)
                    _safe_call(_LIB.LGBM_DatasetGetSubset(
1021
                        self.reference.construct().handle,
wxchan's avatar
wxchan committed
1022
                        used_indices.ctypes.data_as(ctypes.POINTER(ctypes.c_int32)),
Guolin Ke's avatar
Guolin Ke committed
1023
                        ctypes.c_int(used_indices.shape[0]),
wxchan's avatar
wxchan committed
1024
1025
                        c_str(params_str),
                        ctypes.byref(self.handle)))
Guolin Ke's avatar
Guolin Ke committed
1026
1027
                    if not self.free_raw_data:
                        self.get_data()
Guolin Ke's avatar
Guolin Ke committed
1028
1029
                    if self.group is not None:
                        self.set_group(self.group)
wxchan's avatar
wxchan committed
1030
1031
                    if self.get_label() is None:
                        raise ValueError("Label should not be None.")
Guolin Ke's avatar
Guolin Ke committed
1032
1033
1034
                    if isinstance(self._predictor, _InnerPredictor) and self._predictor is not self.reference._predictor:
                        self.get_data()
                        self._set_init_score_by_predictor(self._predictor, self.data, used_indices)
wxchan's avatar
wxchan committed
1035
            else:
1036
                # create train
1037
                self._lazy_init(self.data, label=self.label,
1038
1039
1040
                                weight=self.weight, group=self.group,
                                init_score=self.init_score, predictor=self._predictor,
                                silent=self.silent, feature_name=self.feature_name,
1041
                                categorical_feature=self.categorical_feature, params=self.params)
wxchan's avatar
wxchan committed
1042
1043
1044
            if self.free_raw_data:
                self.data = None
        return self
wxchan's avatar
wxchan committed
1045

wxchan's avatar
wxchan committed
1046
    def create_valid(self, data, label=None, weight=None, group=None,
1047
                     init_score=None, silent=False, params=None):
1048
        """Create validation data align with current Dataset.
wxchan's avatar
wxchan committed
1049
1050
1051

        Parameters
        ----------
1052
        data : string, numpy array, pandas DataFrame, H2O DataTable's Frame, scipy.sparse or list of numpy arrays
wxchan's avatar
wxchan committed
1053
            Data source of Dataset.
1054
            If string, it represents the path to txt file.
1055
        label : list, numpy 1-D array, pandas Series / one-column DataFrame or None, optional (default=None)
1056
1057
            Label of the data.
        weight : list, numpy 1-D array, pandas Series or None, optional (default=None)
wxchan's avatar
wxchan committed
1058
            Weight for each instance.
1059
        group : list, numpy 1-D array, pandas Series or None, optional (default=None)
1060
            Group/query size for Dataset.
1061
        init_score : list, numpy 1-D array, pandas Series or None, optional (default=None)
1062
            Init score for Dataset.
1063
1064
        silent : bool, optional (default=False)
            Whether to print messages during construction.
Nikita Titov's avatar
Nikita Titov committed
1065
        params : dict or None, optional (default=None)
1066
            Other parameters for validation Dataset.
1067
1068
1069

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1070
1071
        valid : Dataset
            Validation Dataset with reference to self.
wxchan's avatar
wxchan committed
1072
        """
1073
        ret = Dataset(data, label=label, reference=self,
1074
1075
                      weight=weight, group=group, init_score=init_score,
                      silent=silent, params=params, free_raw_data=self.free_raw_data)
wxchan's avatar
wxchan committed
1076
        ret._predictor = self._predictor
1077
        ret.pandas_categorical = self.pandas_categorical
wxchan's avatar
wxchan committed
1078
        return ret
wxchan's avatar
wxchan committed
1079

wxchan's avatar
wxchan committed
1080
    def subset(self, used_indices, params=None):
1081
        """Get subset of current Dataset.
wxchan's avatar
wxchan committed
1082
1083
1084
1085

        Parameters
        ----------
        used_indices : list of int
1086
            Indices used to create the subset.
Nikita Titov's avatar
Nikita Titov committed
1087
        params : dict or None, optional (default=None)
1088
            These parameters will be passed to Dataset constructor.
1089
1090
1091
1092
1093

        Returns
        -------
        subset : Dataset
            Subset of the current Dataset.
wxchan's avatar
wxchan committed
1094
        """
wxchan's avatar
wxchan committed
1095
1096
        if params is None:
            params = self.params
wxchan's avatar
wxchan committed
1097
        ret = Dataset(None, reference=self, feature_name=self.feature_name,
1098
1099
                      categorical_feature=self.categorical_feature, params=params,
                      free_raw_data=self.free_raw_data)
wxchan's avatar
wxchan committed
1100
        ret._predictor = self._predictor
1101
        ret.pandas_categorical = self.pandas_categorical
wxchan's avatar
wxchan committed
1102
1103
1104
1105
        ret.used_indices = used_indices
        return ret

    def save_binary(self, filename):
1106
        """Save Dataset to a binary file.
wxchan's avatar
wxchan committed
1107
1108
1109
1110
1111

        Parameters
        ----------
        filename : string
            Name of the output file.
Nikita Titov's avatar
Nikita Titov committed
1112
1113
1114
1115
1116

        Returns
        -------
        self : Dataset
            Returns self.
wxchan's avatar
wxchan committed
1117
1118
1119
1120
        """
        _safe_call(_LIB.LGBM_DatasetSaveBinary(
            self.construct().handle,
            c_str(filename)))
Nikita Titov's avatar
Nikita Titov committed
1121
        return self
wxchan's avatar
wxchan committed
1122
1123

    def _update_params(self, params):
1124
1125
        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
1126
        if not self.params:
1127
            self.params = copy.deepcopy(params)
wxchan's avatar
wxchan committed
1128
        else:
1129
            self.params_back_up = copy.deepcopy(self.params)
wxchan's avatar
wxchan committed
1130
            self.params.update(params)
Nikita Titov's avatar
Nikita Titov committed
1131
        return self
wxchan's avatar
wxchan committed
1132

1133
1134
1135
    def _reverse_update_params(self):
        self.params = copy.deepcopy(self.params_back_up)
        self.params_back_up = None
1136
1137
        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
1138
        return self
1139

wxchan's avatar
wxchan committed
1140
    def set_field(self, field_name, data):
wxchan's avatar
wxchan committed
1141
        """Set property into the Dataset.
wxchan's avatar
wxchan committed
1142
1143
1144

        Parameters
        ----------
Nikita Titov's avatar
Nikita Titov committed
1145
        field_name : string
1146
            The field name of the information.
1147
        data : list, numpy 1-D array, pandas Series or None
1148
            The array of data to be set.
Nikita Titov's avatar
Nikita Titov committed
1149
1150
1151
1152
1153

        Returns
        -------
        self : Dataset
            Dataset with set property.
wxchan's avatar
wxchan committed
1154
        """
1155
1156
        if self.handle is None:
            raise Exception("Cannot set %s before construct dataset" % field_name)
wxchan's avatar
wxchan committed
1157
        if data is None:
1158
            # set to None
wxchan's avatar
wxchan committed
1159
1160
1161
1162
            _safe_call(_LIB.LGBM_DatasetSetField(
                self.handle,
                c_str(field_name),
                None,
Guolin Ke's avatar
Guolin Ke committed
1163
1164
                ctypes.c_int(0),
                ctypes.c_int(FIELD_TYPE_MAPPER[field_name])))
Nikita Titov's avatar
Nikita Titov committed
1165
            return self
Guolin Ke's avatar
Guolin Ke committed
1166
1167
1168
1169
1170
        dtype = np.float32
        if field_name == 'group':
            dtype = np.int32
        elif field_name == 'init_score':
            dtype = np.float64
1171
        data = list_to_1d_numpy(data, dtype, name=field_name)
1172
1173
        if data.dtype == np.float32 or data.dtype == np.float64:
            ptr_data, type_data, _ = c_float_array(data)
wxchan's avatar
wxchan committed
1174
        elif data.dtype == np.int32:
1175
            ptr_data, type_data, _ = c_int_array(data)
wxchan's avatar
wxchan committed
1176
        else:
Nikita Titov's avatar
Nikita Titov committed
1177
            raise TypeError("Expected np.float32/64 or np.int32, met type({})".format(data.dtype))
wxchan's avatar
wxchan committed
1178
        if type_data != FIELD_TYPE_MAPPER[field_name]:
1179
            raise TypeError("Input type error for set_field")
wxchan's avatar
wxchan committed
1180
1181
1182
1183
        _safe_call(_LIB.LGBM_DatasetSetField(
            self.handle,
            c_str(field_name),
            ptr_data,
Guolin Ke's avatar
Guolin Ke committed
1184
1185
            ctypes.c_int(len(data)),
            ctypes.c_int(type_data)))
Nikita Titov's avatar
Nikita Titov committed
1186
        return self
wxchan's avatar
wxchan committed
1187

wxchan's avatar
wxchan committed
1188
1189
    def get_field(self, field_name):
        """Get property from the Dataset.
wxchan's avatar
wxchan committed
1190
1191
1192

        Parameters
        ----------
Nikita Titov's avatar
Nikita Titov committed
1193
        field_name : string
1194
            The field name of the information.
wxchan's avatar
wxchan committed
1195
1196
1197

        Returns
        -------
1198
1199
        info : numpy array
            A numpy array with information from the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1200
        """
1201
        if self.handle is None:
1202
            raise Exception("Cannot get %s before construct Dataset" % field_name)
Guolin Ke's avatar
Guolin Ke committed
1203
1204
        tmp_out_len = ctypes.c_int()
        out_type = ctypes.c_int()
wxchan's avatar
wxchan committed
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
        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
1220
1221
        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)
1222
1223
        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)
1224
        else:
wxchan's avatar
wxchan committed
1225
            raise TypeError("Unknown type")
Guolin Ke's avatar
Guolin Ke committed
1226

1227
    def set_categorical_feature(self, categorical_feature):
1228
        """Set categorical features.
1229
1230
1231

        Parameters
        ----------
1232
1233
        categorical_feature : list of int or strings
            Names or indices of categorical features.
Nikita Titov's avatar
Nikita Titov committed
1234
1235
1236
1237
1238

        Returns
        -------
        self : Dataset
            Dataset with set categorical features.
1239
1240
        """
        if self.categorical_feature == categorical_feature:
Nikita Titov's avatar
Nikita Titov committed
1241
            return self
1242
        if self.data is not None:
1243
1244
            if self.categorical_feature is None:
                self.categorical_feature = categorical_feature
Nikita Titov's avatar
Nikita Titov committed
1245
                return self._free_handle()
1246
1247
            elif categorical_feature == 'auto':
                warnings.warn('Using categorical_feature in Dataset.')
Nikita Titov's avatar
Nikita Titov committed
1248
                return self
1249
            else:
1250
1251
                warnings.warn('categorical_feature in Dataset is overridden.\n'
                              'New categorical_feature is {}'.format(sorted(list(categorical_feature))))
1252
                self.categorical_feature = categorical_feature
Nikita Titov's avatar
Nikita Titov committed
1253
                return self._free_handle()
1254
        else:
1255
1256
            raise LightGBMError("Cannot set categorical feature after freed raw data, "
                                "set free_raw_data=False when construct Dataset to avoid this.")
1257

Guolin Ke's avatar
Guolin Ke committed
1258
    def _set_predictor(self, predictor):
1259
1260
1261
1262
        """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
1263
1264
        """
        if predictor is self._predictor:
Nikita Titov's avatar
Nikita Titov committed
1265
            return self
Guolin Ke's avatar
Guolin Ke committed
1266
        if self.data is not None or (self.used_indices is not None and self.reference is not None and self.reference.data is not None):
Guolin Ke's avatar
Guolin Ke committed
1267
            self._predictor = predictor
Nikita Titov's avatar
Nikita Titov committed
1268
            return self._free_handle()
Guolin Ke's avatar
Guolin Ke committed
1269
        else:
1270
1271
            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
1272
1273

    def set_reference(self, reference):
1274
        """Set reference Dataset.
Guolin Ke's avatar
Guolin Ke committed
1275
1276
1277
1278

        Parameters
        ----------
        reference : Dataset
1279
            Reference that is used as a template to construct the current Dataset.
Nikita Titov's avatar
Nikita Titov committed
1280
1281
1282
1283
1284

        Returns
        -------
        self : Dataset
            Dataset with set reference.
Guolin Ke's avatar
Guolin Ke committed
1285
        """
1286
1287
1288
        self.set_categorical_feature(reference.categorical_feature) \
            .set_feature_name(reference.feature_name) \
            ._set_predictor(reference._predictor)
1289
1290
        # 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
1291
            return self
Guolin Ke's avatar
Guolin Ke committed
1292
1293
        if self.data is not None:
            self.reference = reference
Nikita Titov's avatar
Nikita Titov committed
1294
            return self._free_handle()
Guolin Ke's avatar
Guolin Ke committed
1295
        else:
1296
1297
            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
1298
1299

    def set_feature_name(self, feature_name):
1300
        """Set feature name.
Guolin Ke's avatar
Guolin Ke committed
1301
1302
1303

        Parameters
        ----------
1304
1305
        feature_name : list of strings
            Feature names.
Nikita Titov's avatar
Nikita Titov committed
1306
1307
1308
1309
1310

        Returns
        -------
        self : Dataset
            Dataset with set feature name.
Guolin Ke's avatar
Guolin Ke committed
1311
        """
1312
1313
        if feature_name != 'auto':
            self.feature_name = feature_name
1314
        if self.handle is not None and feature_name is not None and feature_name != 'auto':
wxchan's avatar
wxchan committed
1315
            if len(feature_name) != self.num_feature():
1316
1317
                raise ValueError("Length of feature_name({}) and num_feature({}) don't match"
                                 .format(len(feature_name), self.num_feature()))
1318
            c_feature_name = [c_str(name) for name in feature_name]
wxchan's avatar
wxchan committed
1319
1320
1321
            _safe_call(_LIB.LGBM_DatasetSetFeatureNames(
                self.handle,
                c_array(ctypes.c_char_p, c_feature_name),
Guolin Ke's avatar
Guolin Ke committed
1322
                ctypes.c_int(len(feature_name))))
Nikita Titov's avatar
Nikita Titov committed
1323
        return self
Guolin Ke's avatar
Guolin Ke committed
1324
1325

    def set_label(self, label):
1326
        """Set label of Dataset.
Guolin Ke's avatar
Guolin Ke committed
1327
1328
1329

        Parameters
        ----------
1330
        label : list, numpy 1-D array, pandas Series / one-column DataFrame or None
1331
            The label information to be set into Dataset.
Nikita Titov's avatar
Nikita Titov committed
1332
1333
1334
1335
1336

        Returns
        -------
        self : Dataset
            Dataset with set label.
Guolin Ke's avatar
Guolin Ke committed
1337
1338
        """
        self.label = label
1339
        if self.handle is not None:
1340
            label = list_to_1d_numpy(_label_from_pandas(label), name='label')
wxchan's avatar
wxchan committed
1341
            self.set_field('label', label)
Nikita Titov's avatar
Nikita Titov committed
1342
        return self
Guolin Ke's avatar
Guolin Ke committed
1343
1344

    def set_weight(self, weight):
1345
        """Set weight of each instance.
Guolin Ke's avatar
Guolin Ke committed
1346
1347
1348

        Parameters
        ----------
1349
        weight : list, numpy 1-D array, pandas Series or None
1350
            Weight to be set for each data point.
Nikita Titov's avatar
Nikita Titov committed
1351
1352
1353
1354
1355

        Returns
        -------
        self : Dataset
            Dataset with set weight.
Guolin Ke's avatar
Guolin Ke committed
1356
        """
1357
1358
        if weight is not None and np.all(weight == 1):
            weight = None
Guolin Ke's avatar
Guolin Ke committed
1359
        self.weight = weight
1360
        if self.handle is not None and weight is not None:
wxchan's avatar
wxchan committed
1361
1362
            weight = list_to_1d_numpy(weight, name='weight')
            self.set_field('weight', weight)
Nikita Titov's avatar
Nikita Titov committed
1363
        return self
Guolin Ke's avatar
Guolin Ke committed
1364
1365

    def set_init_score(self, init_score):
1366
        """Set init score of Booster to start from.
Guolin Ke's avatar
Guolin Ke committed
1367
1368
1369

        Parameters
        ----------
1370
        init_score : list, numpy 1-D array, pandas Series or None
1371
            Init score for Booster.
Nikita Titov's avatar
Nikita Titov committed
1372
1373
1374
1375
1376

        Returns
        -------
        self : Dataset
            Dataset with set init score.
Guolin Ke's avatar
Guolin Ke committed
1377
1378
        """
        self.init_score = init_score
1379
        if self.handle is not None and init_score is not None:
Guolin Ke's avatar
Guolin Ke committed
1380
            init_score = list_to_1d_numpy(init_score, np.float64, name='init_score')
wxchan's avatar
wxchan committed
1381
            self.set_field('init_score', init_score)
Nikita Titov's avatar
Nikita Titov committed
1382
        return self
Guolin Ke's avatar
Guolin Ke committed
1383
1384

    def set_group(self, group):
1385
        """Set group size of Dataset (used for ranking).
Guolin Ke's avatar
Guolin Ke committed
1386
1387
1388

        Parameters
        ----------
1389
        group : list, numpy 1-D array, pandas Series or None
1390
            Group size of each group.
Nikita Titov's avatar
Nikita Titov committed
1391
1392
1393
1394
1395

        Returns
        -------
        self : Dataset
            Dataset with set group.
Guolin Ke's avatar
Guolin Ke committed
1396
1397
        """
        self.group = group
1398
        if self.handle is not None and group is not None:
wxchan's avatar
wxchan committed
1399
1400
            group = list_to_1d_numpy(group, np.int32, name='group')
            self.set_field('group', group)
Nikita Titov's avatar
Nikita Titov committed
1401
        return self
Guolin Ke's avatar
Guolin Ke committed
1402
1403

    def get_label(self):
1404
        """Get the label of the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1405
1406
1407

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1408
        label : numpy array or None
1409
            The label information from the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1410
        """
1411
        if self.label is None:
wxchan's avatar
wxchan committed
1412
            self.label = self.get_field('label')
Guolin Ke's avatar
Guolin Ke committed
1413
1414
1415
        return self.label

    def get_weight(self):
1416
        """Get the weight of the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1417
1418
1419

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1420
        weight : numpy array or None
1421
            Weight for each data point from the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1422
        """
1423
        if self.weight is None:
wxchan's avatar
wxchan committed
1424
            self.weight = self.get_field('weight')
Guolin Ke's avatar
Guolin Ke committed
1425
1426
        return self.weight

1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
    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
1451
    def get_init_score(self):
1452
        """Get the initial score of the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1453
1454
1455

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1456
        init_score : numpy array or None
1457
            Init score of Booster.
Guolin Ke's avatar
Guolin Ke committed
1458
        """
1459
        if self.init_score is None:
wxchan's avatar
wxchan committed
1460
            self.init_score = self.get_field('init_score')
Guolin Ke's avatar
Guolin Ke committed
1461
1462
        return self.init_score

1463
1464
1465
1466
1467
    def get_data(self):
        """Get the raw data of the Dataset.

        Returns
        -------
1468
        data : string, numpy array, pandas DataFrame, H2O DataTable's Frame, scipy.sparse, list of numpy arrays or None
1469
1470
1471
1472
            Raw data used in the Dataset construction.
        """
        if self.handle is None:
            raise Exception("Cannot get data before construct Dataset")
Guolin Ke's avatar
Guolin Ke committed
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
        if self.need_slice and self.used_indices is not None and self.reference is not None:
            self.data = self.reference.data
            if self.data is not None:
                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()
                elif isinstance(self.data, DataTable):
                    self.data = self.data[self.used_indices, :]
                else:
                    warnings.warn("Cannot subset {} type of raw data.\n"
                                  "Returning original raw data".format(type(self.data).__name__))
1485
            self.need_slice = False
Guolin Ke's avatar
Guolin Ke committed
1486
1487
1488
        if self.data is None:
            raise LightGBMError("Cannot call `get_data` after freed raw data, "
                                "set free_raw_data=False when construct Dataset to avoid this.")
1489
1490
        return self.data

Guolin Ke's avatar
Guolin Ke committed
1491
    def get_group(self):
1492
        """Get the group of the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1493
1494
1495

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1496
        group : numpy array or None
1497
            Group size of each group.
Guolin Ke's avatar
Guolin Ke committed
1498
        """
1499
        if self.group is None:
wxchan's avatar
wxchan committed
1500
            self.group = self.get_field('group')
Guolin Ke's avatar
Guolin Ke committed
1501
1502
            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
1503
                self.group = np.diff(self.group)
Guolin Ke's avatar
Guolin Ke committed
1504
1505
1506
        return self.group

    def num_data(self):
1507
        """Get the number of rows in the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1508
1509
1510

        Returns
        -------
1511
1512
        number_of_rows : int
            The number of rows in the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1513
        """
1514
        if self.handle is not None:
Guolin Ke's avatar
Guolin Ke committed
1515
            ret = ctypes.c_int()
wxchan's avatar
wxchan committed
1516
1517
1518
            _safe_call(_LIB.LGBM_DatasetGetNumData(self.handle,
                                                   ctypes.byref(ret)))
            return ret.value
Guolin Ke's avatar
Guolin Ke committed
1519
        else:
1520
            raise LightGBMError("Cannot get num_data before construct dataset")
Guolin Ke's avatar
Guolin Ke committed
1521
1522

    def num_feature(self):
1523
        """Get the number of columns (features) in the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1524
1525
1526

        Returns
        -------
1527
1528
        number_of_columns : int
            The number of columns (features) in the Dataset.
Guolin Ke's avatar
Guolin Ke committed
1529
        """
1530
        if self.handle is not None:
Guolin Ke's avatar
Guolin Ke committed
1531
            ret = ctypes.c_int()
wxchan's avatar
wxchan committed
1532
1533
1534
            _safe_call(_LIB.LGBM_DatasetGetNumFeature(self.handle,
                                                      ctypes.byref(ret)))
            return ret.value
Guolin Ke's avatar
Guolin Ke committed
1535
        else:
1536
            raise LightGBMError("Cannot get num_feature before construct dataset")
Guolin Ke's avatar
Guolin Ke committed
1537

1538
    def get_ref_chain(self, ref_limit=100):
1539
1540
1541
1542
1543
        """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.
1544
1545
1546
1547
1548

        Parameters
        ----------
        ref_limit : int, optional (default=100)
            The limit number of references.
1549
1550
1551

        Returns
        -------
1552
1553
1554
        ref_chain : set of Dataset
            Chain of references of the Datasets.
        """
1555
        head = self
1556
        ref_chain = set()
1557
1558
        while len(ref_chain) < ref_limit:
            if isinstance(head, Dataset):
1559
                ref_chain.add(head)
1560
1561
1562
1563
1564
1565
                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
1566
        return ref_chain
1567

1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
    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
1608

wxchan's avatar
wxchan committed
1609
class Booster(object):
1610
    """Booster in LightGBM."""
1611

1612
    def __init__(self, params=None, train_set=None, model_file=None, model_str=None, silent=False):
1613
        """Initialize the Booster.
wxchan's avatar
wxchan committed
1614
1615
1616

        Parameters
        ----------
Nikita Titov's avatar
Nikita Titov committed
1617
        params : dict or None, optional (default=None)
1618
1619
1620
1621
            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
1622
            Path to the model file.
1623
1624
        model_str : string or None, optional (default=None)
            Model will be loaded from this string.
1625
1626
        silent : bool, optional (default=False)
            Whether to print messages during construction.
wxchan's avatar
wxchan committed
1627
        """
1628
        self.handle = None
1629
        self.network = False
wxchan's avatar
wxchan committed
1630
1631
1632
        self.__need_reload_eval_info = True
        self.__train_data_name = "training"
        self.__attr = {}
1633
        self.__set_objective_to_none = False
wxchan's avatar
wxchan committed
1634
        self.best_iteration = -1
wxchan's avatar
wxchan committed
1635
        self.best_score = {}
1636
        params = {} if params is None else copy.deepcopy(params)
1637
1638
1639
        # 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
1640
        if train_set is not None:
1641
            # Training task
wxchan's avatar
wxchan committed
1642
            if not isinstance(train_set, Dataset):
1643
1644
                raise TypeError('Training data should be Dataset instance, met {}'
                                .format(type(train_set).__name__))
wxchan's avatar
wxchan committed
1645
            params_str = param_dict_to_str(params)
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
            # 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
1662
            # construct booster object
1663
            self.handle = ctypes.c_void_p()
wxchan's avatar
wxchan committed
1664
            _safe_call(_LIB.LGBM_BoosterCreate(
wxchan's avatar
wxchan committed
1665
                train_set.construct().handle,
wxchan's avatar
wxchan committed
1666
1667
                c_str(params_str),
                ctypes.byref(self.handle)))
1668
            # save reference to data
wxchan's avatar
wxchan committed
1669
1670
1671
1672
            self.train_set = train_set
            self.valid_sets = []
            self.name_valid_sets = []
            self.__num_dataset = 1
Guolin Ke's avatar
Guolin Ke committed
1673
1674
            self.__init_predictor = train_set._predictor
            if self.__init_predictor is not None:
wxchan's avatar
wxchan committed
1675
1676
                _safe_call(_LIB.LGBM_BoosterMerge(
                    self.handle,
Guolin Ke's avatar
Guolin Ke committed
1677
                    self.__init_predictor.handle))
Guolin Ke's avatar
Guolin Ke committed
1678
            out_num_class = ctypes.c_int(0)
wxchan's avatar
wxchan committed
1679
1680
1681
1682
            _safe_call(_LIB.LGBM_BoosterGetNumClasses(
                self.handle,
                ctypes.byref(out_num_class)))
            self.__num_class = out_num_class.value
1683
            # buffer for inner predict
wxchan's avatar
wxchan committed
1684
1685
1686
            self.__inner_predict_buffer = [None]
            self.__is_predicted_cur_iter = [False]
            self.__get_eval_info()
1687
            self.pandas_categorical = train_set.pandas_categorical
wxchan's avatar
wxchan committed
1688
        elif model_file is not None:
1689
            # Prediction task
Guolin Ke's avatar
Guolin Ke committed
1690
            out_num_iterations = ctypes.c_int(0)
1691
            self.handle = ctypes.c_void_p()
wxchan's avatar
wxchan committed
1692
1693
1694
1695
            _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
1696
            out_num_class = ctypes.c_int(0)
wxchan's avatar
wxchan committed
1697
1698
1699
1700
            _safe_call(_LIB.LGBM_BoosterGetNumClasses(
                self.handle,
                ctypes.byref(out_num_class)))
            self.__num_class = out_num_class.value
1701
            self.pandas_categorical = _load_pandas_categorical(file_name=model_file)
1702
1703
        elif model_str is not None:
            self.model_from_string(model_str, not silent)
wxchan's avatar
wxchan committed
1704
        else:
1705
1706
            raise TypeError('Need at least one training dataset or model file or model string '
                            'to create Booster instance')
1707
        self.params = params
wxchan's avatar
wxchan committed
1708
1709

    def __del__(self):
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
        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
1720

wxchan's avatar
wxchan committed
1721
1722
1723
1724
    def __copy__(self):
        return self.__deepcopy__(None)

    def __deepcopy__(self, _):
1725
        model_str = self.model_to_string(num_iteration=-1)
1726
        booster = Booster(model_str=model_str)
1727
        return booster
wxchan's avatar
wxchan committed
1728
1729
1730
1731
1732
1733
1734

    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:
1735
            this["handle"] = self.model_to_string(num_iteration=-1)
wxchan's avatar
wxchan committed
1736
1737
1738
        return this

    def __setstate__(self, state):
1739
1740
        model_str = state.get('handle', None)
        if model_str is not None:
wxchan's avatar
wxchan committed
1741
            handle = ctypes.c_void_p()
Guolin Ke's avatar
Guolin Ke committed
1742
            out_num_iterations = ctypes.c_int(0)
1743
1744
1745
1746
            _safe_call(_LIB.LGBM_BoosterLoadModelFromString(
                c_str(model_str),
                ctypes.byref(out_num_iterations),
                ctypes.byref(handle)))
wxchan's avatar
wxchan committed
1747
1748
1749
            state['handle'] = handle
        self.__dict__.update(state)

wxchan's avatar
wxchan committed
1750
    def free_dataset(self):
Nikita Titov's avatar
Nikita Titov committed
1751
1752
1753
1754
1755
1756
1757
        """Free Booster's Datasets.

        Returns
        -------
        self : Booster
            Booster without Datasets.
        """
wxchan's avatar
wxchan committed
1758
1759
        self.__dict__.pop('train_set', None)
        self.__dict__.pop('valid_sets', None)
1760
        self.__num_dataset = 0
Nikita Titov's avatar
Nikita Titov committed
1761
        return self
wxchan's avatar
wxchan committed
1762

1763
1764
1765
    def _free_buffer(self):
        self.__inner_predict_buffer = []
        self.__is_predicted_cur_iter = []
Nikita Titov's avatar
Nikita Titov committed
1766
        return self
1767

1768
1769
1770
1771
1772
1773
    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
1774
        machines : list, set or string
1775
            Names of machines.
Nikita Titov's avatar
Nikita Titov committed
1776
        local_listen_port : int, optional (default=12400)
1777
            TCP listen port for local machines.
Nikita Titov's avatar
Nikita Titov committed
1778
        listen_time_out : int, optional (default=120)
1779
            Socket time-out in minutes.
Nikita Titov's avatar
Nikita Titov committed
1780
        num_machines : int, optional (default=1)
1781
            The number of machines for parallel learning application.
Nikita Titov's avatar
Nikita Titov committed
1782
1783
1784
1785
1786

        Returns
        -------
        self : Booster
            Booster with set network.
1787
1788
1789
1790
1791
1792
        """
        _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
1793
        return self
1794
1795

    def free_network(self):
Nikita Titov's avatar
Nikita Titov committed
1796
1797
1798
1799
1800
1801
1802
        """Free Booster's network.

        Returns
        -------
        self : Booster
            Booster with freed network.
        """
1803
1804
        _safe_call(_LIB.LGBM_NetworkFree())
        self.network = False
Nikita Titov's avatar
Nikita Titov committed
1805
        return self
1806

wxchan's avatar
wxchan committed
1807
    def set_train_data_name(self, name):
1808
1809
1810
1811
        """Set the name to the training Dataset.

        Parameters
        ----------
Nikita Titov's avatar
Nikita Titov committed
1812
1813
1814
1815
1816
1817
1818
        name : string
            Name for the training Dataset.

        Returns
        -------
        self : Booster
            Booster with set training Dataset name.
1819
        """
wxchan's avatar
wxchan committed
1820
        self.__train_data_name = name
Nikita Titov's avatar
Nikita Titov committed
1821
        return self
wxchan's avatar
wxchan committed
1822
1823

    def add_valid(self, data, name):
1824
        """Add validation data.
wxchan's avatar
wxchan committed
1825
1826
1827
1828

        Parameters
        ----------
        data : Dataset
1829
1830
1831
            Validation data.
        name : string
            Name of validation data.
Nikita Titov's avatar
Nikita Titov committed
1832
1833
1834
1835
1836

        Returns
        -------
        self : Booster
            Booster with set validation data.
wxchan's avatar
wxchan committed
1837
        """
Guolin Ke's avatar
Guolin Ke committed
1838
        if not isinstance(data, Dataset):
1839
1840
            raise TypeError('Validation data should be Dataset instance, met {}'
                            .format(type(data).__name__))
Guolin Ke's avatar
Guolin Ke committed
1841
        if data._predictor is not self.__init_predictor:
1842
1843
            raise LightGBMError("Add validation data failed, "
                                "you should use same predictor for these data")
wxchan's avatar
wxchan committed
1844
1845
        _safe_call(_LIB.LGBM_BoosterAddValidData(
            self.handle,
wxchan's avatar
wxchan committed
1846
            data.construct().handle))
wxchan's avatar
wxchan committed
1847
1848
1849
1850
1851
        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
1852
        return self
wxchan's avatar
wxchan committed
1853
1854

    def reset_parameter(self, params):
1855
        """Reset parameters of Booster.
wxchan's avatar
wxchan committed
1856
1857
1858
1859

        Parameters
        ----------
        params : dict
1860
            New parameters for Booster.
Nikita Titov's avatar
Nikita Titov committed
1861
1862
1863
1864
1865

        Returns
        -------
        self : Booster
            Booster with new parameters.
wxchan's avatar
wxchan committed
1866
        """
1867
        if any(metric_alias in params for metric_alias in ('metric', 'metrics', 'metric_types')):
wxchan's avatar
wxchan committed
1868
1869
1870
1871
1872
1873
            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
1874
        self.params.update(params)
Nikita Titov's avatar
Nikita Titov committed
1875
        return self
wxchan's avatar
wxchan committed
1876
1877

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

wxchan's avatar
wxchan committed
1880
1881
        Parameters
        ----------
1882
1883
1884
1885
        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
1886
            Customized objective function.
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
            Should accept two parameters: preds, train_data,
            and return (grad, hess).

                preds : list or numpy 1-D array
                    The predicted values.
                train_data : Dataset
                    The training dataset.
                grad : list or numpy 1-D array
                    The value of the first order derivative (gradient) for each sample point.
                hess : list or numpy 1-D array
                    The value of the second order derivative (Hessian) for each sample point.
wxchan's avatar
wxchan committed
1898

1899
1900
            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 score[j * num_data + i]
1901
1902
            and you should group grad and hess in this way as well.

wxchan's avatar
wxchan committed
1903
1904
        Returns
        -------
1905
1906
        is_finished : bool
            Whether the update was successfully finished.
wxchan's avatar
wxchan committed
1907
        """
1908
        # need reset training data
wxchan's avatar
wxchan committed
1909
        if train_set is not None and train_set is not self.train_set:
Guolin Ke's avatar
Guolin Ke committed
1910
            if not isinstance(train_set, Dataset):
1911
1912
                raise TypeError('Training data should be Dataset instance, met {}'
                                .format(type(train_set).__name__))
Guolin Ke's avatar
Guolin Ke committed
1913
            if train_set._predictor is not self.__init_predictor:
1914
1915
                raise LightGBMError("Replace training data failed, "
                                    "you should use same predictor for these data")
wxchan's avatar
wxchan committed
1916
1917
1918
            self.train_set = train_set
            _safe_call(_LIB.LGBM_BoosterResetTrainingData(
                self.handle,
wxchan's avatar
wxchan committed
1919
                self.train_set.construct().handle))
wxchan's avatar
wxchan committed
1920
1921
1922
            self.__inner_predict_buffer[0] = None
        is_finished = ctypes.c_int(0)
        if fobj is None:
1923
            if self.__set_objective_to_none:
1924
                raise LightGBMError('Cannot update due to null objective function.')
wxchan's avatar
wxchan committed
1925
1926
1927
            _safe_call(_LIB.LGBM_BoosterUpdateOneIter(
                self.handle,
                ctypes.byref(is_finished)))
wxchan's avatar
wxchan committed
1928
            self.__is_predicted_cur_iter = [False for _ in range_(self.__num_dataset)]
wxchan's avatar
wxchan committed
1929
1930
            return is_finished.value == 1
        else:
1931
            if not self.__set_objective_to_none:
Nikita Titov's avatar
Nikita Titov committed
1932
                self.reset_parameter({"objective": "none"}).__set_objective_to_none = True
wxchan's avatar
wxchan committed
1933
1934
1935
1936
            grad, hess = fobj(self.__inner_predict(0), self.train_set)
            return self.__boost(grad, hess)

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

1939
1940
1941
1942
1943
        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.
1944

wxchan's avatar
wxchan committed
1945
1946
        Parameters
        ----------
1947
        grad : list or numpy 1-D array
Nikita Titov's avatar
Nikita Titov committed
1948
            The first order derivative (gradient).
1949
        hess : list or numpy 1-D array
Nikita Titov's avatar
Nikita Titov committed
1950
            The second order derivative (Hessian).
wxchan's avatar
wxchan committed
1951
1952
1953

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
1954
1955
        is_finished : bool
            Whether the boost was successfully finished.
wxchan's avatar
wxchan committed
1956
        """
1957
1958
        grad = list_to_1d_numpy(grad, name='gradient')
        hess = list_to_1d_numpy(hess, name='hessian')
1959
1960
        assert grad.flags.c_contiguous
        assert hess.flags.c_contiguous
wxchan's avatar
wxchan committed
1961
        if len(grad) != len(hess):
1962
1963
            raise ValueError("Lengths of gradient({}) and hessian({}) don't match"
                             .format(len(grad), len(hess)))
wxchan's avatar
wxchan committed
1964
1965
1966
1967
1968
1969
        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
1970
        self.__is_predicted_cur_iter = [False for _ in range_(self.__num_dataset)]
wxchan's avatar
wxchan committed
1971
1972
1973
        return is_finished.value == 1

    def rollback_one_iter(self):
Nikita Titov's avatar
Nikita Titov committed
1974
1975
1976
1977
1978
1979
1980
        """Rollback one iteration.

        Returns
        -------
        self : Booster
            Booster with rolled back one iteration.
        """
wxchan's avatar
wxchan committed
1981
1982
        _safe_call(_LIB.LGBM_BoosterRollbackOneIter(
            self.handle))
wxchan's avatar
wxchan committed
1983
        self.__is_predicted_cur_iter = [False for _ in range_(self.__num_dataset)]
Nikita Titov's avatar
Nikita Titov committed
1984
        return self
wxchan's avatar
wxchan committed
1985
1986

    def current_iteration(self):
1987
1988
1989
1990
1991
1992
1993
        """Get the index of the current iteration.

        Returns
        -------
        cur_iter : int
            The index of the current iteration.
        """
Guolin Ke's avatar
Guolin Ke committed
1994
        out_cur_iter = ctypes.c_int(0)
wxchan's avatar
wxchan committed
1995
1996
1997
1998
1999
        _safe_call(_LIB.LGBM_BoosterGetCurrentIteration(
            self.handle,
            ctypes.byref(out_cur_iter)))
        return out_cur_iter.value

2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
    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
2028
    def eval(self, data, name, feval=None):
2029
        """Evaluate for data.
wxchan's avatar
wxchan committed
2030
2031
2032

        Parameters
        ----------
2033
2034
2035
2036
2037
        data : Dataset
            Data for the evaluating.
        name : string
            Name of the data.
        feval : callable or None, optional (default=None)
2038
            Customized evaluation function.
2039
            Should accept two parameters: preds, eval_data,
2040
            and return (eval_name, eval_result, is_higher_better) or list of such tuples.
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052

                preds : list or numpy 1-D array
                    The predicted values.
                eval_data : Dataset
                    The evaluation dataset.
                eval_name : string
                    The name of evaluation function.
                eval_result : float
                    The eval result.
                is_higher_better : bool
                    Is eval result higher better, e.g. AUC is ``is_higher_better``.

2053
2054
            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].
2055

wxchan's avatar
wxchan committed
2056
2057
        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
2058
        result : list
2059
            List with evaluation results.
wxchan's avatar
wxchan committed
2060
        """
Guolin Ke's avatar
Guolin Ke committed
2061
2062
        if not isinstance(data, Dataset):
            raise TypeError("Can only eval for Dataset instance")
wxchan's avatar
wxchan committed
2063
2064
2065
2066
        data_idx = -1
        if data is self.train_set:
            data_idx = 0
        else:
wxchan's avatar
wxchan committed
2067
            for i in range_(len(self.valid_sets)):
wxchan's avatar
wxchan committed
2068
2069
2070
                if data is self.valid_sets[i]:
                    data_idx = i + 1
                    break
2071
        # need to push new valid data
wxchan's avatar
wxchan committed
2072
2073
2074
2075
2076
2077
2078
        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):
2079
        """Evaluate for training data.
wxchan's avatar
wxchan committed
2080
2081
2082

        Parameters
        ----------
2083
        feval : callable or None, optional (default=None)
2084
            Customized evaluation function.
2085
2086
            Should accept two parameters: preds, train_data,
            and return (eval_name, eval_result, is_higher_better) or list of such tuples.
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098

                preds : list or numpy 1-D array
                    The predicted values.
                train_data : Dataset
                    The training dataset.
                eval_name : string
                    The name of evaluation function.
                eval_result : float
                    The eval result.
                is_higher_better : bool
                    Is eval result higher better, e.g. AUC is ``is_higher_better``.

2099
2100
            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
2101
2102
2103

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
2104
        result : list
2105
            List with evaluation results.
wxchan's avatar
wxchan committed
2106
2107
2108
2109
        """
        return self.__inner_eval(self.__train_data_name, 0, feval)

    def eval_valid(self, feval=None):
2110
        """Evaluate for validation data.
wxchan's avatar
wxchan committed
2111
2112
2113

        Parameters
        ----------
2114
        feval : callable or None, optional (default=None)
2115
            Customized evaluation function.
2116
            Should accept two parameters: preds, valid_data,
2117
            and return (eval_name, eval_result, is_higher_better) or list of such tuples.
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129

                preds : list or numpy 1-D array
                    The predicted values.
                valid_data : Dataset
                    The validation dataset.
                eval_name : string
                    The name of evaluation function.
                eval_result : float
                    The eval result.
                is_higher_better : bool
                    Is eval result higher better, e.g. AUC is ``is_higher_better``.

2130
2131
            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
2132
2133
2134

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
2135
        result : list
2136
            List with evaluation results.
wxchan's avatar
wxchan committed
2137
        """
wxchan's avatar
wxchan committed
2138
        return [item for i in range_(1, self.__num_dataset)
wxchan's avatar
wxchan committed
2139
                for item in self.__inner_eval(self.name_valid_sets[i - 1], i, feval)]
wxchan's avatar
wxchan committed
2140

2141
    def save_model(self, filename, num_iteration=None, start_iteration=0):
2142
        """Save Booster to file.
wxchan's avatar
wxchan committed
2143
2144
2145

        Parameters
        ----------
2146
2147
        filename : string
            Filename to save Booster.
2148
2149
2150
2151
        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
2152
        start_iteration : int, optional (default=0)
2153
            Start index of the iteration that should be saved.
Nikita Titov's avatar
Nikita Titov committed
2154
2155
2156
2157
2158

        Returns
        -------
        self : Booster
            Returns self.
wxchan's avatar
wxchan committed
2159
        """
2160
        if num_iteration is None:
2161
            num_iteration = self.best_iteration
wxchan's avatar
wxchan committed
2162
2163
        _safe_call(_LIB.LGBM_BoosterSaveModel(
            self.handle,
2164
            ctypes.c_int(start_iteration),
Guolin Ke's avatar
Guolin Ke committed
2165
            ctypes.c_int(num_iteration),
wxchan's avatar
wxchan committed
2166
            c_str(filename)))
2167
        _dump_pandas_categorical(self.pandas_categorical, filename)
Nikita Titov's avatar
Nikita Titov committed
2168
        return self
wxchan's avatar
wxchan committed
2169

2170
    def shuffle_models(self, start_iteration=0, end_iteration=-1):
2171
        """Shuffle models.
Nikita Titov's avatar
Nikita Titov committed
2172

2173
2174
2175
        Parameters
        ----------
        start_iteration : int, optional (default=0)
2176
            The first iteration that will be shuffled.
2177
2178
        end_iteration : int, optional (default=-1)
            The last iteration that will be shuffled.
2179
            If <= 0, means the last available iteration.
2180

Nikita Titov's avatar
Nikita Titov committed
2181
2182
2183
2184
        Returns
        -------
        self : Booster
            Booster with shuffled models.
2185
        """
2186
2187
        _safe_call(_LIB.LGBM_BoosterShuffleModels(
            self.handle,
Guolin Ke's avatar
Guolin Ke committed
2188
2189
            ctypes.c_int(start_iteration),
            ctypes.c_int(end_iteration)))
Nikita Titov's avatar
Nikita Titov committed
2190
        return self
2191
2192
2193
2194
2195
2196

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

        Parameters
        ----------
Nikita Titov's avatar
Nikita Titov committed
2197
        model_str : string
2198
            Model will be loaded from this string.
Nikita Titov's avatar
Nikita Titov committed
2199
2200
        verbose : bool, optional (default=True)
            Whether to print messages while loading model.
2201
2202
2203

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
2204
        self : Booster
2205
2206
            Loaded Booster object.
        """
2207
2208
2209
2210
        if self.handle is not None:
            _safe_call(_LIB.LGBM_BoosterFree(self.handle))
        self._free_buffer()
        self.handle = ctypes.c_void_p()
2211
2212
2213
2214
2215
2216
2217
2218
2219
        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)))
2220
        if verbose:
Nikita Titov's avatar
Nikita Titov committed
2221
            print('Finished loading model, total used %d iterations' % int(out_num_iterations.value))
2222
        self.__num_class = out_num_class.value
2223
        self.pandas_categorical = _load_pandas_categorical(model_str=model_str)
2224
2225
2226
2227
        return self

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

2229
2230
2231
2232
2233
2234
        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
2235
        start_iteration : int, optional (default=0)
2236
2237
2238
2239
            Start index of the iteration that should be saved.

        Returns
        -------
Nikita Titov's avatar
Nikita Titov committed
2240
        str_repr : string
2241
2242
            String representation of Booster.
        """
2243
        if num_iteration is None:
2244
2245
            num_iteration = self.best_iteration
        buffer_len = 1 << 20
2246
        tmp_out_len = ctypes.c_int64(0)
2247
2248
2249
2250
        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,
2251
            ctypes.c_int(start_iteration),
2252
            ctypes.c_int(num_iteration),
2253
            ctypes.c_int64(buffer_len),
2254
2255
2256
            ctypes.byref(tmp_out_len),
            ptr_string_buffer))
        actual_len = tmp_out_len.value
2257
        # if buffer length is not long enough, re-allocate a buffer
2258
2259
2260
2261
2262
        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,
2263
                ctypes.c_int(start_iteration),
2264
                ctypes.c_int(num_iteration),
2265
                ctypes.c_int64(actual_len),
2266
2267
                ctypes.byref(tmp_out_len),
                ptr_string_buffer))
2268
2269
2270
        ret = string_buffer.value.decode()
        ret += _dump_pandas_categorical(self.pandas_categorical)
        return ret
2271

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

2275
2276
        Parameters
        ----------
2277
2278
2279
2280
        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
2281
        start_iteration : int, optional (default=0)
2282
            Start index of the iteration that should be dumped.
2283

wxchan's avatar
wxchan committed
2284
2285
        Returns
        -------
2286
        json_repr : dict
Nikita Titov's avatar
Nikita Titov committed
2287
            JSON format of Booster.
wxchan's avatar
wxchan committed
2288
        """
2289
        if num_iteration is None:
2290
            num_iteration = self.best_iteration
wxchan's avatar
wxchan committed
2291
        buffer_len = 1 << 20
2292
        tmp_out_len = ctypes.c_int64(0)
wxchan's avatar
wxchan committed
2293
2294
2295
2296
        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,
2297
            ctypes.c_int(start_iteration),
Guolin Ke's avatar
Guolin Ke committed
2298
            ctypes.c_int(num_iteration),
2299
            ctypes.c_int64(buffer_len),
wxchan's avatar
wxchan committed
2300
            ctypes.byref(tmp_out_len),
Guolin Ke's avatar
Guolin Ke committed
2301
            ptr_string_buffer))
wxchan's avatar
wxchan committed
2302
        actual_len = tmp_out_len.value
2303
        # if buffer length is not long enough, reallocate a buffer
wxchan's avatar
wxchan committed
2304
2305
2306
2307
2308
        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,
2309
                ctypes.c_int(start_iteration),
Guolin Ke's avatar
Guolin Ke committed
2310
                ctypes.c_int(num_iteration),
2311
                ctypes.c_int64(actual_len),
wxchan's avatar
wxchan committed
2312
                ctypes.byref(tmp_out_len),
Guolin Ke's avatar
Guolin Ke committed
2313
                ptr_string_buffer))
2314
2315
2316
2317
        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
2318

2319
2320
    def predict(self, data, num_iteration=None,
                raw_score=False, pred_leaf=False, pred_contrib=False,
2321
                data_has_header=False, is_reshape=True, **kwargs):
2322
        """Make a prediction.
wxchan's avatar
wxchan committed
2323
2324
2325

        Parameters
        ----------
2326
        data : string, numpy array, pandas DataFrame, H2O DataTable's Frame or scipy.sparse
2327
2328
            Data source for prediction.
            If string, it represents the path to txt file.
2329
2330
2331
2332
        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).
2333
2334
2335
2336
        raw_score : bool, optional (default=False)
            Whether to predict raw scores.
        pred_leaf : bool, optional (default=False)
            Whether to predict leaf index.
2337
2338
        pred_contrib : bool, optional (default=False)
            Whether to predict feature contributions.
2339
2340
2341

            Note
            ----
2342
            If you want to get more explanations for your model's predictions using SHAP values,
2343
            like SHAP interaction values,
2344
2345
2346
            you can install the shap package (https://github.com/slundberg/shap).
            Note that unlike the shap package, with ``pred_contrib`` we return a matrix with an extra
            column, where the last column is the expected value.
2347

2348
2349
2350
2351
2352
        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].
2353
2354
        **kwargs
            Other parameters for the prediction.
wxchan's avatar
wxchan committed
2355
2356
2357

        Returns
        -------
2358
2359
        result : numpy array
            Prediction result.
wxchan's avatar
wxchan committed
2360
        """
2361
        predictor = self._to_predictor(copy.deepcopy(kwargs))
2362
        if num_iteration is None:
2363
            num_iteration = self.best_iteration
2364
2365
2366
        return predictor.predict(data, num_iteration,
                                 raw_score, pred_leaf, pred_contrib,
                                 data_has_header, is_reshape)
wxchan's avatar
wxchan committed
2367

2368
    def refit(self, data, label, decay_rate=0.9, **kwargs):
Guolin Ke's avatar
Guolin Ke committed
2369
2370
2371
2372
        """Refit the existing Booster by new data.

        Parameters
        ----------
2373
        data : string, numpy array, pandas DataFrame, H2O DataTable's Frame or scipy.sparse
Guolin Ke's avatar
Guolin Ke committed
2374
2375
            Data source for refit.
            If string, it represents the path to txt file.
2376
        label : list, numpy 1-D array or pandas Series / one-column DataFrame
Guolin Ke's avatar
Guolin Ke committed
2377
2378
            Label for refit.
        decay_rate : float, optional (default=0.9)
2379
2380
            Decay rate of refit,
            will use ``leaf_output = decay_rate * old_leaf_output + (1.0 - decay_rate) * new_leaf_output`` to refit trees.
2381
2382
        **kwargs
            Other parameters for refit.
2383
            These parameters will be passed to ``predict`` method.
Guolin Ke's avatar
Guolin Ke committed
2384
2385
2386
2387
2388
2389

        Returns
        -------
        result : Booster
            Refitted Booster.
        """
2390
2391
        if self.__set_objective_to_none:
            raise LightGBMError('Cannot refit due to null objective function.')
2392
        predictor = self._to_predictor(copy.deepcopy(kwargs))
2393
        leaf_preds = predictor.predict(data, -1, pred_leaf=True)
2394
        nrow, ncol = leaf_preds.shape
2395
        train_set = Dataset(data, label, silent=True)
2396
2397
2398
        new_params = copy.deepcopy(self.params)
        new_params['refit_decay_rate'] = decay_rate
        new_booster = Booster(new_params, train_set, silent=True)
Guolin Ke's avatar
Guolin Ke committed
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
        # 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)))
2410
2411
        new_booster.network = self.network
        new_booster.__attr = self.__attr.copy()
Guolin Ke's avatar
Guolin Ke committed
2412
2413
        return new_booster

2414
    def get_leaf_output(self, tree_id, leaf_id):
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
        """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.
        """
2429
2430
2431
2432
2433
2434
2435
2436
        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

2437
    def _to_predictor(self, pred_parameter=None):
2438
        """Convert to predictor."""
2439
        predictor = _InnerPredictor(booster_handle=self.handle, pred_parameter=pred_parameter)
2440
        predictor.pandas_categorical = self.pandas_categorical
wxchan's avatar
wxchan committed
2441
2442
        return predictor

2443
    def num_feature(self):
2444
2445
2446
2447
2448
2449
2450
        """Get number of features.

        Returns
        -------
        num_feature : int
            The number of features.
        """
2451
2452
2453
2454
2455
2456
        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
2457
    def feature_name(self):
2458
        """Get names of features.
wxchan's avatar
wxchan committed
2459
2460
2461

        Returns
        -------
2462
2463
        result : list
            List with names of features.
wxchan's avatar
wxchan committed
2464
        """
2465
        num_feature = self.num_feature()
2466
        # Get name of features
wxchan's avatar
wxchan committed
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
        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)]

2478
    def feature_importance(self, importance_type='split', iteration=None):
2479
        """Get feature importances.
2480

2481
2482
        Parameters
        ----------
2483
2484
2485
2486
        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.
2487
2488
2489
2490
        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).
2491

2492
2493
        Returns
        -------
2494
2495
        result : numpy array
            Array with feature importances.
2496
        """
2497
2498
        if iteration is None:
            iteration = self.best_iteration
2499
2500
2501
2502
2503
2504
        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
2505
        result = np.zeros(self.num_feature(), dtype=np.float64)
2506
2507
2508
2509
2510
2511
2512
2513
2514
        _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
2515

2516
2517
2518
2519
2520
2521
2522
2523
2524
    def get_split_value_histogram(self, feature, bins=None, xgboost_style=False):
        """Get split value histogram for the specified feature.

        Parameters
        ----------
        feature : int or string
            The feature name or index the histogram is calculated for.
            If int, interpreted as index.
            If string, interpreted as name.
2525
2526
2527
2528
2529

            Note
            ----
            Categorical features are not supported.

2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
        bins : int, string or None, optional (default=None)
            The maximum number of bins.
            If None, or int and > number of unique split values and ``xgboost_style=True``,
            the number of bins equals number of unique split values.
            If string, it should be one from the list of the supported values by ``numpy.histogram()`` function.
        xgboost_style : bool, optional (default=False)
            Whether the returned result should be in the same form as it is in XGBoost.
            If False, the returned value is tuple of 2 numpy arrays as it is in ``numpy.histogram()`` function.
            If True, the returned value is matrix, in which the first column is the right edges of non-empty bins
            and the second one is the histogram values.

        Returns
        -------
        result_tuple : tuple of 2 numpy arrays
            If ``xgboost_style=False``, the values of the histogram of used splitting values for the specified feature
            and the bin edges.
        result_array_like : numpy array or pandas DataFrame (if pandas is installed)
            If ``xgboost_style=True``, the histogram of used splitting values for the specified feature.
        """
        def add(root):
            """Recursively add thresholds."""
            if 'split_index' in root:  # non-leaf
                if feature_names is not None and isinstance(feature, string_type):
                    split_feature = feature_names[root['split_feature']]
                else:
                    split_feature = root['split_feature']
                if split_feature == feature:
2557
2558
2559
2560
                    if isinstance(root['threshold'], string_type):
                        raise LightGBMError('Cannot compute split value histogram for the categorical feature')
                    else:
                        values.append(root['threshold'])
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
                add(root['left_child'])
                add(root['right_child'])

        model = self.dump_model()
        feature_names = model.get('feature_names')
        tree_infos = model['tree_info']
        values = []
        for tree_info in tree_infos:
            add(tree_info['tree_structure'])

        if bins is None or isinstance(bins, integer_types) and xgboost_style:
            n_unique = len(np.unique(values))
            bins = max(min(n_unique, bins) if bins is not None else n_unique, 1)
        hist, bin_edges = np.histogram(values, bins=bins)
        if xgboost_style:
            ret = np.column_stack((bin_edges[1:], hist))
            ret = ret[ret[:, 1] > 0]
            if PANDAS_INSTALLED:
                return DataFrame(ret, columns=['SplitValue', 'Count'])
            else:
                return ret
        else:
            return hist, bin_edges

wxchan's avatar
wxchan committed
2585
    def __inner_eval(self, data_name, data_idx, feval=None):
2586
        """Evaluate training or validation data."""
wxchan's avatar
wxchan committed
2587
        if data_idx >= self.__num_dataset:
2588
            raise ValueError("Data_idx should be smaller than number of dataset")
wxchan's avatar
wxchan committed
2589
2590
2591
        self.__get_eval_info()
        ret = []
        if self.__num_inner_eval > 0:
2592
            result = np.zeros(self.__num_inner_eval, dtype=np.float64)
Guolin Ke's avatar
Guolin Ke committed
2593
            tmp_out_len = ctypes.c_int(0)
wxchan's avatar
wxchan committed
2594
2595
            _safe_call(_LIB.LGBM_BoosterGetEval(
                self.handle,
Guolin Ke's avatar
Guolin Ke committed
2596
                ctypes.c_int(data_idx),
wxchan's avatar
wxchan committed
2597
                ctypes.byref(tmp_out_len),
Guolin Ke's avatar
Guolin Ke committed
2598
                result.ctypes.data_as(ctypes.POINTER(ctypes.c_double))))
wxchan's avatar
wxchan committed
2599
            if tmp_out_len.value != self.__num_inner_eval:
2600
                raise ValueError("Wrong length of eval results")
wxchan's avatar
wxchan committed
2601
            for i in range_(self.__num_inner_eval):
2602
2603
                ret.append((data_name, self.__name_inner_eval[i],
                            result[i], self.__higher_better_inner_eval[i]))
wxchan's avatar
wxchan committed
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
        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):
2619
        """Predict for training and validation dataset."""
wxchan's avatar
wxchan committed
2620
        if data_idx >= self.__num_dataset:
2621
            raise ValueError("Data_idx should be smaller than number of dataset")
wxchan's avatar
wxchan committed
2622
2623
2624
2625
2626
        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
2627
            self.__inner_predict_buffer[data_idx] = np.zeros(n_preds, dtype=np.float64)
2628
        # avoid to predict many time in one iteration
wxchan's avatar
wxchan committed
2629
2630
        if not self.__is_predicted_cur_iter[data_idx]:
            tmp_out_len = ctypes.c_int64(0)
Guolin Ke's avatar
Guolin Ke committed
2631
            data_ptr = self.__inner_predict_buffer[data_idx].ctypes.data_as(ctypes.POINTER(ctypes.c_double))
wxchan's avatar
wxchan committed
2632
2633
            _safe_call(_LIB.LGBM_BoosterGetPredict(
                self.handle,
Guolin Ke's avatar
Guolin Ke committed
2634
                ctypes.c_int(data_idx),
wxchan's avatar
wxchan committed
2635
2636
2637
                ctypes.byref(tmp_out_len),
                data_ptr))
            if tmp_out_len.value != len(self.__inner_predict_buffer[data_idx]):
2638
                raise ValueError("Wrong length of predict results for data %d" % (data_idx))
wxchan's avatar
wxchan committed
2639
2640
2641
2642
            self.__is_predicted_cur_iter[data_idx] = True
        return self.__inner_predict_buffer[data_idx]

    def __get_eval_info(self):
2643
        """Get inner evaluation count and names."""
wxchan's avatar
wxchan committed
2644
2645
        if self.__need_reload_eval_info:
            self.__need_reload_eval_info = False
Guolin Ke's avatar
Guolin Ke committed
2646
            out_num_eval = ctypes.c_int(0)
2647
            # Get num of inner evals
wxchan's avatar
wxchan committed
2648
2649
2650
2651
2652
            _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:
2653
                # Get name of evals
Guolin Ke's avatar
Guolin Ke committed
2654
                tmp_out_len = ctypes.c_int(0)
wxchan's avatar
wxchan committed
2655
                string_buffers = [ctypes.create_string_buffer(255) for i in range_(self.__num_inner_eval)]
wxchan's avatar
wxchan committed
2656
                ptr_string_buffers = (ctypes.c_char_p * self.__num_inner_eval)(*map(ctypes.addressof, string_buffers))
wxchan's avatar
wxchan committed
2657
2658
2659
2660
2661
                _safe_call(_LIB.LGBM_BoosterGetEvalNames(
                    self.handle,
                    ctypes.byref(tmp_out_len),
                    ptr_string_buffers))
                if self.__num_inner_eval != tmp_out_len.value:
2662
                    raise ValueError("Length of eval names doesn't equal with num_evals")
2663
                self.__name_inner_eval = \
wxchan's avatar
wxchan committed
2664
                    [string_buffers[i].value.decode() for i in range_(self.__num_inner_eval)]
2665
                self.__higher_better_inner_eval = \
2666
                    [name.startswith(('auc', 'ndcg@', 'map@')) for name in self.__name_inner_eval]
2667

wxchan's avatar
wxchan committed
2668
    def attr(self, key):
2669
        """Get attribute string from the Booster.
wxchan's avatar
wxchan committed
2670
2671
2672

        Parameters
        ----------
2673
2674
        key : string
            The name of the attribute.
wxchan's avatar
wxchan committed
2675
2676
2677

        Returns
        -------
2678
2679
        value : string or None
            The attribute value.
Nikita Titov's avatar
Nikita Titov committed
2680
            Returns None if attribute does not exist.
wxchan's avatar
wxchan committed
2681
        """
2682
        return self.__attr.get(key, None)
wxchan's avatar
wxchan committed
2683
2684

    def set_attr(self, **kwargs):
2685
        """Set attributes to the Booster.
wxchan's avatar
wxchan committed
2686
2687
2688
2689

        Parameters
        ----------
        **kwargs
2690
2691
            The attributes to set.
            Setting a value to None deletes an attribute.
Nikita Titov's avatar
Nikita Titov committed
2692
2693
2694
2695

        Returns
        -------
        self : Booster
2696
            Booster with set attributes.
wxchan's avatar
wxchan committed
2697
2698
2699
        """
        for key, value in kwargs.items():
            if value is not None:
wxchan's avatar
wxchan committed
2700
                if not isinstance(value, string_type):
Nikita Titov's avatar
Nikita Titov committed
2701
                    raise ValueError("Only string values are accepted")
wxchan's avatar
wxchan committed
2702
2703
2704
                self.__attr[key] = value
            else:
                self.__attr.pop(key, None)
Nikita Titov's avatar
Nikita Titov committed
2705
        return self