lightgbm.Dataset

class lightgbm.Dataset(data, label=None, reference=None, weight=None, group=None, init_score=None, feature_name='auto', categorical_feature='auto', params=None, free_raw_data=True, position=None)[source]

基类: object

LightGBM 中的 Dataset。

LightGBM 不直接在原始数据上进行训练。它将连续特征离散化为直方图箱，尝试组合类别特征，并自动处理缺失值和无限值。

此类负责这些预处理，并持有输入数据的替代表示形式。

__init__(data, label=None, reference=None, weight=None, group=None, init_score=None, feature_name='auto', categorical_feature='auto', params=None, free_raw_data=True, position=None)[source]

初始化 Dataset。

参数:

data (str, pathlib.Path, numpy 数组, pandas DataFrame, H2O DataTable 的 Frame (已废弃), scipy.sparse, Sequence, Sequence 列表, numpy 数组列表 或 pyarrow Table) – Dataset 的数据源。如果是 str 或 pathlib.Path，表示文本文件（CSV、TSV 或 LibSVM）或 LightGBM Dataset 二进制文件的路径。
label (list, numpy 1-D 数组, pandas Series / 单列 DataFrame, pyarrow Array, pyarrow ChunkedArray 或 None, 可选 (默认值=None)) – 数据的标签。
reference (Dataset 或 None, 可选 (默认值=None)) – 如果这是用于验证的 Dataset，则应将训练数据用作参考。
weight (list, numpy 1-D 数组, pandas Series, pyarrow Array, pyarrow ChunkedArray 或 None, 可选 (默认值=None)) – 每个实例的权重。权重应为非负数。
group (list, numpy 1-D 数组, pandas Series, pyarrow Array, pyarrow ChunkedArray 或 None, 可选 (默认值=None)) – 分组/查询数据。仅用于排序学习任务。sum(group) = 样本数。例如，如果您有一个包含 100 个文档的数据集，其中 group = [10, 20, 40, 10, 10, 10]，这意味着您有 6 个组，其中前 10 条记录在第一个组中，第 11-30 条记录在第二个组中，第 31-70 条记录在第三个组中，依此类推。
init_score (list, list 的 list (用于多分类任务), numpy 数组, pandas Series, pandas DataFrame (用于多分类任务), pyarrow Array, pyarrow ChunkedArray, pyarrow Table (用于多分类任务) 或 None, 可选 (默认值=None)) – Dataset 的初始分数。
feature_name (str 列表, 或 'auto', 可选 (默认值="auto")) – 特征名称。如果为 'auto' 且 data 为 pandas DataFrame 或 pyarrow Table，则使用数据列名。
categorical_feature (str 列表 或 int 列表, 或 'auto', 可选 (默认值="auto")) – 类别特征。如果是 int 列表，则解释为索引。如果是 str 列表，则解释为特征名称（也需要指定 feature_name）。如果为 'auto' 且 data 为 pandas DataFrame，则使用 pandas 无序类别列。类别特征中的所有值将被转换为 int32，因此应小于 int32 最大值 (2147483647)。大值可能会消耗内存。考虑使用从零开始的连续整数。类别特征中的所有负值将被视为缺失值。输出不能在类别特征方面单调受限。类别特征中的浮点数将被四舍五入到最接近零的整数。
params (dict 或 None, 可选 (默认值=None)) – Dataset 的其他参数。
free_raw_data (bool, 可选 (默认值=True)) – 如果为 True，则在构建内部 Dataset 后释放原始数据。
position (numpy 1-D 数组, pandas Series 或 None, 可选 (默认值=None)) – 在无偏排序学习任务中使用的项目位置。

方法

