Question

4.1 数据接口

4.1.1 数据格式

1. lightgbm 支持csv,tsv,libsvm 格式的输入数据文件。其中：

   • 可以包含标题
   • 可以指定label列、权重列、query/group id 列
   • 也可以指定一个被忽略的列的列表。

   
   xxxxxxxxxx
   train_data = lgb.Dataset('train.svm.txt')

2. lightgbm 也支持numpy 2d array 以及 pandas 对象。

   
   xxxxxxxxxx
   data = np.random.rand(500, 10)  # 500 个样本, 每一个包含 10 个特征
   label = np.random.randint(2, size=500)  # 二元目标变量,  0 和 1
   train_data = lgb.Dataset(data, label=label)

3. lightgbm 也支持scpiy.sparse.csr_matrix：

   
   xxxxxxxxxx
   csr = scipy.sparse.csr_matrix((dat, (row, col)))
   train_data = lgb.Dataset(csr)

4. lightgbm 可以通过Lightgbm 二进制文件来保存和加载数据。

   
   xxxxxxxxxx
   train_data = lgb.Dataset('train.bin')
   train_data.save_binary('train2.bin')

5. 创建验证集：（要求验证集和训练集的格式一致）

   
   xxxxxxxxxx
   test_data = lgb.Dataset('test.svm', reference=train_data)

   或者：

   
   xxxxxxxxxx
   train_data = lgb.Dataset('train.svm.txt')
   test_data = train_data.create_valid('test.svm')

6. lightgbm 中的 Dataset 对象由于仅仅需要保存离散的数据桶，因此它具有很好的内存效率。

   但是由于numpy array/pandas 对象的内存开销较大，因此当使用它们来创建Dataset 时，你可以通过下面的方式来节省内存：

   • 构造Dataset 时，设置free_raw_data=True
   • 在构造Dataset 之后，手动设置raw_data=True
   • 手动调用gc

7. categorical_feature 的支持：

   • 需要指定categorical_feature 参数
   • 对于categorical_feature特征，首选需要将它转换为整数类型，并且只支持非负数。如果转换为连续的范围更佳。

4.1.2 Dataset

1. Dataset： 由lightgbm 内部使用的数据结构，它存储了数据集。

   
   xxxxxxxxxx
   class lightgbm.Dataset(data, label=None, max_bin=None, reference=None, weight=None,
       group=None, init_score=None, silent=False, feature_name='auto',
       categorical_feature='auto', params=None, free_raw_data=True)

   • 参数：

     • data： 一个字符串、numpy array 或者 scipy.parse， 它指定了数据源。

       如果是字符串，则表示数据源文件的文件名。

     • label： 一个列表、1维的numpy array 或者None， 它指定了样本标记。默认为None。

     • max_bin： 一个整数或者None， 指定每个特征的最大分桶数量。默认为None。

       如果为None，则从配置文件中读取。

     • reference： 一个Dataset 或者 None。 默认为None。

       如果当前构建的数据集用于验证集，则reference 必须传入训练集。否则会报告has different bin mappers。

     • weight： 一个列表、1维的numpy array 或者None， 它指定了样本的权重。默认为None。

     • group： 一个列表、1维的numpy array 或者None， 它指定了数据集的group/query size。默认为None。

     • init_score： 一个列表、1维的numpy array 或者None， 它指定了Booster的初始score 。默认为None。

     • silent： 一个布尔值，指示是否在构建过程中输出信息。默认为False

     • feature_name： 一个字符串列表或者'auto'，它指定了特征的名字。默认为'auto'

       • 如果数据源为pandas DataFrame 并且feature_name='auto'，则使用DataFrame 的 column names

     • categorical_feature： 一个字符串列表、整数列表、或者'auto'。它指定了categorical 特征。默认为'auto'

       • 如果是整数列表，则给定了categorical 特征的下标
       • 如果是字符串列表，在给定了categorical 特征的名字。此时必须设定feature_name 参数。
       • 如果是'auto' 并且数据源为pandas DataFrame，则DataFrame 的 categorical 列将作为categorical 特征

     • params： 一个字典或者None，指定了其它的参数。默认为None

     • free_raw_data： 一个布尔值，指定是否在创建完Dataset 之后释放原始的数据。默认为True

       调用Dataset() 之后，并没有构建完Dataset。 构建完需要等到构造一个Booster 的时候。

