econml.iv.dr.ForestDRIV

class econml.iv.dr.ForestDRIV(*, 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', prel_cate_approach='driv', prel_cv=1, prel_opt_reweighted=True, projection=False, featurizer=None, n_estimators=1000, max_depth=None, min_samples_split=5, min_samples_leaf=5, min_weight_fraction_leaf=0.0, max_features='auto', min_impurity_decrease=0.0, max_samples=0.45, min_balancedness_tol=0.45, honest=True, subforest_size=4, n_jobs=- 1, verbose=0, 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)

DRIV 的实例，使用 RegressionForest 作为最终模型，以实现非参数推断。

DRIV 实例，使用 RegressionForest 作为最终模型，以实现非参数推断。

参数

• model_y_xw (estimator, default 'auto') – 决定如何将结果与特征和控制变量拟合 (\(\E[Y | X, W]\))。

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

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

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

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

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

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

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

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

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

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

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

• model_tz_xw (estimator, default 'auto') – 决定如何将协方差与特征和控制变量拟合（\(\E[T*Z | X, W]\) 或 \(\E[\tilde{T}*\tilde{Z} | X, W]\) 取决于 fit_cov_directly）。

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

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

• 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]\)。

• flexible_model_effect (estimator or ‘auto’ (default is ‘auto’)) – 用于 CATE 初步版本的灵活模型，必须在拟合时接受 sample_weight 参数。如果为 ‘auto’，则将应用 StatsModelsLinearRegression。

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

