lightgbm.DaskLGBMRanker

class lightgbm.DaskLGBMRanker(boosting_type='gbdt', num_leaves=31, max_depth=-1, learning_rate=0.1, n_estimators=100, subsample_for_bin=200000, objective=None, class_weight=None, min_split_gain=0.0, min_child_weight=0.001, min_child_samples=20, subsample=1.0, subsample_freq=0, colsample_bytree=1.0, reg_alpha=0.0, reg_lambda=0.0, random_state=None, n_jobs=None, importance_type='split', client=None, **kwargs)[源代码]

基类：LGBMRanker, _DaskLGBMModel

lightgbm.LGBMRanker 的分布式版本。

__init__(boosting_type='gbdt', num_leaves=31, max_depth=-1, learning_rate=0.1, n_estimators=100, subsample_for_bin=200000, objective=None, class_weight=None, min_split_gain=0.0, min_child_weight=0.001, min_child_samples=20, subsample=1.0, subsample_freq=0, colsample_bytree=1.0, reg_alpha=0.0, reg_lambda=0.0, random_state=None, n_jobs=None, importance_type='split', client=None, **kwargs)[源代码]

构建一个梯度提升模型。

参数:

boosting_type (str, optional (default='gbdt')) – ‘gbdt’, 传统的梯度提升决策树。’dart’, Dropouts 遇到多重加性回归树。’rf’, 随机森林。
num_leaves (int, optional (default=31)) – 基学习器的最大树叶子数。
max_depth (int, optional (default=-1)) – 基学习器的最大树深度，<=0 表示无限制。如果设置为正值，请考虑也将 num_leaves 更改为 <= 2^max_depth。
learning_rate (float, optional (default=0.1)) – 提升学习率。你可以使用 fit 方法的 callbacks 参数，通过 reset_parameter 回调在训练中缩小/适应学习率。注意，这将忽略训练中的 learning_rate 参数。
n_estimators (int, optional (default=100)) – 要拟合的提升树数量。
subsample_for_bin (int, optional (default=200000)) – 用于构建分箱的样本数量。
objective (str, callable or None, optional (default=None)) – 指定学习任务和相应的学习目标或自定义目标函数（见下文注释）。默认值：LGBMRegressor 为 ‘regression’，LGBMClassifier 为 ‘binary’ 或 ‘multiclass’，LGBMRanker 为 ‘lambdarank’。
class_weight (dict, 'balanced' or None, optional (default=None)) – 与类相关的权重，形式为 {class_label: weight}。仅在多类分类任务中使用此参数；对于二分类任务，您可以使用 is_unbalance 或 scale_pos_weight 参数。请注意，使用这些参数将导致个体类概率的估计不佳。您可能需要考虑对模型进行概率校准（https://scikit-learn.org/stable/modules/calibration.html）。’balanced’ 模式使用 y 的值自动调整权重，使其与输入数据中的类频率成反比，即 n_samples / (n_classes * np.bincount(y))。如果为 None，则所有类别的权重均为一。请注意，如果指定了 sample_weight``（通过 ``fit 方法传递），这些权重将与 sample_weight 相乘。
min_split_gain (float, optional (default=0.)) – 在树的叶节点上进行进一步分区所需的最小损失减少量。
min_child_weight (float, optional (default=1e-3)) – 子节点（叶）中所需的最小实例权重（Hessian）和。
min_child_samples (int, optional (default=20)) – 子节点（叶节点）中所需的最小数据量。
subsample (float, optional (default=1.)) – 训练实例的子样本比例。
subsample_freq (int, optional (default=0)) – 子样本的频率，<=0 表示不启用。
colsample_bytree (float, optional (default=1.)) – 构建每棵树时列的子样本比例。
reg_alpha (float, optional (default=0.)) – 权重上的L1正则化项。
reg_lambda (float, optional (default=0.)) – 权重上的L2正则化项。
random_state (int, RandomState object or None, optional (default=None)) – 随机数种子。如果是整数，这个数字用于种子化C++代码。如果是RandomState或Generator对象（numpy），则根据其状态选择一个随机整数来种子化C++代码。如果是None，则使用C++代码中的默认种子。
n_jobs (int or None, optional (default=None)) – 用于训练的并行线程数（可以在预测时通过将其作为额外关键字参数传递来更改）。为了获得更好的性能，建议将其设置为CPU中的物理核心数。负整数按照joblib的公式（n_cpus + 1 + n_jobs）解释，就像scikit-learn一样（例如，-1表示使用所有线程）。值为零对应于系统中为OpenMP配置的默认线程数。值为``None``（默认）对应于系统中的物理核心数（其正确检测需要安装``joblib``或``psutil``实用库）。 .. versionchanged:: 4.0.0
importance_type (str, optional (default='split')) – 要填充到 feature_importances_ 中的特征重要性类型。如果为 ‘split’，结果包含特征在模型中使用的次数。如果为 ‘gain’，结果包含使用该特征的分割的总增益。
client (dask.distributed.Client or None, optional (default=None)) – Dask 客户端。如果为 None，将在运行时使用 distributed.default_client()。此类使用的 Dask 客户端在模型对象被序列化时不会被保存。
**kwargs – 模型的其他参数。更多参数请查看 http://lightgbm.readthedocs.io/en/latest/Parameters.html。

