CartLearner

• CartLearner
  • hyperparameters
  • learner_name
  • capabilities
  • cross_validation
  • extract_input_feature_names
  • hyperparameter_templates
  • post_init
  • train
  • train_imp
  • validate_hyperparameters

CartLearner

CartLearner(
    label: str,
    task: Task = CLASSIFICATION,
    *,
    weights: Optional[str] = None,
    ranking_group: Optional[str] = None,
    uplift_treatment: Optional[str] = None,
    features: Optional[ColumnDefs] = None,
    include_all_columns: bool = False,
    max_vocab_count: int = 2000,
    min_vocab_frequency: int = 5,
    discretize_numerical_columns: bool = False,
    num_discretized_numerical_bins: int = 255,
    max_num_scanned_rows_to_infer_semantic: int = 100000,
    max_num_scanned_rows_to_compute_statistics: int = 100000,
    data_spec: Optional[DataSpecification] = None,
    extra_training_config: Optional[TrainingConfig] = None,
    allow_na_conditions: bool = False,
    categorical_algorithm: str = "CART",
    categorical_set_split_greedy_sampling: float = 0.1,
    categorical_set_split_max_num_items: int = -1,
    categorical_set_split_min_item_frequency: int = 1,
    growing_strategy: str = "LOCAL",
    honest: bool = False,
    honest_fixed_separation: bool = False,
    honest_ratio_leaf_examples: float = 0.5,
    in_split_min_examples_check: bool = True,
    keep_non_leaf_label_distribution: bool = True,
    max_depth: int = 16,
    max_num_nodes: Optional[int] = None,
    maximum_model_size_in_memory_in_bytes: float = -1.0,
    maximum_training_duration_seconds: float = -1.0,
    mhld_oblique_max_num_attributes: Optional[int] = None,
    mhld_oblique_sample_attributes: Optional[bool] = None,
    min_examples: int = 5,
    missing_value_policy: str = "GLOBAL_IMPUTATION",
    num_candidate_attributes: Optional[int] = -1,
    num_candidate_attributes_ratio: Optional[float] = None,
    numerical_vector_sequence_num_examples: int = 1000,
    numerical_vector_sequence_num_random_anchors: int = 100,
    pure_serving_model: bool = False,
    random_seed: int = 123456,
    sorting_strategy: str = "IN_NODE",
    sparse_oblique_max_num_features: Optional[int] = None,
    sparse_oblique_max_num_projections: Optional[
        int
    ] = None,
    sparse_oblique_normalization: Optional[str] = None,
    sparse_oblique_num_projections_exponent: Optional[
        float
    ] = None,
    sparse_oblique_projection_density_factor: Optional[
        float
    ] = None,
    sparse_oblique_weights: Optional[str] = None,
    sparse_oblique_weights_integer_maximum: Optional[
        int
    ] = None,
    sparse_oblique_weights_integer_minimum: Optional[
        int
    ] = None,
    sparse_oblique_weights_power_of_two_max_exponent: Optional[
        int
    ] = None,
    sparse_oblique_weights_power_of_two_min_exponent: Optional[
        int
    ] = None,
    split_axis: str = "AXIS_ALIGNED",
    uplift_min_examples_in_treatment: int = 5,
    uplift_split_score: str = "KULLBACK_LEIBLER",
    validation_ratio: float = 0.1,
    working_dir: Optional[str] = None,
    num_threads: Optional[int] = None,
    tuner: Optional[AbstractTuner] = None,
    feature_selector: Optional[
        AbstractFeatureSelector
    ] = None,
    explicit_args: Optional[Set[str]] = None
)

基类: GenericCCLearner

Cart 学习算法。

CART（分类与回归树）是一种决策树。非叶节点包含条件（也称为分裂），而叶节点包含预测值。训练数据集分为两部分。第一部分用于构建树，第二部分用于修剪树。

使用示例

import ydf
import pandas as pd

dataset = pd.read_csv("project/dataset.csv")

model = ydf.CartLearner().train(dataset)

print(model.describe())

超参数已配置为对典型数据集提供合理的结果。超参数也可以手动修改（参见下面的描述），或通过应用 CartLearner.hyperparameter_templates() 中提供的超参数模板（详细信息请参阅此函数的文档）。

属性

