econml.validate.DRTester

class econml.validate.DRTester(*, model_regression, model_propensity, cate, cv: Union[int, List] = 5)[source]

Bases: object

CATE 模型的验证测试。包括 Chernozhukov 等人 (2022) 中的最佳线性预测器 (BLP) 测试，Dwivedi 等人 (2020) 中的校准测试，以及 Radcliffe (2007) 中的 QINI 系数。

最佳线性预测器 (BLP)

对 CATE 模型（和一个常数）的双重稳健 (DR) 结果进行普通最小二乘法 (OLS) 回归。如果 CATE 模型捕捉到真实的异质性，那么 CATE 预测的 OLS 估计值应该为正且显著不为 0。

校准

首先，根据 CATE 预测 (s(Z)) 的样本外定义的分位数将单位进行分组 (k)。在每个组内，计算平均 CATE 预测与 DR 结果之间的绝对差，以及平均 CATE 预测与总体 ATE 之间的绝对差。然后将这些差异加权后在各组中求和，权重为单位属于该组的概率。

\[ \begin{align}\begin{aligned}\mathrm{Cal}_G = \sum_k \pi(k) |{\E[s(Z) | k] - \E[Y^{DR} | k]}|\\\mathrm{Cal}_O = \sum_k \pi(k) |{\E[s(Z) | k] - \E[Y^{DR}]}|\end{aligned}\end{align} \]

校准 R 方定义为

\[\mathcal{R^2}_C = 1 - \frac{\mathrm{Cal}_G}{\mathrm{Cal}_O}\]

校准 R 方指标类似于标准 R 方分数，它可以取小于或等于 1 的任何值，分数越接近 1 表示 CATE 模型校准得越好。

提升建模 (Uplift Modeling)

单位按照预测的 CATE 值排序，并在通过等级进展时，对每个队列的平均处理效应保持一个运行中的度量。由此产生的 TOC 曲线可以被绘制出来，其积分可以作为 CATE 模型捕获的真实异质性的度量；这个积分被称为 AUTOC (area under TOC)。QINI 曲线是此曲线的一个变体，它也结合了处理概率；其积分被称为 QINI 系数。

更正式地，TOC 和 QINI 曲线由以下函数给出

\[ \begin{align}\begin{aligned}\tau_{TOC}(q) = \mathrm{Cov}( Y^{DR}(g,p), \frac{ \mathbb{1}\{\hat{\tau}(Z) \geq \hat{\mu}(q)\} }{ \mathrm{Pr}(\hat{\tau}(Z) \geq \hat{\mu}(q)) } )\\\tau_{QINI}(q) = \mathrm{Cov}(Y^{DR}(g,p), \mathbb{1}\{\hat{\tau}(Z) \geq \hat{\mu}(q)\})\end{aligned}\end{align} \]

其中 \(q\) 是期望的分位数，\(\hat{\mu}\) 是分位数函数，\(\hat{\tau}\) 是预测的 CATE 函数。\(Y^{DR}(g,p)\) 指给定观测的双重稳健结果差异（相对于对照组）。

AUTOC 和 QINI 系数由以下给出

\[ \begin{align}\begin{aligned}AUTOC = \int_0^1 \tau_{TOC}(q) dq\\QINI = \int_0^1 \tau_{QINI}(q) dq\end{aligned}\end{align} \]
参数

  • model_regression (estimator) – 用于将结果拟合到特征的辅助模型估计器。必须能够实现 fit 和 predict 方法

  • model_propensity (estimator) – 用于将处理分配拟合到特征的辅助模型估计器。必须能够实现 fit 方法和 predict（二元处理）或 predict_proba（多分类处理）方法之一。

  • cate (estimator) – 已拟合的条件平均处理效应 (CATE) 估计器，待验证。

  • cv (int or list, default 5) – 用于交叉验证的分割器。可以是整数（对应于所需的折数）或对应于每折成员关系的索引列表。

参考文献

[Chernozhukov2022] V. Chernozhukov et al. 随机实验中异质处理效应的通用机器学习推断 arXiv 预印本 arXiv:1712.04802, 2022. https://arxiv.org/abs/1712.04802

