econml.solutions.causal_analysis.CausalAnalysis

class econml.solutions.causal_analysis.CausalAnalysis(feature_inds, categorical, heterogeneity_inds=None, feature_names=None, classification=False, upper_bound_on_cat_expansion=5, nuisance_models='linear', heterogeneity_model='linear', *, categories='auto', n_jobs=- 1, verbose=0, cv=5, mc_iters=3, skip_cat_limit_checks=False, random_state=None)[源码]

基类: object

注意：此类是实验性的，API 可能会在接下来的几个版本中发生变化。

获取特征的因果重要性。

参数

  • feature_inds (int, str 或 bool 的 array_like) – 用于估计因果效应的特征，表示为列索引、列名称或指示选择哪些列的布尔标志

  • categorical (int, str 或 bool 的 array_like) – 本质上是分类的特征，表示为列索引、列名称或指示选择哪些列的布尔标志

  • heterogeneity_inds (int, str 或 bool 的 array_like，或 None，或 array_like 元素列表或 None，默认为 None) – 如果是 1d 数组，则在估计异质（局部）处理效应模型时，仅使用此数组中的特征进行异质性分析。如果是 2d 数组，则其第一个维度应为 len(feature_inds)，并且在估计目标特征 feature_inds[i] 的局部因果效应时，仅使用 heterogeneity_inds[i] 中的特征进行异质性分析。如果 heterogeneity_inds[i]=None，则在估计 feature_inds[i] 的局部因果效应时，使用所有特征进行异质性分析；类似地，如果 heterogeneity_inds[i]=[]，则不使用任何特征进行异质性分析。如果 heterogeneity_ind=None，则所有特征的异质性分析都使用所有特征；如果 heterogeneity_inds=[]，则不使用任何特征。

  • feature_names (str 列表，可选) – 数据中所有特征的名称。如果输入是 dataframe 则不需要。如果为 None 且输入是普通 numpy 数组，则生成的特征名称将是 [‘X1’, ‘X2’, …]。

  • upper_bound_on_cat_expansion (int, 默认为 5) – 允许的最大分类值数量，因为它们通过独热编码进行扩展。如果一个特征的值数量超过此值，则不会为该目标特征拟合因果效应模型，并会引发警告标志。其余模型将继续拟合。

  • classification (bool, 默认为 False) – 这是否是分类任务（与回归任务相对）

  • nuisance_models ({‘linear’, ‘automl’} 之一，默认为 ‘linear’) – 用于扰动估计的模型类别。在计算该特征列的实际因果效应之前，作为预备步骤，需要训练单独的扰动模型来预测结果以及数据集中所有其他列中的每个独立特征列。如果为 ‘linear’，则使用 LassoCV（用于回归）或 LogisticRegressionCV（用于分类）作为这些模型。如果为 ‘automl’，则模型选择将使用 k 折交叉验证为每个训练的模型从多个不同的模型类别中选择表现最佳的模型，这需要额外的计算。

  • heterogeneity_model ({‘linear’, ‘forest’} 之一，默认为 ‘linear’) – 用于最终异质处理效应模型的模型类型。‘linear’ 表示该列的估计处理效应将是该列异质性特征的线性函数，而 ‘forest’ 表示将训练一个森林模型来计算这些异质性特征产生的效应。

  • categories (‘auto’ 或 (‘auto’ 或值列表) 的列表，默认为 ‘auto’) – 用于分类列的类别。如果为 ‘auto’，则将推断所有分类列的类别；否则此参数应具有与分类列数量相同的条目，每个条目应为 ‘auto’ 以推断该列的值，或该列的值列表。如果提供了显式值，则将第一个值视为该列的“对照”值，与其他值进行比较。

  • n_jobs (int, 默认为 -1) – 通过 joblib.Parallel 训练模型时使用的并行度

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

  • cv (int, 交叉验证生成器或可迭代对象，默认为 5) – 确定为每个特征训练因果模型时使用的交叉拟合策略。cv 的可能输入包括

    • 整数，指定折叠次数。

    • CV 分割器

    • 一个生成 (训练集, 测试集) 分割（作为索引数组）的可迭代对象。

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

  • mc_iters (int, 默认为 3) – 重复运行第一阶段模型的次数，以减少因果模型扰动的方差。

  • skip_cat_limit_checks (bool, 默认为 False) – 默认情况下，分类特征需要每个类别有多个实例，以便模型能够稳健地拟合。将此参数设置为 True 将跳过这些检查（尽管即使在这种情况下，线性异质性模型始终至少需要 2 个实例，森林异质性模型至少需要 4 个实例）。

  • random_state (int, RandomState 实例，或 None，默认为 None) – 控制估计器的随机性。在每次分割时，特征总是被随机排列。当 max_features < n_features 时，算法将在每次分割时随机选择 max_features 个特征，然后在其中找到最佳分割。但是，即使 max_features=n_features，找到的最佳分割也可能因不同的运行而异。这是因为如果多个分割的标准改进相同，则必须随机选择一个分割。为了在拟合期间获得确定性行为，必须将 random_state 固定为一个整数。

