econml.metalearners.TLearner

class econml.metalearners.TLearner(*, models, categories='auto', allow_missing=False)[source]

基类：econml._cate_estimator.TreatmentExpansionMixin, econml._cate_estimator.LinearCateEstimator

条件均值回归估计器。

参数

models (控制组和处理组的结果估计器) – 可以是一个应用于所有控制组和处理组单元的估计器，或是一个元组/列表，其中每个处理组（包括控制组）对应一个估计器。必须实现 fit 和 predict 方法。
categories (‘auto’ 或列表, 默认为 ‘auto’) – 对离散处理进行编码时使用的类别（或使用 ‘auto’ 使用唯一排序值）。第一个类别将被视为控制处理。
allow_missing (布尔值) – 是否允许 X 中存在缺失值。如果为 True，则需要提供能够处理缺失值的模型。

示例

一个简单示例

from econml.metalearners import TLearner
from sklearn.linear_model import LinearRegression

np.random.seed(123)
X = np.random.normal(size=(1000, 5))
T = np.random.binomial(1, scipy.special.expit(X[:, 0]))
y = (1 + .5*X[:, 0]) * T + X[:, 0] + np.random.normal(size=(1000,))
est = TLearner(models=LinearRegression())
est.fit(y, T, X=X)

>>> est.effect(X[:3])
array([0.58547..., 1.82860..., 0.78379...])

__init__(*, models, categories='auto', allow_missing=False)[source]

方法

`__init__`(*, models[, categories, allow_missing])
`ate`([X, T0, T1])	计算平均处理效应 \(E_X[\tau(X, T0, T1)]\)。
`ate_inference`([X, T0, T1])	模型产生的数量 \(E_X[\tau(X, T0, T1)]\) 的推断结果。
`ate_interval`([X, T0, T1, alpha])	模型产生的数量 \(E_X[\tau(X, T0, T1)]\) 的置信区间。
`cate_feature_names`([feature_names])	获取特征名称的公共接口。
`cate_output_names`([output_names])	获取输出名称的公共接口。
`cate_treatment_names`([treatment_names])	获取处理名称。
`const_marginal_ate`([X])	计算平均常数边际 CATE \(E_X[\theta(X)]\)。
`const_marginal_ate_inference`([X])	模型产生的数量 \(E_X[\theta(X)]\) 的推断结果。
`const_marginal_ate_interval`([X, alpha])	模型产生的数量 \(E_X[\theta(X)]\) 的置信区间。
`const_marginal_effect`(X)	计算每个样本在特征向量上的常数边际处理效应。
`const_marginal_effect_inference`([X])	模型产生的数量 \(\theta(X)\) 的推断结果。
`const_marginal_effect_interval`([X, alpha])	模型产生的数量 \(\theta(X)\) 的置信区间。
`effect`([X, T0, T1])	计算异质处理效应 \(\tau(X, T0, T1)\)。
`effect_inference`([X, T0, T1])	模型产生的数量 \(\tau(X, T0, T1)\) 的推断结果。
`effect_interval`([X, T0, T1, alpha])	模型产生的数量 \(\tau(X, T0, T1)\) 的置信区间。
`fit`(Y, T, *, X[, inference])	构建一个 TLearner 实例。
`marginal_ate`(T[, X])	计算平均边际效应 \(E_{T, X}[\partial\tau(T, X)]\)。
`marginal_ate_inference`(T[, X])	模型产生的数量 \(E_{T,X}[\partial \tau(T, X)]\) 的推断结果。
`marginal_ate_interval`(T[, X, alpha])	模型产生的数量 \(E_{T,X}[\partial \tau(T, X)]\) 的置信区间。
`marginal_effect`(T[, X])	计算异质边际效应 \(\partial\tau(T, X)\)。
`marginal_effect_inference`(T[, X])	模型产生的数量 \(\partial \tau(T, X)\) 的推断结果。
`marginal_effect_interval`(T[, X, alpha])	模型产生的数量 \(\partial \tau(T, X)\) 的置信区间。
`shap_values`(X, *[, feature_names, ...])	最终阶段模型 (const_marginal_effect) 的 Shap 值

