lightgbm.Booster

class lightgbm.Booster(params=None, train_set=None, model_file=None, model_str=None)

基类: object

LightGBM 中的 Booster。

__init__(params=None, train_set=None, model_file=None, model_str=None)

初始化 Booster。

参数:

• params (dict 或 None, 可选 (默认=None)) – Booster 的参数。

• train_set (Dataset 或 None, 可选 (默认=None)) – 训练数据集。

• model_file (str, pathlib.Path 或 None, 可选 (默认=None)) – 模型文件的路径。

• model_str (str 或 None, 可选 (默认=None)) – 将从该字符串加载模型。

方法

__init__([params, train_set, model_file, ...])	初始化 Booster。
add_valid(data, name)	添加验证数据。
current_iteration()	获取当前迭代的索引。
dump_model([num_iteration, start_iteration, ...])	将 Booster 导出为 JSON 格式。
eval(data, name[, feval])	评估数据。
eval_train([feval])	评估训练数据。
eval_valid([feval])	评估验证数据。
feature_importance([importance_type, iteration])	获取特征重要性。
feature_name()	获取特征名称。
free_dataset()	释放 Booster 的数据集。
free_network()	释放 Booster 的网络。
get_leaf_output(tree_id, leaf_id)	获取叶节点的输出。
get_split_value_histogram(feature[, bins, ...])	获取指定特征的分割值直方图。
lower_bound()	获取模型的下界值。
model_from_string(model_str)	从字符串加载 Booster。
model_to_string([num_iteration, ...])	将 Booster 保存为字符串。
num_feature()	获取特征数量。
num_model_per_iteration()	获取每次迭代的模型数量。
num_trees()	获取弱子模型的数量。
predict(data[, start_iteration, ...])	进行预测。
refit(data, label[, decay_rate, reference, ...])	使用新数据重新训练现有 Booster。
reset_parameter(params)	重置 Booster 的参数。
rollback_one_iter()	回滚一次迭代。
save_model(filename[, num_iteration, ...])	将 Booster 保存到文件。
set_leaf_output(tree_id, leaf_id, value)	设置叶节点的输出。
set_network(machines[, local_listen_port, ...])	设置网络配置。
set_train_data_name(name)	为训练数据集设置名称。
shuffle_models([start_iteration, end_iteration])	打乱模型顺序。
trees_to_dataframe()	解析已拟合的模型并以易于阅读的 pandas DataFrame 格式返回。
update([train_set, fobj])	更新 Booster 一次迭代。
upper_bound()	获取模型的上界值。

add_valid(data, name)

添加验证数据。

参数:

• data (Dataset) – 验证数据。

• name (str) – 验证数据的名称。

返回值:

self – 设置了验证数据的 Booster。

返回类型:

Booster

current_iteration()

获取当前迭代的索引。

返回值:

cur_iter – 当前迭代的索引。

返回类型:

int

dump_model(num_iteration=None, start_iteration=0, importance_type='split', object_hook=None)

将 Booster 导出为 JSON 格式。

参数:

• num_iteration (int 或 None, 可选 (默认=None)) – 应导出的迭代索引。如果为 None，则如果存在最佳迭代，则导出最佳迭代；否则，导出所有迭代。如果 <= 0，则导出所有迭代。

• start_iteration (int, 可选 (默认=0)) – 应导出的迭代起始索引。

• importance_type (str, 可选 (默认="split")) – 应导出的特征重要性类型。如果为 “split”，结果包含特征在模型中被使用的次数。如果为 “gain”，结果包含使用该特征进行分割的总增益。

• object_hook (callable 或 None, 可选 (默认=None)) – 如果不为 None，则 object_hook 是在解析 C API 返回的 JSON 字符串时调用的函数。它可用于修改 JSON，在构建 JSON 结构时存储特定值。这避免了再次遍历结构。如果树的数量巨大，这将节省大量时间。函数签名是 def object_hook(node: dict) -> dict。None 等同于 lambda node: node。有关更多详细信息，请参阅 json.loads() 的文档。

返回值:

json_repr – Booster 的 JSON 格式。

返回类型:

dict

eval(data, name, feval=None)

评估数据。

参数:

• data (Dataset) – 用于评估的数据。

• name (str) – 数据的名称。