备注

可以为 objective 参数提供自定义目标函数。在这种情况下，它应该具有以下签名之一：objective(y_true, y_pred) -> grad, hess，objective(y_true, y_pred, weight) -> grad, hess 或 objective(y_true, y_pred, weight, group) -> grad, hess：

y_truenumpy 一维数组，形状为 = [n_samples]
目标值。

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

重量numpy 一维数组，形状为 = [n_samples]
样本的权重。权重应为非负数。

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

梯度numpy 一维数组，形状为 [n_samples] 或 numpy 二维数组，形状为 [n_samples, n_classes]（用于多类任务）
每个样本点相对于 y_pred 元素的损失的一阶导数（梯度）的值。

hessnumpy 一维数组，形状为 [n_samples] 或 numpy 二维数组，形状为 [n_samples, n_classes]（用于多类任务）
每个样本点关于 y_pred 元素的损失的二阶导数（Hessian）的值。

对于多类任务，y_pred 是一个形状为 [n_samples, n_classes] 的 numpy 二维数组，grad 和 hess 应以相同格式返回。

方法

`__init__`([boosting_type, num_leaves, ...])	构建一个梯度提升模型。
`fit`(X, y[, sample_weight, init_score, ...])	从训练集 (X, y) 构建一个梯度提升模型。
`get_metadata_routing`()	获取此对象的元数据路由。
`get_params`([deep])	获取此估计器的参数。
`predict`(X[, raw_score, start_iteration, ...])	返回每个样本的预测值。
`set_fit_request`(*[, eval_at, eval_group, ...])	传递给 `fit` 方法的请求元数据。
`set_params`(**params)	设置此估计器的参数。
`set_predict_request`(*[, num_iteration, ...])	传递给 `predict` 方法的请求元数据。
`to_local`()	从分布式版本创建 lightgbm.LGBMRanker 的常规版本。

属性

`best_iteration_`	如果指定了 `early_stopping()` 回调，这是拟合模型的最佳迭代。
`best_score_`	拟合模型的最佳得分。
`booster_`	该模型的底层助推器。
`client_`	Dask 客户端。
`evals_result_`	如果指定了验证集，则显示评估结果。
`feature_importances_`	特征重要性（越高越重要）。
`feature_name_`	功能名称。
`feature_names_in_`	scikit-learn 兼容版本的 `.feature_name_`。
`n_estimators_`	实际执行的提升迭代次数。
`n_features_`	拟合模型的特征数量。
`n_features_in_`	拟合模型的特征数量。
`n_iter_`	实际执行的提升迭代次数。
`objective_`	拟合此模型时使用的具体目标。