`__init__`(data[, label, reference, weight, ...])	初始化 Dataset。
`add_features_from`(other)	从其他 Dataset 添加特征到当前 Dataset。
`construct`()	惰性初始化。
`create_valid`(data[, label, weight, group, ...])	创建与当前 Dataset 对齐的验证数据。
`feature_num_bin`(feature)	获取特征的 bin 数量。
`get_data`()	获取 Dataset 的原始数据。
`get_feature_name`()	获取 Dataset 中列（特征）的名称。
`get_field`(field_name)	从 Dataset 获取属性。
`get_group`()	获取 Dataset 的分组。
`get_init_score`()	获取 Dataset 的初始分数。
`get_label`()	获取 Dataset 的标签。
`get_params`()	获取 Dataset 中使用的参数。
`get_position`()	获取 Dataset 的位置。
`get_ref_chain`([ref_limit])	获取 Dataset 对象链。
`get_weight`()	获取 Dataset 的权重。
`num_data`()	获取 Dataset 的行数。
`num_feature`()	获取 Dataset 的列（特征）数量。
`save_binary`(filename)	将 Dataset 保存到二进制文件。
`set_categorical_feature`(categorical_feature)	设置类别特征。
`set_feature_name`(feature_name)	设置特征名称。
`set_field`(field_name, data)	将属性设置到 Dataset 中。
`set_group`(group)	设置 Dataset 的分组大小（用于排序）。
`set_init_score`(init_score)	设置 Booster 的初始分数以便从中开始训练。
`set_label`(label)	设置 Dataset 的标签。
`set_position`(position)	设置 Dataset 的位置（用于排序）。
`set_reference`(reference)	设置参考 Dataset。
`set_weight`(weight)	设置每个实例的权重。
`subset`(used_indices[, params])	获取当前 Dataset 的子集。

add_features_from(other)[source]

从其他 Dataset 添加特征到当前 Dataset。

在调用此方法之前，两个 Dataset 都必须已构建。

参数:: other (Dataset) – 从中获取特征的 Dataset。
返回:: self – 添加了新特征的 Dataset。
返回类型:: Dataset

construct()[source]

惰性初始化。

返回:: self – 已构建的 Dataset 对象。
返回类型:: Dataset

create_valid(data, label=None, weight=None, group=None, init_score=None, params=None, position=None)[source]

创建与当前 Dataset 对齐的验证数据。

参数:

data (str, pathlib.Path, numpy 数组, pandas DataFrame, H2O DataTable 的 Frame (已废弃), scipy.sparse, Sequence, Sequence 列表或 numpy 数组列表) – Dataset 的数据源。如果是 str 或 pathlib.Path，表示文本文件（CSV、TSV 或 LibSVM）或 LightGBM Dataset 二进制文件的路径。
label (list, numpy 1-D 数组, pandas Series / 单列 DataFrame, pyarrow Array, pyarrow ChunkedArray 或 None, 可选 (默认值=None)) – 数据的标签。
weight (list, numpy 1-D 数组, pandas Series, pyarrow Array, pyarrow ChunkedArray 或 None, 可选 (默认值=None)) – 每个实例的权重。权重应为非负数。
group (list, numpy 1-D 数组, pandas Series, pyarrow Array, pyarrow ChunkedArray 或 None, 可选 (默认值=None)) – 分组/查询数据。仅用于排序学习任务。sum(group) = 样本数。例如，如果您有一个包含 100 个文档的数据集，其中 group = [10, 20, 40, 10, 10, 10]，这意味着您有 6 个组，其中前 10 条记录在第一个组中，第 11-30 条记录在第二个组中，第 31-70 条记录在第三个组中，依此类推。
init_score (list, list 的 list (用于多分类任务), numpy 数组, pandas Series, pandas DataFrame (用于多分类任务), pyarrow Array, pyarrow ChunkedArray, pyarrow Table (用于多分类任务) 或 None, 可选 (默认值=None)) – Dataset 的初始分数。
params (dict 或 None, 可选 (默认值=None)) – 验证 Dataset 的其他参数。
position (numpy 1-D 数组, pandas Series 或 None, 可选 (默认值=None)) – 在无偏排序学习任务中使用的项目位置。