• feval (callable, callable 列表, 或 None, 可选 (默认=None)) –

  自定义评估函数。每个评估函数应接受两个参数：preds、eval_data，并返回 (eval_name, eval_result, is_higher_better) 或此类元组的列表。

  predsnumpy 1-D 数组 或 numpy 2-D 数组 (用于多分类任务)

  预测值。对于多分类任务，preds 是形状为 [n_samples, n_classes] 的 numpy 2-D 数组。如果使用自定义目标函数，预测值在任何转换之前返回，例如，在这种情况下，对于二分类任务，它们是原始 margin 而不是正类的概率。

  eval_dataDataset

  要评估的 Dataset。

  eval_namestr

  评估函数的名称（无空格）。

  eval_resultfloat

  评估结果。

  is_higher_betterbool

  评估结果是否越高越好，例如 AUC 是 is_higher_better。

返回值:

result – 包含 (dataset_name, eval_name, eval_result, is_higher_better) 元组的列表。

返回类型:

list

eval_train(feval=None)

评估训练数据。

参数:

feval (callable, callable 列表, 或 None, 可选 (默认=None)) –

自定义评估函数。每个评估函数应接受两个参数：preds、eval_data，并返回 (eval_name, eval_result, is_higher_better) 或此类元组的列表。

predsnumpy 1-D 数组 或 numpy 2-D 数组 (用于多分类任务)

预测值。对于多分类任务，preds 是形状为 [n_samples, n_classes] 的 numpy 2-D 数组。如果使用自定义目标函数，预测值在任何转换之前返回，例如，在这种情况下，对于二分类任务，它们是原始 margin 而不是正类的概率。

eval_dataDataset

训练数据集。

eval_namestr

评估函数的名称（无空格）。

eval_resultfloat

评估结果。

is_higher_betterbool

评估结果是否越高越好，例如 AUC 是 is_higher_better。

返回值:

result – 包含 (train_dataset_name, eval_name, eval_result, is_higher_better) 元组的列表。

返回类型:

list

eval_valid(feval=None)

评估验证数据。

参数:

feval (callable, callable 列表, 或 None, 可选 (默认=None)) –

自定义评估函数。每个评估函数应接受两个参数：preds、eval_data，并返回 (eval_name, eval_result, is_higher_better) 或此类元组的列表。

predsnumpy 1-D 数组 或 numpy 2-D 数组 (用于多分类任务)

预测值。对于多分类任务，preds 是形状为 [n_samples, n_classes] 的 numpy 2-D 数组。如果使用自定义目标函数，预测值在任何转换之前返回，例如，在这种情况下，对于二分类任务，它们是原始 margin 而不是正类的概率。

eval_dataDataset

验证数据集。

eval_namestr

评估函数的名称（无空格）。

eval_resultfloat

评估结果。

is_higher_betterbool

评估结果是否越高越好，例如 AUC 是 is_higher_better。

返回值:

result – 包含 (validation_dataset_name, eval_name, eval_result, is_higher_better) 元组的列表。

返回类型:

list

feature_importance(importance_type='split', iteration=None)

获取特征重要性。

参数:

• importance_type (str, 可选 (默认="split")) – 如何计算重要性。如果为 “split”，结果包含特征在模型中被使用的次数。如果为 “gain”，结果包含使用该特征进行分割的总增益。

• iteration (int 或 None, 可选 (默认=None)) – 限制特征重要性计算中的迭代次数。如果为 None，则如果存在最佳迭代，则使用最佳迭代；否则，使用所有树。如果 <= 0，则使用所有树（无限制）。

返回值:

result – 包含特征重要性的数组。

返回类型:

numpy array

feature_name()

获取特征名称。

返回值:

result – 包含特征名称的列表。

返回类型:

str 列表

free_dataset()

释放 Booster 的数据集。

返回值:

self – 不含数据集的 Booster。

返回类型:

Booster

free_network()

释放 Booster 的网络。

返回值:

self – 网络已释放的 Booster。

返回类型:

Booster

get_leaf_output(tree_id, leaf_id)

获取叶节点的输出。

参数:

• tree_id (int) – 树的索引。

• leaf_id (int) – 树中叶节点的索引。

返回值:

result – 叶节点的输出。

返回类型:

float

get_split_value_histogram(feature, bins=None, xgboost_style=False)

获取指定特征的分割值直方图。

参数:

• feature (int 或 str) –

  计算直方图的特征名称或索引。如果为 int，则解释为索引。如果为 str，则解释为名称。

  警告

  不支持分类特征。

• bins (int, str 或 None, 可选 (默认=None)) – 最大 bin 数。如果为 None，或者为 int 且 > 唯一分割值的数量且 xgboost_style=True，则 bin 数等于唯一分割值的数量。如果为 str，则应是 numpy.histogram() 函数支持的值列表中的一个。

