econml.dml.CausalForestDML

class econml.dml.CausalForestDML(*, model_y='auto', model_t='auto', featurizer=None, treatment_featurizer=None, discrete_outcome=False, discrete_treatment=False, categories='auto', cv=2, mc_iters=None, mc_agg='mean', drate=True, n_estimators=100, criterion='mse', max_depth=None, min_samples_split=10, min_samples_leaf=5, min_weight_fraction_leaf=0.0, min_var_fraction_leaf=None, min_var_leaf_on_val=False, max_features='auto', min_impurity_decrease=0.0, max_samples=0.45, min_balancedness_tol=0.45, honest=True, inference=True, fit_intercept=True, subforest_size=4, n_jobs=- 1, random_state=None, verbose=0, allow_missing=False, use_ray=False, ray_remote_func_options=None)[源代码]

基类: econml.dml.dml._BaseDML

因果森林 [cfdml1] 结合基于双重机器学习的处理变量和结果变量残差化。它拟合了一个解决局部矩方程问题的森林：

E[ (Y - E[Y|X, W] - <theta(x), T - E[T|X, W]> - beta(x)) (T;1) | X=x] = 0

其中 E[Y|X, W] 和 E[T|X, W] 在第一阶段通过交叉拟合的方式进行拟合。

参数

model_y (估计器, default 'auto') – 确定如何将结果拟合到特征。
- 如果是 'auto'，模型将是从一组线性和森林模型中选择的最优拟合模型
- 否则，请参见模型选择查看支持的选项范围；如果指定单个模型，则在 discrete_outcome 为 True 时应为分类器，否则为回归器
model_t (估计器, default 'auto') – 确定如何将处理拟合到特征。
- 如果是 'auto'，模型将是从一组线性和森林模型中选择的最优拟合模型
- 否则，请参见模型选择查看支持的选项范围；如果指定单个模型，则在 discrete_treatment 为 True 时应为分类器，否则为回归器
featurizer (转换器, optional) – 必须支持 fit_transform 和 transform 方法。用于在最终 CATE 回归中创建复合特征。如果 X 为 None，则忽略。最终 CATE 将在 featurizer.fit_transform(X) 的输出上进行训练。如果 featurizer=None，则 CATE 在 X 上进行训练。
treatment_featurizer (转换器, optional) – 必须支持 fit_transform 和 transform 方法。用于在最终 CATE 回归中创建复合处理。最终 CATE 将在 featurizer.fit_transform(T) 的输出上进行训练。如果 featurizer=None，则 CATE 在 T 上进行训练。
discrete_outcome (bool, default False) – 结果是否应被视为二元变量
discrete_treatment (bool, default False) – 处理值是否应被视为类别变量，而不是连续量
categories (‘auto’ 或 list, default ‘auto’) – 对离散处理进行编码时使用的类别（或使用 ‘auto’ 表示使用唯一的排序值）。第一个类别将被视为对照处理。
cv (int, 交叉验证生成器或可迭代对象, default 2) – 确定交叉验证的分割策略。cv 可能的输入有：
- None，使用默认的 3 折交叉验证，
- 整数，指定折数。
- CV 分割器
- 一个可迭代对象，以索引数组的形式产生 (训练集, 测试集) 分割。
对于整数/None 输入，如果处理是离散的，使用 StratifiedKFold，否则使用 KFold（这两种情况都包含随机打乱）。

除非使用可迭代对象，否则我们调用 split(X,T) 来生成分割。
mc_iters (int, optional) – 重新运行第一阶段模型的次数，以减少混杂项的方差。
mc_agg ({‘mean’, ‘median’}, default ‘mean’) – 如何在 mc_iters 次交叉拟合 Monte Carlo 迭代中聚合每个样本的混杂项值。
drate (bool, default True) – 是否在拟合时计算训练数据上的双重鲁棒平均处理效应估计。仅在 discrete_treatment=True 时发生。训练数据上的双重鲁棒 ATE 估计不适用于连续处理。
n_estimators (int, default 100) – 树的数量
criterion ({"mse", "het"}, default “mse”) – 衡量分割质量的函数。支持的准则有 "mse" 用于衡量线性矩估计树中的均方误差，以及 "het" 用于衡量异质性得分。
- “mse” 准则寻找最小化得分的分割
```
sum_{child} E[(Y - <theta(child), T> - beta(child))^2 | X=child] weight(child)
```
  在内部，对于处理数量多于两个或处理数量为两个且 fit_intercept=True 的情况，出于计算目的，该准则通过计算上更简单的变体进行近似。特别是，它被替换为：