名称	类型	描述
label		数据集的标签。标签列不应在 features 参数中被标识为特征。
task		要解决的任务（例如 Task.CLASSIFICATION, Task.REGRESSION, Task.RANKING, Task.CATEGORICAL_UPLIFT, Task.NUMERICAL_UPLIFT）。
weights		标识每个样本权重的特征名称。如果未指定权重，则假定单位权重。权重列不应在 features 参数中被标识为特征。
ranking_group		仅适用于 task=Task.RANKING。标识查询/文档排序任务中查询的特征名称。排序分组不应在 features 参数中被标识为特征。
uplift_treatment		仅适用于 task=Task.CATEGORICAL_UPLIFT 和 task=Task.NUMERICAL_UPLIFT。一个数值特征的名称，用于标识提升问题中的处理方式。值 0 保留给对照处理。目前仅支持 0/1 二元处理。
features		如果为 None，则所有列都用作特征。特征的语义会自动确定。否则，如果 include_all_columns=False（默认），则仅导入 features 中列出的列。如果 include_all_columns=True，则所有列都作为特征导入，并且仅自动确定不在 columns 中的列的语义。如果指定，则定义特征的顺序 - 任何未列出的特征将按顺序附加到指定的特征之后（如果 include_all_columns=True）。标签、权重、提升处理和排序分组列不应被指定为特征。
include_all_columns		参见 features。
max_vocab_count		存储为字符串的 CATEGORICAL 和 CATEGORICAL_SET 列的词汇表最大大小。如果存在更多唯一值，则仅保留最频繁的值，其余值被视为词汇外 (out-of-vocabulary)。
min_vocab_frequency		CATEGORICAL 和 CATEGORICAL_SET 列中值的最小出现次数。出现次数少于 min_vocab_frequency 的值被视为词汇外 (out-of-vocabulary)。
discretize_numerical_columns		如果为 true，则在训练前对所有数值列进行离散化。离散化后的数值列训练速度更快，但可能会对模型质量产生负面影响。使用 discretize_numerical_columns=True 等同于在 column 参数中设置列语义 DISCRETIZED_NUMERICAL。有关 DISCRETIZED_NUMERICAL 的更多详细信息，请参见其定义。
num_discretized_numerical_bins		对数值列进行离散化时使用的 bin 数量。
max_num_scanned_rows_to_infer_semantic		在未明确指定列语义时，扫描多少行来推断其语义。仅在从文件读取时使用，内存中的数据集总是完整读取。将其设置为较小的值会加快数据集读取速度，但可能导致不正确的列语义。设置为 -1 扫描整个数据集。
max_num_scanned_rows_to_compute_statistics		在计算列统计信息时扫描多少行。仅在从文件读取时使用，内存中的数据集总是完整读取。列的统计信息包括类别特征的字典和数值特征的均值/最小值/最大值。将其设置为较小的值会加快数据集读取速度，但会使 dataspec 中的统计信息失真，这可能会损害模型质量（例如，如果类别特征的一个重要类别被视为 OOV）。设置为 -1 扫描整个数据集。
data_spec		要使用的数据规范 (dataspec)（高级）。如果提供了数据规范，则 columns、include_all_columns、max_vocab_count、min_vocab_frequency、discretize_numerical_columns 和 num_discretized_numerical_bins 将被忽略。
extra_training_config		训练配置 proto（高级）。如果设置，此训练配置 proto 将与学习器隐式定义的配置合并。可用于设置未作为构造函数参数公开的内部或高级参数。extra_training_config 中的参数优先于构造函数参数。
allow_na_conditions		如果为 true，树训练会评估 X is NA 即 X 缺失 类型的条件。默认值：False。
categorical_algorithm		如何学习类别属性上的分裂。- CART：CART 算法。查找形如“值 \in mask”的类别分裂。对于二元分类、回归和排序，该解决方案是精确的。对于多类别分类，该方案是近似的。这是首选的算法。在过拟合情况下（数据集非常小，字典很大），“随机”算法是一个很好的替代方案。- ONE_HOT：独热编码 (One-hot encoding)。找到形如“属性 == 参数”的最优类别分裂。这种方法与将每个可能的类别值转换为布尔特征的方法类似（但更高效）。该方法可用于比较目的，通常性能不如其他替代方案。- RANDOM：在一组随机候选分裂中找到最佳分裂。使用随机搜索查找形如“值 \in mask”的类别分裂。该解决方案可以看作是 CART 算法的近似。这种方法是 CART 的有力替代方案。该算法的灵感来源于 2001 年“随机森林”论文的“5.1 类别变量”部分。默认值：“CART”。
categorical_set_split_greedy_sampling		用于类别集合分裂，例如文本。一个类别值成为正向集合候选的概率。采样应用于每个节点一次（即并非贪婪优化的每一步）。默认值：0.1。
categorical_set_split_max_num_items		用于类别集合分裂，例如文本。项目（采样前）的最大数量。如果项目数量较多，则忽略出现频率最低的项目。更改此值类似于在加载数据集之前更改“max_vocab_count”，但有一个例外：使用 max_vocab_count 时，所有剩余项目都归入一个特殊的词汇外项目。使用 max_num_items 时则不是这样。默认值：-1。
categorical_set_split_min_item_frequency		用于类别集合分裂，例如文本。考虑一个项目的最小出现次数。默认值：1。
growing_strategy		如何生长树。- LOCAL：每个节点独立于其他节点进行分裂。换句话说，只要一个节点满足分裂约束（例如最大深度、最小观察数量），该节点就会被分裂。这是构建决策树的“经典”方式。- BEST_FIRST_GLOBAL：选择树中所有节点中损失减少最好的节点进行分裂。这种方法也称为“最佳优先”或“叶子优先生长”。有关更多详细信息，请参见 Shi 的“最佳优先决策树学习”和 Friedman 的“加性逻辑回归：提升的统计学观点”。默认值：“LOCAL”。
honest		在 honest 树中，使用不同的训练样本来推断结构和叶节点值。这种正则化技术用样本换取偏差估计。它可能会提高或降低模型质量。参见 Athey 等人的“广义随机森林”。在该论文中，Honest 树使用不放回采样 (sampling without replacement) 的随机森林算法进行训练。默认值：False。
honest_fixed_separation		仅适用于 honest 树，即 honest=true。如果为 true，则为每棵树生成一个新的随机分离。如果为 false，则所有树使用相同的分离（例如，在包含多棵树的梯度提升树中）。默认值：False。
honest_ratio_leaf_examples		仅适用于 honest 树，即 honest=true。用于设置叶节点值的样本比例。默认值：0.5。
in_split_min_examples_check		是在分裂搜索中检查 min_examples 约束（即导致一个子节点样本数少于 min_examples 的分裂被视为无效），还是在分裂搜索之前检查（即只有当节点包含的样本数多于 min_examples 时才能派生分裂）。如果为 false，则可能存在训练样本少于 min_examples 的节点。默认值：True。
keep_non_leaf_label_distribution		是否保留非叶节点的节点值（即训练样本标签的分布）。此信息在服务期间不使用，但可用于模型解释和超参数调优。这会占用大量空间，有时可占模型大小的一半。默认值：True。
max_depth		树的最大深度。max_depth=1 表示所有树都是根节点。max_depth=-1 表示树的深度不受此参数限制。小于等于 -2 的值将被忽略。默认值：16。
max_num_nodes		树中的最大节点数。设置为 -1 可禁用此限制。仅适用于 growing_strategy=BEST_FIRST_GLOBAL。默认值：None。
maximum_model_size_in_memory_in_bytes		限制模型存储在内存中的大小。不同的算法可能会以不同的方式强制执行此限制。请注意，当模型编译成推理引擎时，推理引擎的大小通常比原始模型小得多。默认值：-1.0。
maximum_training_duration_seconds		模型的最大训练时长，以秒为单位。每个学习算法可以根据需要自由使用此参数。启用最大训练时长会使模型训练变得不确定。默认值：-1.0。
mhld_oblique_max_num_attributes		用于 MHLD 斜向分裂，即 split_axis=MHLD_OBLIQUE。投影中属性的最大数量。增加此值会增加训练时间。减小此值起到正则化作用。该值应在 [2, num_numerical_features] 范围内。如果该值高于数值特征总数，则会自动截断。允许值为 1，但会导致普通（非斜向）分裂。默认值：None。
mhld_oblique_sample_attributes		用于 MHLD 斜向分裂，即 split_axis=MHLD_OBLIQUE。如果为 true，则应用由“num_candidate_attributes”或“num_candidate_attributes_ratio”参数控制的属性采样。如果为 false，则测试所有属性。默认值：None。
min_examples		一个节点中的最小样本数。默认值：5。
missing_value_policy		处理缺失属性值的方法。- GLOBAL_IMPUTATION：使用在整个数据集上计算的均值（数值属性）或最频繁项（类别属性）填充缺失属性值（即数据规范中包含的信息）。- LOCAL_IMPUTATION：使用在当前节点的训练样本上评估的均值（数值属性）或最频繁项（类别属性）填充缺失属性值。- RANDOM_LOCAL_IMPUTATION：从当前节点训练样本中随机采样值填充缺失属性值。这种方法由 Clinic 等人在“Random Survival Forests”论文中提出 (https://projecteuclid.org/download/pdfview_1/euclid.aoas/1223908043)。默认值：“GLOBAL_IMPUTATION”。
num_candidate_attributes		每个节点测试的唯一有效属性数量。如果一个属性至少有一个有效分裂，则该属性有效。如果 num_candidate_attributes=0，该值将设置为随机森林的经典默认值：分类时为 sqrt(number of input attributes)，回归时为 number_of_input_attributes / 3。如果 num_candidate_attributes=-1，则测试所有属性。默认值：-1。
num_candidate_attributes_ratio		每个节点测试的属性比例。如果设置，则等同于 num_candidate_attributes = number_of_input_features x num_candidate_attributes_ratio。可能的值在 ]0, 1] 之间以及 -1。如果未设置或等于 -1，则使用 num_candidate_attributes。默认值：None。
numerical_vector_sequence_num_examples		对于具有 NUMERICAL_VECTOR_SEQUENCE 特征的数据集（即固定大小数值向量的序列）。用于寻找分裂的最大样本数量。较大的值可以提高模型质量，但训练时间更长。默认值：1000。
numerical_vector_sequence_num_random_anchors		对于具有 NUMERICAL_VECTOR_SEQUENCE 特征的数据集（即固定大小数值向量的序列）。随机生成的锚点值的数量。较大的值可以提高模型质量，但训练时间更长。默认值：100。
pure_serving_model		清除模型中任何模型服务不需要的信息。这包括调试、模型解释及其他元数据。序列化模型的大小可显著减小（模型大小减少 50% 很常见）。此参数对模型服务的质量、服务速度或 RAM 使用没有影响。默认值：False。
random_seed		模型训练的随机种子。学习器应由随机种子决定性地运行。默认值：123456。
sorting_strategy		如何对数值特征进行排序以寻找分裂 - AUTO：在 IN_NODE、FORCE_PRESORT 和 LAYER 中选择最有效的方法。- IN_NODE：特征在节点中使用前才进行排序。该方案速度慢，但内存消耗少。- FORCE_PRESORT：特征在训练开始时预排序。该方案速度快，但比 IN_NODE 消耗更多内存。- PRESORT：自动选择 FORCE_PRESORT 和 IN_NODE。默认值：“IN_NODE”。
sparse_oblique_max_num_features		用于稀疏斜向分裂，即 split_axis=SPARSE_OBLIQUE。控制一个分裂中的最大特征数量。设置为 -1 表示无最大限制。仅在需要对变量数量进行硬性限制时使用，否则 prefer projection_density_factor 来控制每个投影中的特征数量。默认值：None。
sparse_oblique_max_num_projections		用于稀疏斜向分裂，即 split_axis=SPARSE_OBLIQUE。最大投影数量（在 num_projections_exponent 后应用）。斜向分裂尝试 max(p^num_projections_exponent, max_num_projections) 次随机投影来选择分裂，其中 p 是数值特征的数量。增加“max_num_projections”会增加训练时间，但不影响推理时间。在模型开发的后期阶段，如果每一个精度都很重要，请增加此值。论文“Sparse Projection Oblique Random Forests”（Tomita 等人，2020 年）没有定义此超参数。默认值：None。
sparse_oblique_normalization		用于稀疏斜向分裂，即 split_axis=SPARSE_OBLIQUE。在应用稀疏斜向投影之前，对特征应用的归一化。- NONE：无归一化。- STANDARD_DEVIATION：按整个训练数据集上估计的标准差对特征进行归一化，也称为 Z-Score 归一化。- MIN_MAX：按整个训练数据集上估计的范围（即最大值 - 最小值）对特征进行归一化。默认值：None。
sparse_oblique_num_projections_exponent		用于稀疏斜向分裂，即 split_axis=SPARSE_OBLIQUE。控制在每个节点测试的随机投影数量。增加此值很可能提高模型质量，显著增加训练时间，但不影响推理时间。斜向分裂尝试 max(p^num_projections_exponent, max_num_projections) 次随机投影来选择分裂，其中 p 是数值特征的数量。因此，增加 num_projections_exponent 以及可能的 max_num_projections 可以提高模型质量，但也会显著增加训练时间。请注意，(经典) 随机森林的复杂度大约与 num_projections_exponent=0.5 成正比，因为它在一个分裂中考虑 sqrt(num_features)。(经典) GBDT 的复杂度大约与 num_projections_exponent=1 成正比，因为它在一个分裂中考虑所有特征。论文“Sparse Projection Oblique Random Forests”（Tomita 等人，2020 年）建议的值在 [1/4, 2] 范围内。默认值：None。
sparse_oblique_projection_density_factor		投影密度作为特征数量的指数。对于每个投影，每个特征独立地有“projection_density_factor / num_features”的概率被考虑在投影中。论文“Sparse Projection Oblique Random Forests”（Tomita 等人，2020 年）将此参数称为 lambda 并建议值在 [1, 5] 范围内。增加此值会增加训练和推理时间（平均而言）。此值最好针对每个数据集进行调整。默认值：None。
sparse_oblique_weights		用于稀疏斜向分裂，即 split_axis=SPARSE_OBLIQUE。请注意，归一化是在采样权重后应用的，例如，只有在归一化为 NONE 时，才能保证二元权重为二元。 可能的值：- BINARY：斜向权重在 {-1,1} 中采样（默认）。- CONTINUOUS：斜向权重在 [-1,1] 中采样。- POWER_OF_TWO：斜向权重是 2 的幂。指数在 [sparse_oblique_weights_power_of_two_min_exponent, sparse_oblique_weights_power_of_two_max_exponent] 范围内均匀采样，符号均匀采样。- INTEGER：权重是在 [sparse_oblique_weights_integer_minimum, sparse_oblique_weights_integer_maximum] 范围内均匀采样的整数。默认值：None。
sparse_oblique_weights_integer_maximum		用于稀疏斜向分裂，即 split_axis=SPARSE_OBLIQUE 且权重为整数，即 sparse_oblique_weights=INTEGER。权重的最大值。默认值：None。
sparse_oblique_weights_integer_minimum		用于稀疏斜向分裂，即 split_axis=SPARSE_OBLIQUE 且权重为整数，即 sparse_oblique_weights=INTEGER。权重的最小值。默认值：None。
sparse_oblique_weights_power_of_two_max_exponent		用于稀疏斜向分裂，即 split_axis=SPARSE_OBLIQUE 且权重为 2 的幂，即 sparse_oblique_weights=POWER_OF_TWO。权重的最大指数。默认值：None。
sparse_oblique_weights_power_of_two_min_exponent		用于稀疏斜向分裂，即 split_axis=SPARSE_OBLIQUE 且权重为 2 的幂，即 sparse_oblique_weights=POWER_OF_TWO。权重的最小指数。默认值：None。
split_axis		对数值特征考虑哪种分裂结构。- AXIS_ALIGNED：轴对齐分裂（即一次一个条件）。这是训练树的“经典”方法。默认值。- SPARSE_OBLIQUE：来自“Sparse Projection Oblique Random Forests”（Tomita 等人，2020 年）的稀疏斜向分裂（即对少量特征进行随机分裂）。- MHLD_OBLIQUE：来自“Classification Based on Multivariate Contrast Patterns”（Canete-Sifuentes 等人，2029 年）的多类别 Hellinger 线性判别分裂。默认值：“AXIS_ALIGNED”。
uplift_min_examples_in_treatment		仅适用于提升模型。节点中每个处理类型的最小样本数。默认值：5。
uplift_split_score		仅适用于提升模型。分裂器得分，即分裂器优化的得分。这些得分在 Rzepakowski 等人的论文“用于单处理和多处理提升建模的决策树”中介绍。符号：p 是正向结果的概率/平均值，q 是对照组的概率/平均值。- KULLBACK_LEIBLER 或 KL：- p log (p/q) - EUCLIDEAN_DISTANCE 或 ED：(p-q)^2 - CHI_SQUARED 或 CS：(p-q)^2/q 默认值：“KULLBACK_LEIBLER”。
validation_ratio		用于创建验证数据集以修剪树的训练数据集比例。如果设置为 0，则整个数据集用于训练，并且不修剪树。默认值：0.1。
working_dir		学习算法可用于存储中间计算结果的目录路径。根据学习算法和参数的不同，working_dir 可能是可选的、必需的或被忽略。例如，分布式训练算法总是需要“working_dir”，如果提供了“working_dir”，梯度提升树和超参数调优器将导出工件到该目录。
num_threads		用于训练模型的线程数。不同的学习算法使用多线程的方式和效率各不相同。如果为 None，num_threads 将自动设置为处理器数量（最多 32 个；如果处理器数量不可用，则设置为 6）。将 num_threads 设置为远大于处理器数量可能会降低训练速度。默认值逻辑将来可能会改变。
tuner		如果设置，则使用提供的调优器自动选择最佳超参数。使用分布式训练时，调优也是分布式的。
feature_selector		如果设置，则使用指定的特征选择器通过自动化特征选择来自动选择模型的输入特征。
explicit_args		用于内部使用的辅助参数。如果用户明确提供，则抛出错误。