• prel_cv (int, cross-validation generator or an iterable, 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 (转换器, 可选) – 必须支持 fit_transform 和 transform 方法。用于在最终 CATE 回归中创建复合特征。如果 X 为 None，则忽略此参数。最终 CATE 将在 featurizer.fit_transform(X) 的输出上进行训练。如果 featurizer=None，则在 X 上训练 CATE。

• n_estimators (int, default 1000) – 森林中的树木总数。森林由 sqrt(n_estimators) 个子森林组成，每个子森林包含 sqrt(n_estimators) 棵树。

• max_depth (int or None, optional) – 树的最大深度。如果为 None，则节点将扩展，直到所有叶节点都是纯的，或者直到所有叶节点包含少于 min_samples_split 个样本为止。

• min_samples_split (int, float, default 5) – 分割内部节点所需的最小分割样本数。

  • 如果为 int，则将 min_samples_split 视为最小数量。

  • 如果为 float，则 min_samples_split 是一个比例，ceil(min_samples_split * n_samples) 是每个分割所需的最小样本数。

• min_samples_leaf (int, float, default 5) – 叶节点所需的最小样本数。只有当任何深度的分割点在左右分支中都留下至少 min_samples_leaf 个分割样本时，才会考虑该分割点。这可能有助于平滑模型，特别是在回归中。构建后，还会对树进行剪枝，以确保每个叶节点至少有 min_samples_leaf 个估计样本。

  • 如果为 int，则将 min_samples_leaf 视为最小数量。

  • 如果为 float，则 min_samples_leaf 是一个比例，ceil(min_samples_leaf * n_samples) 是每个节点所需的最小样本数。

• min_weight_fraction_leaf (float, default 0.) – 叶节点所需的总权重（所有分割样本）的最小加权比例。未提供 sample_weight 时，样本权重相等。构建后，对树进行剪枝，以确保每个叶节点中包含的估计样本的总权重比例至少为 min_weight_fraction_leaf。

• max_features (int, float, str, or None, default “auto”) – 寻找最佳分割时要考虑的特征数量

  • 如果为 int，则在每个分割点考虑 max_features 个特征。

  • 如果为 float，则 max_features 是一个比例，并在每个分割点考虑 int(max_features * n_features) 个特征。

  • 如果为 “auto”，则 max_features=n_features。

  • 如果为 “sqrt”，则 max_features=sqrt(n_features)。

  • 如果为 “log2”，则 max_features=log2(n_features)。

  • 如果为 None，则 max_features=n_features。

  注意：寻找分割不会停止，直到找到节点样本的至少一个有效划分，即使这需要实际检查超过 max_features 个特征。

• min_impurity_decrease (float, default 0.) – 如果此分割导致的杂质减少大于或等于此值，则该节点将被分割。

  加权杂质减少公式如下

  N_t / N * (impurity - N_t_R / N_t * right_impurity
                      - N_t_L / N_t * left_impurity)
  

  其中 N 是分割样本总数，N_t 是当前节点的分割样本数，N_t_L 是左子节点的分割样本数，N_t_R 是右子节点的分割样本数。

  如果传入了 sample_weight，则 N、N_t、N_t_R 和 N_t_L 均指加权总和。

• max_samples (int or float in (0, .5], default .45,) – 用于训练每棵树的每个子样本的样本数

  • 如果为 int，则在 max_samples 个样本上训练每棵树，这些样本是从所有样本中无放回抽样的

  • 如果为 float，则在 ceil(max_samples * n_samples) 个样本上训练每棵树，这些样本是从所有样本中无放回抽样的。

• min_balancedness_tol (float in [0, .5], default .45) – 我们能容忍的分割不平衡程度。这确保每个分割点在分割的两侧至少留下 (.5 - min_balancedness_tol) 的样本比例；如果提供了 sample_weight，则为样本总权重的比例。默认值确保父节点权重的至少 5% 落入分割的每一侧。将其设置为 0.0 表示不进行平衡性检查，设置为 .5 表示完美平衡的分割。为了使正式的推断理论有效，这必须是任何远离零的正常数。

• honest (bool, default True) – 是否使用诚实树，即一半样本用于创建树结构，另一半用于叶节点的估计。如果为 False，则所有样本都用于这两部分。

• subforest_size (int, default 4,) – 在小袋 bootstrap 计算中使用的每个子森林中的树木数量。参数 n_estimators 必须能被 subforest_size 整除。通常应为一个小的常数。

• n_jobs (int or None, default -1) – fit 和 predict 并行运行的作业数。None 表示 1，除非在 joblib.parallel_backend() 上下文中。-1 表示使用所有处理器。有关更多详细信息，请参阅 术语表。

• verbose (int, default 0) – 控制拟合和预测时的详细程度。

• cov_clip (float, default 0.001) – 对“重叠”区域协变量进行裁剪，以减少方差

• 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 (转换器, 可选) – 必须支持 fit_transform 和 transform 方法。用于在最终 CATE 回归中创建复合处理。最终 CATE 将在 featurizer.fit_transform(T) 的输出上进行训练。如果 featurizer=None，则在 T 上训练 CATE。

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

• cv (int, cross-validation generator or an iterable, default 2) – 决定交叉验证分割策略。cv 的可能输入包括

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

  • 整数，指定折叠数。

  • CV 分割器

  • 可迭代对象，生成 (训练, 测试) 分割作为索引数组。

  对于整数/None 输入，如果处理是离散的，则使用 StratifiedKFold，否则使用 KFold（两种情况下都有随机洗牌）。

  除非使用可迭代对象，否则我们调用 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 instance, or 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

示例

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

from econml.iv.dr import ForestDRIV

# 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 = ForestDRIV(discrete_treatment=True, discrete_instrument=True, random_state=42)
est.fit(Y=y, T=T, Z=Z, X=X)

>>> est.effect(X[:3])
array([-2.11667...,  6.31903..., -3.65700...])
>>> est.effect_interval(X[:3])
(array([-5.53359...,  2.40420..., -7.14977...]),
array([ 1.30025..., 10.23385..., -0.16424...]))

__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', prel_cate_approach='driv', prel_cv=1, prel_opt_reweighted=True, projection=False, featurizer=None, n_estimators=1000, max_depth=None, min_samples_split=5, min_samples_leaf=5, min_weight_fraction_leaf=0.0, max_features='auto', min_impurity_decrease=0.0, max_samples=0.45, min_balancedness_tol=0.45, honest=True, subforest_size=4, n_jobs=- 1, verbose=0, 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)]\) 的推断结果。仅在调用 fit 方法时，当 inference 不为 None 时可用。
ate_interval([X, T0, T1, alpha])	模型产生的数量 \(E_X[\tau(X, T0, T1)]\) 的置信区间。仅在调用 fit 方法时，当 inference 不为 None 时可用。
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)]\) 的推断结果。仅在调用 fit 方法时，当 inference 不为 None 时可用。
const_marginal_ate_interval([X, alpha])	模型产生的数量 \(E_X[\theta(X)]\) 的置信区间。仅在调用 fit 方法时，当 inference 不为 None 时可用。
const_marginal_effect([X])	计算常数边际 CATE \(\theta(·)\)。
const_marginal_effect_inference([X])	模型产生的数量 \(\theta(X)\) 的推断结果。仅在调用 fit 方法时，当 inference 不为 None 时可用。
const_marginal_effect_interval([X, alpha])	模型产生的数量 \(\theta(X)\) 的置信区间。仅在调用 fit 方法时，当 inference 不为 None 时可用。
effect([X, T0, T1])	计算异质处理效应 \(\tau(X, T0, T1)\)。
effect_inference([X, T0, T1])	模型产生的数量 \(\tau(X, T0, T1)\) 的推断结果。仅在调用 fit 方法时，当 inference 不为 None 时可用。
effect_interval([X, T0, T1, alpha])	模型产生的数量 \(\tau(X, T0, T1)\) 的置信区间。仅在调用 fit 方法时，当 inference 不为 None 时可用。
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)]\) 的推断结果。仅在调用 fit 方法时，当 inference 不为 None 时可用。
marginal_ate_interval(T[, X, alpha])	模型产生的数量 \(E_{T,X}[\partial \tau(T, X)]\) 的置信区间。仅在调用 fit 方法时，当 inference 不为 None 时可用。
marginal_effect(T[, X])	计算异质边际效应 \(\partial\tau(T, X)\)。
marginal_effect_inference(T[, X])	模型产生的数量 \(\partial \tau(T, X)\) 的推断结果。仅在调用 fit 方法时，当 inference 不为 None 时可用。
marginal_effect_interval(T[, X, alpha])	模型产生的数量 \(\partial \tau(T, X)\) 的置信区间。仅在调用 fit 方法时，当 inference 不为 None 时可用。
refit_final(*[, inference])	使用新的最终模型规范但使用缓存的第一阶段结果来估计反事实模型。
score(Y, T, Z[, X, W, sample_weight])	在新数据集上对拟合的 CATE 模型进行评分。根据拟合的残差干扰模型（在拟合时创建）为新数据集生成干扰参数。它使用不同交叉拟合折叠拟合模型的平均预测。然后计算最终残差 Y 对残差 T 回归的 MSE。
如果 model_final 没有 score 方法，则会引发 AttributeError	shap_values(X, *[, feature_names, ...])

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