• xgboost_style (bool, 可选 (默认=False)) – 返回结果是否应与 XGBoost 中的形式相同。如果为 False，返回值为 numpy.histogram() 函数中返回的 2 个 numpy 数组的元组。如果为 True，返回值为矩阵，其中第一列是非空 bin 的右边缘，第二列是直方图值。

返回值:

• result_tuple (2 个 numpy 数组的元组) – 如果 xgboost_style=False，返回指定特征已使用的分割值的直方图值和 bin 边缘。

• result_array_like (numpy 数组 或 pandas DataFrame (如果安装了 pandas)) – 如果 xgboost_style=True，返回指定特征已使用的分割值的直方图。

lower_bound()

获取模型的下界值。

返回值:

lower_bound – 模型的下界值。

返回类型:

float

model_from_string(model_str)

从字符串加载 Booster。

参数:

model_str (str) – 将从该字符串加载模型。

返回值:

self – 已加载的 Booster 对象。

返回类型:

Booster

model_to_string(num_iteration=None, start_iteration=0, importance_type='split')

将 Booster 保存为字符串。

参数:

• num_iteration (int 或 None, 可选 (默认=None)) – 应保存的迭代索引。如果为 None，则如果存在最佳迭代，则保存最佳迭代；否则，保存所有迭代。如果 <= 0，则保存所有迭代。

• start_iteration (int, 可选 (默认=0)) – 应保存的迭代起始索引。

• importance_type (str, 可选 (默认="split")) – 应保存的特征重要性类型。如果为 “split”，结果包含特征在模型中被使用的次数。如果为 “gain”，结果包含使用该特征进行分割的总增益。

返回值:

str_repr – Booster 的字符串表示形式。

返回类型:

str

num_feature()

获取特征数量。

返回值:

num_feature – 特征的数量。

返回类型:

int

num_model_per_iteration()

获取每次迭代的模型数量。

返回值:

model_per_iter – 每次迭代的模型数量。

返回类型:

int

num_trees()

获取弱子模型的数量。

返回值:

num_trees – 弱子模型的数量。

返回类型:

int

predict(data, start_iteration=0, num_iteration=None, raw_score=False, pred_leaf=False, pred_contrib=False, data_has_header=False, validate_features=False, **kwargs)

进行预测。

参数:

• data (str, pathlib.Path, numpy 数组, pandas DataFrame, pyarrow Table, H2O DataTable 的 Frame (已弃用) 或 scipy.sparse) – 预测的数据源。如果为 str 或 pathlib.Path，则表示文本文件（CSV、TSV 或 LibSVM）的路径。

• start_iteration (int, 可选 (默认=0)) – 预测的迭代起始索引。如果 <= 0，则从第一次迭代开始。

• num_iteration (int 或 None, 可选 (默认=None)) – 预测中使用的总迭代次数。如果为 None，则如果存在最佳迭代且 start_iteration <= 0，则使用最佳迭代；否则，使用 start_iteration 之后的所有迭代（无限制）。如果 <= 0，则使用 start_iteration 之后的所有迭代（无限制）。

• raw_score (bool, 可选 (默认=False)) – 是否预测原始分数。

• pred_leaf (bool, 可选 (默认=False)) – 是否预测叶节点索引。

