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)

基类：object

LightGBM 中的数据集。

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)

初始化数据集。

参数:

• data (str, pathlib.Path, numpy array, pandas DataFrame, H2O DataTable's Frame, scipy.sparse, Sequence, list of Sequence, list of numpy array or pyarrow Table) – 数据集的数据源。如果是 str 或 pathlib.Path，它表示文本文件（CSV、TSV 或 LibSVM）或 LightGBM 数据集二进制文件的路径。

• label (list, numpy 1-D array, pandas Series / one-column DataFrame, pyarrow Array, pyarrow ChunkedArray or None, optional (default=None)) – 数据的标签。

• reference (Dataset or None, optional (default=None)) – 如果这是用于验证的数据集，应使用训练数据作为参考。

• weight (list, numpy 1-D array, pandas Series, pyarrow Array, pyarrow ChunkedArray or None, optional (default=None)) – 每个实例的权重。权重应为非负数。

• group (list, numpy 1-D array, pandas Series, pyarrow Array, pyarrow ChunkedArray or None, optional (default=None)) – 分组/查询数据。仅用于学习排序任务。sum(group) = n_samples。例如，如果您有一个包含100个文档的数据集，且 group = [10, 20, 40, 10, 10, 10]，这意味着您有6个组，其中前10条记录在第一组，记录11-30在第二组，记录31-70在第三组，依此类推。

• 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)) – 数据集的初始分数。

• feature_name (list of str, or 'auto', optional (default="auto")) – 特征名称。如果为 ‘auto’ 且数据是 pandas DataFrame 或 pyarrow Table，则使用数据列名称。

• categorical_feature (list of str or int, or 'auto', optional (default="auto")) – 分类特征。如果是整数列表，则解释为索引。如果是字符串列表，则解释为特征名称（还需要指定 feature_name）。如果是 ‘auto’ 且数据是 pandas DataFrame，则使用 pandas 的无序分类列。分类特征中的所有值将被转换为 int32，因此应小于 int32 的最大值（2147483647）。大值可能会消耗大量内存。考虑使用从零开始的连续整数。分类特征中的所有负值将被视为缺失值。输出不能相对于分类特征进行单调约束。分类特征中的浮点数将向 0 舍入。

• params (dict or None, optional (default=None)) – Dataset 的其他参数

• free_raw_data (bool, optional (default=True)) – 如果为真，原始数据在构建内部数据集后被释放。

• position (numpy 1-D array, pandas Series or None, optional (default=None)) – 在无偏学习排序任务中使用的项目位置。

方法

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

add_features_from(other)

将其他数据集的特性添加到当前数据集中。

在调用此方法之前，必须先构建两个数据集。

参数:

other (Dataset) – 要从中提取特征的数据集。

返回:

self – 添加了新特征的数据集。

返回类型:

Dataset

construct()

延迟初始化。

返回:

self – 构造的 Dataset 对象。

返回类型:

Dataset

create_valid(data, label=None, weight=None, group=None, init_score=None, params=None, position=None)

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

参数:

• data (str, pathlib.Path, numpy array, pandas DataFrame, H2O DataTable's Frame, scipy.sparse, Sequence, list of Sequence or list of numpy array) – 数据集的数据源。如果是 str 或 pathlib.Path，它表示文本文件（CSV、TSV 或 LibSVM）或 LightGBM 数据集二进制文件的路径。

• label (list, numpy 1-D array, pandas Series / one-column DataFrame, pyarrow Array, pyarrow ChunkedArray or None, optional (default=None)) – 数据的标签。

• weight (list, numpy 1-D array, pandas Series, pyarrow Array, pyarrow ChunkedArray or None, optional (default=None)) – 每个实例的权重。权重应为非负数。

• group (list, numpy 1-D array, pandas Series, pyarrow Array, pyarrow ChunkedArray or None, optional (default=None)) – 分组/查询数据。仅用于学习排序任务。sum(group) = n_samples。例如，如果您有一个包含100个文档的数据集，且 group = [10, 20, 40, 10, 10, 10]，这意味着您有6个组，其中前10条记录在第一组，记录11-30在第二组，记录31-70在第三组，依此类推。

• 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)) – 数据集的初始分数。

• params (dict or None, optional (default=None)) – 验证数据集的其他参数。

• position (numpy 1-D array, pandas Series or None, optional (default=None)) – 在无偏学习排序任务中使用的项目位置。

返回:

valid – 带有自我引用的验证数据集。

返回类型:

Dataset

feature_num_bin(feature)

获取特征的箱数。

Added in version 4.0.0.

参数:

feature (int or str) – 特征的索引或名称。

返回:

number_of_bins – 在数据集中为特征构建的箱数。

返回类型:

int

get_data()

获取数据集的原始数据。

返回:

data – 用于数据集构建的原始数据。

返回类型:

str, pathlib.Path, numpy array, pandas DataFrame, H2O DataTable’s Frame, scipy.sparse, Sequence, list of Sequence or list of numpy array or None