hyperparameters property

hyperparameters: HyperParameters

此学习器的（可变）超参数字典。

此对象可用于创建学习器后检查或修改超参数。在构建学习器后修改超参数适用于某些高级用例。由于这种方法绕过了对给定超参数集的一些可行性检查，因此通常最好为每个模型重新创建学习器。可以使用 validate_hyperparameters() 手动验证当前的超参数集。

learner_name property

learner_name: str

capabilities classmethod

capabilities() -> LearnerCapabilities

cross_validation

cross_validation(
    ds: InputDataset,
    folds: int = 10,
    bootstrapping: Union[bool, int] = False,
    parallel_evaluations: int = 1,
) -> Evaluation

extract_input_feature_names

extract_input_feature_names(ds: InputDataset) -> List[str]

hyperparameter_templates classmethod

hyperparameter_templates() -> (
    Dict[str, HyperparameterTemplate]
)

此学习器的超参数模板。

此学习器目前不提供任何超参数模板，提供此方法是为了与其他学习器保持一致。

返回值

类型	描述
Dict[str, HyperparameterTemplate]	空字典。

post_init

post_init()

train

train(
    ds: InputDataset,
    valid: Optional[InputDataset] = None,
    verbose: Optional[Union[int, bool]] = None,
) -> RandomForestModel