属性	dowhy
feature_importances_
featurizer_	获取拟合的 featurizer。
model_cate	获取拟合的最终 CATE 模型。
model_final
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。
transformer

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

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

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

参数

• T0 ((m, d_t) matrix or vector of length m) – 每个样本的基础处理

• T1 ((m, d_t) matrix or vector of length m) – 每个样本的目标处理

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

返回

τ – 对每个结果的平均处理效应 注意：当 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) matrix, optional) – 每个样本的特征

• T0 ((m, d_t) matrix or vector of length m, default 0) – 每个样本的基础处理

• T1 ((m, d_t) matrix or vector of length m, default 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) matrix, optional) – 每个样本的特征

• T0 ((m, d_t) matrix or vector of length m, default 0) – 每个样本的基础处理

• T1 ((m, d_t) matrix or vector of length m, default 1) – 每个样本的目标处理

• alpha (float in [0, 1], default 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 (list of str of length X.shape[1] or None) – 输入特征的名称。如果为 None 且 X 是数据框，则默认为数据框的列名。

返回

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

返回类型

str 列表或 None

cate_output_names(output_names=None)

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

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

参数

output_names (list of str of length Y.shape[1] or None) – 结果的名称。如果为 None 且传递给 fit 的 Y 是数据框，则默认为数据框的列名。

返回

output_names – 返回输出名称。

返回类型

str 列表

cate_treatment_names(treatment_names=None)

获取处理名称。

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

参数

treatment_names (list of str of length T.shape[1], optional) – 处理的名称。如果为 None 且传递给 fit 的 T 是数据框，则默认为数据框的列名。

返回

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

返回类型

str 列表

const_marginal_ate(X=None)

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

参数

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

返回

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) matrix, optional) – 每个样本的特征

返回

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

返回类型

对象

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

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

参数

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

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

返回

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

返回类型

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

const_marginal_effect(X=None)

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

边际效应以 m 个测试样本 X[i] 的特征向量为条件。

参数

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

返回

theta – 每个特征化处理对每个样本 X[i] 的每个结果的常数边际 CATE。注意：当 Y 或特征化 T（或 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 时可用。

参数

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

返回

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

返回类型

对象

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

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

参数

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

• alpha (float in [0, 1], default 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) matrix or vector of length m) – 每个样本的基础处理