get_feature_name()

获取数据集中列（特征）的名称。

返回:

feature_names – 数据集中列（特征）的名称。

返回类型:

list of str

get_field(field_name)

从数据集中获取属性。

只能在构造的数据集上运行。

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

参数:

field_name (str) – 信息的字段名称。

返回:

info – 包含数据集信息的numpy数组。

返回类型:

numpy array or None

get_group()

获取数据集的组。

返回:

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

返回类型:

list, numpy 1-D array, pandas Series or None

get_init_score()

获取数据集的初始分数。

返回:

init_score – Booster 的初始分数。对于一个已构建的 Dataset，这将只返回 None 或一个 numpy 数组。

返回类型:

list, list of lists (for multi-class task), numpy array, pandas Series, pandas DataFrame (for multi-class task), or None

get_label()

获取数据集的标签。

返回:

label – 数据集的标签信息。对于一个构建的 Dataset ，这只会返回一个 numpy 数组。

返回类型:

list, numpy 1-D array, pandas Series / one-column DataFrame or None

get_params()

获取数据集中使用的参数。

返回:

params – 在此 Dataset 对象中使用的参数。

返回类型:

dict

get_position()

获取数据集的位置。

返回:

position – 在无偏学习排序任务中使用的项目位置。对于一个构建的 Dataset ，这将只返回 None 或一个 numpy 数组。

返回类型:

numpy 1-D array, pandas Series or None

get_ref_chain(ref_limit=100)

获取一个数据集对象链。

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

参数:

ref_limit (int, optional (default=100)) – 引用数量的限制。

返回:

ref_chain – 数据集的引用链。

返回类型:

set of Dataset

get_weight()

获取数据集的权重。

返回:

weight – 数据集中每个数据点的权重。权重应为非负数。对于一个构造的 Dataset，这将仅返回 None 或一个 numpy 数组。

返回类型:

list, numpy 1-D array, pandas Series or None

num_data()

获取数据集中的行数。

返回:

number_of_rows – 数据集中的行数。

返回类型:

int

num_feature()

获取数据集中的列数（特征数）。

返回:

number_of_columns – 数据集中的列数（特征数）。

返回类型:

int

save_binary(filename)

将数据集保存到二进制文件。

备注

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

参数:

filename (str or pathlib.Path) – 输出文件的名称。

返回:

self – 返回自身。

返回类型:

Dataset

set_categorical_feature(categorical_feature)

设置分类特征。

参数:

categorical_feature (list of str or int, or 'auto') – 分类特征的名称或索引。

返回:

self – 带有设定分类特征的数据集。

返回类型:

Dataset

set_feature_name(feature_name)

设置功能名称。

参数:

feature_name (list of str) – 功能名称。

返回:

self – 带有设定特征名称的数据集。

返回类型:

Dataset

set_field(field_name, data)

将属性设置到数据集中。

参数:

• field_name (str) – 信息的字段名称。

• data (list, list of lists (for multi-class task), numpy array, pandas Series, pandas DataFrame (for multi-class task), pyarrow Array, pyarrow ChunkedArray or None) – 要设置的数据。

返回:

self – 具有设置属性的数据集。

返回类型:

Dataset

set_group(group)

设置数据集的组大小（用于排名）。

参数:

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

返回:

self – 带有设置组的Dataset。

返回类型:

Dataset

set_init_score(init_score)

设置Booster的初始分数以开始。

参数:

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) – Booster 的初始分数。

返回:

self – 带有设置初始分数的数据集。

返回类型:

Dataset

set_label(label)

设置数据集的标签。

参数:

label (list, numpy 1-D array, pandas Series / one-column DataFrame, pyarrow Array, pyarrow ChunkedArray or None) – 要设置到数据集中的标签信息。

返回:

self – 带有设定标签的数据集。

返回类型:

Dataset

set_position(position)

设置数据集的位置（用于排名）。

参数:

position (numpy 1-D array, pandas Series or None, optional (default=None)) – 在无偏学习排序任务中使用的项目位置。

返回:

self – 具有设定位置的数据集。

返回类型:

Dataset

set_reference(reference)

设置参考数据集。

参数:

reference (Dataset) – 作为模板用于构建当前数据集的引用。

返回:

self – 带有集合引用的数据集。

返回类型:

Dataset

set_weight(weight)

设置每个实例的权重。

参数:

weight (list, numpy 1-D array, pandas Series, pyarrow Array, pyarrow ChunkedArray or None) – 为每个数据点设置的权重。权重应为非负数。

返回:

self – 带有设置权重的数据集。

返回类型:

Dataset

subset(used_indices, params=None)

获取当前数据集的子集。

参数:

• used_indices (list of int) – 用于创建子集的索引。

• params (dict or None, optional (default=None)) – 这些参数将被传递给 Dataset 构造函数。

返回:

subset – 当前数据集的子集。

返回类型:

Dataset