[Dwivedi2020] R. Dwivedi et al. 通过因果研究中的校准稳定发现可解释子群 arXiv 预印本 arXiv:2008.10109, 2020. https://arxiv.org/abs/2008.10109

[Radcliffe2007] N. Radcliffe 使用对照组以预测升降量为目标：构建和评估提升模型。Direct Marketing Analytics Journal (2007)，第 14–21 页。

__init__(*, model_regression, model_propensity, cate, cv: Union[int, List] = 5)[source]

方法

__init__(*, model_regression, ...[, cv])

evaluate_all([Xval, Xtrain, n_groups, ...])

实现最佳线性预测 (evaluate_blp)、校准 (evaluate_cal)、提升曲线 (evaluate_uplift) 方法

evaluate_blp([Xval, Xtrain])

实现 [Chernozhukov2022] 中的最佳线性预测器 (BLP) 测试。

evaluate_cal([Xval, Xtrain, n_groups])

实现 [Dwivedi2020] 中的校准测试

evaluate_uplift([Xval, Xtrain, percentiles, ...])

计算给定模型的提升曲线和系数，其中单位按预测的 CATE 值排序，并在通过等级进展时，对每个队列的平均处理效应保持一个运行中的度量。

fit_nuisance(Xval, Dval, yval[, Xtrain, ...])

通过 (1) 在验证样本中交叉拟合，或 (2) 在训练样本中拟合并应用于验证样本，生成辅助预测并计算双重稳健 (DR) 结果。

fit_nuisance_cv(X, D, y)

使用 k 折交叉验证生成辅助函数预测。

fit_nuisance_train(Xtrain, Dtrain, ytrain, Xval)

在训练样本中拟合辅助模型，并应用于验证样本生成预测。

get_cate_preds(Xval[, Xtrain])

从已拟合的 CATE 模型生成预测。

get_cv_splits(vars, T)

给定一组变量和处理向量，生成交叉验证的分割。

get_cv_splitter([random_state])

生成用于交叉验证的分割器对象。
evaluate_all(Xval: Optional[numpy.array] = None, Xtrain: Optional[numpy.array] = None, n_groups: int = 4, n_bootstrap: int = 1000) → econml.validate.results.EvaluationResults[source]

实现最佳线性预测 (evaluate_blp)、校准 (evaluate_cal)、提升曲线 (evaluate_uplift) 方法

参数

  • Xval ((n_cal x k) matrix, optional) – 用于 CATE 模型的验证样本特征。如果未指定，则必须已实现 fit_cate 方法

  • Xtrain ((n_train x k) matrix, optional) – 用于 CATE 模型的训练样本特征。如果未指定，则必须已实现 fit_cate 方法

  • n_groups (integer, default 4) – 用于计算校准分数的基于分位数的组数。

  • n_bootstrap (integer, default 1000) – 计算提升曲线的均匀置信带时运行的 Bootstrap 样本数。

Return type

EvaluationResults 对象，总结所有测试结果

evaluate_blp(Xval: Optional[numpy.array] = None, Xtrain: Optional[numpy.array] = None) → econml.validate.results.BLPEvaluationResults[source]

实现 [Chernozhukov2022] 中的最佳线性预测器 (BLP) 测试。fit_nusiance 方法必须已实现。

参数

  • Xval ((n_val x k) matrix, optional) – 用于 CATE 模型的验证样本特征。如果未指定，则必须已实现 fit_cate 方法

  • Xtrain ((n_train x k) matrix, optional) – 用于 CATE 模型的训练样本特征。如果指定，则 CATE 在训练样本上拟合并应用于 Xval。如果指定，则 Xtrain, Dtrain, Ytrain 必须已在 fit_nuisance 方法中指定（反之亦然）

Return type

BLPEvaluationResults 对象，显示 BLP 测试结果

evaluate_cal(Xval: Optional[numpy.array] = None, Xtrain: Optional[numpy.array] = None, n_groups: int = 4) → econml.validate.results.CalibrationEvaluationResults[source]