• T1 ((m, d_t) matrix or vector of length m) – 每个样本的目标处理

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

返回

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

返回类型

(m, d_y) 矩阵

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

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

参数

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

• T0 ((m, d_t) matrix or vector of length m, default 0) – 每个样本的基础处理

• T1 ((m, d_t) matrix or vector of length m, default 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) matrix, optional) – 每个样本的特征

• T0 ((m, d_t) matrix or vector of length m, default 0) – 每个样本的基础处理

• T1 ((m, d_t) matrix or vector of length m, default 1) – 每个样本的目标处理

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

返回

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

返回类型

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

fit(Y, T, *, Z, X=None, W=None, sample_weight=None, groups=None, cache_values=False, inference='auto')

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

参数

• Y ((n,) vector of length n) – 每个样本的结果

• T ((n,) vector of length n) – 每个样本的处理

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

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

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

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

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

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

• inference (str, Inference instance, or None) – 执行推断的方法。此估计器支持 ‘bootstrap’（或 BootstrapInference 的实例）和 ‘blb’（基于小袋 Bootstrap 的推断）

返回类型

self

marginal_ate(T, X=None)

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

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

参数

• T ((m, d_t) matrix) – 每个样本的基础处理

• X ((m, d_x) matrix, 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 时可用。

参数

• T ((m, d_t) matrix) – 每个样本的基础处理

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

返回

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) matrix) – 每个样本的基础处理

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

• alpha (float in [0, 1], default 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) matrix) – 每个样本的基础处理

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

返回

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) matrix) – 每个样本的基础处理

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

返回

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

返回类型

对象

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

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

参数

• T ((m, d_t) matrix) – 每个样本的基础处理

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

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

返回

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

返回类型

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

refit_final(*, inference='auto')

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

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

参数

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

返回

self – 此实例

返回类型

对象

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

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

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

参数

• Y ((n, d_y) matrix or vector of length n) – 每个样本的结果

• T ((n, d_t) matrix or vector of length n) – 每个样本的处理

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

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

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

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

返回

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

返回类型

浮点数

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

shap_values(X, *[, feature_names, ...])

参数

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

• feature_names (str 列表，长度为 X.shape[1]，可选) – 输入特征的名称。

• treatment_names (list，可选) – 特征化处理的名称。在离散处理场景中，名称不应包含基线处理（即对照处理，默认为按字母顺序靠前的那个）的名称。

• output_names (list，可选) – 结果的名称。

• background_samples (int，默认为 100) – 用于计算基线效应的样本数。如果为 None，则使用所有样本。

返回

shap_outs – 一个嵌套字典，以每个输出名称（例如，当 output_names=None 时为 ‘Y0’、‘Y1’ 等）和每个处理名称（例如，当 treatment_names=None 时为 ‘T0’、‘T1’ 等）作为键，并以 shap_values explanation 对象作为值。如果拟合时的输入数据也包含元数据（例如，是 pandas DataFrame），则使用处理、结果和特征的列元数据，而不是上述默认值（除非用户通过显式传递相应名称来覆盖）。

返回类型

Explanation 对象的嵌套字典

property dowhy

获取一个 DoWhyWrapper 实例，以使用 dowhy 包提供的其他功能。（例如，因果图、反驳测试等）

返回

DoWhyWrapper – DoWhyWrapper 的实例

返回类型

实例

property featurizer_

获取拟合的 featurizer。

返回

featurizer – 拟合后的特征化器实例，用于在最终的 CATE 模型训练中预处理 X。仅当 featurizer 不为 None 且 X 不为 None 时可用。

返回类型

类型为 featurizer 的对象

property model_cate

获取拟合的最终 CATE 模型。

返回

model_cate – 拟合后获得的 model_final 对象实例，对应于常数边际 CATE 模型。

返回类型

类型为 model_final 的对象

property models_prel_model_effect

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

返回

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

返回类型

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

property models_t_xw

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

返回

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

返回类型

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

property models_t_xwz

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

返回

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

返回类型

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

property models_tz_xw

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

返回

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

返回类型

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

property models_y_xw

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

返回

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

返回类型

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

property models_z_xw

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

返回

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

返回类型

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

property nuisance_scores_prel_model_effect

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

property nuisance_scores_t_xw

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

property nuisance_scores_t_xwz

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

property nuisance_scores_tz_xw

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

property nuisance_scores_y_xw

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

property nuisance_scores_z_xw

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

property residuals_

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