property best_iteration_

如果指定了 early_stopping() 回调，这是拟合模型的最佳迭代。

类型:: int

property best_score_

拟合模型的最佳得分。

类型:: dict

property booster_

该模型的底层助推器。

类型:: 助推器

property client_

Dask 客户端。

此属性可以在构造函数中传递，或者通过 model.set_params(client=client) 进行更新。

类型:: dask.distributed.Client

property evals_result_

如果指定了验证集，则显示评估结果。

类型:: dict

property feature_importances_

特征重要性（越高越重要）。

备注

importance_type 属性被传递给函数，以配置要提取的重要性值的类型。

类型:: array of shape = [n_features]

property feature_name_

功能名称。

备注

如果输入不包含特征名称，它们将在拟合过程中以 Column_0, Column_1, …, Column_N 的格式添加。

类型:: list of shape = [n_features]

property feature_names_in_

scikit-learn 兼容版本的 .feature_name_。

Added in version 4.5.0.

类型:: array of shape = [n_features]

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, eval_at=(1, 2, 3, 4, 5), **kwargs)[源代码]

从训练集 (X, y) 构建一个梯度提升模型。

参数:

X (Dask Array or Dask DataFrame of shape = [n_samples, n_features]) – 输入特征矩阵。
y (Dask Array, Dask DataFrame or Dask Series of shape = [n_samples]) – 目标值（分类中的类别标签，回归中的实数）。
sample_weight (Dask Array or Dask Series of shape = [n_samples] or None, optional (default=None)) – 训练数据的权重。权重应为非负数。
init_score (Dask Array or Dask Series of shape = [n_samples] or None, optional (default=None)) – 训练数据的初始分数。
group (Dask Array or Dask Series or None, optional (default=None)) – 分组/查询数据。仅在排序学习任务中使用。sum(group) = n_samples。例如，如果你有一个包含100个文档的数据集，且 group = [10, 20, 40, 10, 10, 10]，这意味着你有6个组，其中前10条记录在第一组，记录11-30在第二组，记录31-70在第三组，依此类推。
eval_set (list or None, optional (default=None)) – 用于作为验证集的 (X, y) 元组对列表。
eval_names (list of str, or None, optional (default=None)) – eval_set 的名称。
eval_sample_weight (list of Dask Array or Dask Series, or None, optional (default=None)) – 评估数据的权重。权重应为非负数。
eval_init_score (list of Dask Array or Dask Series, or None, optional (default=None)) – 评估数据的初始分数。
eval_group (list of Dask Array or Dask Series, or None, optional (default=None)) – 分组评估数据。
eval_metric (str, callable, list or None, optional (default=None)) – 如果是字符串，它应该是要使用的内置评估指标。如果是可调用对象，它应该是一个自定义评估指标，请参见下面的注释以获取更多详细信息。如果是列表，它可以是内置指标的列表、自定义评估指标的列表，或者是两者的混合。在任何情况下，模型参数中的 metric 也将被评估并使用。默认值：LGBMRegressor 为 ‘l2’，LGBMClassifier 为 ‘logloss’，LGBMRanker 为 ‘ndcg’。
eval_at (list or tuple of int, optional (default=(1, 2, 3, 4, 5))) – 指定指标的评估位置。
feature_name (list of str, or 'auto', optional (default='auto')) – 特征名称。如果为 ‘auto’ 且数据是 pandas DataFrame，则使用数据列名称。
categorical_feature (list of str or int, or 'auto', optional (default='auto')) – 分类特征。如果是整数列表，则解释为索引。如果是字符串列表，则解释为特征名称（还需要指定 feature_name）。如果是 ‘auto’ 且数据是 pandas DataFrame，则使用 pandas 的无序分类列。分类特征中的所有值将被转换为 int32，因此应小于 int32 的最大值（2147483647）。大值可能会消耗大量内存。考虑使用从零开始的连续整数。分类特征中的所有负值将被视为缺失值。输出不能相对于分类特征进行单调约束。分类特征中的浮点数将向 0 舍入。
**kwargs – 传递给 LGBMRanker.fit() 的其他参数。