2. 方法：

   • .construct()： 延迟初始化函数。它返回当前的Dataset 本身

   • .create_valid(data,label=None,weight=None,group=None,init_score=None,silent=False,params=None)： 创建一个验证集（其格式与当前的Dataset 相同）

     • 参数：参考Dataset 的初始化函数
     • 返回值：当前的Dataset 本身

   • .get_field(field_name)： 获取当前Dataset 的属性

     它要求Dataset 已经构建完毕。否则抛出Cannot get group before construct Dataset 异常。

     • 参数：field_name： 一个字符串，指示了属性的名字
     • 返回值：一个numpy array， 表示属性的值。如果属性不存在则返回None

   • .set_field(field_name,data)： 设置当前Dataset 的属性

     • 参数：

       • field_name： 一个字符串，指示了属性的名字
       • data： 一个列表、numpy array 或者None，表示属性的值

   • .get_group()： 获取当前Dataset 的group

     get_xxx() 等方法，都是调用的 get_field() 方法来实现的

     • 返回值：一个numpy array，表示每个分组的size 。

   • .set_group(group)： 设置当前Dataset 的group

     • 参数：group： 一个列表、numpy array 或者None，表示每个分组的size 。

   • .get_init_score()： 获取当前Dataset 的初始化score

     get_xxx() 等方法，都是调用的 get_field() 方法来实现的

     • 返回值：一个numpy array，表示Booster 的初始化score

   • .set_init_score(init_score)： 设置Booster 的初始化score

     • 参数：init_score： 一个列表、numpy array 或者None，表示Booster的初始化score

   • .get_label()： 获取当前Dataset 的标签

     get_xxx() 等方法，都是调用的 get_field() 方法来实现的

     • 返回值：一个numpy array，表示当前Dataset 的标签信息

   • .set_label(label)： 设置当前Dataset 的标签

     • 参数：label： 一个列表、numpy array 或者None，表示当前Dataset 的标签信息

   • .get_ref_chain(ref_limit=100)： 获取Dataset 对象的reference 链。

     假设d 为一个Dataset 对象，则只要d.reference存在，则获取d.reference；只要d.reference.reference存在，则获取d.reference.reference...

     • 参数：ref_limit： 一个整数，表示链条的最大长度
     • 返回值：一个Dataset 的集合

   • .set_reference(reference)： 设置当前Dataset 的 reference

     • 参数：reference： 另一个Dataset 对象，它作为创建当前Dataset 的模板

   • .get_weight()： 返回Dataset 中每个样本的权重

     get_xxx() 等方法，都是调用的 get_field() 方法来实现的

     • 返回值：一个numpy array，表示当前Dataset 每个样本的权重

   • .set_weight(weight)： 设置Dataset 中每个样本的权重

     • 参数：weight： 一个列表、numpy array 或者None，表示当前Dataset 每个样本的权重

   • .num_data()： 返回Dataset 中的样本数量

   • .num_feature()： 返回Dataset 中的特征数量

   • .save_binary(filename)： 以二进制文件的方式保存Dataset

     • 参数：filename： 保存的二进制文件的文件名

   • .set_categorical_feature(categorical_feature)： 设置categorical 特征

     • 参数：categorical_feature： 一个字符串列表或者整数列表。给出了categorical 特征的名字，或者给出了categorical 特征的下标

   • .set_feature_name(feature_name)： 设置特征名字

     • 参数：feature_name： 一个字符串列表。给出了特征名字

   • .subset(used_indices,params=None)： 获取当前Dataset 的一个子集

     • 参数：

       • used_indices： 一个整数的列表，它给出了当前Dataset 中样本的下标。这些样本将构建子集
       • params： 一个字典或者None，给出了其它的参数。默认为None

     • 返回值：一个新的Dataset 对象。

3. 当你通过 Dataset() 来创建一个 Dataset 对象的时候，它并没有真正的创建必要的数据（必要的数据指的是为训练、预测等准备好的数据），而是推迟到构造一个Booster 的时候。

   因为lightgbm 需要构造bin mappers 来建立子树、建立同一个Booster 内的训练集和验证集（训练集和验证集共享同一个bin mappers、categorical features、feature names）。所以Dataset 真实的数据推迟到了构造Booster 的时候。

   在构建Dataset 之前：

   • get_label()、get_weight()、get_init_score()、get_group()： 等效于self.label、self.weight、self.init_score、self.group

     此时调用 self.get_field(field) 会抛出异常：Cannot get group before construct Dataset

   • set_label()、set_weight()、set_init_score()、set_group()： 等效于self.label=xxx、self.weight=xxx、self.init_score=xxx、self.group=xxx

   • self.num_data()、self._num_feature() 可以从self.data 中获取。

     如果self.data 是 ndarray，则它们就是self.data.shape[0],self.data.shape[1]

4. 示例：

   ​x
   import lightgbm as lgb
   import numpy as np
   class DatasetTest:
     def __init__(self):
       self._matrix1 = lgb.Dataset('data/train.svm.txt')
       self._matrix2 = lgb.Dataset(data=np.arange(0, 12).reshape((4, 3)), 
                                   label=[1, 2, 3, 4], weight=[0.5, 0.4, 0.3, 0.2],
                                   silent=False, feature_name=['a', 'b', 'c'])
     def print(self,matrix):
       '''
       Matrix 构建尚未完成时的属性
       :param matrix:
       :return:
       '''
       print('data: %s' % matrix.data)
       print('label: %s' % matrix.label)
       print('weight: %s' % matrix.weight)
       print('init_score: %s' % matrix.init_score)
       print('group: %s' % matrix.group)
   ​
     def run_method(self,matrix):
       '''
       测试一些 方法
       :param matrix:
       :return:
       '''
       print('get_ref_chain():', matrix.get_ref_chain(ref_limit=10))
       # get_ref_chain(): {<lightgbm.basic.Dataset object at 0x7f29cd762f28>}
       print('subset():', matrix.subset(used_indices=[0,1]))
       # subset(): <lightgbm.basic.Dataset object at 0x7f29a4aeb518>
       
     def test(self):
       self.print(self._matrix1)
       # data: data/train.svm.txt
       # label: None
       # weight: None
       # init_score: None
       # group: None
       
       self.print(self._matrix2)
       # data: [[ 0  1  2]
       #  [ 3  4  5]
       #  [ 6  7  8]
       #  [ 9 10 11]]
       # label: [1, 2, 3, 4]
       # weight: [0.5, 0.4, 0.3, 0.2]
       # init_score: No
       
       self.run_method(self._matrix2)

5. 你要确保你的数据集的样本数足够大，从而满足一些限制条件（如：单个节点的最小样本数、单个桶的最小样本数等）。否则会直接报错。

4.2 模型接口

4.2.1 Booster

1. LightGBM 中的 Booster类：

   
   xxxxxxxxxx
   class lightgbm.Booster(params=None, train_set=None, model_file=None, silent=False)

   参数：

   • params： 一个字典或者None，给出了Booster 的参数。默认为None
   • train_set： 一个Dataset对象或者None，给出了训练集。 默认为None
   • model_file： 一个字符串或者None，给出了model file 的路径。 默认为None
   • silent： 一个布尔值，指示是否在构建过程中打印消息。默认为False

