econml._ortho_learner

正交机器学习是一种估计因果模型的通用方法，通过将它们表述为依赖于辅助回归模型的某个损失函数的最小化器来完成，这些辅助回归模型也需要从数据中估计。本模块中的类以一种非常灵活的方式实现了这种通用逻辑，以便各种子类可以简单地实例化相应的模型并节省大量的代码重复。

参考文献

Dylan Foster, Vasilis Syrgkanis (2019). Orthogonal Statistical Learning.

ACM 学习理论会议。https://arxiv.org/abs/1901.09036

Xinkun Nie, Stefan Wager (2017). 异质处理效应的准预言机估计。

https://arxiv.org/abs/1712.04912

Chernozhukov 等人 (2017)。用于处理和结构参数的双重/去偏机器学习。

计量经济学期刊。https://arxiv.org/abs/1608.00060

函数

_crossfit(models, folds, use_ray, ...)

基于 Cross-fitting 的一般扰动参数计算方法。

类

CachedValues(nuisances, Y, T, X, W, Z, ...)

_OrthoLearner(*, discrete_outcome, ...[, ...])

所有正交学习器的基类。
class econml._ortho_learner.CachedValues(nuisances, Y, T, X, W, Z, sample_weight, freq_weight, sample_var, groups)

基类: tuple

count(value, /)

返回 value 出现的次数。

index(value, start=0, stop=9223372036854775807, /)

返回 value 第一次出现的索引。

如果值不存在，则引发 ValueError。

T

字段编号 2 的别名

W

字段编号 4 的别名

X

字段编号 3 的别名

Y

字段编号 1 的别名

Z

字段编号 5 的别名

freq_weight

字段编号 7 的别名

groups

字段编号 9 的别名

nuisances

字段编号 0 的别名

sample_var

字段编号 8 的别名

sample_weight

字段编号 6 的别名

class econml._ortho_learner._OrthoLearner(*, discrete_outcome, discrete_treatment, treatment_featurizer, discrete_instrument, categories, cv, random_state, mc_iters=None, mc_agg='mean', allow_missing=False, use_ray=False, ray_remote_func_options=None)[source]

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

所有正交学习器的基类。此类是具有以下架构的任何方法的父类

  1. CATE \(\theta(X)\) 是某个预期损失函数的最小化器

    \[\mathbb{E}[\ell(V; \theta(X), h(V))]\]

    其中 \(V\) 是所有随机变量，h 是扰动函数向量。或者，如果 \(\theta(X)\) 是一组也依赖于扰动函数 \(h\) 的矩方程的解，此类也适用。

  2. 为了估计 \(\theta(X)\)，我们首先拟合 h 函数，并以 Cross-fitting 的方式为每个样本 \(i\) 计算 \(h(V_i)\)。

    • 设 (F1_train, F1_test), …, (Fk_train, Fk_test) 是数据的任意 KFold 划分，其中 Ft_train, Ft_test 是输入样本索引的子集，且 F1_train 与 F1_test 不相交。集合 F1_test, …, Fk_test 构成所有输入索引的不完全划分，即它们不相交，且它们的并集可能是所有输入索引的子集。例如，在时间序列划分中，F0_train 可以是数据的前缀，F0_test 是后缀。通常，这些折叠将由 KFold 划分创建，即如果 S1, …, Sk 是数据的任意划分，则 Ft_train 是除 St 之外的所有索引的集合，而 Ft_test = St。如果 Ft_test 的并集不是所有数据，则最终阶段将仅使用 Ft_test 集合并集中的数据子集。

    • 然后对于 [1, …, k] 中的每个 t

      • 使用 Ft_train 估计 \(h\) 的模型 \(\hat{h}_t\)

      • 在 Ft_test 中的数据上评估学习到的 \(\hat{h}_t\) 模型，并将该值用作 Ft_test 中索引 i 的扰动值/向量 \(\hat{U}_i=\hat{h}(V_i)\)。

  3. 通过最小化在拥有扰动值（即 {F1_test, …, Fk_test} 的并集）的索引子集上的经验（正则化）插件损失，来估计 \(\theta(X)\) 的模型。

    \[\mathbb{E}_n[\ell(V; \theta(X), \hat{h}(V))] = \frac{1}{n} \sum_{i=1}^n \ell(V_i; \theta(X_i), \hat{U}_i)\]

    该方法更为通用，最终步骤无需是损失最小化步骤。此类接受一个模型作为输入，该模型用于给定一组样本拟合扰动 h 的估计值，并在任何其他样本集上预测学习到的扰动模型的值。它还接受一个用于最终估计的模型作为输入，该模型接受第一阶段的数据及其相关的估计扰动值作为输入，并拟合 CATE \(\theta(X)\) 的模型。然后在预测时，最终模型给定 X 变量的任何样本集，返回估计的 \(\theta(X)\)。