属性

`dowhy`	获取 `DoWhyWrapper` 的实例，以使用 dowhy 包的其他功能。(例如，因果图、反驳测试等)
`transformer`

ate(X=None, *, T0=0, T1=1)

计算平均处理效应 \(E_X[\tau(X, T0, T1)]\)。

效应是在两个处理点之间计算，并在 X 变量总体上取平均值。

参数

T0 (形状为 (m, d_t) 的矩阵或长度为 m 的向量) – 每个样本的基础处理
T1 (形状为 (m, d_t) 的矩阵或长度为 m 的向量) – 每个样本的目标处理
X (形状为 (m, d_x) 的矩阵, 可选) – 每个样本的特征

返回值

τ – 每个结果的平均处理效应。注意，当 Y 是向量而非二维数组时，结果将是一个标量

返回类型

float 或形状为 (d_y,) 的数组

ate_inference(X=None, *, T0=0, T1=1)

模型产生的数量 \(E_X[\tau(X, T0, T1)]\) 的推断结果。仅当调用 fit 方法时 inference 不为 None 时可用。

参数

X (形状为 (m, d_x) 的矩阵, 可选) – 每个样本的特征
T0 (形状为 (m, d_t) 的矩阵或长度为 m 的向量, 默认为 0) – 每个样本的基础处理
T1 (形状为 (m, d_t) 的矩阵或长度为 m 的向量, 默认为 1) – 每个样本的目标处理

返回值

PopulationSummaryResults – 推断结果实例包含预测值和预测标准误差，并可按需计算置信区间、z 统计量和 p 值。它还可以输出这些推断结果的数据框摘要。

返回类型

对象

ate_interval(X=None, *, T0=0, T1=1, alpha=0.05)

模型产生的数量 \(E_X[\tau(X, T0, T1)]\) 的置信区间。仅当调用 fit 方法时 inference 不为 None 时可用。

参数

X (形状为 (m, d_x) 的矩阵, 可选) – 每个样本的特征
T0 (形状为 (m, d_t) 的矩阵或长度为 m 的向量, 默认为 0) – 每个样本的基础处理
T1 (形状为 (m, d_t) 的矩阵或长度为 m 的向量, 默认为 1) – 每个样本的目标处理
alpha ([0, 1] 范围内的浮点数, 默认为 0.05) – 所报告区间的总体置信水平。报告的是 alpha/2, 1-alpha/2 置信区间。

返回值

lower, upper – 每个数量的置信区间的下限和上限。

返回类型

tuple(类型为 ate(X, T0, T1) , 类型为 ate(X, T0, T1)) 的元组 )

cate_feature_names(feature_names=None)

获取特征名称的公共接口。

由对输入特征应用变换的估计器重写。

参数: feature_names (长度为 X.shape[1] 的字符串列表或 None) – 输入特征的名称。如果为 None 且 X 是数据框，则默认为数据框中的列名。
返回值: out_feature_names – 返回特征名称。
返回类型: 字符串列表或 None

cate_output_names(output_names=None)

获取输出名称的公共接口。

由对输出应用变换的估计器重写。

参数: output_names (长度为 Y.shape[1] 的字符串列表或 None) – 结果的名称。如果为 None 且传递给 fit 的 Y 是数据框，则默认为数据框中的列名。
返回值: output_names – 返回输出名称。
返回类型: 字符串列表

cate_treatment_names(treatment_names=None)

获取处理名称。

如果处理是离散的或经过特征化，它将返回扩展的处理名称。

参数: treatment_names (长度为 T.shape[1] 的字符串列表, 可选) – 处理的名称。如果为 None 且传递给 fit 的 T 是数据框，则默认为数据框中的列名。
返回值: out_treatment_names – 返回（可能已扩展的）处理名称。
返回类型: 字符串列表

const_marginal_ate(X=None)

计算平均常数边际 CATE \(E_X[\theta(X)]\)。