• pred_contrib (bool, 可选 (默认=False)) –

  是否预测特征贡献。

  注意

  如果您想使用 SHAP 值（例如 SHAP 交互值）获取更多关于模型预测的解释，可以安装 shap 包 (https://github.com/slundberg/shap)。请注意，与 shap 包不同，使用 pred_contrib 时，我们返回一个多一列的矩阵，其中最后一列是期望值。

• data_has_header (bool, 可选 (默认=False)) – 数据是否包含头部。仅当数据为 str 时使用。

• validate_features (bool, 可选 (默认=False)) – 如果为 True，确保用于预测的特征与用于训练的特征匹配。仅当数据为 pandas DataFrame 时使用。

• **kwargs – 其他预测参数。

返回值:

result – 预测结果。对于特征贡献（当 pred_contrib=True 时），可以是稀疏矩阵或稀疏对象列表（每个元素表示一类的预测）。

返回类型:

numpy 数组, scipy.sparse 或 scipy.sparse 列表

refit(data, label, decay_rate=0.9, reference=None, weight=None, group=None, init_score=None, feature_name='auto', categorical_feature='auto', dataset_params=None, free_raw_data=True, validate_features=False, **kwargs)

使用新数据重新训练现有 Booster。

参数:

• data (str, pathlib.Path, numpy 数组, pandas DataFrame, H2O DataTable 的 Frame (已弃用), scipy.sparse, Sequence, Sequence 列表 或 numpy 数组列表) – 重新训练的数据源。如果为 str 或 pathlib.Path，则表示文本文件（CSV、TSV 或 LibSVM）的路径。

• label (list, numpy 1-D 数组, pandas Series / 单列 DataFrame, pyarrow Array 或 pyarrow ChunkedArray) – 重新训练的标签。

• decay_rate (float, 可选 (默认=0.9)) – 重新训练的衰减率，将使用 leaf_output = decay_rate * old_leaf_output + (1.0 - decay_rate) * new_leaf_output 来重新训练树。

• reference (Dataset 或 None, 可选 (默认=None)) –

  data 的参考。

  版本 4.0.0 中新增。

• weight (list, numpy 1-D 数组, pandas Series, pyarrow Array, pyarrow ChunkedArray 或 None, 可选 (默认=None)) –

  每个 data 实例的权重。权重应为非负数。

  版本 4.0.0 中新增。

• group (list, numpy 1-D 数组, pandas Series, pyarrow Array, pyarrow ChunkedArray 或 None, 可选 (默认=None)) –

  data 的组/查询大小。仅用于排序学习任务。sum(group) = n_samples。例如，如果您有一个包含 100 个文档的数据集，group = [10, 20, 40, 10, 10, 10]，这意味着您有 6 个组，其中前 10 条记录在第一个组中，记录 11-30 在第二个组中，记录 31-70 在第三个组中，以此类推。

  版本 4.0.0 中新增。

• init_score (list, 列表的列表 (用于多分类任务), numpy 数组, pandas Series, pandas DataFrame (用于多分类任务), pyarrow Array, pyarrow ChunkedArray, pyarrow Table (用于多分类任务) 或 None, 可选 (默认=None)) –

  data 的初始分数。

  版本 4.0.0 中新增。

• feature_name (str 列表, 或 'auto', 可选 (默认="auto")) –

  data 的特征名称。如果为 'auto' 且 data 是 pandas DataFrame，则使用数据列名。

  版本 4.0.0 中新增。

• categorical_feature (str 列表 或 int, 或 'auto', 可选 (默认="auto")) –

  data 的分类特征。如果为 int 列表，则解释为索引。如果为 str 列表，则解释为特征名称（也需要指定 feature_name）。如果为 'auto' 且 data 是 pandas DataFrame，则使用 pandas 的无序分类列。分类特征中的所有值都将转换为 int32，因此应小于 int32 最大值 (2147483647)。较大的值可能会占用大量内存。考虑使用从零开始的连续整数。分类特征中的所有负值都将被视为缺失值。输出不能相对于分类特征进行单调约束。分类特征中的浮点数将四舍五入到最接近 0 的整数。

  版本 4.0.0 中新增。

• dataset_params (dict 或 None, 可选 (默认=None)) –

  数据集 data 的其他参数。

  版本 4.0.0 中新增。

• free_raw_data (bool, 可选 (默认=True)) –

  如果为 True，则在为 data 构建内部数据集后释放原始数据。

  版本 4.0.0 中新增。

• validate_features (bool, 可选 (默认=False)) –

  如果为 True，确保用于重新训练模型的特征与原始特征匹配。仅当数据为 pandas DataFrame 时使用。

  版本 4.0.0 中新增。

• **kwargs – 重新训练的其他参数。这些参数将传递给 predict 方法。

返回值:

result – 重新训练的 Booster。

返回类型:

Booster

reset_parameter(params)

重置 Booster 的参数。

参数:

params (dict) – Booster 的新参数。

返回值:

self – 带有新参数的 Booster。

返回类型:

Booster

rollback_one_iter()

回滚一次迭代。

返回值:

self – 回滚了一次迭代的 Booster。

返回类型:

Booster

save_model(filename, num_iteration=None, start_iteration=0, importance_type='split')

将 Booster 保存到文件。

参数:

• filename (str 或 pathlib.Path) – 保存 Booster 的文件名。

• num_iteration (int 或 None, 可选 (默认=None)) – 应保存的迭代索引。如果为 None，则如果存在最佳迭代，则保存最佳迭代；否则，保存所有迭代。如果 <= 0，则保存所有迭代。

• start_iteration (int, 可选 (默认=0)) – 应保存的迭代起始索引。

• importance_type (str, 可选 (默认="split")) – 应保存的特征重要性类型。如果为 “split”，结果包含特征在模型中被使用的次数。如果为 “gain”，结果包含使用该特征进行分割的总增益。

返回值:

self – 返回自身。

返回类型:

Booster

set_leaf_output(tree_id, leaf_id, value)

设置叶节点的输出。

版本 4.0.0 中新增。

参数:

• tree_id (int) – 树的索引。

• leaf_id (int) – 树中叶节点的索引。

• value (float) – 要设置为叶节点输出的值。

返回值:

self – 设置了叶节点输出的 Booster。

返回类型:

Booster

set_network(machines, local_listen_port=12400, listen_time_out=120, num_machines=1)

设置网络配置。

参数:

• machines (list, set 或 str) – 机器名称。

• local_listen_port (int, 可选 (默认=12400)) – 本地机器的 TCP 监听端口。

• listen_time_out (int, 可选 (默认=120)) – Socket 超时时间（分钟）。

• num_machines (int, 可选 (默认=1)) – 分布式学习应用的机器数量。

返回值:

self – 设置了网络的 Booster。

返回类型:

Booster

set_train_data_name(name)

为训练数据集设置名称。

参数:

name (str) – 训练数据集的名称。

返回值:

self – 设置了训练数据集名称的 Booster。

返回类型:

Booster

shuffle_models(start_iteration=0, end_iteration=-1)

打乱模型顺序。

参数:

• start_iteration (int, 可选 (默认=0)) – 将被打乱的第一此迭代。

• end_iteration (int, 可选 (默认=-1)) – 将被打乱的最后一次迭代。如果 <= 0，表示最后一次可用的迭代。

返回值:

self – 模型顺序已打乱的 Booster。

返回类型:

Booster

trees_to_dataframe()

解析已拟合的模型并以易于阅读的 pandas DataFrame 格式返回。

返回的 DataFrame 包含以下列。

• tree_index : int64，节点所属的树。基于 0，因此值为 6 表示“此节点在第 7 棵树中”。

• node_depth : int64，节点距离树根的距离。根节点的值为 1，其直接子节点为 2，以此类推。

• node_index : str，节点的唯一标识符。

• left_child : str，分割左侧子节点的 node_index。叶节点为 None。

• right_child : str，分割右侧子节点的 node_index。叶节点为 None。

• parent_index : str，此节点父节点的 node_index。根节点为 None。

• split_feature : str，用于分割的特征名称。叶节点为 None。

• split_gain : float64，将此分割添加到树中获得的增益。叶节点为 NaN。

• threshold : float64，用于决定记录将进入分割哪一侧的特征值。叶节点为 NaN。

• decision_type : str，描述如何将值与 threshold 进行比较的逻辑运算符。例如，split_feature = "Column_10", threshold = 15, decision_type = "<=" 表示 Column_10 <= 15 的记录沿着分割的左侧，否则沿着分割的右侧。叶节点为 None。

• missing_direction : str，缺失值应走向的分割方向。叶节点为 None。

• missing_type : str，描述哪些类型的值被视为缺失值。

• value : float64，此叶节点的预测值，乘以学习率。

• weight : float64 或 int64，Hessian（目标函数的二阶导数）之和，对落在此节点中的观测值求和。

• count : int64，落在此节点中的训练数据记录数。

返回值:

result – 返回解析后模型的 pandas DataFrame。

返回类型:

pandas DataFrame

update(train_set=None, fobj=None)

更新 Booster 一次迭代。

参数:

• train_set (Dataset 或 None, 可选 (默认=None)) – 训练数据。如果为 None，则使用上次的训练数据。

• fobj (callable 或 None, 可选 (默认=None)) –

  自定义目标函数。应接受两个参数：preds、train_data，并返回 (grad, hess)。

  predsnumpy 1-D 数组 或 numpy 2-D 数组 (用于多分类任务)

  预测值。预测值在任何转换之前返回，例如，对于二分类任务，它们是原始 margin 而不是正类的概率。

  train_dataDataset

  训练数据集。

  gradnumpy 1-D 数组 或 numpy 2-D 数组 (用于多分类任务)

  对于每个样本点，损失函数对 preds 元素的偏导数值（梯度）。

  hessnumpy 1-D 数组 或 numpy 2-D 数组 (用于多分类任务)

  对于每个样本点，损失函数对 preds 元素的二阶偏导数值（Hessian）。

  对于多分类任务，preds 是形状为 [n_samples, n_classes] 的 numpy 2-D 数组，grad 和 hess 应以相同的格式返回。

返回值:

is_finished – 更新是否成功完成。

返回类型:

bool

upper_bound()

获取模型的上界值。

返回值:

upper_bound – 模型的上界值。

返回类型:

float