实现 [Dwivedi2020] 中的校准测试

参数

  • Xval ((n_val x n_treatment) matrix, optional) – 用于 CATE 模型的验证样本特征。如果未指定，则必须已实现 fit_cate 方法

  • Xtrain ((n_train x n_treatment) matrix, optional) – 用于 CATE 模型的训练样本特征。如果未指定，则必须已实现 fit cate 方法（并指定了 Xtrain）

  • n_groups (integer, default 4) – 用于计算校准分数的基于分位数的组数。

Return type

CalibrationEvaluationResults 对象，显示校准测试结果

evaluate_uplift(Xval: Optional[numpy.array] = None, Xtrain: Optional[numpy.array] = None, percentiles: numpy.array = array([5., 6.83673469, 8.67346939, 10.51020408, 12.34693878, 14.18367347, 16.02040816, 17.85714286, 19.69387755, 21.53061224, 23.36734694, 25.20408163, 27.04081633, 28.87755102, 30.71428571, 32.55102041, 34.3877551, 36.2244898, 38.06122449, 39.89795918, 41.73469388, 43.57142857, 45.40816327, 47.24489796, 49.08163265, 50.91836735, 52.75510204, 54.59183673, 56.42857143, 58.26530612, 60.10204082, 61.93877551, 63.7755102, 65.6122449, 67.44897959, 69.28571429, 71.12244898, 72.95918367, 74.79591837, 76.63265306, 78.46938776, 80.30612245, 82.14285714, 83.97959184, 85.81632653, 87.65306122, 89.48979592, 91.32653061, 93.16326531, 95.]), metric: str = 'qini', n_bootstrap: int = 1000) → econml.validate.results.UpliftEvaluationResults[source]

计算给定模型的提升曲线和系数，其中单位按预测的 CATE 值排序，并在通过等级进展时，对每个队列的平均处理效应保持一个运行中的度量。提升系数是结果曲线下的面积，值为 0 表示模型具有随机分配的 CATE 系数。所有计算均在验证数据集结果上执行，使用训练集作为输入。

参数

  • Xval ((n_val x k) matrix, optional) – 用于 CATE 模型的验证样本特征。如果未指定，则必须已实现 fit_cate 方法

  • Xtrain ((n_train x k) matrix, optional) – 用于 CATE 模型的训练样本特征。如果指定，则 CATE 在训练样本上拟合并应用于 Xval。如果指定，则 Xtrain, Dtrain, Ytrain 必须已在 fit_nuisance 方法中指定（反之亦然）

  • percentiles (one-dimensional array, default np.linspace(5, 95, 50)) – 应构建 QINI 曲线的分位数数组。默认为 5% 到 95%，间隔 5%。

  • metric (string, default ‘qini’) – 评估哪种类型的提升曲线。必须是 ['toc', 'qini'] 之一。

  • n_bootstrap (integer, default 1000) – 计算均匀置信带时运行的 Bootstrap 样本数。

Return type

UpliftEvaluationResults 对象，显示拟合结果

fit_nuisance(Xval: numpy.array, Dval: numpy.array, yval: numpy.array, Xtrain: Optional[numpy.array] = None, Dtrain: Optional[numpy.array] = None, ytrain: Optional[numpy.array] = None)[source]

通过 (1) 在验证样本中交叉拟合，或 (2) 在训练样本中拟合并应用于验证样本，生成辅助预测并计算双重稳健 (DR) 结果。如果 Xtrain, Dtrain, 和 ytrain 均不为 None，则将实施选项 (2)，否则将实施选项 (1)。为了使用 evaluate_cal 方法，则必须指定 Xtrain, Dtrain, 和 ytrain。

