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)[源代码]

初始化加速器。

参数:

params (dict or None, optional (default=None)) – Booster 的参数
train_set (Dataset or None, optional (default=None)) – 训练数据集。
model_file (str, pathlib.Path or None, optional (default=None)) – 模型文件的路径。
model_str (str or None, optional (default=None)) – 模型将从该字符串加载。

方法

`__init__`([params, train_set, model_file, ...])	初始化加速器。
`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`()	Free Booster 的数据集。
`free_network`()	Free 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, ...])	用新数据重新调整现有助推器。
`reset_parameter`(params)	重置 Booster 的参数。
`rollback_one_iter`()	回滚一个迭代。
`save_model`(filename[, num_iteration, ...])	将助推器保存到文件。
`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])	更新助推器进行一次迭代。
`upper_bound`()	获取模型的上界值。

add_valid(data, name)[源代码]

添加验证数据。

参数:

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

返回:

self – 带有设置验证数据的提升器。

返回类型:

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 or None, optional (default=None)) – 应转储的迭代索引。如果为 None，如果存在最佳迭代，则转储最佳迭代；否则，转储所有迭代。如果 <= 0，则转储所有迭代。
start_iteration (int, optional (default=0)) – 应该转储的迭代的起始索引。
importance_type (str, optional (default="split")) – 应该转储哪种特征重要性。如果选择“split”，结果包含特征在模型中使用的次数。如果选择“gain”，结果包含使用该特征的分割的总增益。
object_hook (callable or None, optional (default=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, list of callable, or None, optional (default=None)) –
自定义评估函数。每个评估函数应接受两个参数：preds, eval_data，并返回 (eval_name, eval_result, is_higher_better) 或此类元组的列表。

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

eval_data数据集
一个用于评估的 Dataset。

eval_namestr
评估函数的名称（不包含空格）。

eval_result浮动
评估结果。

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

返回:

结果 – 包含 (数据集名称, 评估名称, 评估结果, 是否越高越好) 元组的列表。

返回类型:

list

eval_train(feval=None)[源代码]

评估训练数据。

参数:

feval (callable, list of callable, or None, optional (default=None)) –

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

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

eval_data数据集
训练数据集。

eval_namestr
评估函数的名称（不包含空格）。

eval_result浮动
评估结果。

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

返回:

结果 – 包含 (训练数据集名称, 评估名称, 评估结果, 是否越高越好) 元组的列表。

返回类型:

list

eval_valid(feval=None)[源代码]

评估验证数据。

参数:

feval (callable, list of callable, or None, optional (default=None)) –

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

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

eval_data数据集
验证数据集。

eval_namestr
评估函数的名称（不包含空格）。

eval_result浮动
评估结果。

is_higher_better布尔
评估结果是否越高越好，例如 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, optional (default="split")) – 重要性是如何计算的。如果选择“分割”，结果包含特征在模型中使用的次数。如果选择“增益”，结果包含使用该特征的分割的总增益。
iteration (int or None, optional (default=None)) – 限制特征重要性计算中的迭代次数。如果为 None，如果存在最佳迭代，则使用它；否则，使用所有树。如果 <= 0，则使用所有树（无限制）。

返回:

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

返回类型:

numpy array

feature_name()[源代码]

获取特征的名称。

返回:: 结果 – 包含特征名称的列表。
返回类型:: list of str

free_dataset()[源代码]

Free Booster 的数据集。

返回:: self – 不带数据集的助推器。
返回类型:: Booster

free_network()[源代码]

Free Booster 的网络。

返回:: self – 释放了网络的助推器。
返回类型:: Booster

get_leaf_output(tree_id, leaf_id)[源代码]

获取叶子的输出。

参数:

tree_id (int) – 树的索引。
leaf_id (int) – 树中叶子的索引。

返回:

结果 – 叶子的输出。

返回类型:

float

get_split_value_histogram(feature, bins=None, xgboost_style=False)[源代码]

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

参数:

feature (int or str) – 直方图计算所针对的特征名称或索引。如果是整数，则解释为索引。如果是字符串，则解释为名称。 .. warning:: 不支持分类特征。
bins (int, str or None, optional (default=None)) – 最大分箱数。如果为 None，或者为 int 且大于唯一分割值的数量并且 xgboost_style=True，则分箱数等于唯一分割值的数量。如果为 str，则应为 numpy.histogram() 函数支持的值列表中的一个。
xgboost_style (bool, optional (default=False)) – 返回的结果是否应与在XGBoost中的形式相同。如果为False，返回值是两个numpy数组的元组，如同在 numpy.histogram() 函数中那样。如果为True，返回值是一个矩阵，其中第一列是非空箱的右边缘，第二列是直方图值。

返回:

result_tuple (2个numpy数组的元组) – 如果 xgboost_style=False，则为指定特征的分裂值直方图的值和箱边缘。
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 or None, optional (default=None)) – 应保存的迭代索引。如果为 None，如果存在最佳迭代，则保存最佳迭代；否则，保存所有迭代。如果 <= 0，则保存所有迭代。
start_iteration (int, optional (default=0)) – 应保存的迭代的起始索引。
importance_type (str, optional (default="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 array, pandas DataFrame, pyarrow Table, H2O DataTable's Frame or scipy.sparse) – 预测的数据源。如果是 str 或 pathlib.Path，它表示指向一个文本文件（CSV、TSV 或 LibSVM）的路径。
start_iteration (int, optional (default=0)) – 开始预测的迭代索引。如果 <= 0，则从第一次迭代开始。
num_iteration (int or None, optional (default=None)) – 预测中使用的总迭代次数。如果为 None，如果存在最佳迭代并且 start_iteration <= 0，则使用最佳迭代；否则，使用从 start_iteration 开始的所有迭代（无限制）。如果 <= 0，则使用从 start_iteration 开始的所有迭代（无限制）。
raw_score (bool, optional (default=False)) – 是否预测原始分数。
pred_leaf (bool, optional (default=False)) – 是否预测叶索引。
pred_contrib (bool, optional (default=False)) – 是否预测特征贡献。 .. 注意:: 如果你想使用 SHAP 值为你的模型预测获得更多解释，比如 SHAP 交互值，你可以安装 shap 包 (https://github.com/slundberg/shap)。请注意，与 shap 包不同，使用 pred_contrib 我们返回一个带有额外列的矩阵，其中最后一列是期望值。
data_has_header (bool, optional (default=False)) – 数据是否有标题。仅在数据为字符串时使用。
validate_features (bool, optional (default=False)) – 如果为真，确保用于预测的特征与用于训练的特征匹配。仅在数据为 pandas DataFrame 时使用。
**kwargs – 预测的其他参数。

返回:

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

返回类型:

numpy array, scipy.sparse or list of 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)[源代码]

用新数据重新调整现有助推器。

参数:

data (str, pathlib.Path, numpy array, pandas DataFrame, H2O DataTable's Frame, scipy.sparse, Sequence, list of Sequence or list of numpy array) – refit 的数据源。如果是 str 或 pathlib.Path，它表示指向一个文本文件（CSV、TSV 或 LibSVM）的路径。
label (list, numpy 1-D array, pandas Series / one-column DataFrame, pyarrow Array or pyarrow ChunkedArray) – 重构的标签。
decay_rate (float, optional (default=0.9)) – 重拟合的衰减率，将使用 leaf_output = decay_rate * old_leaf_output + (1.0 - decay_rate) * new_leaf_output 来重拟合树。
reference (Dataset or None, optional (default=None)) – data 的参考。 .. versionadded:: 4.0.0
weight (list, numpy 1-D array, pandas Series, pyarrow Array, pyarrow ChunkedArray or None, optional (default=None)) – 每个 data 实例的权重。权重应为非负数。 .. versionadded:: 4.0.0
group (list, numpy 1-D array, pandas Series, pyarrow Array, pyarrow ChunkedArray or None, optional (default=None)) – data 的组/查询大小。仅在排序学习任务中使用。sum(group) = n_samples。例如，如果您有一个包含 100 个文档的数据集，且 group = [10, 20, 40, 10, 10, 10]，这意味着您有 6 个组，其中前 10 条记录在第一组，记录 11-30 在第二组，记录 31-70 在第三组，依此类推。 .. versionadded:: 4.0.0
init_score (list, list of lists (for multi-class task), numpy array, pandas Series, pandas DataFrame (for multi-class task), pyarrow Array, pyarrow ChunkedArray, pyarrow Table (for multi-class task) or None, optional (default=None)) – data 的初始分数。 .. versionadded:: 4.0.0
feature_name (list of str, or 'auto', optional (default="auto")) – data 的特征名称。如果为 ‘auto’ 且数据是 pandas DataFrame，则使用数据列名。 .. versionadded:: 4.0.0
categorical_feature (list of str or int, or 'auto', optional (default="auto")) – data 的分类特征。如果是整数列表，则解释为索引。如果是字符串列表，则解释为特征名称（还需要指定 feature_name）。如果是 ‘auto’ 并且数据是 pandas DataFrame，则使用 pandas 的无序分类列。分类特征中的所有值将被转换为 int32，因此应小于 int32 的最大值（2147483647）。大值可能会消耗大量内存。建议使用从零开始的连续整数。分类特征中的所有负值将被视为缺失值。输出不能相对于分类特征进行单调约束。分类特征中的浮点数将向 0 舍入。 .. versionadded:: 4.0.0
dataset_params (dict or None, optional (default=None)) – 数据集 data 的其他参数。 .. versionadded:: 4.0.0
free_raw_data (bool, optional (default=True)) – 如果为 True，则在构建 data 的内部数据集后释放原始数据。 .. versionadded:: 4.0.0
validate_features (bool, optional (default=False)) – 如果为 True，确保用于重新拟合模型的特征与原始特征匹配。仅在数据为 pandas DataFrame 时使用。 .. versionadded:: 4.0.0
**kwargs – refit 的其他参数。这些参数将被传递给 predict 方法。

返回:

结果 – 重新改装的助推器。

返回类型:

Booster

reset_parameter(params)[源代码]

重置 Booster 的参数。

参数:: params (dict) – Booster 的新参数
返回:: self – 带有新参数的提升器。
返回类型:: Booster

rollback_one_iter()[源代码]

回滚一个迭代。

返回:: self – 回滚了一步迭代的增强器。
返回类型:: Booster

save_model(filename, num_iteration=None, start_iteration=0, importance_type='split')[源代码]

将助推器保存到文件。

参数:

filename (str or pathlib.Path) – 保存助推器的文件名。
num_iteration (int or None, optional (default=None)) – 应保存的迭代索引。如果为 None，如果存在最佳迭代，则保存最佳迭代；否则，保存所有迭代。如果 <= 0，则保存所有迭代。
start_iteration (int, optional (default=0)) – 应保存的迭代的起始索引。
importance_type (str, optional (default="split")) – 应该保存哪种类型的特征重要性。如果选择“split”，结果包含特征在模型中使用的次数。如果选择“gain”，结果包含使用该特征的分割的总增益。

返回:

self – 返回自身。

返回类型:

Booster

set_leaf_output(tree_id, leaf_id, value)[源代码]

设置叶子的输出。

Added in version 4.0.0.

参数:

tree_id (int) – 树的索引。
leaf_id (int) – 树中叶子的索引。
value (float) – 设置为叶子的输出值。

返回:

self – 设置了叶子输出的提升器。

返回类型:

Booster

set_network(machines, local_listen_port=12400, listen_time_out=120, num_machines=1)[源代码]

设置网络配置。

参数:

machines (list, set or str) – 机器的名称。
local_listen_port (int, optional (default=12400)) – 本地机器的TCP监听端口。
listen_time_out (int, optional (default=120)) – 套接字超时时间，单位为分钟。
num_machines (int, optional (default=1)) – 分布式学习应用的机器数量。

返回:

self – 带有设置网络的助推器。

返回类型:

Booster

set_train_data_name(name)[源代码]

将名称设置为训练数据集。

参数:: name (str) – 训练数据集的名称。
返回:: self – 带有设置训练数据集名称的提升器。
返回类型:: Booster

shuffle_models(start_iteration=0, end_iteration=-1)[源代码]

洗牌模型。

参数:

start_iteration (int, optional (default=0)) – 将要被打乱的第一次迭代。
end_iteration (int, optional (default=-1)) – 将要进行洗牌的最后一次迭代。如果 <= 0，则表示最后一次可用迭代。

返回:

self – 带有打乱模型的提升器。

返回类型:

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, 训练数据中落入此节点的记录数量。

返回:: 结果 – 返回解析模型的 pandas DataFrame。
返回类型:: pandas DataFrame

update(train_set=None, fobj=None)[源代码]

更新助推器进行一次迭代。

参数:

train_set (Dataset or None, optional (default=None)) – 训练数据。如果为 None，则使用上一次的训练数据。
fobj (callable or None, optional (default=None)) –
自定义目标函数。应接受两个参数：preds, train_data，并返回 (grad, hess)。

预测numpy 一维数组或 numpy 二维数组（用于多类任务）
预测值。预测值在任何转换之前返回，例如，对于二分类任务，它们是原始边际而不是正类的概率。

训练数据数据集
训练数据集。

梯度numpy 一维数组或 numpy 二维数组（用于多类任务）
每个样本点相对于preds元素的损失的一阶导数（梯度）的值。

hessnumpy 一维数组或 numpy 二维数组（用于多类任务）
每个样本点关于 preds 元素的损失的二阶导数（Hessian）的值。

对于多类任务，preds 是形状为 [n_样本, n_类] 的 numpy 二维数组，grad 和 hess 应以相同格式返回。

返回:

is_finished – 更新是否成功完成。

返回类型:

bool

upper_bound()[源代码]

获取模型的上界值。

返回:: upper_bound – 模型的上界值。
返回类型:: float