nuisance_models_

最近一次调用 fit 时使用的扰动模型设置

类型

str

heterogeneity_model

最近一次调用 fit 时使用的异质性模型设置

类型

str

feature_names_

最近一次调用 fit 时数据中的特征名称列表

类型

str 列表

trained_feature_indices_

成功训练模型的特征索引列表

类型

int 列表

untrained_feature_indices_

已请求但未能成功训练的索引列表，以及每个索引的原因或捕获的 Exception

类型

元组列表，每个元组包含 (int, str 或 Exception)

__init__(feature_inds, categorical, heterogeneity_inds=None, feature_names=None, classification=False, upper_bound_on_cat_expansion=5, nuisance_models='linear', heterogeneity_model='linear', *, categories='auto', n_jobs=- 1, verbose=0, cv=5, mc_iters=3, skip_cat_limit_checks=False, random_state=None)[源码]

方法

__init__(feature_inds, categorical[, ...])

cohort_causal_effect(Xtest, *[, alpha, ...])

获取由 X 的总体定义的特定群组的平均因果效应。

fit(X, y[, warm_start])

在数据上为 feature_inds 中的每个特征拟合全局和局部因果效应模型

global_causal_effect(*[, alpha, keep_all_levels])

获取每个特征的全局因果效应，以 pandas DataFrame 的形式返回。

individualized_policy(Xtest, feature_index, *)

根据学到的特征模型获取个体化处理策略，并按预测效应排序。

local_causal_effect(Xtest, *[, alpha, ...])

获取每个特征的局部因果效应，以 pandas DataFrame 的形式返回。

plot_heterogeneity_tree(Xtest, feature_index, *)

使用 matplotlib 绘制效应异质性树。

plot_policy_tree(Xtest, feature_index, *[, ...])

使用 matplotlib 绘制推荐策略树。

typical_treatment_value(feature_index)

获取指定特征使用的典型处理值

whatif(X, Xnew, feature_index, y, *[, alpha])

获取将 feature_index 从其观察值对应项更改为 Xnew 时的反事实预测。
cohort_causal_effect(Xtest, *, alpha=0.05, keep_all_levels=False)[源码]

获取由 X 的总体定义的特定群组的平均因果效应。

参数

  • Xtest (array_like) – 返回群组内平均因果效应的群组样本

  • alpha (float, 默认为 0.05) – 置信区间的置信水平

  • keep_all_levels (bool, 默认为 False) – 是否保留输出 dataframe 的所有级别（‘outcome’、‘feature’ 和 ‘feature_level’），即使该级别只有一个值；默认情况下，单值级别会被丢弃。

返回

cohort_effects – 结构如下的 DataFrame

列

[‘point’, ‘stderr’, ‘zstat’, ‘pvalue’, ‘ci_lower’, ‘ci_upper’]

索引

[‘feature’, ‘feature_value’]

行