2. 方法：

   • .add_valid(data,name)： 添加一个验证集。

     • 参数：

       • data： 一个Dataset，代表一个验证集
       • name： 一个字符串，表示该验证集的名字。不同的验证集通过名字来区分

   • .attr(key)： 获取属性的值。

     • 参数：key： 一个字符串，表示属性的名字
     • 返回值：该属性的名字。如果属性不存在则返回None

   • .current_iteration()： 返回当前的迭代的index（即迭代的编号）

   • .dump_model(num_iteration=-1)： dump 当前的Booster 对象为json 格式。

     • 参数：num_iteration： 一个整数，指定需要dump 第几轮训练的结果。如果小于0，则最佳迭代步的结果（如果存在的话）将被dump。默认为-1。
     • 返回值：一个字典，它表示dump 之后的json

   • .eval(data,name,feval=None)： 对指定的数据集evaluate

     • 参数：

       • data： 一个Dataset 对象，代表被评估的数据集
       • name： 一个字符串，表示被评估的数据集的名字。不同的验证集通过名字来区分
       • feval： 一个可调用对象或者None， 它表示自定义的evaluation 函数。默认为None。它的输入为(y_true, y_pred)、或者( y_true, y_pred, weight) 、或者(y_true, y_pred, weight, group)， 返回一个元组：(eval_name,eval_result,is_higher_better) 。或者返回该元组的列表。

     • 返回值：一个列表，给出了evaluation 的结果。

   • .eval_train(feval=None)： 对训练集进行evaluate

     • 参数：feval： 参考.eval() 方法
     • 返回值：一个列表，给出了evaluation 的结果。

   • .eval_valid(feval=None)：对验证集进行evaluate

     • 参数：feval： 参考.eval() 方法
     • 返回值：一个列表，给出了evaluation 的结果。

   • .feature_importance(importance_type='split', iteration=-1)： 获取特征的importance

     • 参数：

       • importance_type： 一个字符串，给出了特征的importance衡量指标。默认为'split'。 可以为：

         • 'split'： 此时特征重要性衡量标准为：该特征在所有的树中，被用于划分数据集的总次数。
         • 'gain'： 此时特征重要性衡量标准为：该特征在所有的树中获取的总收益。

       • iteration： 一个整数，指定需要考虑的是第几轮训练的结果。如果小于0，则最佳迭代步的结果（如果存在的话）将被考虑。默认为-1。

     • 返回值：一个numpy array，表示每个特征的重要性

   • .feature_name()： 获取每个特征的名字。

     • 返回值：一个字符串的列表，表示每个特征的名字

   • .free_dataset()：释放Booster 对象的数据集

   • .free_network()： 释放Booster 对象的Network

   • .get_leaf_output(tree_id, leaf_id)： 获取指定叶子的输出

     • 输入：

       • tree_id： 一个整数，表示子学习器的编号
       • leaf_id： 一个整数，表示该子学习器的叶子的编号

     • 返回值：一个浮点数，表示该叶子节点的输出

   • .num_feature()： 获取特征的数量（即由多少列特征）

   • .predict(data, num_iteration=-1, raw_score=False, pred_leaf=False, pred_contrib=False, data_has_header=False, is_reshape=True, pred_parameter=None)： 执行预测

     • 参数：

       • data： 一个字符串、numpy array 或者scipy.sparse， 表示被测试的数据集。如果为字符串，则表示测试集所在的文件的文件名。

         注意：如果是numpy array 或者 pandas dataframe 时，要求数据的列必须与训练时的列顺序一致。

       • num_iteration：一个整数，表示用第几轮的迭代结果来预测。如果小于0，则最佳迭代步的结果（如果存在的话）将被使用。默认为-1。

       • raw_score： 一个布尔值，指示是否输出raw scores。 默认为False

       • pred_leaf： 一个布尔值。如果为True，则会输出每个样本在每个子树的哪个叶子上。它是一个nsample x ntrees 的矩阵。默认为False。

         每个子树的叶节点都是从1 开始编号的。

       • pred_contrib：一个布尔值。如果为True， 则输出每个特征对每个样本预测结果的贡献程度。它是一个nsample x ( nfeature+1) 的矩阵。默认为False。

         之所以加1，是因为有bias 的因素。它位于最后一列。

         其中样本所有的贡献程度相加，就是该样本最终的预测的结果。

       • data_has_header：一个布尔值，指示数据集是否含有标题。仅当data 是字符串时有效。默认为False。

       • is_reshape：一个布尔值，指示是否reshape 结果成[nrow,ncol]。 默认为True

       • pred_parameter： 一个字典或者None，给出了其它的参数。默认为None

     • 返回值：一个numpy array，表示预测结果

   • .reset_parameter(params)：重设Booster 的参数。

     • 参数：params：一个字典，给出了新的参数

   • .rollback_one_iter()： 将Booster 回滚一个迭代步

   • .save_model(filename,num_iteration=-1)： 保存Booster 对象到文件中。

     • 参数：

       • filename： 一个字符串，给出了保存的文件的文件名
       • num_iteration： 一个整数，指定需要保存的是第几轮训练的结果。如果小于0，则最佳迭代步的结果（如果存在的话）将被保存。默认为-1。

   • .set_attr(**kwargs)： 设置Booster 的属性。

     • 参数：kwargs： 关键字参数，用于设定Booster 属性。对于值为None 的设置，等效于删除该属性。

   • .set_network(machines,local_listen_port=12400,listen_time_out=120,num_machines=1)： 配置网络

     • 参数：

       • machines：一个字符串的列表、或者字符串的集合。它给出了每台机器的名字
       • local_listen_port： 一个整数，默认为 12400，指定了监听端口
       • listen_time_out： 一个整数，默认为120， 制定了socket 超时的时间（单位为分钟）
       • num_machines： 一个整数，默认为1，表示并行学习的机器的数量

   • .set_train_data_name(name)： 设置训练集的名字

     • 参数：name： 一个字符串，表示训练集的名字

   • .update(train_set=None, fobj=None)： 更新一个迭代步

     • 参数：

       • train_set： 一个Dataset 或者None， 表示训练集。如果为None，则上一个训练集被使用

       • fobj： 一个可调用对象或者None，表示自定义的目标函数。

         注意：如果是多类别分类任务，则：score 首先根据class_id 进行分组，然后根据row_id 分组。如果你想得到第i 个样本在第j 个类别上的得分，访问方式为：score[j*num_data+i]。 同理：grad 和 hess 也是以这样的方式访问。

     • 返回值：一个布尔值，指示该次更新迭代步是否成功结束。