在给定数据集上训练模型。

数据集读取选项在学习器上给出。有关 YDF 中数据集读取的更多信息，请查阅学习器或 ydf.create_vertical_dataset() 的文档。

使用示例

import ydf
import pandas as pd

train_ds = pd.read_csv(...)

learner = ydf.CartLearner(label="label")
model = learner.train(train_ds)
print(model.summary())

如果训练中断（例如，通过中断 Colab 中的单元格执行），模型将恢复到中断时的状态。

参数

名称	类型	描述	默认值
ds	InputDataset	训练数据集。	必需
valid	Optional[InputDataset]	可选的验证数据集。某些学习器（例如 Random Forest）不需要验证数据集。某些学习器（例如 GradientBoostedTrees）如果在未提供验证数据集时会自动从训练数据集中提取验证数据集。	None
verbose	Optional[Union[int, bool]]	训练期间的详细程度。如果为 None，则使用 ydf.verbose 的全局详细级别。级别包括：0 或 False：无日志，1 或 True：在笔记本中打印少量日志；在终端中打印所有日志。2：在所有表面上打印所有日志。	None

返回值

类型	描述
RandomForestModel	训练好的模型。

train_imp

train_imp(
    ds: InputDataset,
    valid: Optional[InputDataset],
    verbose: Optional[Union[int, bool]],
) -> ModelType

validate_hyperparameters

validate_hyperparameters() -> None