对于每个数值特征，我们有一个索引为 [‘{feature_name}’, ‘num’] 的条目，其中 ‘num’ 字面上是字符串 ‘num’，feature_name 是输入的特征名称。对于每个分类特征，我们有一个索引为 [‘{feature_name}’, ‘{cat}v{base}’] 的条目，其中 cat 是类别值，base 是用作基线的类别。如果所有特征都是数值，则 feature_value 索引在 dataframe 中被丢弃，但在序列化字典中不会。

返回类型

DataFrame

fit(X, y, warm_start=False)[源码]

在数据上为 feature_inds 中的每个特征拟合全局和局部因果效应模型

参数

  • X (array_like) – 特征数据

  • y (形状为 (n,) 或 (n,1) 的 array_like) – 结果。如果 classification=True，则 y 应该取两个值。否则会引发错误，因为目前只实现了二分类。TODO. 启用 y 的多分类（MVP 后）

  • warm_start (bool, 默认为 False) – 如果为 False，则为 feature_inds 中的每个特征训练模型。如果为 True，则仅为之前调用 fit 未训练过的 feature_inds 中的特征训练模型，并且其相应的 heterogeneity_inds 或 automl 标志均未改变。如果 heterogeneity_inds 已改变，则这些特征的最终阶段模型将被重新拟合。如果 automl 标志已改变，则整个模型将被重新拟合，即使 warm start 标志为 True。

global_causal_effect(*, alpha=0.05, keep_all_levels=False)[源码]

获取每个特征的全局因果效应，以 pandas DataFrame 的形式返回。

参数

  • alpha (float, 默认为 0.05) – 置信区间的置信水平

  • keep_all_levels (bool, 默认为 False) – 是否保留输出 dataframe 的所有级别（‘outcome’、‘feature’ 和 ‘feature_level’），即使该级别只有一个值；默认情况下，单值级别会被丢弃。

返回

global_effects – 结构如下的 DataFrame

列

[‘point’, ‘stderr’, ‘zstat’, ‘pvalue’, ‘ci_lower’, ‘ci_upper’]

索引

[‘feature’, ‘feature_value’]

行

对于每个数值特征，我们有一个索引为 [‘{feature_name}’, ‘num’] 的条目，其中 ‘num’ 字面上是字符串 ‘num’，feature_name 是输入的特征名称。对于每个分类特征，我们有一个索引为 [‘{feature_name}’, ‘{cat}v{base}’] 的条目，其中 cat 是类别值，base 是用作基线的类别。如果所有特征都是数值，则 feature_value 索引在 dataframe 中被丢弃，但在序列化字典中不会。

返回类型

DataFrame

individualized_policy(Xtest, feature_index, *, n_rows=None, treatment_costs=0, alpha=0.05)[源码]

根据学到的特征模型获取个体化处理策略，并按预测效应排序。

参数

  • Xtest (array_like) – 特征

  • feature_index (int 或 str) – 被视为处理的特征索引

  • n_rows (int, 可选) – 返回的行数（默认为所有行）

  • treatment_costs (array_like, 默认为 0) – 处理成本，可以是标量值或每样本值。对于连续特征，这是每单位处理的边际成本；对于离散特征，这是每个非默认值与默认值之间的成本差（即，如果不是标量，数组的形状应为 (n, d_t-1)）

  • alpha (float, 范围 [0, 1], 默认为 0.05) – 置信区间的置信水平。返回 (1-alpha)*100% 的置信区间

返回

output – 包含推荐处理、效应、置信区间的 DataFrame，按效应排序

返回类型

DataFrame

local_causal_effect(Xtest, *, alpha=0.05, keep_all_levels=False)[源码]

获取每个特征的局部因果效应，以 pandas DataFrame 的形式返回。

参数

  • Xtest (array_like) – 返回因果效应的样本

  • alpha (float, 默认为 0.05) – 置信区间的置信水平

  • keep_all_levels (bool, 默认为 False) – 是否保留输出 dataframe 的所有级别（‘sample’、‘outcome’、‘feature’ 和 ‘feature_level’），即使该级别只有一个值；默认情况下，单值级别会被丢弃。

返回

global_effect – 结构如下的 DataFrame