3. 示例：

   
   xxxxxxxxxx
   _label_map={
     # 'Iris-setosa':0,
     'Iris-versicolor':0,
     'Iris-virginica':1
   }
   class BoosterTest:
     def __init__(self):
       df = pd.read_csv('./data/iris.csv')
       _feature_names = ['Sepal Length', 'Sepal Width', 'Petal Length', 'Petal Width']
       x = df[_feature_names]
       y = df['Class'].map(lambda x: _label_map[x])
   ​
       train_X, test_X, train_Y, test_Y = train_test_split(x, y, test_size=0.3,
                      stratify=y, shuffle=True, random_state=1)
       print([item.shape for item in (train_X, test_X, train_Y, test_Y)])
       self._train_set = lgb.Dataset(data=train_X, label=train_Y, 
                                     feature_name=_feature_names)
       self._validate_set = lgb.Dataset(data=test_X, label=test_Y, 
                                     reference=self._train_set)
       self._booster = lgb.Booster(params={
         'boosting': 'gbdt',
         'verbosity': 1,  # 打印消息
         'learning_rate': 0.1,  # 学习率
         'num_leaves':5,
         'max_depth': 5,
         'objective': 'binary',
         'metric': 'auc',
         'seed': 321,
       },
         train_set=self._train_set)
       self._booster.add_valid(self._validate_set,'validate1')
       self._booster.set_train_data_name('trainAAAAA')
   ​
     def print_attr(self):
       print('feature name:',self._booster.feature_name())
       # feature name: ['Sepal_Length', 'Sepal_Width', 'Petal_Length', 'Petal_Width']
       print('feature nums:', self._booster.num_feature())
       # feature nums: 4
     def test_train(self):
       for i in range(0,4):
         self._booster.update(self._train_set)
         print('after iter:%d'%self._booster.current_iteration())
         print('train eval:',self._booster.eval(self._train_set, name='train'))
         print('test eval:',self._booster.eval(self._validate_set,name='eval'))
      # after iter:1
      # train eval: [('train', 'auc', 0.9776530612244898, True)]
      # test eval: [('eval', 'auc', 0.9783333333333334, True)]
      # after iter:2
      # train eval: [('train', 'auc', 0.9907142857142858, True)]
      # test eval: [('eval', 'auc', 0.9872222222222222, True)]
      # after iter:3
      # train eval: [('train', 'auc', 0.9922448979591837, True)]
      # test eval: [('eval', 'auc', 0.9888888888888889, True)]
      # after iter:4
      # train eval: [('train', 'auc', 0.9922448979591837, True)]
      # test eval: [('eval', 'auc', 0.9888888888888889, True)]
     def test(self):
       self.print_attr()
       self.test_train()

4.2.2 直接学习

1. lightgbm.train() 函数执行直接训练。

   
   xxxxxxxxxx
   lightgbm.train(params, train_set, num_boost_round=100, valid_sets=None,
     valid_names=None, fobj=None, feval=None, init_model=None, feature_name='auto',
     categorical_feature='auto', early_stopping_rounds=None, evals_result=None, 
     verbose_eval=True, learning_rates=None, keep_training_booster=False, callbacks=None)

   参数：

   • params： 一个字典，给出了训练参数

   • train_set： 一个Dataset对象，给出了训练集

   • num_boost_round： 一个整数，给出了boosting iteration 的次数。默认为100

   • valid_sets：一个Dataset 的列表或者None，给出了训练期间用于evaluate的数据集。默认为None

   • valid_names：一个字符串列表或者None， 给出了valid_sets 中每个数据集的名字。默认为None

   • fobj：一个可调用对象或者None，表示自定义的目标函数。默认为None

   • feval：一个可调用对象或者None， 它表示自定义的evaluation 函数。默认为None。它的输入为(y_true, y_pred)、或者( y_true, y_pred, weight) 、或者(y_true, y_pred, weight, group)， 返回一个元组：(eval_name,eval_result,is_higher_better) 。或者返回该元组的列表。

   • init_model：一个字符串或者None，它给出了lightgbm model 保存的文件名，或者Booster实例的名字。后续的训练在该model 或者Booster 实例的基础上继续训练。默认为None

   • feature_name： 一个字符串列表或者'auto'，它指定了特征的名字。默认为'auto'

     • 如果数据源为pandas DataFrame 并且feature_name='auto'，则使用DataFrame 的 column names

   • categorical_feature：一个字符串列表、整数列表、或者'auto'。它指定了categorical 特征。默认为'auto'

     • 如果是整数列表，则给定了categorical 特征的下标
     • 如果是字符串列表，在给定了categorical 特征的名字。此时必须设定feature_name 参数。
     • 如果是'auto' 并且数据源为pandas DataFrame，则DataFrame 的 categorical 列将作为categorical 特征

   • early_stopping_rounds：一个整数或者None，表示验证集的score 在连续多少轮未改善之后就早停。默认为None

     该参数要求至少有一个验证集以及一个metric。

     如果由多个验证集或者多个metric，则对所有的验证集和所有的metric 执行。

     如果发生了早停，则模型会添加一个best_iteration字段。该字段持有了最佳的迭代步。

   • evals_result：一个字典或者None，这个字典用于存储在valid_sets 中指定的所有验证集的所有验证结果。默认为None

   • verbose_eval：一个布尔值或者整数。默认为True

     • 如果是True，则在验证集上每个boosting stage 打印对验证集评估的metric。
     • 如果是整数，则每隔verbose_eval 个 boosting stage 打印对验证集评估的metric。
     • 否则，不打印这些

     该参数要求至少由一个验证集。

   • learning_rates：一个列表、None、 可调用对象。它指定了学习率。默认为None

     • 如果为列表，则它给出了每一个boosting 步的学习率
     • 如果为一个可调用对象，则在每个boosting 步都调用它，从而生成一个学习率
     • 如果为一个数值，则学习率在学习期间都固定为它。

     你可以使用学习率衰减从而生成一个更好的学习率序列。

   • keep_training_booster：一个布尔值，指示训练得到的Booster对象是否还会继续训练。默认为False

     • 如果为False，则返回的booster 对象在返回之前将被转换为_InnerPredictor 。

       当然你也可以将_InnerPredictor 传递给init_model 参数从而继续训练。

   • callbacks：一个可调用对象的列表，或者None。 它给出了在每个迭代步之后需要执行的函数。默认为None

   返回：一个Booster 实例