该方法实质上实现了所有的 Cross-fitting 和插件逻辑，因此任何子类只需实现相应的 model_nuisance 和 model_final，基本上无需更多。它还实现了将离散处理扩展为独热编码背后的基本预处理逻辑。

参数

  • discrete_outcome (bool) – 输出是否应视为二元变量

  • discrete_treatment (bool) – 处理值是否应视为分类量而非连续量

  • treatment_featurizer (转换器 或 None) – 必须支持 fit_transform 和 transform。用于在最终 CATE 回归中创建复合处理。最终 CATE 将在 featurizer.fit_transform(T) 的结果上进行训练。如果 featurizer=None，则 CATE 在 T 上进行训练。

  • discrete_instrument (bool) – 工具变量值是否应视为分类量而非连续量

  • categories (‘auto’ 或 list) – 对离散处理进行编码时使用的类别（或使用 ‘auto’ 表示使用唯一排序值）。第一个类别将视为控制处理。

  • cv (int, 交叉验证生成器 或 可迭代对象) – 确定交叉验证的划分策略。cv 的可能输入有

    • None，使用默认的 3 折交叉验证，

    • 整数，指定折叠数。

    • CV 划分器

    • 一个可迭代对象，以索引数组的形式生成 (训练集, 测试集) 划分。

    对于整数/None 输入，如果处理是离散的，则使用 StratifiedKFold；否则使用 KFold（两种情况都会进行随机打乱）。

    除非使用可迭代对象，否则我们调用 split(concat[Z, W, X], T) 来生成划分。如果所有 Z, W, X 均为 None，则我们调用 split(ones((T.shape[0], 1)), T)。

  • random_state (int, RandomState 实例 或 None) – 如果是整数，random_state 是随机数生成器使用的种子；如果是 RandomState 实例，random_state 是随机数生成器；如果是 None，随机数生成器是 np.random 使用的 RandomState 实例。

  • mc_iters (int, 可选) – 重复运行第一阶段模型的次数，以减少扰动项的方差。

  • mc_agg ({‘mean’, ‘median’}, 默认为 ‘mean’) – 如何在 mc_iters 次 Cross-fitting 蒙特卡洛迭代中聚合每个样本的扰动值。

  • allow_missing (bool) – 是否允许 X, W 中存在缺失值。如果为 True，则需要提供能够处理缺失值的扰动模型。

  • use_ray (bool, 默认为 False) – 是否使用 ray 并行化 Cross-fitting 步骤。

  • ray_remote_func_options (dict, 默认为 None) – 传递给 ray.remote 装饰器的选项。

示例

下面的示例代码在 _OrthoLearner 类之上实现了一个非常简单的双重机器学习方法版本，仅作说明之用。有关 _OrthoLearner 类的双重机器学习子类的更详细实现，请参阅 DML 及其子类。

import numpy as np
from sklearn.linear_model import LinearRegression
from econml._ortho_learner import _OrthoLearner
class ModelNuisance:
    def __init__(self, model_t, model_y):
        self._model_t = model_t
        self._model_y = model_y
    def train(self, is_selecting, folds, Y, T, W=None):
        self._model_t.fit(W, T)
        self._model_y.fit(W, Y)
        return self
    def predict(self, Y, T, W=None):
        return Y - self._model_y.predict(W), T - self._model_t.predict(W)
