econml.iv.dr.DRIV

class econml.iv.dr.DRIV(*, model_y_xw='auto', model_t_xw='auto', model_z_xw='auto', model_t_xwz='auto', model_tz_xw='auto', fit_cov_directly=True, flexible_model_effect='auto', model_final=None, prel_cate_approach='driv', prel_cv=1, prel_opt_reweighted=True, projection=False, featurizer=None, fit_cate_intercept=False, cov_clip=0.001, opt_reweighted=False, discrete_outcome=False, discrete_instrument=False, discrete_treatment=False, treatment_featurizer=None, categories='auto', cv=2, mc_iters=None, mc_agg='mean', random_state=None, allow_missing=False, use_ray=False, ray_remote_func_options=None)[source]

用于使用工具变量估计 CATE 的 DRIV 算法。它是公共类 {LinearDRIV, SparseLinearDRIV, ForestDRIV} 的父类

参数

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

  • 如果 'auto'，模型将是线性模型和森林模型集合中的最佳拟合模型

    • 否则，请参阅 模型选择 以了解支持的选项范围；如果指定了单个模型，当 discrete_outcome 为 True 时，它应该是一个分类器，否则是一个回归器

    • model_t_xw (估计器, default 'auto') – 确定如何将处理拟合到特征和控制变量 (\(\E[T | X, W]\))。

  • 否则，请参阅 模型选择 以了解支持的选项范围；如果指定了单个模型，当 discrete_treatment 为 True 时，它应该是一个分类器，否则是一个回归器

    • 否则，请参阅 模型选择 以了解支持的选项范围；如果指定了单个模型，当 discrete_outcome 为 True 时，它应该是一个分类器，否则是一个回归器

    • model_z_xw (估计器, default 'auto') – 确定如何将工具变量拟合到特征和控制变量 (\(\E[Z | X, W]\))。

  • 否则，请参阅 模型选择 以了解支持的选项范围；如果指定了单个模型，当 discrete_instrument 为 True 时，它应该是一个分类器，否则是一个回归器

    • 否则，请参阅 模型选择 以了解支持的选项范围；如果指定了单个模型，当 discrete_outcome 为 True 时，它应该是一个分类器，否则是一个回归器

    • model_t_xwz (估计器, default 'auto') – 确定如何将处理拟合到特征、控制变量和工具变量 (\(\E[T | X, W, Z]\))。

  • model_tz_xw (估计器, default 'auto') – 确定如何将协方差拟合到特征和控制变量 (\(\E[T*Z | X, W]\) 或 \(\E[\tilde{T}*\tilde{Z} | X, W]\)，具体取决于 fit_cov_directly)。

    • 否则，请参阅 模型选择 以了解支持的选项范围；如果指定了单个模型，当 discrete_outcome 为 True 时，它应该是一个分类器，否则是一个回归器

    • model_z_xw (估计器, default 'auto') – 确定如何将工具变量拟合到特征和控制变量 (\(\E[Z | X, W]\))。

  • fit_cov_directly (bool, default True) – 是否拟合 \(\E[\tilde{T}*\tilde{Z} | X, W]\) 而不是 \(\E[T*Z | X, W]\)。否则，我们从 \(\E[T*Z | X, W] - \E[T | X, W] \E[Z | X, W]\) 计算 \(\E[\tilde{T}*\tilde{Z} | X, W]\)。

    • 否则，请参阅 模型选择 以了解支持的选项范围；如果指定了单个模型，当 discrete_outcome 为 True 时，它应该是一个分类器，否则是一个回归器

    • model_z_xw (估计器, default 'auto') – 确定如何将工具变量拟合到特征和控制变量 (\(\E[Z | X, W]\))。

  • flexible_model_effect (估计器 或 ‘auto’ (默认值为 ‘auto’)) – 用于初步 CATE 版本的灵活模型，必须在拟合时接受 sample_weight。如果为 ‘auto’，将应用 StatsModelsLinearRegression。

  • model_final (估计器, optional) – 用于 CATE 和投影的最终模型。如果为 None，则 flexible_model_effect 也将用作最终模型

  • prel_cate_approach ({‘driv’, ‘dmliv’} 之一, default ‘driv’) – 估计初步 CATE 版本的模型。如果为 ‘driv’，将使用 _DRIV。如果为 ‘dmliv’，将使用 NonParamDMLIV。

  • prel_cv (int, 交叉验证生成器或可迭代对象, default 1) – 确定初步效应模型的交叉验证分割策略。

  • prel_opt_reweighted (bool, default True) – 是否对样本进行重新加权，以最小化初步效应模型的方差。

  • projection (bool, default False) – 如果为 True，我们将拟合 DRIV 的一个稍微不同的变体，其中使用 E[T|X, W, Z] 作为工具变量，而不是 Z，此时 model_z_xw 将被禁用；如果为 False，则 model_t_xwz 将被禁用。

  • featurizer (转换器, optional) – 必须支持 fit_transform 和 transform。用于在最终的 CATE 回归中创建复合特征。如果 X 为 None，则忽略此参数。最终的 CATE 将在 featurizer.fit_transform(X) 的结果上训练。如果 featurizer=None，则 CATE 在 X 上训练。

  • fit_cate_intercept (bool, default False) – 线性 CATE 模型是否应该包含常数项。

  • cov_clip (float, default 0.1) – 对“重叠”较低区域的协变量进行裁剪，以减小方差

  • opt_reweighted (bool, default False) – 是否对样本进行重新加权，以最小化方差。如果为 True，则 model_final.fit 必须接受 sample_weight 作为关键字参数。如果为 True，则假定 model_final 足够灵活以拟合真实的 CATE 模型。否则，此方法将返回对 model_final 空间的有偏投影，偏向于对工具变量强度较高的特征空间部分赋予更多权重。

  • discrete_outcome (bool, default False) – 是否应将结果视为二元的

  • discrete_instrument (bool, default False) – 工具变量值是否应被视为分类量，而不是连续量

  • discrete_treatment (bool, default False) – 处理变量值是否应被视为分类量，而不是连续量

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

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

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

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

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

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

  • mc_agg ({‘mean’, ‘median’}, default ‘mean’) – 如何在 mc_iters 次蒙特卡洛交叉拟合迭代中聚合每个样本的干扰值。

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

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

  • use_ray (bool, default False) – 是否使用 Ray 并行化交叉验证步骤。如果为 True，则必须安装 Ray。

  • ray_remote_func_options (dict, default None) – 使用 Ray 时传递给远程函数的选项。请参阅 https://docs.rayai.org.cn/en/latest/ray-core/api/doc/ray.remote.html

  • 示例