2. lightgbm.cv() 函数执行交叉验证训练。

   
   xxxxxxxxxx
   lightgbm.cv(params, train_set, num_boost_round=10, folds=None, nfold=5,
       stratified=True, shuffle=True, metrics=None, fobj=None, feval=None,
       init_model=None, feature_name='auto', categorical_feature='auto', 
       early_stopping_rounds=None, fpreproc=None, verbose_eval=None, show_stdv=True,
       seed=0, callbacks=None)

   参数：

   • params： 一个字典，给出了训练参数

   • train_set： 一个Dataset对象，给出了训练集

   • num_boost_round：一个整数，给出了boosting iteration 的次数。默认为10

   • folds：一个生成器、一个迭代器、或者None。 如果是生成器或者迭代器，则其迭代结果为元组：(训练部分样本下标列表,测试部分样本下标列表)，分别给出了每个fold 的训练部分和测试部分的下标。默认为None。

     该参数比其它的拆分参数优先级更高。

   • nfold：一个整数，指定了CV 的数量。默认为5 。

   • stratified：一个布尔值，指示是否进行分层拆分。默认为True 。

   • shuffle：一个布尔值，指示是否在拆分之前先混洗数据。默认为True 。

   • metrics：一个字符串、字符串列表、或者None。 指定在CV 过程中的evaluation metric 。默认为None。

     如果非None，则它会覆盖params 的metric 参数。

   • fobj：参考lightgbm.train()

   • feval：参考lightgbm.train()

   • init_model：参考lightgbm.train()

   • feature_name： 参考lightgbm.train()

   • categorical_feature：参考lightgbm.train()

   • early_stopping_rounds：一个整数或者None，表示CV error在连续多少轮未改善之后就早停。默认为None

     在返回的evaluation history 中，最后一项就是最佳迭代时的结果（而不是最后一次迭代时的结果）。

   • fpreproc：一个可调用对象或者None，默认为None 。 它是一个预处理函数，在训练开始之前进行。

     它的参数为(dtrain,dtest,params)， 返回值是经过处理之后的(dtrain,dtest,params)

   • verbose_eval：参考lightgbm.train()

   • show_stdv：一个布尔值，指示是否在训练过程中展示标准差信息。默认为True。

     注意：返回结果中始终包含标准差信息，与该参数无关。

   • seed：一个整数，给出了生成fold 的随机数种子。默认为0

   • callbacks：参考lightgbm.train()

   返回值：evaluation history， 它是一个字典，格式为：

   
   xxxxxxxxxx
   {
       'metric1-mean': [values], 'metric1-stdv': [values], 
       'metric2-mean': [values], 'metric2-stdv': [values],
       ...
   }

4.2.3 scikit-learn API

4.2.3.1 LGBMModel

1. LGBMModel 实现了lightgbm 类似于scikit-learn 的接口

   
   xxxxxxxxxx
   class lightgbm.LGBMModel(boosting_type='gbdt', num_leaves=31, max_depth=-1,
      learning_rate=0.1, n_estimators=10, max_bin=255, subsample_for_bin=200000,
      objective=None, min_split_gain=0.0, min_child_weight=0.001, min_child_samples=20,
      subsample=1.0, subsample_freq=1, colsample_bytree=1.0, reg_alpha=0.0,
      reg_lambda=0.0, random_state=None, n_jobs=-1, silent=True,class_weight=None,
      **kwargs)

   参数：

   • boosting_type： 一个字符串，指定了基学习器的算法。默认为'gbdt'。 可以为：

     • 'gbdt'： 表示传统的梯度提升决策树。默认值为'gbdt'
     • 'rf'： 表示随机森林。
     • 'dart'： 表示带dropout 的gbdt
     • goss：表示Gradient-based One-Side Sampling 的gbdt

   • num_leaves：一个整数，给出了一棵树上的叶子数。默认为 31

   • max_depth：一个整数，限制了树模型的最大深度，默认值为-1。

     • 如果小于0，则表示没有限制。

   • learning_rate： 一个浮点数，给出了学习率。默认为 0.1

   • n_estimators：一个整数，给出了boosted trees 的数量。默认为 10

   • max_bin： 一个整数， 指定每个特征的最大分桶数量。默认为255。

   • class_weight：给出了每个类别的权重占比。

     • 可以为字符串'balanced'，此时类别权重反比与类别的频率。
     • 可以为字典，此时人工给出了每个类别的权重。
     • 如果为None，则认为每个类别的比例一样。

     该参数仅用于多类分类问题。对于二类分类问题，可以使用is_unbalance 参数。

   • subsample_for_bin：一个整数，表示用来构建直方图的样本的数量。默认为200000。

   • objective： 一个字符串、可调用对象或者为None，表示问题类型以及对应的目标函数。参考2.2.1 核心参数->objective 。

     默认为None ，此时对于LGBMRegressor 为'regression'；对于LGBMClassifier 为'binary' 或者'multiclass'；对于LGBMRanker 为'lambdarank'。

     如果为自定义的可调用对象，则它的签名为：objective(y_true, y_pred) -> grad, hess ；或者签名为：objective(y_true, y_pred, group) -> grad, hess。其中：

     • y_true： 一个形状为(n_samples,)（对于多类分类问题，则是(n_samples,n_classes)） 的array-like 对象，给出了真实的标签值。
     • y_pred： 一个形状为(n_samples,) （对于多类分类问题，则是(n_samples,n_classes)）的array-like 对象，给出了预测的标签值。
     • group： 一个array-like对象，给出了数据的分组信息。它用于ranking 任务
     • grad：一个形状为(n_samples,)（对于多类分类问题，则是(n_samples,n_classes)） 的array-like 对象，给出了每个样本的梯度值。
     • hess：一个形状为(n_samples,)（对于多类分类问题，则是(n_samples,n_classes)） 的array-like 对象，给出了每个样本的二阶导数值。

   • min_split_gain：一个浮点数，表示执行切分的最小增益，默认为0

   • min_child_weight：一个浮点数，表示一个叶子节点上的最小hessian 之和。（也就是叶节点样本权重之和的最小值） 默认为1e-3 。

   • min_child_samples： 一个整数，表示一个叶子节点上包含的最少样本数量。默认值为 20

   • subsample： 一个浮点数，表示训练样本的采样比例。参考2.2.2 学习控制参数->subsample 。

   • subsample_freq：一个浮点数，表示训练样本的采样频率。参考2.2.2 学习控制参数->subsample_freq 。

   • colsample_bytree：一个浮点数，表示特征的采样比例。参考2.2.2 学习控制参数->colsample_bytree 。

   • reg_alpha： 一个浮点数，表示L1正则化系数。默认为0

   • reg_lambda：一个浮点数，表示L2正则化系数。默认为0

   • random_state：一个整数或者None，表示随机数种子。如果为None，则使用默认的种子。默认为None

   • n_jobs：一个整数，指定并行的线程数量。如果为-1，则表示使用所有的CPU。默认为-1

   • silent：一个布尔值，指示是否在训练过程中屏蔽输出。默认为True。

   • kwargs：其它的参数。