class ModelFinal:
    def __init__(self):
        return
    def fit(self, Y, T, W=None, nuisances=None):
        Y_res, T_res = nuisances
        self.model = LinearRegression(fit_intercept=False).fit(T_res.reshape(-1, 1), Y_res)
        return self
    def predict(self, X=None):
        return self.model.coef_[0]
    def score(self, Y, T, W=None, nuisances=None):
        Y_res, T_res = nuisances
        return np.mean((Y_res - self.model.predict(T_res.reshape(-1, 1)))**2)
class OrthoLearner(_OrthoLearner):
    def _gen_ortho_learner_model_nuisance(self):
        return ModelNuisance(LinearRegression(), LinearRegression())
    def _gen_ortho_learner_model_final(self):
        return ModelFinal()
np.random.seed(123)
X = np.random.normal(size=(100, 3))
y = X[:, 0] + X[:, 1] + np.random.normal(0, 0.1, size=(100,))
est = OrthoLearner(cv=2, discrete_outcome=False, discrete_treatment=False, treatment_featurizer=None,
                   discrete_instrument=False, categories='auto', random_state=None)
est.fit(y, X[:, 0], W=X[:, 1:])

>>> est.score_
0.00756830...
>>> est.const_marginal_effect()
1.02364992...
>>> est.effect()
array([1.023649...])
>>> est.effect(T0=0, T1=10)
array([10.236499...])
>>> est.score(y, X[:, 0], W=X[:, 1:])
0.00727995...
>>> est.ortho_learner_model_final_.model
LinearRegression(fit_intercept=False)
>>> est.ortho_learner_model_final_.model.coef_
array([1.023649...])

以下示例展示了如何使用 _OrthoLearner 进行离散处理的双重机器学习

class ModelNuisance:
    def __init__(self, model_t, model_y):
        self._model_t = model_t
        self._model_y = model_y
    def train(self, is_selecting, folds, Y, T, W=None):
        self._model_t.fit(W, np.matmul(T, np.arange(1, T.shape[1]+1)))
        self._model_y.fit(W, Y)
        return self
    def predict(self, Y, T, W=None):
        return Y - self._model_y.predict(W), T - self._model_t.predict_proba(W)[:, 1:]
class ModelFinal:
    def __init__(self):
        return
    def fit(self, Y, T, W=None, nuisances=None):
        Y_res, T_res = nuisances
        self.model = LinearRegression(fit_intercept=False).fit(T_res.reshape(-1, 1), Y_res)
        return self
    def predict(self):
        # theta needs to be of dimension (1, d_t) if T is (n, d_t)
        return np.array([[self.model.coef_[0]]])
    def score(self, Y, T, W=None, nuisances=None):
        Y_res, T_res = nuisances
        return np.mean((Y_res - self.model.predict(T_res.reshape(-1, 1)))**2)
from sklearn.linear_model import LogisticRegression
class OrthoLearner(_OrthoLearner):
    def _gen_ortho_learner_model_nuisance(self):
        return ModelNuisance(LogisticRegression(solver='lbfgs'), LinearRegression())
    def _gen_ortho_learner_model_final(self):
        return ModelFinal()
np.random.seed(123)
W = np.random.normal(size=(100, 3))
import scipy.special
T = np.random.binomial(1, scipy.special.expit(W[:, 0]))
y = T + W[:, 0] + np.random.normal(0, 0.01, size=(100,))
est = OrthoLearner(cv=2, discrete_outcome=False, discrete_treatment=True, discrete_instrument=False,
                   treatment_featurizer=None, categories='auto', random_state=None)
est.fit(y, T, W=W)

>>> est.score_
0.00673015...
>>> est.const_marginal_effect()
array([[1.008401...]])
>>> est.effect()
array([1.008401...])
>>> est.score(y, T, W=W)
0.00310431...
>>> est.ortho_learner_model_final_.model.coef_[0]
1.00840170...
models_nuisance_