参数: X (形状为 (m, d_x) 的矩阵, 可选) – 每个样本的特征。
返回值: theta – 每个处理对每个结果的平均常数边际 CATE。注意，当 Y 或特征化处理 T (如果 treatment_featurizer 为 None 则为 T) 是向量而非二维数组时，输出中相应的单例维度将被折叠（例如，如果两者都是向量，则此方法的输出也将是标量）
返回类型: 形状为 (d_y, d_f_t) 的矩阵，其中 d_f_t 是特征化处理的维度。如果 treatment_featurizer 为 None，则 d_f_t = d_t。

const_marginal_ate_inference(X=None)

模型产生的数量 \(E_X[\theta(X)]\) 的推断结果。仅当调用 fit 方法时 inference 不为 None 时可用。

参数: X (形状为 (m, d_x) 的矩阵, 可选) – 每个样本的特征
返回值: PopulationSummaryResults – 推断结果实例包含预测值和预测标准误差，并可按需计算置信区间、z 统计量和 p 值。它还可以输出这些推断结果的数据框摘要。
返回类型: 对象

const_marginal_ate_interval(X=None, *, alpha=0.05)

模型产生的数量 \(E_X[\theta(X)]\) 的置信区间。仅当调用 fit 方法时 inference 不为 None 时可用。

参数

X (形状为 (m, d_x) 的矩阵, 可选) – 每个样本的特征
alpha ([0, 1] 范围内的浮点数, 默认为 0.05) – 所报告区间的总体置信水平。报告的是 alpha/2, 1-alpha/2 置信区间。

返回值

lower, upper – 每个数量的置信区间的下限和上限。

返回类型

tuple(类型为 const_marginal_ate(X) , 类型为 const_marginal_ate(X) 的元组 )

const_marginal_effect(X)[source]

计算每个样本在特征向量上的常数边际处理效应。

参数: X (形状为 (m × d_x) 的矩阵) – 每个样本的特征矩阵。
返回值: τ_hat – 每个样本 X[i] 的每个处理对每个结果的常数边际 CATE。注意，当 Y 是向量而非二维数组时，输出中相应的单例维度将被折叠
返回类型: 矩阵, 形状为 (m, d_y, d_t)

const_marginal_effect_inference(X=None)

模型产生的数量 \(\theta(X)\) 的推断结果。仅当调用 fit 方法时 inference 不为 None 时可用。

参数: X (形状为 (m, d_x) 的矩阵, 可选) – 每个样本的特征
返回值: InferenceResults – 推断结果实例包含预测值和预测标准误差，并可按需计算置信区间、z 统计量和 p 值。它还可以输出这些推断结果的数据框摘要。
返回类型: 对象

const_marginal_effect_interval(X=None, *, alpha=0.05)

模型产生的数量 \(\theta(X)\) 的置信区间。仅当调用 fit 方法时 inference 不为 None 时可用。

参数

X (形状为 (m, d_x) 的矩阵, 可选) – 每个样本的特征
alpha ([0, 1] 范围内的浮点数, 默认为 0.05) – 所报告区间的总体置信水平。报告的是 alpha/2, 1-alpha/2 置信区间。

返回值

lower, upper – 每个数量的置信区间的下限和上限。

返回类型

tuple(类型为 const_marginal_effect(X) , 类型为 const_marginal_effect(X) 的元组 )

effect(X=None, *, T0=0, T1=1)

计算异质处理效应 \(\tau(X, T0, T1)\)。

效应是在一组 m 个测试样本 \(\{T0_i, T1_i, X_i\}\) 的特征向量条件下，在两个处理点之间计算的。

参数

T0 (形状为 (m, d_t) 的矩阵或长度为 m 的向量) – 每个样本的基础处理
T1 (形状为 (m, d_t) 的矩阵或长度为 m 的向量) – 每个样本的目标处理
X (形状为 (m, d_x) 的矩阵, 可选) – 每个样本的特征

返回值

τ – 每个样本的每个结果的异质处理效应。注意，当 Y 是向量而非二维数组时，相应的单例维度将被折叠（因此此方法将返回一个向量）