2. 属性：

   • .n_features_：一个整数，给出了特征的数量
   • .classes_：一个形状为(n_classes,) 的numpy array， 给出了样本的标签。（仅仅在分类问题中有效）
   • .n_classes_：一个整数，给出了类别的数量。（仅仅在分类问题中有效）
   • .best_score_：一个字典或者None，给出了训练完毕模型的最好的score
   • .best_iteration_：一个字典或者None。当early_stopping_round 参数设定时，它给出了训练完毕模型的最好的迭代步。
   • .objective_：一个字符串或者可调用对象，给出了训练模型的目标函数
   • .booster_：一个Booster对象，给出了底层的Booster 对象。
   • .evals_result_：一个字典或者None。当early_stopping_round 参数设定时，它给出了模型的evaluation results 。
   • .feature_importances_： 一个形状为(n_features,) 的 numpy array，给出了特征的重要性（值越大，则对于的特征越重要）。

3. 方法：

   • .apply(X,num_iteration=0)： 预测每个样本在每个树的哪个叶节点上。

     • 参数：

       • X： 一个array-like 对象，或者一个sparse matrix， 其形状为(n_samples,n_features) ，表示测试样本集
       • num_iteration： 一个整数，指示在预测时，使用多少个子树。默认为0，表示使用所有的子树。

     • 返回值：一个array-like对象，形状为(n_samples,n_trees)。 它给出了每个样本在每个子树的哪个节点上。

   • .fit()： 训练模型。

     
     xxxxxxxxxx
     .fit(X, y, sample_weight=None, init_score=None, group=None, eval_set=None,
         eval_names=None, eval_sample_weight=None, eval_init_score=None,
         eval_group=None, eval_metric=None, early_stopping_rounds=None, verbose=True,
         feature_name='auto', categorical_feature='auto', callbacks=None)

     参数：

     • X： 一个array-like 对象，或者一个sparse matrix， 其形状为(n_samples,n_features) ，表示训练样本集

     • y： 一个array-like对象，形状为(n_samples,)，给出了标签值。

     • sample_weight：一个形状为(n_samples,) 的array-like 对象，或者为None。给出了每个训练样本的权重。默认为None

     • init_score： 一个形状为(n_samples,) 的array-like 对象，或者为None。给出了每个训练样本的init score 。默认为None

     • group： 一个形状为(n_samples,) 的array-like 对象，或者为None。给出了每个训练样本的分组。默认为None

     • eval_set：一个元素为(X,y) 的列表，或者None。 给出了验证集，用于早停。默认为None。

       其中X,y 的类型与参数X,y 相同。

     • eval_names：一个字符串的列表，或者None。给出了每个验证集的名字。默认为None。

     • eval_sample_weight：一个array-like 的列表，或者None。 给出了每个验证集中，每个样本的权重。默认为None。

     • eval_init_score：一个array-like 的列表，或者None。 给出了每个验证集中，每个样本的init score。默认为None。

     • eval_group：一个array-like 的列表，或者None。 给出了每个验证集中，每个样本的分组。默认为None。

     • eval_metric：一个字符串、字符串列表、可调用对象、或者None。 给出了验证的metric。默认为None。

     • early_stopping_rounds：一个整数或者None，默认为None。参考lightgbm.train()

     • verbose： 一个布尔值。如果为True，并且至少有一个验证集，则输出evaluation 信息。

     • feature_name：一个字符串列表、或者'auto'。参考lightgbm.train()

     • categorical_feature：一个字符串列表、整数、或者'auto'。参考lightgbm.train()

     • callbacks：一个可调用对象的列表或者为None 。参考lightgbm.train()

     返回值：self，即当前LGBMModel 对象自己

   • .predict(X,raw_score=False,num_iteration=0)： 执行预测。

     参数：

     • X： 一个array-like 对象，或者一个sparse matrix， 其形状为(n_samples,n_features) ，表示测试样本集。

       注意：如果是numpy array 或者 pandas dataframe 时，要求数据的列必须与训练时的列顺序一致。

     • raw_score：一个布尔值，指示是否输出raw score。 默认为False

     • num_iteration：一个整数，指示在预测时，使用多少个子树。默认为0，表示使用所有的子树。

     返回值：一个形状为(n_samples,) 或者形状为(n_samples,n_classed) 的array-like 对象，表示预测结果

4.2.3.2 LGBMClassifier

1. LGBMClassifier 是LGBMModel 的子类，它用于分类任务。

   
   xxxxxxxxxx
   class lightgbm.LGBMClassifier(boosting_type='gbdt', num_leaves=31, max_depth=-1,
      learning_rate=0.1, n_estimators=10, max_bin=255, subsample_for_bin=200000,
      objective=None, min_split_gain=0.0, min_child_weight=0.001, min_child_samples=20, 
      subsample=1.0, subsample_freq=1, colsample_bytree=1.0, reg_alpha=0.0,
      reg_lambda=0.0, random_state=None, n_jobs=-1, silent=True, **kwargs)

   参数：参考LGBMModel

2. 属性：参考LGBMModel