model_nuisance 对象的实例的嵌套列表。子列表的数量等于蒙特卡洛迭代的次数。子列表中的每个元素对应于一个 Cross-fitting 折叠，并且是为该训练折叠拟合的模型实例。

类型

类型为 model_nuisance 的对象的嵌套列表

ortho_learner_model_final_

调用 fit 后拟合的 model_final 对象的实例。

类型

类型为 model_final 的对象

score_

如果 model_final 具有 score 方法，则 score_ 包含在第一阶段拟合的扰动项上评估时最终模型得分的结果。表示最终 CATE 模型的拟合优度。

类型

float 或 浮点数数组

nuisance_scores_

训练每个扰动模型的样本外得分

类型

float 或 None 的列表的列表的元组

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 (float 在 [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 (float 在 [0, 1] 范围内, 默认为 0.05) – 所报告区间的总体置信水平。报告的是 alpha/2, 1-alpha/2 置信区间。

返回

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

返回类型

tuple(类型为 const_marginal_ate(X) , 类型为 const_marginal_ate(X) )

const_marginal_effect(X=None)[source]

计算常数边际 CATE \(\theta(·)\)。

边际效应是条件于一组 m 个测试样本 X[i] 的特征向量。

参数

X ((m, d_x) 矩阵, 可选) – 每个样本的特征。

返回

theta – 每个特征化处理对每个样本 X[i] 的每个输出的常数边际 CATE。注意，当 Y 或特征化的 T（或如果 treatment_featurizer 为 None 时的 T）是向量而不是二维数组时，输出中相应的单一维度将被折叠（例如，如果两者都是向量，则此方法的输出也将是向量）。

返回类型

(m, d_y, d_f_t) 矩阵，或如果 X 为 None 时的 (d_y, d_f_t) 矩阵，其中 d_f_t 是特征化处理的维度。如果 treatment_featurizer 为 None，则 d_f_t = d_t。

const_marginal_effect_inference(X=None)[source]

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

参数

X ((m, d_x) 矩阵, 可选) – 每个样本的特征

返回

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

返回类型

对象

const_marginal_effect_interval(X=None, *, alpha=0.05)[source]

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

参数

  • X ((m, d_x) 矩阵, 可选) – 每个样本的特征

  • alpha (float 在 [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)[source]

模型产生的数量 \(\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)[source]

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

参数

  • X ((m, d_x) 矩阵, 可选) – 每个样本的特征

  • T0 ((m, d_t) 矩阵 或 长度为 m 的向量, 默认为 0) – 每个样本的基础处理

  • T1 ((m, d_t) 矩阵 或 长度为 m 的向量, 默认为 1) – 每个样本的目标处理

  • alpha (float 在 [0, 1] 范围内, 默认为 0.05) – 所报告区间的总体置信水平。报告的是 alpha/2, 1-alpha/2 置信区间。

返回

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

返回类型

tuple(类型为 effect(X, T0, T1), 类型为 effect(X, T0, T1)) )

fit(Y, T, *, X=None, W=None, Z=None, sample_weight=None, freq_weight=None, sample_var=None, groups=None, cache_values=False, inference=None, only_final=False, check_input=True)[source]

从数据中估计反事实模型，即估计函数 \(\theta(\cdot)\)。

参数

  • Y ((n, d_y) 矩阵 或 长度为 n 的向量) – 每个样本的输出

  • T ((n, d_t) 矩阵 或 长度为 n 的向量) – 每个样本的处理

  • X ((n, d_x) 矩阵, 可选) – 每个样本的特征

  • W ((n, d_w) 矩阵, 可选) – 每个样本的控制变量

  • Z ((n, d_z) 矩阵, 可选) – 每个样本的工具变量

  • sample_weight ((n,) 数组状对象, 可选) – 每个样本的个体权重。如果为 None，则假定权重相等。

  • freq_weight ((n, ) 整型数组状对象, 可选) – 观测值的权重。观测 i 被视为 freq_weight[i] 个独立观测值的平均输出。当 sample_var 不为 None 时，应提供此参数。

  • sample_var ({(n,), (n, d_y)} nd 数组状对象, 可选) – 用于计算观测 i 所代表的平均输出的原始 freq_weight[i] 个观测值的输出方差。

  • groups ((n,) 向量, 可选) – 在划分期间，同一组对应的所有行将保持在一起。如果 groups 不为 None，则传递给此类的初始化器的 cv 参数必须支持其 split 方法的 ‘groups’ 参数。

  • cache_values (bool, 默认为 False) – 是否缓存输入和计算的扰动项，这将允许重新拟合不同的最终模型

  • inference (str, Inference 实例, 或 None) – 执行推断的方法。此估计器支持 ‘bootstrap’（或 BootstrapInference 的实例）。

  • only_final (bool, 默认为 False) – 是否拟合扰动模型或使用现有的缓存值。注意：此参数仅由 refit 方法在内部使用，公共类中 fit 方法的重写不应公开此参数。

  • check_input (bool, 默认为 True) – 是否检查输入是否有效。注意：此参数仅由 refit 方法在内部使用，公共类中 fit 方法的重写不应公开此参数。

返回

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 (float 在 [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 (float 在 [0, 1] 范围内, 默认为 0.05) – 所报告区间的总体置信水平。报告的是 alpha/2, 1-alpha/2 置信区间。

返回

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

返回类型

tuple(类型 marginal_effect(T, X), 类型 marginal_effect(T, X) )

refit_final(inference=None)[source]

使用新的最终模型规范但使用缓存的第一阶段结果来估计反事实模型。

为了使此操作成功，必须在调用 fit 方法时设置 cache_values=True。此调用只会重新拟合最终模型。此调用将使用任何改变最终阶段估计参数的当前设置。如果改变第一阶段干扰项估计方式的任何参数也被更改了，则此调用不会产生影响。您需要再次调用 fit 方法来更改第一阶段的估计结果。

参数

inference (推断方法, 可选) – 表示推断方法的字符串或对象。

返回

self – 此实例。

返回类型

对象

score(Y, T, X=None, W=None, Z=None, sample_weight=None, groups=None)[source]

在新数据集上对已拟合的 CATE 模型进行评分。根据在 fit 时创建的已拟合干扰项模型，为新数据集生成干扰项参数。它使用不同迭代中由不同 crossfit 折叠拟合的模型预测的平均值。然后调用 model_final 的 score 函数并返回计算出的分数。model_final 模型必须有一个 score 方法。

如果 model_final 没有 score 方法，则会引发 AttributeError。

参数

  • Y ((n, d_y) 矩阵 或 长度为 n 的向量) – 每个样本的输出

  • T ((n, d_t) 矩阵 或 长度为 n 的向量) – 每个样本的处理

  • X ((n, d_x) 矩阵, 可选) – 每个样本的特征

  • W ((n, d_w) 矩阵, 可选) – 每个样本的控制变量

  • Z ((n, d_z) 矩阵, 可选) – 每个样本的工具变量

  • sample_weight ((n,) 向量, 可选) – 每个样本的权重。

  • groups ((n,) 向量, 可选) – 对应于同一组的所有行将在分割期间保持在一起。

返回

score – 最终 CATE 模型在新数据上的得分。与 model_final.score 方法的返回类型相同。

返回类型

float 或 (array of float)

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

最终阶段模型（const_marginal_effect）的 Shap 值。

参数

  • X ((m, d_x) 矩阵) – 每个样本的特征。应与最终阶段拟合的 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 explanation 对象作为值。如果在 fit 时输入数据也包含元数据（例如，是 pandas DataFrames），则使用处理、结果和特征的列元数据，而不是上述默认值（除非用户通过显式传递相应名称进行覆盖）。

返回类型

Explanation 对象的嵌套字典。

property dowhy

获取 DoWhyWrapper 的实例，以允许使用 dowhy 包的其他功能（例如，因果图、反驳检验等）。

返回

DoWhyWrapper – DoWhyWrapper 的实例。

返回类型

实例

econml._ortho_learner._crossfit(models: Union[econml.sklearn_extensions.model_selection.ModelSelector, List[econml.sklearn_extensions.model_selection.ModelSelector]], folds, use_ray, ray_remote_fun_option, *args, **kwargs)[source]

基于 Cross-fitting 的一般扰动参数计算方法。

参数

  • models (ModelSelector 或 List[ModelSelector]) – 具有 train 和 predict 方法的一个或多个对象。train 方法必须首先接受一个 'is_selecting' 参数，然后接受一组折叠（非选择时为 None），然后接受位置参数 args 和关键字参数 kwargs；predict 方法只接受这些 args 和 kwargs。train 方法根据输入数据选择或估计干扰项函数的模型。predict 方法在输入数据上评估已拟合的干扰项函数以进行预测。

  • folds (tuple 列表或 None) – 交叉拟合折叠结构。列表中的每个条目是一个 tuple，其第一个元素是 args 和 kwargs 数据的训练索引，第二个元素是测试索引。如果测试索引的并集不是所有索引的完整集合，则缺失索引的剩余干扰项参数的值为 NaN。如果 folds 为 None，则不执行交叉拟合；所有索引都用于模型拟合和预测。

  • use_ray (bool, 默认为 False) – 指示是否使用 ray 并行化交叉拟合步骤的标志。

  • ray_remote_fun_option (dict, 默认为 None) – 传递给 ray.remote 装饰器的选项。

  • args ((numpy 矩阵或 None) 序列) – 每个矩阵都是一个数据变量，其第一个索引对应于一个样本。

  • kwargs (键值参数序列, 值为 (numpy 矩阵或 None)) – 每个关键字参数的形式为 Var=x，其中 x 是一个 numpy 数组。每个这些数组都是数据变量。模型 fit 和 predict 将以以下签名调用：model.fit(*args, **kwargs) 和 model.predict(*args, **kwargs)。值为 None 的键值参数将从这两个调用中省略。因此，所有 args 和非 None 的 kwargs 变量必须是 models 签名的一部分。

返回

  • nuisances (array_like 的 tuple) – tuple 中的每个条目都是一个干扰项参数矩阵。矩阵中的每一行 i 对应于第 i 个输入样本的干扰项参数值。

  • model_list (与输入 model 类型相同的对象列表) – 每个折叠的克隆和已拟合模型。可用于检查不同折叠之间的拟合模型的变异性。

  • fitted_inds (np array1d) – 已计算干扰项值的数组的索引。这对应于输入折叠列表中每个折叠的测试部分的索引的并集。

  • scores (float 或 None 的列表的 tuple) – 每个干扰项模型的样本外模型得分。

示例

import numpy as np
from sklearn.model_selection import KFold
from sklearn.linear_model import Lasso
from econml._ortho_learner import _crossfit
class Wrapper:
    def __init__(self, model):
        self._model = model
    def train(self, is_selecting, folds, X, y, W=None):
        self._model.fit(X, y)
        return self
    def predict(self, X, y, W=None):
        return self._model.predict(X)
np.random.seed(123)
X = np.random.normal(size=(5000, 3))
y = X[:, 0] + np.random.normal(size=(5000,))
folds = list(KFold(2).split(X, y))
model = Lasso(alpha=0.01)
use_ray = False
ray_remote_fun_option = {}
nuisance, model_list, fitted_inds, scores = _crossfit(Wrapper(model),folds, use_ray, ray_remote_fun_option,
 X, y,W=y, Z=None)

>>> nuisance
(array([-1.105728... , -1.537566..., -2.451827... , ...,  1.106287...,
   -1.829662..., -1.782273...]),)
>>> model_list
[<Wrapper object at 0x...>, <Wrapper object at 0x...>]
>>> fitted_inds
array([   0,    1,    2, ..., 4997, 4998, 4999])