列

[‘point’, ‘stderr’, ‘zstat’, ‘pvalue’, ‘ci_lower’, ‘ci_upper’]

索引

[‘sample’, ‘feature’, ‘feature_value’]

行

对于每个数值特征，我们有一个索引为 [‘{sampleid}’, ‘{feature_name}’, ‘num’] 的条目，其中 ‘num’ 字面上是字符串 ‘num’，feature_name 是输入的特征名称，sampleid 是 Xtest 中样本的索引。对于每个分类特征，我们有一个索引为 [‘{sampleid’, ‘{feature_name}’, ‘{cat}v{base}’] 的条目，其中 cat 是类别值，base 是用作基线的类别。如果所有特征都是数值，则 feature_value 索引在 dataframe 中被丢弃，但在序列化字典中不会。

返回类型

DataFrame

plot_heterogeneity_tree(Xtest, feature_index, *, max_depth=3, min_samples_leaf=2, min_impurity_decrease=0.0001, include_model_uncertainty=False, alpha=0.05)[源码]

使用 matplotlib 绘制效应异质性树。

参数

  • X (array_like) – 特征

  • feature_index – 被视为处理的特征索引

  • max_depth (int, 默认为 3) – 树的最大深度

  • min_samples_leaf (int, 默认为 2) – 每个叶子上的最小样本数

  • min_impurity_decrease (float, 默认为 1e-4) – 分割需要达到的因果效应不纯度/均匀度的最小减少量，才能构建该分割

  • include_model_uncertainty (bool, 默认为 False) – 在构建简化的 CATE 模型时是否包含置信区间信息。

  • alpha (float, 范围 [0, 1], 默认为 0.05) – 叶节点中显示的置信区间的置信水平。显示 (1-alpha)*100% 的置信区间。

plot_policy_tree(Xtest, feature_index, *, treatment_costs=0, max_depth=3, min_samples_leaf=2, min_value_increase=0.0001, include_model_uncertainty=False, alpha=0.05)[源码]

使用 matplotlib 绘制推荐策略树。

参数

  • X (array_like) – 特征

  • feature_index – 被视为处理的特征索引

  • treatment_costs (array_like, 默认为 0) – 处理成本，可以是标量值或每样本值。对于连续特征，这是每单位处理的边际成本；对于离散特征，这是每个非默认值与默认值之间的成本差（即，如果不是标量，数组的形状应为 (n, d_t-1)）

  • max_depth (int, 默认为 3) – 树的最大深度

  • min_samples_leaf (int, 默认为 2) – 每个叶子上的最小样本数

  • min_value_increase (float, 默认为 1e-4) – 分割需要创建的最小策略值增加量，才能构建该分割

  • include_model_uncertainty (bool, 默认为 False) – 在构建简化的 CATE 模型时是否包含置信区间信息。

  • alpha (float, 范围 [0, 1], 默认为 0.05) – 叶节点中显示的置信区间的置信水平。显示 (1-alpha)*100% 的置信区间。

typical_treatment_value(feature_index)[源码]

获取指定特征使用的典型处理值

参数

feature_index (int 或 str) – 被视为处理的特征索引

返回

treatment_value – 被视为此特征的“典型”处理值

返回类型

float

whatif(X, Xnew, feature_index, y, *, alpha=0.05)[源码]

获取将 feature_index 从其观察值对应项更改为 Xnew 时的反事实预测。

请注意，这仅适用于回归用例；分类不支持情景分析（what-if analysis）。

参数

  • X (array_like) – 特征

  • Xnew (array_like) – X 中单列的新值

  • feature_index (int 或 str) – 变动到 Xnew 的特征索引，可以是数字索引，如果输入是 dataframe 则可以是字符串名称

  • y (array_like) – 基线 y 值的观察标签或预测模型的输出

  • alpha (float, 范围 [0, 1], 默认为 0.05) – 叶节点中显示的置信区间的置信水平。显示 (1-alpha)*100% 的置信区间。

返回

y_new – 在反事实特征下可能被观察到的预测输出

返回类型

DataFrame