3. 方法：

   • .fit()： 训练模型

     
     xxxxxxxxxx
     fit(X, y, sample_weight=None, init_score=None, eval_set=None, eval_names=None,
         eval_sample_weight=None, eval_init_score=None, eval_metric='logloss',
         early_stopping_rounds=None, verbose=True, feature_name='auto',
         categorical_feature='auto', callbacks=None)

     参数：参考LGBMModel.fit()

     返回值：参考LGBMModel.fit()

   • .predict_proba(X, raw_score=False, num_iteration=0)：预测每个样本在每个类上的概率。

     参数：参考LGBMModel.predict()

     返回值：一个形状为(n_samples,n_classes) 的array-like 对象，给出了每个样本在每个类别上的概率。

   • 其它方法参考LGBMModel

4.2.3.3 LGBMRegressor

1. LGBMRegressor 是LGBMModel 的子类，它用于回归任务。

   
   xxxxxxxxxx
   class lightgbm.LGBMRegressor(boosting_type='gbdt', num_leaves=31, max_depth=-1, 
      learning_rate=0.1, n_estimators=10, max_bin=255, subsample_for_bin=200000,
      objective=None, min_split_gain=0.0, min_child_weight=0.001, min_child_samples=20,
      subsample=1.0, subsample_freq=1, colsample_bytree=1.0, reg_alpha=0.0,
      reg_lambda=0.0, random_state=None, n_jobs=-1, silent=True, **kwargs)

   参数：参考LGBMModel

2. 属性：参考LGBMModel

3. 方法：

   • .fit()： 训练模型

     
     xxxxxxxxxx
     fit(X, y, sample_weight=None, init_score=None, eval_set=None, eval_names=None,
         eval_sample_weight=None, eval_init_score=None, eval_metric='l2',
         early_stopping_rounds=None, verbose=True, feature_name='auto',
         categorical_feature='auto', callbacks=None)

     参数：参考LGBMModel.fit()

     返回值：参考LGBMModel.fit()

   • 其它方法参考LGBMModel

4.2.3.4 LGBMRanker

1. LGBMRegressor 是LGBMModel 的子类，它用于ranking 任务。

   
   xxxxxxxxxx
   class lightgbm.LGBMRanker(boosting_type='gbdt', num_leaves=31, max_depth=-1, 
      learning_rate=0.1, n_estimators=10, max_bin=255, subsample_for_bin=200000,
      objective=None, min_split_gain=0.0, min_child_weight=0.001, min_child_samples=20,
      subsample=1.0, subsample_freq=1, colsample_bytree=1.0, reg_alpha=0.0,
      reg_lambda=0.0, random_state=None, n_jobs=-1, silent=True, **kwargs)

   参数：参考LGBMModel

2. 属性：参考LGBMModel

3. 方法：

   • .fit()： 训练模型

     
     xxxxxxxxxx
     fit(X, y, sample_weight=None, init_score=None, group=None, eval_set=None,
         eval_names=None, eval_sample_weight=None, eval_init_score=None,
         eval_group=None, eval_metric='ndcg', eval_at=[1], early_stopping_rounds=None, 
         verbose=True, feature_name='auto', categorical_feature='auto', callbacks=None)

     参数：

     • eval_at：一个整数列表，给出了NDCG 的evaluation position 。默认为[1] 。
     • 其它参数参考LGBMModel.fit()

     返回值：参考LGBMModel.fit()

   • 其它方法参考LGBMModel

4.2.3.5 Callbacks

1. 这里介绍的callback 生成一些可调用对象，它们用于LGBMModel.fit() 方法的 callbacks 参数。

2. lightgbm.early_stopping(stopping_rounds,verbose=True)： 创建一个回调函数，它用于触发早停。

   触发早停时，要求至少由一个验证集以及至少有一种评估指标。如果由多个，则将它们都检查一遍。

   参数：

   • stopping_rounds：一个整数。如果一个验证集的度量在early_stopping_round 循环中没有提升，则停止训练。如果为0则表示不开启早停。
   • verbose：一个布尔值。是否打印早停的信息。

   返回值：一个回调函数。

3. lightgbm.print_evaluation(period=1,show_stdv=True)： 创建一个回调函数，它用于打印evaluation 的结果。

   参数：

   • period： 一个整数，默认为1。给出了打印evaluation 的周期。默认每个周期都打印。
   • show_stdv： 一个不热值，默认为True。 指定是否打印标准差的信息（如果提供了标准差的话）。

   返回值：一个回调函数。

4. lightgbm.record_evaluation(eval_result)： 创建一个回调函数，它用于将evaluation history 写入到 eval_result 中。

   参数：eval_result： 一个字典，它将用于存放evaluation history。

   返回值：一个回调函数。

5. lightgbm.reset_parameter(**kwargs)：创建一个回调函数，它用于在第一次迭代之后重新设置参数。

   注意：当第一次迭代时，初始的参数仍然发挥作用。

   参数：

   • kwargs：一些关键字参数（如key=val） ，每个关键字参数的值必须是一个列表或者一个函数。给出了每一个迭代步的相应参数。

     • 如果是列表，则current_round 迭代时的参数为：val[current_round]
     • 如果是函数，则current_round 迭代时的参数值为：val(current_round)

   返回值：一个回调函数。

4.4 绘图API

1. lightgbm.plot_importance()： 绘制特征的重要性。

   
   xxxxxxxxxx
   lightgbm.plot_importance(booster, ax=None, height=0.2, xlim=None, ylim=None, 
       title='Feature importance', xlabel='Feature importance', ylabel='Features',
       importance_type='split', max_num_features=None, ignore_zero=True, 
       figsize=None, grid=True, **kwargs)

   参数：

   • booster： 一个Booster 或者LGBMModel 对象。即将绘制的就是该对象的特征的重要性

   • ax：一个matplotlib.axes.Axes 实例或者None。 它制定了绘制图形的Axes。

     如果为None，则创建一个新的figure以及axes。 默认为None。

   • height： 一个浮点数，给出了bar 的高度（将被传递给ax.barh() 方法） 。默认为0.2

   • xlim： 一个二元元组或者None， 给出了x 轴的范围（将被传递给ax.xlim() 方法）。 默认为None

   • ylim： 一个二元元组或者None， 给出了y 轴的范围（将被传递给ax.ylim() 方法）。 默认为None

   • title： 一个字符串或者None，给出了Axes 的标题。默认为Feature importance 。

     如果为None，则没有标题。

   • xlabel： 一个字符串或者None，给出了X轴的标题。默认为Feature importance 。

     如果为None，则没有标题。

   • ylabel： 一个字符串或者None，给出了Y 的标题。默认为Features 。

     如果为None，则没有标题。

   • importance_type： 一个字符串，给出了如何计算出重要性的。默认为'split'。 参考lightgbm.Booster.feature_importance() 方法

   • max_num_features： 一个整数或者None， 给出了最多展示多少个特征的重要性。默认为None 。

     如果为None 或者小于1 的整数，则展示所有的。

   • ignore_zero： 一个布尔值，指定是否忽略为0 的特征。默认为True 。

   • figsize： 一个二元的元组或者None，指定了图像的尺寸。默认为None

   • grid：一个布尔值，指示是否添加网格。默认为True

   • kwargs： 其它的关键字参数。它将被传递给ax.barh() 方法。

   返回值：一个matplotlib.axes.Axes 对象，它就是传入的ax 本身。