返回:

self – 返回自身。

返回类型:

lightgbm.DaskLGBMRanker

备注

自定义评估函数期望一个具有以下签名的可调用对象：func(y_true, y_pred)、func(y_true, y_pred, weight) 或 func(y_true, y_pred, weight, group)，并返回 (eval_name, eval_result, is_higher_better) 或 (eval_name, eval_result, is_higher_better) 的列表：

y_truenumpy 一维数组，形状为 = [n_samples]
目标值。

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

重量numpy 一维数组，形状为 = [n_samples]
样本的权重。权重应为非负数。

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

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

eval_result浮动
评估结果。

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

get_metadata_routing()

获取此对象的元数据路由。

请查看用户指南以了解路由机制的工作原理。

返回:: routing – 一个封装了路由信息的 MetadataRequest。
返回类型:: MetadataRequest

get_params(deep=True)

获取此估计器的参数。

参数:: deep (bool, optional (default=True)) – 如果为 True，将返回此估计器及其包含的作为估计器的子对象的参数。
返回:: params – 参数名称映射到它们的值。
返回类型:: dict

property n_estimators_

实际执行的提升迭代次数。

如果启用了早期停止或由于复杂性限制（如 min_gain_to_split）导致提升提前停止，这可能会少于参数 n_estimators。

Added in version 4.0.0.

类型:: int

property n_features_

拟合模型的特征数量。

类型:: int

property n_features_in_

拟合模型的特征数量。

类型:: int

property n_iter_

实际执行的提升迭代次数。

如果启用了早期停止或由于复杂性限制（如 min_gain_to_split）导致提升提前停止，这可能会少于参数 n_estimators。

Added in version 4.0.0.

类型:: int

property objective_

拟合此模型时使用的具体目标。

类型:: str or callable

predict(X, raw_score=False, start_iteration=0, num_iteration=None, pred_leaf=False, pred_contrib=False, validate_features=False, **kwargs)[源代码]

返回每个样本的预测值。

参数:

X (Dask Array or Dask DataFrame of shape = [n_samples, n_features]) – 输入特征矩阵。
raw_score (bool, optional (default=False)) – 是否预测原始分数。
start_iteration (int, optional (default=0)) – 开始预测的迭代索引。如果 <= 0，则从第一次迭代开始。
num_iteration (int or None, optional (default=None)) – 预测中使用的总迭代次数。如果为 None，如果存在最佳迭代并且 start_iteration <= 0，则使用最佳迭代；否则，使用从 start_iteration 开始的所有迭代（无限制）。如果 <= 0，则使用从 start_iteration 开始的所有迭代（无限制）。
pred_leaf (bool, optional (default=False)) – 是否预测叶索引。
pred_contrib (bool, optional (default=False)) – 是否预测特征贡献。 .. 注意:: 如果你想使用 SHAP 值为你的模型预测获得更多解释，比如 SHAP 交互值，你可以安装 shap 包（https://github.com/slundberg/shap）。请注意，与 shap 包不同，使用 pred_contrib 我们返回一个带有额外列的矩阵，其中最后一列是期望值。
validate_features (bool, optional (default=False)) – 如果为真，确保用于预测的特征与用于训练的特征匹配。仅在数据为 pandas DataFrame 时使用。
**kwargs – 预测的其他参数。

返回:

predicted_result (Dask 数组的形状 = [n_samples]) – 预测的值。
X_leaves (Dask Array of shape = [n_samples, n_trees]) – 如果 pred_leaf=True，则为每个样本预测的每棵树的叶子。
X_SHAP_values (Dask Array of shape = [n_samples, n_features + 1]) – 如果 pred_contrib=True，则为每个样本的特征贡献。