返回类型

形状为 (m, d_y) 的矩阵

effect_inference(X=None, *, T0=0, T1=1)

模型产生的数量 \(\tau(X, T0, T1)\) 的推断结果。仅当调用 fit 方法时 inference 不为 None 时可用。

参数

X (形状为 (m, d_x) 的矩阵, 可选) – 每个样本的特征
T0 (形状为 (m, d_t) 的矩阵或长度为 m 的向量, 默认为 0) – 每个样本的基础处理
T1 (形状为 (m, d_t) 的矩阵或长度为 m 的向量, 默认为 1) – 每个样本的目标处理

返回值

InferenceResults – 推断结果实例包含预测值和预测标准误差，并可按需计算置信区间、z 统计量和 p 值。它还可以输出这些推断结果的数据框摘要。

返回类型

对象

effect_interval(X=None, *, T0=0, T1=1, alpha=0.05)

模型产生的数量 \(\tau(X, T0, T1)\) 的置信区间。仅当调用 fit 方法时 inference 不为 None 时可用。

参数

X (形状为 (m, d_x) 的矩阵, 可选) – 每个样本的特征
T0 (形状为 (m, d_t) 的矩阵或长度为 m 的向量, 默认为 0) – 每个样本的基础处理
T1 (形状为 (m, d_t) 的矩阵或长度为 m 的向量, 默认为 1) – 每个样本的目标处理
alpha ([0, 1] 范围内的浮点数, 默认为 0.05) – 所报告区间的总体置信水平。报告的是 alpha/2, 1-alpha/2 置信区间。

返回值

lower, upper – 每个数量的置信区间的下限和上限。

返回类型

tuple(类型为 effect(X, T0, T1), 类型为 effect(X, T0, T1)) 的元组 )

fit(Y, T, *, X, inference=None)[source]

构建一个 TLearner 实例。

参数

Y (类数组, 形状为 (n, ) 或 (n, d_y)) – 处理策略的结果。
T (类数组, 形状为 (n, ) 或 (n, 1)) – 处理策略。只接受二元处理作为输入。如果形状是 (n, 1)，T 将被展平。
X (类数组, 形状为 (n, d_x)) – 捕获异质性的特征向量。
inference (str, Inference 实例, 或 None) – 执行推断的方法。此估计器支持 ‘bootstrap’（或 BootstrapInference 的实例）

返回值

self

返回类型

self 的一个实例。

marginal_ate(T, X=None)

计算平均边际效应 \(E_{T, X}[\partial\tau(T, X)]\)。

边际效应围绕一个基础处理点计算，并在 X 总体上取平均值。

参数

T (形状为 (m, d_t) 的矩阵) – 每个样本的基础处理
X (形状为 (m, d_x) 的矩阵, 可选) – 每个样本的特征

返回值

grad_tau – 每个结果的平均边际效应。注意，当 Y 或 T 是向量而非二维数组时，输出中相应的单例维度将被折叠（例如，如果两者都是向量，则此方法的输出将是标量）

返回类型

形状为 (d_y, d_t) 的数组

marginal_ate_inference(T, X=None)

模型产生的数量 \(E_{T,X}[\partial \tau(T, X)]\) 的推断结果。仅当调用 fit 方法时 inference 不为 None 时可用。

参数

T (形状为 (m, d_t) 的矩阵) – 每个样本的基础处理
X (形状为 (m, d_x) 的矩阵, 可选) – 每个样本的特征

返回值

PopulationSummaryResults – 推断结果实例包含预测值和预测标准误差，并可按需计算置信区间、z 统计量和 p 值。它还可以输出这些推断结果的数据框摘要。

返回类型

对象

marginal_ate_interval(T, X=None, *, alpha=0.05)

模型产生的数量 \(E_{T,X}[\partial \tau(T, X)]\) 的置信区间。仅当调用 fit 方法时 inference 不为 None 时可用。

参数