一个使用默认模型的简单示例

__init__(*, model_y_xw='auto', model_t_xw='auto', model_z_xw='auto', model_t_xwz='auto', model_tz_xw='auto', fit_cov_directly=True, flexible_model_effect='auto', model_final=None, prel_cate_approach='driv', prel_cv=1, prel_opt_reweighted=True, projection=False, featurizer=None, fit_cate_intercept=False, cov_clip=0.001, opt_reweighted=False, discrete_outcome=False, discrete_instrument=False, discrete_treatment=False, treatment_featurizer=None, categories='auto', cv=2, mc_iters=None, mc_agg='mean', random_state=None, allow_missing=False, use_ray=False, ray_remote_func_options=None)[source]

from econml.iv.dr import DRIV

# Define the data generation functions
def dgp(n, p, true_fn):
    X = np.random.normal(0, 1, size=(n, p))
    Z = np.random.binomial(1, 0.5, size=(n,))
    nu = np.random.uniform(0, 10, size=(n,))
    coef_Z = 0.8
    C = np.random.binomial(
        1, coef_Z * scipy.special.expit(0.4 * X[:, 0] + nu)
    )  # Compliers when recomended
    C0 = np.random.binomial(
        1, 0.06 * np.ones(X.shape[0])
    )  # Non-compliers when not recommended
    T = C * Z + C0 * (1 - Z)
    y = true_fn(X) * T + 2 * nu + 5 * (X[:, 3] > 0) + 0.1 * np.random.uniform(0, 1, size=(n,))
    return y, T, Z, X

def true_heterogeneity_function(X):
    return 5 * X[:, 0]

np.random.seed(123)
y, T, Z, X = dgp(1000, 5, true_heterogeneity_function)
est = DRIV(discrete_treatment=True, discrete_instrument=True)
est.fit(Y=y, T=T, Z=Z, X=X)

>>> est.effect(X[:3])
array([-4.15079...,  5.99291..., -2.86514...])
__init__(*, model_y_xw='auto', model_t_xw='auto', model_z_xw='auto', model_t_xwz='auto', model_tz_xw='auto', fit_cov_directly=True, flexible_model_effect='auto', model_final=None, prel_cate_approach='driv', prel_cv=1, prel_opt_reweighted=True, projection=False, featurizer=None, fit_cate_intercept=False, cov_clip=0.001, opt_reweighted=False, discrete_outcome=False, discrete_instrument=False, discrete_treatment=False, treatment_featurizer=None, categories='auto', cv=2, mc_iters=None, mc_agg='mean', random_state=None, allow_missing=False, use_ray=False, ray_remote_func_options=None)[源码]