参数

  • Xval ((n_val x k) matrix or vector of length n) – 用于验证样本中辅助模型的特征

  • Dval (vector of length n_val) – 验证样本的处理分配。对照组状态必须是最小值。建议对照组状态为 0，所有其他处理为从 1 开始的整数。

  • yval (vector of length n_val) – 验证样本的结果

  • Xtrain ((n_train x k) matrix or vector of length n, optional) – 用于训练样本中辅助模型的特征

  • Dtrain (vector of length n_train, optional) – 训练样本的处理分配。对照组状态必须是最小值。建议对照组状态为 0，所有其他处理为从 1 开始的整数。

  • ytrain (vector of length n_train, optional) – 训练样本的结果

返回

  • self，以及用于验证处理 (Dval)、处理值 (tmts)、

  • 不包括对照组的处理数 (n_treat)、是否提供训练数据的布尔标志

  • (fit_on_train)、验证集的双重稳健结果值 (dr_val)，以及 DR ATE 值 (ate_val) 的附加属性。

  • 如果提供训练数据，还将添加训练集双重稳健结果 (dr_train) 和训练处理 (Dtrain) 的属性

  • 设置 (dr_train) 和 训练处理 (Dtrain)

fit_nuisance_cv(X: numpy.array, D: numpy.array, y: numpy.array) → Tuple[numpy.array, numpy.array][source]

使用 k 折交叉验证生成辅助函数预测。

参数

  • X ((n x k) matrix) – 用于预测处理/结果的特征

  • D (array of length n) – 处理分配。应具有整数值，最低值对应于对照处理。建议对照组取值为 0，所有其他处理为从 1 开始的整数

  • y (array of length n) – 结果

返回

  • 2 个 (n x n_treatment + 1) 数组，分别对应于处理状态下的预测结果和预测的

  • 处理概率。

fit_nuisance_train(Xtrain: numpy.array, Dtrain: numpy.array, ytrain: numpy.array, Xval: numpy.array) → Tuple[numpy.array, numpy.array][source]

在训练样本中拟合辅助模型，并应用于验证样本生成预测。

参数

  • Xtrain ((n_train x k) matrix) – 训练样本特征，用于预测处理状态和结果

  • Dtrain (array of length n_train) – 训练样本处理分配。应具有整数值，最低值对应于对照处理。建议对照组取值为 0，所有其他处理为从 1 开始的整数

  • ytrain (array of length n_train) – 训练样本的结果

  • Xval ((n_train x k) matrix) – 验证样本特征，用于预测处理状态和结果

返回

  • 2 个 (n_val x n_treatment + 1) 数组，分别对应于处理状态下的预测结果和预测的

  • 处理概率。两者均在验证集上评估。

get_cate_preds(Xval: numpy.array, Xtrain: Optional[numpy.array] = None)[source]

从已拟合的 CATE 模型生成预测。如果 Xtrain 为 None，则使用 k 折交叉验证在验证集上生成预测。如果指定了 Xtrain，则假定 CATE 已在训练样本上拟合（其中使用 k 折 CV 生成了 DR 结果），然后应用于验证样本。

参数

  • Xval ((n_val x n_treatment) matrix) – 验证集特征，用于预测（可能也用于拟合）CATE 模型中的 DR 结果

  • Xtrain (n_train x n_treatment) matrix, optional – 训练集特征，用于拟合 CATE 模型

返回

  • 无，但添加了属性 cate_preds_val_ 用于验证集上的预测 CATE 值，并且如果提供了训练

  • 数据，则添加属性 cate_preds_train_ 用于训练集上的预测 CATE 值

get_cv_splits(vars: numpy.array, T: numpy.array)[source]

给定一组变量和处理向量，生成交叉验证的分割。

参数

  • vars ((n x k) matrix or vector of length n) – 用于辅助模型的特征

  • T (vector of length n_val) – 处理分配向量。对照组状态必须是最小值。建议对照组状态为 0，所有其他处理为从 1 开始的整数。

Return type

数据折叠列表，用于运行交叉验证

get_cv_splitter(random_state: int = 123)[source]

生成用于交叉验证的分割器对象。检查在初始化时传递的 cv 对象是分割机制还是折数，并返回适当修改的对象以用于后续交叉验证。

参数

random_state (integer) – 分割器的种子，默认为 123

Return type

无，但添加了属性 'cv_splitter'，包含构建的分割器对象。