返回:

valid – 参考当前 Dataset 的验证 Dataset。

返回类型:

Dataset

feature_num_bin(feature)[source]

获取特征的 bin 数量。

在 4.0.0 版本中添加。

参数:: feature (int 或 str) – 特征的索引或名称。
返回:: number_of_bins – 在 Dataset 中为该特征构建的 bin 数量。
返回类型:: int

get_data()[source]

获取 Dataset 的原始数据。

返回:: data – Dataset 构建中使用的原始数据。
返回类型:: str, pathlib.Path, numpy 数组, pandas DataFrame, H2O DataTable 的 Frame (已废弃), scipy.sparse, Sequence, Sequence 列表或 numpy 数组列表或 None

get_feature_name()[source]

获取 Dataset 中列（特征）的名称。

返回:: feature_names – Dataset 中列（特征）的名称。
返回类型:: str 列表

get_field(field_name)[source]

从 Dataset 获取属性。

只能在已构建的 Dataset 上运行。

与 get_group(), get_init_score(), get_label(), get_position() 和 get_weight() 不同，此方法忽略 Python 端传递给 lgb.Dataset() 的任何原始数据，并且只会从构建的 C++ Dataset 对象中读取数据。

参数:: field_name (str) – 信息的字段名称。
返回:: info – 包含 Dataset 信息的 numpy 数组。
返回类型:: numpy 数组或 None

get_group()[source]

获取 Dataset 的分组。

返回:: group – 分组/查询数据。仅用于排序学习任务。sum(group) = 样本数。例如，如果您有一个包含 100 个文档的数据集，其中 group = [10, 20, 40, 10, 10, 10]，这意味着您有 6 个组，其中前 10 条记录在第一个组中，第 11-30 条记录在第二个组中，第 31-70 条记录在第三个组中，依此类推。对于已构建的 Dataset，这将只返回 None 或 numpy 数组。
返回类型:: list, numpy 1-D 数组, pandas Series 或 None

get_init_score()[source]

获取 Dataset 的初始分数。

返回:: init_score – Booster 的初始分数。对于已构建的 Dataset，这将只返回 None 或 numpy 数组。
返回类型:: list, list 的 list（用于多分类任务）, numpy 数组, pandas Series, pandas DataFrame（用于多分类任务）, 或 None

get_label()[source]

获取 Dataset 的标签。

返回:: label – 来自 Dataset 的标签信息。对于已构建的 Dataset，这将只返回 numpy 数组。
返回类型:: list, numpy 1-D 数组, pandas Series / 单列 DataFrame 或 None

get_params()[source]

获取 Dataset 中使用的参数。

返回:: params – 此 Dataset 对象中使用的参数。
返回类型:: dict

get_position()[source]

获取 Dataset 的位置。

返回:: position – 在无偏排序学习任务中使用的项目位置。对于已构建的 Dataset，这将只返回 None 或 numpy 数组。
返回类型:: numpy 1-D 数组, pandas Series 或 None

get_ref_chain(ref_limit=100)[source]

获取 Dataset 对象链。

从 r 开始，然后是 r.reference（如果存在），然后是 r.reference.reference，依此类推，直到达到 ref_limit 或出现引用循环。

参数:: ref_limit (int, 可选 (默认值=100)) – 引用的限制数量。
返回:: ref_chain – Dataset 的引用链。
返回类型:: 一个 Dataset 集合

get_weight()[source]

获取 Dataset 的权重。

返回:: weight – 来自 Dataset 的每个数据点的权重。权重应为非负数。对于已构建的 Dataset，这将只返回 None 或 numpy 数组。
返回类型:: list, numpy 1-D 数组, pandas Series 或 None

num_data()[source]

获取 Dataset 的行数。

返回:: number_of_rows – Dataset 中的行数。
返回类型:: int

num_feature()[source]

获取 Dataset 的列（特征）数量。