2. lightgbm.plot_metric()： 在训练过程中绘制一个metric

   
   xxxxxxxxxx
   lightgbm.plot_metric(booster, metric=None, dataset_names=None, ax=None, 
         xlim=None, ylim=None, title='Metric during training', 
         xlabel='Iterations', ylabel='auto', figsize=None, grid=True)

   参数：

   • booster：一个字典或者一个LGBMModel 实例。

     • 如果是一个字典，则它是由lightgbm.train() 返回的字典

   • metric：一个字符串或者None，指定了要绘制的metric 的名字。如果为None， 则从字典中取出第一个metric（根据hashcode的顺序）。默认为None。

     只支持绘制一个metric，因为不同的metric 无法绘制在一张图上（不同的metric 有不同的量级）。

   • dataset_names： 一个字符串列表，或者None。 它给出了用于计算metric 的样本集的名字。如果为None，则使用所有的样本集。默认为None。

   • title： 一个字符串或者None，给出了Axes 的标题。默认为Metric during training 。

     如果为None，则没有标题。

   • xlabel： 一个字符串或者None，给出了X轴的标题。默认为Iterations 。

     如果为None，则没有标题。

   • ylabel： 一个字符串或者None，给出了Y 的标题。默认为auto 。

     • 如果为None，则没有标题。
     • 如果为'auto'，则使用metric 的名字。

   • 其它参数：参考lightgbm.plot_importance()

   返回值：一个matplotlib.axes.Axes 对象，它就是传入的ax 本身。

3. lightgbm.plot_tree()：绘制指定的树模型。

   
   xxxxxxxxxx
   lightgbm.plot_tree(booster, ax=None, tree_index=0, figsize=None, 
        graph_attr=None, node_attr=None, edge_attr=None, show_info=None)

   参数：

   • booster： 一个Booster 或者LGBMModel 对象。即将绘制的就是该对象的树模型。
   • tree_index： 一个整数，指定要绘制哪棵树。默认为0。
   • graph_attr： 一个字典或者None， 给出了graphviz graph 的属性。默认为None
   • node_attr： 一个字典或者None， 给出了graphviz node 的属性。默认为None
   • edge_attr： 一个字典或者None， 给出了graphviz edge 的属性。默认为None
   • show_info： 一个列表或者None， 给出了将要在graph node 中显示哪些信息。可以为：'split_gain', 'internal_value', internal_count', leaf_count' 。默认为None。
   • 其它参数： 参考lightgbm.plot_importance()

   返回值：一个matplotlib.axes.Axes 对象，它就是传入的ax 本身。

4. lightgbm.create_tree_digraph()： 绘制指定的树模型，但是返回一个digraph，而不是直接绘制。

   
   xxxxxxxxxx
   lightgbm.create_tree_digraph(booster, tree_index=0, show_info=None, name=None,
       comment=None, filename=None, directory=None, format=None, engine=None,
       encoding=None, graph_attr=None, node_attr=None, edge_attr=None, 
       body=None, strict=False)

   参数：

   • booster： 一个Booster 或者LGBMModel 对象。即将绘制的就是该对象的树模型。
   • name： 一个字符串或者None。 给出了graphviz源文件的名字 。 默认为None。
   • comment： 一个字符串或者None。 给出了添加到 graphviz 源文件第一行的评论 。 默认为None。
   • filename：一个字符串或者None。 给出了保存graphviz 源文件的名字。如果为None，则是name+'.gv' 。默认为None
   • directory： 一个字符串或者None，给出了保存和渲染graphviz 文件的目录。默认为None
   • format： 一个字符串或者None， 表示输出图片的格式。可以为'png','pdf',...。默认为None
   • engine： 一个字符串或者None， 制定了graphviz 的排版引擎。可以为'dot','neato',...。 。默认为None
   • encoding： 一个字符串或者None， 指定了graphviz 源文件的编码。默认为None
   • body： 一个字符列表或者None， 给出了添加到grapviz graph body 中的线条。默认为None
   • strict： 一个布尔值，指示是否应该合并multi-edges 。默认为False。
   • 其它参数： 参考lightgbm.plot_tree()

   返回值：一个graphviz.Digraph 对象，代表指定的树模型的digraph 。

4.5 Booster API 转换

1. 从 LGBMModel 转换到Booster：通过.booster_ 属性来获取底层的Booster。

   源码：

   
   xxxxxxxxxx
   @property
   def booster_(self):
       """Get the underlying lightgbm Booster of this model."""
       if self._Booster is None:
         raise LGBMNotFittedError('No booster found. Need to call fit beforehand.')
         return self._Booster

   • 用途：当使用scikit-learn API 学习到一个模型之后，需要保存模型。则需要先转换成Booster 对象，再调用其.save_model() 方法。

2. 使用 Booster 来预测分类的概率：

   • 因为Booster 仅仅提供了predict 接口，而未提供predict_proba 接口。因此需要使用这种转换

   • 在LGBMClassifier 的 predict_proba 方法中的源码：

     
     xxxxxxxxxx
     class_probs = self.booster_.predict(X, raw_score=raw_score, num_iteration=num_iteration)
     if self._n_classes > 2:return class_probs
     else:return np.vstack((1. - class_probs, class_probs)).transpose()

   ​