```
sum_{child} weight(child) * rho(child).T @ E[(T;1) @ (T;1).T | X in child] @ rho(child)
```
  其中
```
rho(child) := E[(T;1) @ (T;1).T | X in parent]^{-1}
                * E[(Y - <theta(x), T> - beta(x)) (T;1) | X in child]
```
  这可以被视为一种引入异质性的得分，但对子节点 Jacobian E[(T;1) @ (T;1).T | X in child] 的最小特征值较大的得分赋予更多权重，这会导致估计值的方差更小，参数识别更强。
- “het” 准则寻找最大化纯参数异质性得分的分割
```
sum_{child} weight(child) * rho(child)[:n_T].T @ rho(child)[:n_T]
```
  这可以被视为理想异质性得分的近似：
```
weight(left) * weight(right) || theta(left) - theta(right)||_2^2 / weight(parent)^2
```
  正如 [cfdml1] 中概述的那样
max_depth (int, default None) – 树的最大深度。如果是 None，则节点会扩展，直到所有叶子都是纯的，或者直到所有叶子包含的样本数少于 min_samples_split。
min_samples_split (int 或 float, default 10) – 分割内部节点所需的最小样本数
- 如果是整数，则将 min_samples_split 视为最小数量。
- 如果是浮点数，则 min_samples_split 是一个比例，并且 ceil(min_samples_split * n_samples) 是每次分割所需的最小样本数。
min_samples_leaf (int 或 float, default 5) – 叶节点所需的最小样本数。任何深度的分割点仅在左右分支中都至少留下 min_samples_leaf 个训练样本时才会被考虑。这可能对平滑模型有作用，特别是在回归中。
- 如果是整数，则将 min_samples_leaf 视为最小数量。
- 如果是浮点数，则 min_samples_leaf 是一个比例，并且 ceil(min_samples_leaf * n_samples) 是每个节点所需的最小样本数。
min_weight_fraction_leaf (float, default 0.0) – 叶节点所需的总权重（所有输入样本的总权重）的最小加权比例。未提供 sample_weight 时，样本权重相等。
min_var_fraction_leaf (None 或 float in (0, 1], default None) – 对处理向量变异的某个代理进行的约束，该代理应作为叶子节点内部处理向量总方差的百分比存在。这避免了进行处理方差很小，因此局部参数无法很好识别且方差很高的分割。不同准则下，方差的代理不同，这主要是出于计算效率考虑。如果 criterion='het'，则此约束转化为：
```
for all i in {1, ..., T.shape[1]}:
    Var(T[i] | X in leaf) > `min_var_fraction_leaf` * Var(T[i])
```
如果 criterion='mse'，因为该准则为每个候选分割存储了关于叶子的更多信息，所以此约束对每个处理的不同坐标的成对相关性施加了进一步的约束，即：
```
for all i neq j:
    sqrt( Var(T[i]|X in leaf) * Var(T[j]|X in leaf)
        * ( 1 - rho(T[i], T[j]| in leaf)^2 ) )
        > `min_var_fraction_leaf` sqrt( Var(T[i]) * Var(T[j]) * (1 - rho(T[i], T[j])^2 ) )
```
其中 rho(X, Y) 是两个随机变量 X, Y 的 Pearson 相关系数。因此，此约束还强制叶子节点内部的任何两对处理都不能高度共线。此额外约束主要在输入处理数量多于两个时有效，并且也避免了由于处理的局部共线性导致参数估计具有大方差的叶子节点。
min_var_leaf_on_val (bool, default False) – min_var_fraction_leaf 约束是否也应在诚实分割的验证集上强制执行。如果 min_var_leaf=None，则此标志不起作用。将此设置为 True 应谨慎，因为它部分违反了诚实性结构，因为验证集的处理变量被用于指导树的分割结构。然而，这是一种良性依赖，因为它仅使用处理 T 的局部相关结构来决定分割是否可行。
max_features (int, float, {“auto”, “sqrt”, “log2”}, 或 None, default None) – 寻找最佳分割时考虑的特征数量
- 如果是整数，则在每次分割时考虑 max_features 个特征。
- 如果是浮点数，则 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.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 是右子节点的样本数。N, N_t, N_t_R 和 N_t_L 都指加权总和（如果传递了 sample_weight）。
max_samples (int 或 float in (0, 1], default .45,) – 用于训练每棵树的子样本所使用的样本数量
- 如果是整数，则在 max_samples 个样本上训练每棵树，这些样本从所有样本中无放回采样
- 如果是浮点数，则在 ceil(`max_samples * n_samples)` 个样本上训练每棵树，这些样本从所有样本中无放回采样。
如果 inference=True，则 max_samples 必须是小于 n_samples//2 的整数，或是小于或等于 .5 的浮点数。
min_balancedness_tol (float in [0, .5], default .45) – 我们可以容忍多大程度的分割不平衡。这强制每次分割在分割的两侧至少留下 (.5 - min_balancedness_tol) 比例的样本；或者当 sample_weight 不为 None 时，留下样本总权重的相应比例。默认值确保父节点权重的至少 5% 落入分割的每一侧。设置为 0.0 表示没有平衡性要求，设置为 .5 表示完全平衡的分割。为了使正式推断理论有效，这必须是一个任何远离零的有界正数。
honest (bool, default True) – 每棵树是否应以诚实的方式进行训练，即训练集被分割成两个等大的子集，训练集和验证集。训练集中的所有样本用于创建分割结构，验证集中的所有样本用于计算树中每个节点的值。
inference (bool, default True) – 是否应启用推断（即置信区间构建和估计值的不确定性量化）。如果 inference=True，则估计器使用 bootstrap-of-little-bags 方法计算参数向量的协方差，并进行客观贝叶斯去偏校正，以确保方差量为正。
fit_intercept (bool, default True) – 我们是否应该拟合一个截距混杂参数 beta(x)。
subforest_size (int, default 4,) – 在 bootstrap-of-little-bags 计算中使用的每个子森林中的树的数量。参数 n_estimators 必须能被 subforest_size 整除。通常应为一个小的常数。
n_jobs (int 或 None, default -1) – 用于并行化的并行作业数量；遵循 joblib 的语义。n_jobs=-1 表示使用所有可用的 CPU 核心。n_jobs=None 表示不进行并行化。
random_state (int, RandomState 实例, 或 None, default None) – 控制估计器的随机性。在每次分割时，特征总是被随机打乱。当 max_features < n_features 时，算法将在每次分割时随机选择 max_features 个特征，然后在其中找到最佳分割。但即使 max_features=n_features，找到的最佳分割也可能在不同运行中变化。如果多个分割的标准改进相同，并且必须随机选择其中一个分割，则会出现这种情况。为了在拟合期间获得确定性行为，random_state 必须固定为一个整数。
verbose (int, default 0) – 控制拟合和预测时的详细程度。
allow_missing (bool) – 是否允许 W 中存在缺失值。如果为 True，则需要提供能够处理缺失值的 model_y 和 model_t。
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.dml import CausalForestDML

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 = CausalForestDML(discrete_treatment=True)
est.fit(y, T, X=X, W=None)

>>> est.effect(X[:3])
array([0.62947..., 1.64576..., 0.68496... ])
>>> est.effect_interval(X[:3])
(array([0.19136...  , 1.17143..., 0.10789...]),
array([1.06758..., 2.12009..., 1.26203...]))

ate_

经过训练数据平均，并使用双重鲁棒校正得到的每个处理对每个结果的平均恒定边际处理效应。仅在 discrete_treatment=True 且 drate=True 时可用。

类型: 形状为 (n_outcomes, n_treatments) 的 ndarray

ate_stderr_

ate_ 属性的标准误差。

类型: 形状为 (n_outcomes, n_treatments) 的 ndarray

feature_importances_

基于特征产生的参数异质性量计算的特征重要性。值越高，特征越重要。特征的重要性计算为其产生的（归一化）总异质性。

parent_weight * (left_weight * right_weight)
    * mean((value_left[k] - value_right[k])**2) / parent_weight**2

选择该特征的每次分割都会增加

类型: 到特征的重要性。每个这样的量也根据分割的深度进行加权。默认情况下，max_depth=4 以下的分割不用于此计算，并且深度为 depth 的每个分割都按 1 / (1 + depth)**2.0 进行重新加权。有关允许更改这些默认值的方法，请参见 feature_importances 方法。

参考文献

形状为 (n_features,) 的 ndarray: cfdml1(1,2)

Athey, Susan, Julie Tibshirani, and Stefan Wager. “Generalized random forests.” The Annals of Statistics 47.2 (2019): 1148-1178 https://arxiv.org/pdf/1610.01271.pdf

方法

`__init__`(*[, model_y, model_t, featurizer, ...])
`ate`([X, T0, T1])	计算平均处理效应 \(E_X[\tau(X, T0, T1)]\)。
`ate__inference`()	返回 ate__inference -- ate_ 属性的推断结果信息，它是经过训练数据平均，并使用双重鲁棒校正得到的平均
`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` 时可用。
`att_`(*, T)	参数 T (int) -- 获取 ATT 的处理索引。它对应于离散输入处理的字典序排名。
`att__inference`(*, T)	参数 T (int) -- 获取 ATT 的处理索引。它对应于离散输入处理的字典序排名。
`att_stderr_`(*, T)	参数 T (int) -- 获取 ATT 的处理索引。它对应于离散输入处理的字典序排名。
`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` 时可用。
`feature_importances`([max_depth, ...])
`fit`(Y, T, *[, X, W, sample_weight, groups, ...])	从数据估计反事实模型，即估计函数 τ(·,·,·)，∂τ(·,·)。
`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[, X, W, sample_weight])	在新数据集上对已拟合的 CATE 模型进行评分。
`shap_values`(X, *[, feature_names, ...])	最终阶段模型 (const_marginal_effect) 的 Shap 值
`summary`([alpha, value, decimals, ...])	恒定边际处理效应线性模型中系数和截距的摘要。
`tune`(Y, T, *[, X, W, sample_weight, groups, ...])	根据样本外 R 分数性能调优最终阶段因果森林的主要超参数。

属性

`ate_`
`ate_stderr_`
`dowhy`	获取 `DoWhyWrapper` 实例，以便使用 dowhy 包的其他功能。
`feature_importances_`
`featurizer_`
`model_cate`	获取已拟合的最终 CATE 模型。
`model_final`
`model_final_`
`models_nuisance_`
`models_t`	获取已拟合的 E[T \| X, W] 模型。
`models_y`	获取已拟合的 E[Y \| X, W] 模型。
`nuisance_scores_t`
`nuisance_scores_y`
`original_featurizer`
`ortho_learner_model_final_`
`residuals_`	一个包含第一阶段估计残差以及相关联的 X 和 W 的元组 (y_res, T_res, X, W)。
`rlearner_model_final_`
`transformer`
`tunable_params`

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

返回

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

返回类型

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

ate__inference()[源代码]

返回: ate__inference – ate_ 属性的推断结果信息，它是经过训练数据平均，并使用双重鲁棒校正得到的每个处理对每个结果的平均恒定边际处理效应。仅在 discrete_treatment=True 且 drate=True 时可用。
返回类型: NormalInferenceResults

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

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

参数

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

返回

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

返回类型

object

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

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

参数

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(类型为 ate(X, T0, T1), 类型为 ate(X, T0, T1) )

att_(*, T)[源代码]

参数: T (int) – 获取 ATT 的处理索引。它对应于离散输入处理的字典序排名。
返回: att_ – 经过接受处理 T 的训练数据平均，并使用双重鲁棒校正得到的每个处理对每个结果的平均恒定边际处理效应。如果输入变量是向量，则会删除单例维度。
返回类型: ndarray (n_y, n_t)

att__inference(*, T)[源代码]

参数: T (int) – 获取 ATT 的处理索引。它对应于离散输入处理的字典序排名。
返回: att__inference – att_ 属性的推断结果信息，它是经过接受处理 T 的训练数据平均，并使用双重鲁棒校正得到的每个处理对每个结果的平均恒定边际处理效应。仅在 discrete_treatment=True 且 drate=True 时可用。
返回类型: NormalInferenceResults

att_stderr_(*, T)[源代码]

参数: T (int) – 获取 ATT 的处理索引。它对应于离散输入处理的字典序排名。
返回: att_stderr_ – 相应 att_ 的标准误差。
返回类型: ndarray (n_y, n_t)

cate_feature_names(feature_names=None)

获取输出特征名称。

参数: feature_names (list of str of length X.shape[1] or None) – 输入特征的名称。如果为 None 且 X 是一个 dataframe，则默认为 dataframe 的列名。
返回: out_feature_names – 输出特征 \(\phi(X)\) 的名称，即最终恒定边际 CATE 模型在其上线性的特征。它是与 coef_() 参数每个条目相关联的特征名称。当 featurizer 不为 None 且没有方法 get_feature_names(feature_names) 时不可用。否则返回 None。
返回类型: 字符串列表或 None

cate_output_names(output_names=None)

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

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

参数: output_names (list of str of length Y.shape[1] or None) – 结果的名称。如果为 None 且传递给 fit 的 Y 是一个 dataframe，则默认为 dataframe 的列名。
返回: output_names – 返回输出名称。
返回类型: 字符串列表

cate_treatment_names(treatment_names=None)

获取处理名称。

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

参数: treatment_names (list of str of length T.shape[1], optional) – 处理的名称。如果为 None 且传递给 fit 的 T 是一个 dataframe，则默认为 dataframe 的列名。
返回: out_treatment_names – 返回（可能已扩展的）处理名称。
返回类型: 字符串列表

const_marginal_ate(X=None)

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

参数: X ((m, d_x) 矩阵, 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) 矩阵, optional) – 每个样本的特征
返回: PopulationSummaryResults – 推断结果实例包含预测和预测标准误差，并可按需计算置信区间、z 统计量和 p 值。它还可以输出这些推断结果的 dataframe 摘要。
返回类型: object

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

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

参数

X ((m, d_x) 矩阵, 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) 矩阵, optional) – 每个样本的特征。
返回: theta – 每个特征化处理对每个结果的恒定边际 CATE，对应于每个样本 X[i]。请注意，当 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) 矩阵, optional) – 每个样本的特征
返回: InferenceResults – 推断结果实例包含预测和预测标准误差，并可按需计算置信区间、z 统计量和 p 值。它还可以输出这些推断结果的 dataframe 摘要。
返回类型: object

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

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

参数

X ((m, d_x) 矩阵, 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) 矩阵或长度为 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 时可用。

参数

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

返回

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

返回类型

object

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

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

参数

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(类型为 effect(X, T0, T1), 类型为 effect(X, T0, T1) )

fit(Y, T, *, X=None, W=None, sample_weight=None, groups=None, cache_values=False, inference='auto')[源代码]

从数据估计反事实模型，即估计函数 τ(·,·,·)，∂τ(·,·)。

参数

Y ((n × d_y) 矩阵或长度为 n 的向量) – 每个样本的结果
T ((n × dₜ) 矩阵或长度为 n 的向量) – 每个样本的处理
X ((n × dₓ) 矩阵) – 每个样本的特征
W ((n × d_w) 矩阵, optional) – 每个样本的控制变量
sample_weight ((n,) array_like 或 None) – 每个样本的个体权重。如果为 None，则假定权重相等。
groups (形状为 (n,) 的向量, optional) – 对应于同一组的所有行在分割期间将保持在一起。如果 groups 不为 None，则传递给此类的初始化器的 cv 参数必须支持其 split 方法的 ‘groups’ 参数。
cache_values (bool, default False) – 是否缓存输入和第一阶段结果，这将允许重新拟合不同的最终模型。
inference (str, Inference 实例, 或 None) – 执行推断的方法。此估计器支持 ‘bootstrap’（或 BootstrapInference 的实例）、‘blb’ 或 ‘auto’（基于 Bootstrap-of-Little-Bags 的推断）

返回类型

self

marginal_ate(T, X=None)

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

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

参数

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 时可用。

参数

T ((m, d_t) 矩阵) – 每个样本的基础处理
X ((m, d_x) 矩阵, optional) – 每个样本的特征

返回

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

返回类型

object

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) 矩阵, 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) 矩阵) – 每个样本的基础处理
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 时可用。

参数

T ((m, d_t) 矩阵) – 每个样本的基础处理
X ((m, d_x) 矩阵, optional) – 每个样本的特征

返回

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

返回类型

object

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

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

参数

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(marginal_effect(T, X) 的类型, marginal_effect(T, X) 的类型 )

refit_final(*, inference='auto')[source]

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

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

参数: inference (推断方法，可选) – 表示推断方法的字符串或对象
返回: self – 当前实例
返回类型: object

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

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

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

参数

Y ((n, d_y) 的矩阵或长度为 n 的向量) – 每个样本的结果变量
T ((n, d_t) 的矩阵或长度为 n 的向量) – 每个样本的处理变量
X ((n, d_x) 的矩阵，可选) – 每个样本的特征变量
W ((n, d_w) 的矩阵，可选) – 每个样本的控制变量
sample_weight ((n,) 的向量，可选) – 每个样本的权重

返回

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

返回类型

float

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

最终阶段模型 (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 解释对象作为值。如果在拟合时的输入数据也包含元数据（例如，是 pandas DataFrames），则将使用处理变量、结果变量和特征变量的列元数据，而不是上述默认值（除非用户显式传递相应的名称进行覆盖）。

返回类型

Explanation 对象的嵌套字典

summary(alpha=0.05, value=0, decimals=3, feature_names=None, treatment_names=None, output_names=None)[source]

恒定边际处理效应线性模型中系数和截距的摘要。

参数

alpha (float in [0, 1], default 0.05) – 报告区间总的置信水平。报告 alpha/2, 1-alpha/2 置信区间。
value (浮点型, 默认 0) – 在零假设下您想测试的指标的均值。
decimals (整型, 默认 3) – 每列保留的小数位数。
feature_names (字符串列表，可选) – 输入特征的名称。
treatment_names (字符串列表，可选) – 处理变量的名称。
output_names (字符串列表，可选) – 输出变量的名称。

返回

smry – 包含摘要表格和文本，可以打印或转换为各种输出格式。

返回类型

Summary 实例

tune(Y, T, *, X=None, W=None, sample_weight=None, groups=None, params='auto')[source]

基于样本外 R 分数性能调整最终阶段因果森林的主要超参数。它在参数网格上训练包含 100 棵树的小型森林，并测试样本外 R 分数。函数调用后，self 的所有参数都已设置为找到的最优超参数。但是，估计器仍未拟合，因此您需要在之后调用 fit 方法以使用选定的超参数拟合估计器。可调整参数列表可以通过 tunable_params 属性访问。

参数

Y ((n × d_y) 矩阵或长度为 n 的向量) – 每个样本的结果
T ((n × dₜ) 矩阵或长度为 n 的向量) – 每个样本的处理
X ((n × dₓ) 矩阵) – 每个样本的特征
W ((n × d_w) 矩阵, optional) – 每个样本的控制变量
sample_weight ((n,) 的向量，可选) – 每行的权重
groups (形状为 (n,) 的向量, optional) – 对应于同一组的所有行在分割期间将保持在一起。如果 groups 不为 None，则传递给此类的初始化器的 cv 参数必须支持其 split 方法的 ‘groups’ 参数。
params (字典或 ‘auto’，默认 ‘auto’) – 包含要尝试的超参数网格的字典，例如 {‘param1’: [value1, value2, …], ‘param2’: [value1, value2, …], …}。如果 params='auto'，则使用默认网格。

返回

self – 调优后的因果森林对象。这与原始对象是同一个对象（而非副本），但对象的参数都已设置为调优网格中性能最佳的参数。

返回类型

CausalForestDML 对象

property dowhy

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

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

property model_cate

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

返回: model_cate – 调用 fit 后拟合的 model_final 对象实例，对应于常数边际 CATE 模型。
返回类型: 类型为 model_final 的对象

property models_t

获取已拟合的 E[T | X, W] 模型。

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

property models_y

获取已拟合的 E[Y | X, W] 模型。

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

property residuals_: 一个元组 (y_res, T_res, X, W)，包含第一阶段估计的残差以及相关的 X 和 W。不保证样本顺序与输入顺序相同。