方法

__init__(*[, model_y_xw, model_t_xw, ...])

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])

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

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, *, Z[, X, W, sample_weight, ...])

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

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)\) 的置信区间。

refit_final(*[, inference])

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

score(Y, T, Z[, X, W, sample_weight])

在新的数据集上对拟合的 CATE 模型进行评分。基于拟合时创建的拟合残差干扰项模型，为新数据集生成干扰项参数。它使用不同交叉拟合折叠拟合模型的平均预测。然后计算最终残差 Y 在残差 T 回归上的 MSE。

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

Shap value for the final stage models (const_marginal_effect)

属性

dowhy

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

featurizer_

获取已拟合的 featurizer。

model_cate

获取已拟合的最终 CATE 模型。

model_final_

models_nuisance_

models_prel_model_effect

获取已拟合的初步 CATE 估计器。

models_t_xw

获取 \(\E[T | X]\) 的已拟合模型。

models_t_xwz

获取 \(\E[Z | X]\) 的已拟合模型。

models_tz_xw

获取 \(\E[T*Z | X]\) 的已拟合模型。

models_y_xw

获取 \(\E[Y | X]\) 的已拟合模型。

models_z_xw

获取 \(\E[Z | X]\) 的已拟合模型。

nuisance_scores_prel_model_effect

获取 prel_model_effect 模型在样本外训练数据上的评分

nuisance_scores_t_xw

获取 t_xw 模型在样本外训练数据上的评分

nuisance_scores_t_xwz

获取 z_xw 模型在样本外训练数据上的评分

nuisance_scores_tz_xw

获取 tz_xw 模型在样本外训练数据上的评分

nuisance_scores_y_xw

获取 y_xw 模型在样本外训练数据上的评分

nuisance_scores_z_xw

获取 z_xw 模型在样本外训练数据上的评分

original_featurizer

ortho_learner_model_final_

residuals_

一个元组 (prel_theta, Y_res, T_res, Z_res, cov, X, W, Z)，包含第一阶段估计的残差以及相关的 X、W 和 Z。

转换器

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

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

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

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

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

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

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

返回

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

返回类型

float 或 (d_y,) 数组

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

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

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

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

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

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

返回

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

返回类型

对象

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

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

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

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

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

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

  • alpha (float in [0, 1], default 0.05) – 报告区间的总体置信水平。报告的是 alpha/2 和 1-alpha/2 置信区间。

返回

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

返回类型

tuple(type of ate(X, T0, T1), type of ate(X, T0, T1)) )

cate_feature_names(feature_names=None)

获取输出特征名称。

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

feature_names (str 列表, 长度与 X.shape[1] 相同, 或 None) – 输入特征的名称。如果为 None 且 X 是一个 dataframe，则默认为 dataframe 的列名。

返回

out_feature_names – 输出特征 \(\phi(X)\) 的名称，即最终 CATE 模型对于每个处理变量呈线性的特征。它是与 coef_() 参数的每个条目关联的特征名称。仅当 featurizer 不为 None 且具有方法 get_feature_names(feature_names) 时可用。否则返回 None。

返回类型

str 列表 或 None

cate_output_names(output_names=None)

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

由对输出应用转换的估计器覆盖。

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

output_names (str 列表, 长度与 Y.shape[1] 相同, 或 None) – 结果的名称。如果为 None 且传递给 fit 的 Y 是一个 dataframe，则默认为 dataframe 的列名。

返回

output_names – 返回输出名称。

返回类型

str 列表

cate_treatment_names(treatment_names=None)

获取处理变量名称。

如果处理变量是离散的或已进行特征化，它将返回扩展的处理变量名称。

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

treatment_names (str 列表, 长度与 T.shape[1] 相同, optional) – 处理变量的名称。如果为 None 且传递给 fit 的 T 是一个 dataframe，则默认为 dataframe 的列名。

返回

out_treatment_names – 返回（可能已扩展的）处理变量名称。

返回类型

str 列表

const_marginal_ate(X=None)

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

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

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

返回

theta – 每个处理变量对每个结果的平均常数边际 CATE。请注意，当 Y 或特征化处理变量（如果 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 时可用。

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

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