T (形状为 (m, d_t) 的矩阵) – 每个样本的基础处理
X (形状为 (m, d_x) 的矩阵, 可选) – 每个样本的特征
alpha ([0, 1] 范围内的浮点数, 默认为 0.05) – 所报告区间的总体置信水平。报告的是 alpha/2, 1-alpha/2 置信区间。

返回值

lower, upper – 每个数量的置信区间的下限和上限。

返回类型

tuple(类型为 marginal_ate(T, X), 类型为 marginal_ate(T, X) 的元组 )

marginal_effect(T, X=None)

计算异质边际效应 \(\partial\tau(T, X)\)。

边际效应是在一组 m 个测试样本 \(\{T_i, X_i\}\) 的特征向量条件下，围绕一个基础处理点计算的。如果 treatment_featurizer 为 None，则在此计算中忽略基础处理，结果等同于 const_marginal_effect。

参数

T (形状为 (m, d_t) 的矩阵) – 每个样本的基础处理
X (形状为 (m, d_x) 的矩阵, 可选) – 每个样本的特征

返回值

grad_tau – 每个样本的每个结果的异质边际效应。注意，当 Y 或 T 是向量而非二维数组时，输出中相应的单例维度将被折叠（例如，如果两者都是向量，则此方法的输出也将是向量）

返回类型

形状为 (m, d_y, d_t) 的数组

marginal_effect_inference(T, X=None)

模型产生的数量 \(\partial \tau(T, X)\) 的推断结果。仅当调用 fit 方法时 inference 不为 None 时可用。

参数

T (形状为 (m, d_t) 的矩阵) – 每个样本的基础处理
X (形状为 (m, d_x) 的矩阵, 可选) – 每个样本的特征

返回值

InferenceResults – 推断结果实例包含预测值和预测标准误差，并可按需计算置信区间、z 统计量和 p 值。它还可以输出这些推断结果的数据框摘要。

返回类型

对象

marginal_effect_interval(T, X=None, *, alpha=0.05)

模型产生的数量 \(\partial \tau(T, X)\) 的置信区间。仅当调用 fit 方法时 inference 不为 None 时可用。

参数

T (形状为 (m, d_t) 的矩阵) – 每个样本的基础处理
X (形状为 (m, d_x) 的矩阵, 可选) – 每个样本的特征
alpha ([0, 1] 范围内的浮点数, 默认为 0.05) – 所报告区间的总体置信水平。报告的是 alpha/2, 1-alpha/2 置信区间。

返回值

lower, upper – 每个数量的置信区间的下限和上限。

返回类型

tuple(类型为 marginal_effect(T, X), 类型为 marginal_effect(T, X) 的元组 )

shap_values(X, *, feature_names=None, treatment_names=None, output_names=None, background_samples=100)

最终阶段模型 (const_marginal_effect) 的 Shap 值

参数

X (形状为 (m, d_x) 的矩阵) – 每个样本的特征。应与最终阶段 fit 时的 X 具有相同形状。
feature_names (长度为 X.shape[1] 的字符串列表, 可选) – 输入特征的名称。
treatment_names (列表, 可选) – 特征化处理的名称。在离散处理场景中，名称不应包含基线处理的名称（即控制处理，默认情况下它是按字母顺序更小的）
output_names (列表, 可选) – 结果的名称。
background_samples (整数, 默认为 100) – 用于计算基线效应的样本数量。如果为 None，则使用所有样本。

返回值

shap_outs – 一个嵌套字典，使用每个输出名称（例如，当 output_names=None 时为 ‘Y0’, ‘Y1’, …）和每个处理名称（例如，当 treatment_names=None 时为 ‘T0’, ‘T1’, …）作为键，shap_values 解释对象作为值。如果在 fit 时输入数据也包含元数据（例如，是 pandas DataFrames），则使用处理、结果和特征的列元数据代替上述默认值（除非用户通过显式传递相应的名称进行覆盖）。

返回类型

Explanation 对象的嵌套字典

property dowhy

获取 DoWhyWrapper 的实例，以使用 dowhy 包的其他功能。(例如，因果图、反驳测试等)

返回值: DoWhyWrapper – DoWhyWrapper 的一个实例
返回类型: 实例