set_fit_request(*, eval_at='$UNCHANGED$', eval_group='$UNCHANGED$', eval_init_score='$UNCHANGED$', eval_metric='$UNCHANGED$', eval_names='$UNCHANGED$', eval_sample_weight='$UNCHANGED$', eval_set='$UNCHANGED$', group='$UNCHANGED$', init_score='$UNCHANGED$', sample_weight='$UNCHANGED$')

传递给 fit 方法的请求元数据。

请注意，此方法仅在 enable_metadata_routing=True 时相关（参见 sklearn.set_config()）。请参阅用户指南了解路由机制的工作原理。

每个参数的选项是：

True: 请求元数据，并在提供时传递给 fit。如果未提供元数据，则忽略该请求。
False: 不请求元数据，元估计器不会将其传递给 fit。
None: 不需要元数据，如果用户提供了元数据，元估计器将引发错误。
str: 元数据应使用此给定别名传递给元估计器，而不是原始名称。

默认值 (sklearn.utils.metadata_routing.UNCHANGED) 保留现有的请求。这允许你更改某些参数的请求，而不更改其他参数。

Added in version 1.3.

备注

此方法仅在将此估计器用作元估计器的子估计器时相关，例如在 Pipeline 内部使用。否则它不会有任何效果。

参数:

eval_at (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 eval_at 参数的元数据路由。
eval_group (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 中 eval_group 参数的元数据路由。
eval_init_score (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 eval_init_score 参数的元数据路由。
eval_metric (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 eval_metric 参数的元数据路由。
eval_names (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 中 eval_names 参数的元数据路由。
eval_sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 eval_sample_weight 参数的元数据路由。
eval_set (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 eval_set 参数的元数据路由。
group (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 中 group 参数的元数据路由。
init_score (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 init_score 参数的元数据路由。
sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – fit 方法中 sample_weight 参数的元数据路由。

返回:

self – 更新后的对象。

返回类型:

object

set_params(**params)

设置此估计器的参数。

参数:: **params – 带有新值的参数名称。
返回:: self – 返回自身。
返回类型:: object

set_predict_request(*, num_iteration='$UNCHANGED$', pred_contrib='$UNCHANGED$', pred_leaf='$UNCHANGED$', raw_score='$UNCHANGED$', start_iteration='$UNCHANGED$', validate_features='$UNCHANGED$')

传递给 predict 方法的请求元数据。

请注意，此方法仅在 enable_metadata_routing=True 时相关（参见 sklearn.set_config()）。请参阅用户指南了解路由机制的工作原理。

每个参数的选项是：

True: 请求元数据，并在提供时传递给 predict。如果未提供元数据，则忽略请求。
False: 不需要元数据，元估计器不会将其传递给 predict。
None: 不需要元数据，如果用户提供了元数据，元估计器将引发错误。
str: 元数据应使用此给定别名传递给元估计器，而不是原始名称。

默认值 (sklearn.utils.metadata_routing.UNCHANGED) 保留现有的请求。这允许你更改某些参数的请求，而不更改其他参数。

Added in version 1.3.

备注

此方法仅在将此估计器用作元估计器的子估计器时相关，例如在 Pipeline 内部使用。否则它不会有任何效果。

参数:

num_iteration (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 num_iteration 参数的元数据路由。
pred_contrib (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 pred_contrib 参数的元数据路由。
pred_leaf (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 pred_leaf 参数的元数据路由。
raw_score (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 raw_score 参数的元数据路由。
start_iteration (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 start_iteration 参数的元数据路由。
validate_features (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – predict 方法中 validate_features 参数的元数据路由。

返回:

self – 更新后的对象。

返回类型:

object

to_local()[源代码]

从分布式版本创建 lightgbm.LGBMRanker 的常规版本。

返回:: 模型 – 本地基础模型。
返回类型:: lightgbm.LGBMRanker