返回

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

返回类型

对象

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

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

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

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

  • alpha (float in [0, 1], default 0.05) – 报告区间的总体置信水平。报告的是 alpha/2 和 1-alpha/2 置信区间。

返回

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

返回类型

tuple(type of const_marginal_ate(X) , type of const_marginal_ate(X) )

const_marginal_effect(X=None)

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

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

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

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

返回

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

返回类型

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

const_marginal_effect_inference(X=None)

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

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

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

返回

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

返回类型

对象

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

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

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

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

  • alpha (float in [0, 1], default 0.05) – 报告区间的总体置信水平。报告的是 alpha/2 和 1-alpha/2 置信区间。

返回

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

返回类型

tuple(type of const_marginal_effect(X) , type of const_marginal_effect(X) )

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

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

效应是在 m 个测试样本 \(\{T0_i, T1_i, X_i\}\) 上条件于特征向量计算的。

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

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

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

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

返回

τ – 每个样本在每个结果上的异质处理效应 请注意，当 Y 是向量而不是二维数组时，对应的单维度将被压缩（因此此方法将返回一个向量）

返回类型

(m, d_y) 矩阵

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

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

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

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

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

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

返回

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

返回类型

对象

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

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

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

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

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

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

  • alpha (float in [0, 1], default 0.05) – 报告区间的总体置信水平。报告的是 alpha/2 和 1-alpha/2 置信区间。

返回

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

返回类型

tuple(type of effect(X, T0, T1), type of effect(X, T0, T1)) )

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

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

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

  • Y (长度为 n 的 (n,) 向量) – 每个样本的结果

  • T (长度为 n 的 (n,) 向量) – 每个样本的处理变量

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

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

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

  • sample_weight ((n,) array_like, optional) – 每个样本的个体权重。如果为 None，则假定权重相等。

  • freq_weight ((n,) array_like of int, optional) – 观测值的权重。观测值 i 被视为 freq_weight[i] 个独立观测值的平均结果。当 sample_var 不为 None 时，应提供此参数。

  • sample_var ((n,) nd array_like, optional) – 用于计算观测值 i 代表的平均结果的原始 freq_weight[i] 个观测值的结果方差。

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

  • cache_values (bool, default False) – 是否缓存输入和第一阶段结果，这将允许重新拟合不同的最终模型

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

返回类型

自身

marginal_ate(T, X=None)

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

边际效应在基础处理点附近计算，并在 X 总体上求平均。

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

  • T ((m, d_t) 矩阵) – 每个样本的基础处理变量

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

返回

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

返回类型

(d_y, d_t) 数组

marginal_ate_inference(T, X=None)

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

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

  • T ((m, d_t) 矩阵) – 每个样本的基础处理变量

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

返回

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

返回类型

对象

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

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

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

  • T ((m, d_t) 矩阵) – 每个样本的基础处理变量

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

  • alpha (float in [0, 1], default 0.05) – 报告区间的总体置信水平。报告的是 alpha/2 和 1-alpha/2 置信区间。

返回

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

返回类型

tuple(type of marginal_ate(T, X), type of marginal_ate(T, X) )

marginal_effect(T, X=None)

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

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

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

  • T ((m, d_t) 矩阵) – 每个样本的基础处理变量

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

返回

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

返回类型

(m, d_y, d_t) 数组

marginal_effect_inference(T, X=None)

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

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

  • T ((m, d_t) 矩阵) – 每个样本的基础处理变量

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

返回

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

返回类型

对象

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

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

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

  • T ((m, d_t) 矩阵) – 每个样本的基础处理变量

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

  • alpha (float in [0, 1], default 0.05) – 报告区间的总体置信水平。报告的是 alpha/2 和 1-alpha/2 置信区间。

返回

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

返回类型

tuple(type of marginal_effect(T, X), type of marginal_effect(T, X) )

refit_final(*, inference='auto')

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

为了成功执行此操作，必须使用 cache_values=True 调用 fit。此调用仅会重新拟合最终模型。此调用将使用更改最终阶段估计的任何参数的当前设置。如果更改了第一阶段干扰项估计方式的任何参数也已更改，则此操作将无效。您需要再次调用 fit 来更改第一阶段估计结果。

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

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

返回

self – 此实例

返回类型

对象

score(Y, T, Z, X=None, W=None, sample_weight=None)

在新的数据集上对拟合的 CATE 模型进行评分。基于拟合时创建的拟合残差干扰项模型，为新数据集生成干扰项参数。它使用不同交叉拟合折叠拟合模型的平均预测。然后计算最终残差 Y 在残差 T 回归上的 MSE。

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

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

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

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

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

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

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

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