返回:: number_of_columns – Dataset 中列（特征）的数量。
返回类型:: int

save_binary(filename)[source]

将 Dataset 保存到二进制文件。

注意

请注意，init_score 不会保存在二进制文件中。如果需要，请在加载 Dataset 后再次设置。

参数:: filename (str 或 pathlib.Path) – 输出文件的名称。
返回:: self – 返回自身。
返回类型:: Dataset

set_categorical_feature(categorical_feature)[source]

设置类别特征。

参数:: categorical_feature (str 列表 或 int 列表, 或 'auto') – 类别特征的名称或索引。
返回:: self – 设置了类别特征的 Dataset。
返回类型:: Dataset

set_feature_name(feature_name)[source]

设置特征名称。

参数:: feature_name (str 列表) – 特征名称。
返回:: self – 设置了特征名称的 Dataset。
返回类型:: Dataset

set_field(field_name, data)[source]

将属性设置到 Dataset 中。

参数:

field_name (str) – 信息的字段名称。
data (list, list 的 list (用于多分类任务), numpy 数组, pandas Series, pandas DataFrame (用于多分类任务), pyarrow Array, pyarrow ChunkedArray 或 None) – 要设置的数据。

返回:

self – 设置了属性的 Dataset。

返回类型:

Dataset

set_group(group)[source]

设置 Dataset 的分组大小（用于排序）。

参数:: group (list, numpy 1-D 数组, pandas Series, pyarrow Array, pyarrow ChunkedArray 或 None) – 分组/查询数据。仅用于排序学习任务。sum(group) = 样本数。例如，如果您有一个包含 100 个文档的数据集，其中 group = [10, 20, 40, 10, 10, 10]，这意味着您有 6 个组，其中前 10 条记录在第一个组中，第 11-30 条记录在第二个组中，第 31-70 条记录在第三个组中，依此类推。
返回:: self – 设置了分组的 Dataset。
返回类型:: Dataset

set_init_score(init_score)[source]

设置 Booster 的初始分数以便从中开始训练。

参数:: init_score (list, list 的 list (用于多分类任务), numpy 数组, pandas Series, pandas DataFrame (用于多分类任务), pyarrow Array, pyarrow ChunkedArray, pyarrow Table (用于多分类任务) 或 None) – Booster 的初始分数。
返回:: self – 设置了初始分数的 Dataset。
返回类型:: Dataset

set_label(label)[source]

设置 Dataset 的标签。

参数:: label (list, numpy 1-D 数组, pandas Series / 单列 DataFrame, pyarrow Array, pyarrow ChunkedArray 或 None) – 要设置到 Dataset 中的标签信息。
返回:: self – 设置了标签的 Dataset。
返回类型:: Dataset

set_position(position)[source]

设置 Dataset 的位置（用于排序）。

参数:: position (numpy 1-D 数组, pandas Series 或 None, 可选 (默认值=None)) – 在无偏排序学习任务中使用的项目位置。
返回:: self – 设置了位置的 Dataset。
返回类型:: Dataset

set_reference(reference)[source]

设置参考 Dataset。

参数:: reference (Dataset) – 用作模板以构建当前 Dataset 的参考。
返回:: self – 设置了参考的 Dataset。
返回类型:: Dataset

set_weight(weight)[source]

设置每个实例的权重。

参数:: weight (list, numpy 1-D 数组, pandas Series, pyarrow Array, pyarrow ChunkedArray 或 None) – 要为每个数据点设置的权重。权重应为非负数。
返回:: self – 设置了权重的 Dataset。
返回类型:: Dataset

subset(used_indices, params=None)[source]

获取当前 Dataset 的子集。

参数:

used_indices (int 列表) – 用于创建子集的索引。
params (dict 或 None, 可选 (默认值=None)) – 这些参数将传递给 Dataset 构造函数。

返回:

subset – 当前 Dataset 的子集。

返回类型:

Dataset