返回

score – 最终 CATE 模型在新数据上的 MSE。

返回类型

float

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

Shap value for the final stage models (const_marginal_effect)

model_y_xw (估计器, default 'auto') – 确定如何将结果拟合到特征和控制变量 (\(\E[Y | X, W]\))。

  • X ((m, d_x) 矩阵) – 每个样本的特征。应与最终阶段拟合的 X 具有相同的形状。

  • feature_names (str 列表, 长度与 X.shape[1] 相同, optional) – 输入特征的名称。

  • treatment_names (list, optional) – 特征化处理变量的名称。在离散处理情景下，名称不应包含基准处理变量（即对照处理变量，默认为按字母顺序较小的那个）的名称。

  • output_names (list, optional) – 结果的名称。

  • background_samples (int , default 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 的一个实例

返回类型

实例

property featurizer_

获取已拟合的 featurizer。

返回

featurizer – 在最终 CATE 模型训练中用于预处理 X 的已拟合 featurizer 的一个实例。仅当 featurizer 不为 None 且 X 不为 None 时可用。

返回类型

type(featurizer) 类型的对象

property model_cate

获取已拟合的最终 CATE 模型。

返回

model_cate – 调用 fit 后拟合的 model_final 对象的一个实例，对应于常数边际 CATE 模型。

返回类型

type(model_final) 类型的对象

property models_prel_model_effect

获取已拟合的初步 CATE 估计器。

返回

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

返回类型

type(prel_model_effect) 对象的嵌套列表

property models_t_xw

获取 \(\E[T | X]\) 的已拟合模型。

返回

models_t_xw – model_t_xw 对象实例的嵌套列表。子列表的数量等于蒙特卡罗迭代次数，每个子列表中的元素对应一个交叉拟合折叠，并且是在该训练折叠上拟合的模型实例。

返回类型

类型为 (model_t_xw) 的对象的嵌套列表

属性 models_t_xwz

获取 \(\E[Z | X]\) 的已拟合模型。

返回

models_z_xw – model_z_xw 对象实例的嵌套列表。子列表的数量等于蒙特卡罗迭代次数，每个子列表中的元素对应一个交叉拟合折叠，并且是在该训练折叠上拟合的模型实例。

返回类型

类型为 (model_z_xw) 的对象的嵌套列表

属性 models_tz_xw

获取 \(\E[T*Z | X]\) 的已拟合模型。

返回

models_tz_xw – model_tz_xw 对象实例的嵌套列表。子列表的数量等于蒙特卡罗迭代次数，每个子列表中的元素对应一个交叉拟合折叠，并且是在该训练折叠上拟合的模型实例。

返回类型

类型为 (model_tz_xw) 的对象的嵌套列表

属性 models_y_xw

获取 \(\E[Y | X]\) 的已拟合模型。

返回

models_y_xw – model_y_xw 对象实例的嵌套列表。子列表的数量等于蒙特卡罗迭代次数，每个子列表中的元素对应一个交叉拟合折叠，并且是在该训练折叠上拟合的模型实例。

返回类型

类型为 (model_y_xw) 的对象的嵌套列表

属性 models_z_xw

获取 \(\E[Z | X]\) 的已拟合模型。

返回

models_z_xw – model_z_xw 对象实例的嵌套列表。子列表的数量等于蒙特卡罗迭代次数，每个子列表中的元素对应一个交叉拟合折叠，并且是在该训练折叠上拟合的模型实例。

返回类型

类型为 (model_z_xw) 的对象的嵌套列表

属性 nuisance_scores_prel_model_effect

获取 prel_model_effect 模型在样本外训练数据上的评分

属性 nuisance_scores_t_xw

获取 t_xw 模型在样本外训练数据上的评分

属性 nuisance_scores_t_xwz

获取 z_xw 模型在样本外训练数据上的评分

属性 nuisance_scores_tz_xw

获取 tz_xw 模型在样本外训练数据上的评分

属性 nuisance_scores_y_xw

获取 y_xw 模型在样本外训练数据上的评分

属性 nuisance_scores_z_xw

获取 z_xw 模型在样本外训练数据上的评分

属性 residuals_

一个元组 (prel_theta, Y_res, T_res, Z_res, cov, X, W, Z)，包含来自第一阶段估计的残差以及相关的 X, W 和 Z。样本不保证与输入顺序相同。