欢迎来到 YLearn 文档!

YLearn是一个因果学习算法工具包，这个名字是“learn why”的谐音。它主要支持因果学习任务中的各类相关任务，从因果效应识别（causal effect idenfitication），到因果效应估计（causal effect estimation），到因果发现（causal discovery）等等，都可以通过YLearn实现，最大程度地降低了学习一个因果工具的成本。

用户指南

YLearn与因果推断概述

机器学习近年来取得了巨大的成就。机器学习成功的领域主要在预测方面，比如：分类猫和狗的图片。然而，机器学习不能够回答在许多场景中自然地产生的问题。 一个例子是在策略评估中的 反事实问题：如果策略发生改变，会发生什么？事实上，由于这些反事实不能够被观测到。机器学习模型，预测工具不能够被使用。 机器学习的这些缺点是导致如今因果推断应用的部分原因。

因果推断直接的建模了干涉的结果，并将反事实推理形式化。在机器学习的帮助下，如今，因果推断能够从观察到的数据中以不同的方式得到因果的结论，而不是依靠精心设计的实验。

一个常见的完整的因果推断过程是由三部分组成。首先，它使用叫做因果发现的技术学习因果关系。这些关系将在之后以结构化因果模型或者有向无环图（DAG）的形式表示。 其次，它将根据观测到的数据来表示因果估计量。该因果估计量由感兴趣的因果问题，比如平均治疗效果阐明。这个过程被称为识别。最终，一旦因果估计量被识别了，因果推断将会专注 于从观测到的数据中估计因果估计量。接着，策略评估问题和反事实问题都能够被回答。

YLearn, 配备了许多最近的文献中发展的技术，在机器学习的帮助下，用于支持从因果发现到因故估计量的估计的整个因果推断流程。这尤其在有大量的观测数据时，更有发展前景。

YLearn中的概念和相关的问题设置

在YLearn中，关于因果推断流程有5个主要组成部分。

Components in YLearn

1. 因果发现. 在观测数据中发现因果关系。

2. 因果模型. 以 CausalGraph 的形式表示因果关系并做其他的相关操作比如用 CausalModel 识别。

3. 估计模型. 使用不同的技术对因果估计量进行估计。

4. 策略模型. 对每一个个体选择最好的策略。

5. 解释器. 解释因果效应和策略。

这些组成部分被连接在一起形成一个完整的因果推断流程，被封装在一个API Why 中。

YLearn中因果推断的流程. 从训练数据中, 首先使用 CausalDiscovery 来得到数据中的因果结构，通常输出一个 CausalGraph 。 因果图被传入 CausalModel , 其中，感兴趣的因果效应被识别并转换成统计估计量。一个 EstimatorModel 接着通过训练数据进行训练来建模 因果效应和其他变量之间的关系，等价于估计训练数据中的因果效应。之后，可以使用一个训练过的 EstimatorModel 在一些新的测试数据集上预测因果效应并估计 分配给每个个体的策略或者解释估计的因果效应。

所有的APIs将在 API: 与YLearn交互 中介绍。

快速开始

在这部分中，我们首先展示几个简单的YLearn的用法示例。这些例子包含了大部分常见的功能。之后我们以一个使用 Why 的例子来学习揭露数据中隐藏的因果关系。

示例用法

我们在这部分中展示几个必要的YLearn的用法示例。细节请参考它们的具体的文档。

1. 因果图的表示

   对一个给定的因果图 \(X \leftarrow W \rightarrow Y\), 该因果图由 CausalGraph 表示

   causation = {'X': ['W'], 'W':[], 'Y':['W']}
   cg = CausalGraph(causation=causation)
   

   cg 将成为YLearn中的因果图的表示.

2. 识别因果效应

   假如我们对识别因果估计量感兴趣 \(P(Y|do(X=x))\) 在因果图 cg 中, 接着我们应该定义一个实例 CausalModel 的实例并使用 identify() 方法:

   cm = CausalModel(causal_graph=cg)
   cm.identify(treatment={'X'}, outcome={'Y'}, identify_method=('backdoor', 'simple'))
   

3. 估计因果效应

   通过 EstimatorModel 估计因果效应由4步组成:

   • 以 pandas.DataFrame 的形式给出数据, 找到 treatment, outcome, adjustment, covariate 的名称。

   • 使用 EstimatorModel 的 fit() 方法来训练模型。

   • 使用 EstimatorModel 的 estimate() 方法来估计测试数据中的因果效应。

案例分析

API: 与YLearn交互

一体化的API

类名	描述
Why	一个API封装了YLearn中几乎所有的东西，比如 识别因果效应 和 给一个训练过的估计模型打分 。 它给用户提供了简单和有效的方法使用YLearn。

因果结构发现

类名	描述
CausalDiscovery	发现观测数据中的因果结构。

因果模型

类名	描述
CausalGraph	表示因果结构和支持因果图其他相关的操作，例如加减图中的边。
CausalModel	编码由 CausalGraph 表示的因果关系。主要支持因果效应识别，比如后门调整。
Prob	表示概率分布。

估计模型

类名	描述
ApproxBound	一个用于估计因果效应上下界的模型。该模型不需要无混杂条件。
CausalTree	一个通过决策树估计因果效应的类。需要无混杂条件。
DeepIV	具有深度神经网络的工具变量。必须提供工具变量的名字。
NP2SLS	无参数的工具变量。必须提供工具变量的名字。
DoubleML	双机器学习模型用于估计CATE。需要无混杂条件。
DoublyRobust and PermutedDoublyRobust	双鲁棒方法用于估计CATE。置换的版本考虑了所有可能的治疗控制对。需要无混杂条件且治疗必须是离散的。
SLearner and PermutedSLearner	SLearner。 置换的版本考虑了所有可能的治疗控制对。需要无混杂条件且治疗必须是离散的。
TLearner and PermutedTLearner	使用了多个机器学习模型的TLearner。置换的版本考虑了所有可能的治疗控制对。需要无混杂条件且治疗必须是离散的。
XLearner and PermutedXLearner	使用了多个机器学习模型的XLearner。置换的版本考虑了所有可能的治疗控制对。需要无混杂条件且治疗必须是离散的。
RLoss	通过测量估计模型的效果得到效果分。需要无混杂条件。

策略

类名	描述
PolicyTree	一个通过树模型和最大化因果效应来找到最优的策略的类。

解释器

类名	描述
CEInterpreter	一个使用决策树模型的对象，用于解释估计的CATE。
PolicyInterpreter	一个用于解释由一些 PolicyModel 给出的策略的对象。

因果模型：表示因果结构

因果图

这是一个表示因果结构的DAGs的类。

通常来说，对于一组变量 \(V\) ，如果 \(V_j\) 能够对应于 \(V_i\) 的变化而变化，那么变量 \(V_i\) 被称为变量 \(V_j\) 的因。在 一个因果结构的DAG中，每个父节点都是它所有的孩子的直接的因。我们把这些因果结构的DAGs称为因果图。对于图的术语，举个例子，可以参考 [Pearl] 的Chapter 1.2。

有五个基本的由两到三个节点组成的结构用于构建因果图。除了这些结构，还有用概率的语言描述的在因果图中的关联和因果关系的流。任意两个节点 \(X\) 和 \(Y\) ，如果被关联流连接在一起，则表示它们是统计不独立的。等价于 \(P(X, Y) \neq P(X)P(Y)\) 。令 \(X, Y\) 和 \(W\) 为三个不同的节点，那么五个基本的结构包括：

1. 链:

\[X \rightarrow W \rightarrow Y,\]

\(X\) 和 \(Y\) 是统计不独立的;

2. 叉:

\[X \leftarrow W \rightarrow Y,\]

\(X\) 和 \(Y\) 是统计不独立的;

3. 对撞:

\[X \rightarrow W \leftarrow Y,\]

\(X\) 和 \(Y\) 是统计独立的;

4. 两个不相连的节点:

\[X \quad Y,\]

\(X\) 和 \(Y\) 是统计独立的；

5. 两个相连的节点:

\[X \rightarrow Y,\]

\(X\) 和 \(Y\) 是统计不独立的。

在YLearn中，使用 CausalGraph 来表示因果结构，首先给一个python的字典，其中每个键都是它对应的通常由字符串的列表表示的值的每个元素的子节点。

例子

因果结构，其中所有的绿色节点都是未观察到的（一个变量是未观察到的如果它没有显示在数据集中但是可以相信它与其他变量有因果关系）。

因果结构，其中所有的未观察到的变量都被移除了，它们相关的因果关系都被混淆的弧线（有两个箭头的黑色虚线）取代了。

我们可以像下面那样用YLearn表示这个因果结构：

from ylearn.causal_model.graph import CausalGraph
causation = {
    'X': ['Z2'],
    'Z1': ['X', 'Z2'],
    'Y': ['Z1', 'Z3'],
    'Z3': ['Z2'],
    'Z2': [],
}
arcs = [('X', 'Z2'), ('X', 'Z3'), ('X', 'Y'), ('Z2', 'Y')]

cg = CausalGraph(causation=causation, latent_confounding_arcs=arcs)

list(cg.c_components)

>>> [{'X', 'Y', 'Z2', 'Z3'}, {'Z1'}]

类结构

class ylearn.causal_model.graph.CausalGraph(causation, dag=None, latent_confounding_arcs=None)

参数:

• causation (dict) – 描述因果结构，其中值是对应的键的父节点。

• dag (networkx.MultiGraph, optional, default=None) – 一个已知的图结构。如果提供了，DAG必须表示存储在因果关系中的因果结构。

• latent_confounding_arcs (set or list of tuple of two str, optional, default=None,) – 元组中的两个元素是图中节点的名字 其中它们之间存在潜在的混淆弧线。有未观测的混淆因素的半马尔可夫图能够被转化为一个没有未观测到变量的图，其中可以添加双向潜在混淆弧线 表示这些关系。比如，在因果图X <- U -> Y，其中U是一个未观测到的X和Y的混淆因素，可以被等价的转变为X <–> Y，其中<–>是一个潜在的混淆弧线。

ancestors(x)

返回x中所有节点的祖先。

参数:

x (set of str) – 图中的一组节点。

返回:

图中x中节点的祖先。

返回类型:

一组str

descendents(x)

返回x中所有节点的后代。

参数:

x (set of str) – 图中的一组节点。

返回:

图中x中节点的后代。

返回类型:

一组str

parents(x, only_observed=True)

返回图中x节点的直接父节点。

参数:

• x (str) – x节点的名字.

• only_observed (bool, default=True) – 如果为True，那么仅找到观测到的在因果图中的父节点，否则，也包含未观测到的变量，默认是True。

返回:

图中x节点的父节点

返回类型:

列表

add_nodes(nodes, new=False)

如果new是False，则把nodes中所有的节点加入到现在的CausalGraph，否则创建一个新图并加入节点。

参数:

• x (set or list) – 等待被加入到现在的因果图的节点

• new (bool, default=False) – 如果是新创建，则返回一个新的图。默认是False。

返回:

修改的因果图

返回类型:

CausalGraph的实例

add_edges_from(edge_list, new=False, observed=True)

在因果图中加入边。

参数:

• edge_list (list) – 列表中的每个元素包含两个元素，第一个元素是父节点

• new (bool, default=False) – 如果是新创建，则返回一个新的图。默认是False。

• observed (bool, default=True) – 如果未观测到，添加未观测到的双向混淆弧线。

返回:

修改的因果图

返回类型:

CausalGraph的实例

add_edge(edge_list, s, t, observed=True)

在因果图中加入边。

参数:

• s (str) – 边的源。

• t (str) – 边的目的。

• observed (bool, default=True) – 如果未观测到，添加未观测到的双向混淆弧线。

remove_nodes(nodes, new=True)

把nodes所有的节点从图中移除。

参数:

• nodes (set or list) – 等待移除的节点。

• new (bool, default=True) – 如果为True，创建一个新图，移除图中的节点并返回。默认是False。

返回:

修改的因果图

返回类型:

CausalGraph的实例

remove_edge(edge, observed=True)

移除CausalGraph中的边。如果未观察到，移除未观察到的潜在的混淆弧线。

参数:

• edge (tuple) – 2个元素分别表示边的起点和终点。

• observed (bool, default=True) – 如果未观察到，移除未观察到的潜在的混淆弧线。

remove_edges_from(edge_list, new=False, observed=True)

移除图中在edge_list中所有的边。

参数:

• edge_list (list) – 要移除的边的列表。

• new (bool, default=False) – 如果new为真, 创建一个新的CausalGraph并移除边。

• observed (bool, default=True) – 如果未观察到，移除未观察到的潜在的混淆弧线。

返回:

修改的因果图

返回类型:

CausalGraph的实例

build_sub_graph(subset)

返回一个新的CausalGraph作为图的子图，子图中的节点为subset中的节点。

参数:

subset (set) – 子图的集合。

返回:

修改的因果图

返回类型:

CausalGraph的实例

remove_incoming_edges(x, new=False)

移除x中所有节点的入射边。如果new为真，在新的CausalGraph做这个操作。

参数:

• x (set or list) –

• new (bool, default=False,) – 如果为真，返回一个新图。

返回:

修改的因果图

返回类型:

CausalGraph的实例

remove_outgoing_edges(x, new=False)

移除x中所有节点的出射边。如果new为真，在新的CausalGraph做这个操作。

参数:

• x (set or list) –

• new (bool, default=False,) – 如果为真，返回一个新图。

返回:

修改的因果图

返回类型:

CausalGraph的实例

property c_components

图的C-components集合。

返回:

图的C-components集合

返回类型:

str的集合

property observed_dag

返回图的观测到的部分，包含观测到的节点和它们之间的边。

返回:

图的观测到的部分

返回类型:

networkx.MultiGraph

property explicit_unob_var_dag

构建一个新的DAG其中所有未观测到的混淆曲线由明确的未观测的变量取代。

返回:

有明确的未观测到节点的DAG

返回类型:

networkx.MultiGraph

property topo_order

返回观测到的图中的节点的拓扑顺序。

返回:

Nodes in the topological order

返回类型:

generator

因果模型

CausalModel 是一个核心对象来执行 识别 和寻找工具变量。

在介绍因果模型之前，我们首先需要阐明 干涉 的定义。干涉是对整个人群的，并给每一个人一些操作。 [Pearl] 定义了 \(do\)-operator 来描述了这样的操作。概率模型不能够服务预测干涉效果，这导致了对因果模型的需求。

对 causal model 的正式定义归因于 [Pearl] 。一个因果模型是一个三元组

\[M = \left< U, V, F\right>\]

其中

• \(U\) 是 外生的 （由模型外的因素决定的变量）；

• \(V\) 是 内生的 决定于 \(U \cup V\), 和 \(F\) 是这样的一组函数

\[V_i = F_i(pa_i, U_i)\]

其中 \(pa_i \subset V \backslash V_i\).

例如， \(M = \left< U, V, F\right>\) 是一个因果模型其中

\[ \begin{align}\begin{aligned}V = \{V_1, V_2\},\\U = \{ U_1, U_2, I, J\},\\F = \{F_1, F_2 \}\end{aligned}\end{align} \]

这样

\[\begin{split}V_1 = F_1(I, U_1) = \theta_1 I + U_1\\ V_2 = F_2(V_1, J, U_2, ) = \phi V_1 + \theta_2 J + U_2.\end{split}\]

注意每个因果模型都可以和一个DAG关联并编码变量之间必要的因果关系信息。 YLearn使用 CausalModel 来表示一个因果模型并支持许多关于因果模型的操作比如 识别 。

识别

为了表征干涉的效果，需要考虑 因果效应 ，其是一个因果估计量包含 \(do\)-operator 。把因果效应转变为对应的统计估计量的行为被称为 识别 且 在YLearn中的 CausalModel 里实现。注意不是所有的因果效应都能被转变为统计估计量的。我们把这样的因果效应称为不可识别的。我们列出几个 CausalModel 支持的识别方法。

后门调整

\(X\) 对 \(Y\) 的因果效应由下式给出

\[P(y|do(x)) = \sum_w P(y|x, w)P(w)\]

如果变量的集合 \(W\) 满足后门准则关于 \((X, Y)\).

前门调整

\(X\) 对 \(Y\) 的因果效应由下式给出

\[P(y|do(x)) = \sum_w P(w|x) \sum_{x'}P(y|x', w)P(x')\]

如果变量的集合 \(W\) 满足前门准则关于 \((X, Y)\) and if \(P(x, w) > 0\).

通用识别

[Shpitser2006] 给出一个必要充分的图的条件这样任意一个集合的变量对另一个任意集合的因果效应能够被唯一的识别无论它是不是可识别的。 我们称验证这个条件对应的行动为 通用识别。

找到工具变量

当有未观测到的 \(X\) 和 \(Y\) 的混淆因素时，工具变量在识别和估计 \(X\) 对 \(Y\) 的因果效应很有用处。 一组变量 \(Z\) 被称为一组 工具变量 如果 \(Z\) 中任意的 \(z\) ：

1. \(z\) 对 \(X\) 有因果效应。

2. \(z\) 对 \(Y\) 的因果效应完全由于 \(X\) 。

3. 没有后门路径从 \(z\) 到 \(Y\) 。

例子1: 用通用识别方法识别因果效应

因果结构，其中所有的未观察到的变量都被移除了，它们相关的因果关系都被混淆的弧线（有两个箭头的黑色虚线）取代了。

对于图中的因果结构，我们想要使用 通用识别 方法识别 \(X\) 对 \(Y\) 的因果效应。第一步是用 CausalModel 表示因果结构。

from ylearn.causal_model.graph import CausalGraph

causation = {
    'X': ['Z2'],
    'Z1': ['X', 'Z2'],
    'Y': ['Z1', 'Z3'],
    'Z3': ['Z2'],
    'Z2': [],
}
arcs = [('X', 'Z2'), ('X', 'Z3'), ('X', 'Y'), ('Z2', 'Y')]
cg = CausalGraph(causation=causation, latent_confounding_arcs=arcs)

然后我们需要为编码在 cg 中的因果结构定义一个 CausalModel 的实例，从而进行识别。

from ylearn.causal_model.model import CausalModel
cm = CausalModel(causal_model=cg)
stat_estimand = cm.id(y={'Y'}, x={'X'})
stat_estimand.show_latex_expression()

>>> :math:`\sum_{Z3, Z1, Z2}[P(Z2)P(Y|Z3, Z2)][P(Z1|Z2, X)][P(Z3|Z2)]`

结果是想要的识别的在给定的因果结构中 \(X\) 对 \(Y\) 的因果效应。

例子2: 使用后门调整识别因果效应

所有节点都是观测到的变量。

对于图中的因果结构，我们想要使用 后门调整 方法识别 \(X\) 对 \(Y\) 的因果效应。

from ylearn.causal_model.graph import CausalGraph
from ylearn.causal_model.model import CausalModel

causation = {
    'X1': [],
    'X2': [],
    'X3': ['X1'],
    'X4': ['X1', 'X2'],
    'X5': ['X2'],
    'X6': ['X'],
    'X': ['X3', 'X4'],
    'Y': ['X6', 'X4', 'X5', 'X'],
}

cg = CausalGraph(causation=causation)
cm = CausalModel(causal_graph=cg)
backdoor_set, prob = cm3.identify(treatment={'X'}, outcome={'Y'}, identify_method=('backdoor', 'simple'))['backdoor']

print(backdoor_set)

>>> ['X3', 'X4']

例子3: 找到合理的工具变量

变量 \(p, t, l, g\) 的因果结构

我们想要为 \(t\) 对 \(g\) 的因果效应找到合理的工具变量。

causation = {
    'p':[],
    't': ['p'],
    'l': ['p'],
    'g': ['t', 'l']
}
arc = [('t', 'g')]
cg = CausalGraph(causation=causation, latent_confounding_arcs=arc)
cm = CausalModel(causal_graph=cg)

cm.get_iv('t', 'g')

>>> No valid instrument variable has been found.

对变量 \(p, t, l, g\) 的另一个因果结构

我们依然想要在这个新的因果结构中，为 \(t\) 对 \(g\) 的因果效应找到合理的工具变量。

causation = {
    'p':[],
    't': ['p', 'l'],
    'l': [],
    'g': ['t', 'l']
}
arc = [('t', 'g')]
cg = CausalGraph(causation=causation, latent_confounding_arcs=arc)
cm = CausalModel(causal_graph=cg)

cm.get_iv('t', 'g')

>>> {'p'}

类结构

class ylearn.causal_model.CausalModel(causal_graph=None, data=None)

参数:

• causal_graph (CausalGraph, optional, default=None) – CausalGraph的实例，编码了因果结构

• data (pandas.DataFrame, optional, default=None) – 用于发现因果结构的数据，如果causal_graph没有提供。

id(y, x, prob=None, graph=None)

识别因果量 \(P(y|do(x))\) 如果可识别否则返回 raise IdentificationError 。 注意这里我们仅考虑半马尔可夫因果模型，其中每个未观测到的变量正好是两个节点的父节点。这是因为任何的有未观测的变量的因果模型可以被转变为 一个编码了同样集合的条件独立性的半马尔可夫模型。

参数:

• y (set of str) – 结果的名字的集合。

• x (set of str) – 治疗的名字的集合。

• prob (Prob, optional, default=None) – 编码在图中的概率分布。

• graph (CausalGraph) – CausalGraph编码了对应的因果结构中的信息。

返回:

转变的因果效应的概率分布。

返回类型:

Prob

抛出:

IdentificationError – 如果感兴趣的因果效应不能识别，则raise IdentificationError。

is_valid_backdoor_set(set_, treatment, outcome)

决定给定的集合是否是对结果的治疗的因果效应的一个合理的后门调整集合。

参数:

• set (set) – 调整集合。

• treatment (set or list of str) – 治疗的名字。对单个治疗，str也是可以接受的。

• outcome (set or list of str) – 结果的名字。对单个结果，str也是可以接受的。

返回:

True，如果在现在的因果图中，给定的集合是对结果的治疗的因果效应的一个合理的后门调整集合。

返回类型:

bool

get_backdoor_set(treatment, outcome, adjust='simple', print_info=False)

对给定的治疗和结果返回后门调整集合。

参数:

• treatment (set or list of str) – 治疗的名字。对单个治疗，str也是可以接受的。

• outcome (set or list of str) – 结果的名字。对单个结果，str也是可以接受的。

• adjust (str) –

  设置后门集合的样式。可选的选项是

  simple: 直接返回治疗的父节点集合

  minimal: 返回最小的后门调整集合

  all: 返回所有合理的后门调整集合。

• print_info (bool, default=False) – 如果为True，打印识别的结果。

返回:

第一个元素是调整列表，同时第二个是编码的Prob。

返回类型:

两个元素的元组

抛出:

IdentificationError – Raise error如果样式不在simple，minimal或者all或者没有集合能满足后门准则。

get_backdoor_path(treatment, outcome)

返回所有的连接治疗和结果的后门路径。

参数:

• treatment (str) – 治疗的名字。

• outcome (str) – 结果的名字。

返回:

一个包含图中所有合理的治疗和结果之间的后门路径的列表。

返回类型:

list

has_collider(path, backdoor_path=True)

如果现在图的path中有一个对撞，返回True，否则返回False。

参数:

• path (list of str) – 包含路径中节点的列表。

• backdoor_path (bool, default=True) – 该路径是否是一个后门路径。

返回:

True，如果path有一个对撞。

返回类型:

bool

is_connected_backdoor_path(path)

测试是否一个后门路径是连接的。

参数:

path (list of str) – 描述这个路径的列表。

返回:

True，如果路径是一个d-connected的后门路径，否则False。

返回类型:

bool

is_frontdoor_set(set_, treatment, outcome)

决定给定的集合是否是对结果的治疗的因果效应的一个合理的前门调整集合。

参数:

• set (set) – 等待决定是否是合理的前门调整集合的集合。

• treatment (str) – 治疗的名字。

• outcome (str) – 结果的名字。

返回:

True如果给定的集合是对结果的治疗的因果效应的一个合理的前门调整集合。

返回类型:

bool

get_frontdoor_set(treatment, outcome, adjust='simple')

返回用于调整治疗和结果之间因果效应的前门集合。

参数:

• treatment (set of str or str) – 治疗的名字。应该只包含一个元素。

• outcome (set of str or str) – 结果的名字。应该只包含一个元素。

• adjust (str, default='simple') –

  可选的选项包括 ‘simple’: 返回有最少数量元素的前门集合。

  ’minimal’: 返回有最少数量元素的前门集合。

  ’all’: 返回所有可能的前门集合。

返回:

2个元素（adjustment_set, Prob）

返回类型:

元组

抛出:

IdentificationError – Raise error如果样式不在simple，minimal或者all或者没有集合能满足前门准则。

get_iv(treatment, outcome)

为结果的治疗的因果效应找到工具变量。

参数:

• treatment (iterable) – 治疗的名字（们）。

• outcome (iterable) – 结果的名字（们）。

返回:

一个合理的工具变量集合将会是空的如果没有这样的集合。

返回类型:

set

is_valid_iv(treatment, outcome, set_)

决定给出的集合是否是一个合法的工具变量集合。

参数:

• treatment (iterable) – 治疗的名字（们）。

• outcome (iterable) – 结果的名字（们）。

• set (set) – 等待测试的集合。

返回:

True如果集合是一个合理的工具变量集合否则False。

返回类型:

bool

identify(treatment, outcome, identify_method='auto')

识别因果效应表达式。识别是转变任何因果效应量的操作。比如，用do operator的量，变为对应的统计量这样它就可以用给出的数据估计因果效应。但是， 注意不是所有的因果量都是可识别的，这种情况下，一个IdentificationError被抛出。

参数:

• treatment (set or list of str) – 治疗名字的集合。

• outcome (set or list of str) – 结果名字的集合。

• identify_method (tuple of str or str, optional, default='auto') –

  如果传入的值是元组或者列表，那么它应该有两个元素， 其中第一个是识别方法，第二个是返回的集合样式。

  可选的选项：

  ’auto’ : 使用所有可能的方法进行识别

  ’general’: 通用识别方法，看id()

  (‘backdoor’, ‘simple’): 返回治疗和结果的所有的直接的混淆因素的集合作为后门调整集合。

  (‘backdoor’, ‘minimal’): 返回所有的可能的有最小数量元素的后门调整集合。

  (‘backdoor’, ‘all’): 返回所有的可能的后门调整集合。

  (‘frontdoor’, ‘simple’): 返回所有的可能的有最小数量元素的前门调整集合。

  (‘frontdoor’, ‘minimal’): 返回所有的可能的有最小数量元素的前门调整集合。

  (‘frontdoor’, ‘all’): 返回所有的可能的前门调整集合。

返回:

一个python字典，其中字典中的键是识别方法，值是对应的结果。

返回类型:

dict

抛出:

IdentificationError – 如果因果效应不可识别或者identify_method给的不正确。

estimate(estimator_model, data=None, *, treatment=None, outcome=None, adjustment=None, covariate=None, quantity=None, **kwargs)

估计新的数据集中识别的因果效应。

参数:

• estimator_model (EstimatorModel) – 任何在EstimatorModel中实现的合适的估计器模型可以在这里使用。

• data (pandas.DataFrame, optional, default=None) – 用于估计的因果效应的数据集。如果是None，使用用于因果图发现的数据。

• treatment (set or list, optional, default=None) – 治疗的名字们。如果是None，用于后门调整的治疗被当作治疗。

• outcome (set or list, optional, default=None) – 结果的名字们。如果是None，用于后门调整的结果被当作结果。

• adjustment (set or list, optional, default=None) – 调整集合的名字们。如果是None，调整集合由CausalModel找到的最简单的后门集合给出。

• covariate (set or list, optional, default=None) – 协变量集合的名字。如果是None则忽略。

• quantity (str, optional, default=None) – 估计因果效应时，感兴趣的量。

返回:

估计的数据中的因果效应。

返回类型:

np.ndarray or float

identify_estimate(data, outcome, treatment, estimator_model=None, quantity=None, identify_method='auto', **kwargs)

组合识别方法和估计方法。然而，既然现在实现的估计器模型自动假设（有条件地）无混淆（除了有关iv的方法）。我们可能仅考虑使用后门集合调整来实现无混淆条件。

参数:

• treatment (set or list of str, optional) – 治疗的名字们。

• outcome (set or list of str, optional) – 结果的名字们。

• identify_method (tuple of str or str, optional, default='auto') –

  如果传入的值是元组或者列表，那么它应该有两个元素， 其中第一个是识别方法，第二个是返回的集合样式。

  可选的选项：

  ’auto’ : 使用所有可能的方法进行识别

  ’general’: 通用识别方法，看id()

  (‘backdoor’, ‘simple’): 返回治疗和结果的所有的直接的混淆因素的集合作为后门调整集合。

  (‘backdoor’, ‘minimal’): 返回所有的可能的有最小数量元素的后门调整集合。

  (‘backdoor’, ‘all’): 返回所有的可能的后门调整集合。

  (‘frontdoor’, ‘simple’): 返回所有的可能的有最小数量元素的前门调整集合。

  (‘frontdoor’, ‘minimal’): 返回所有的可能的有最小数量元素的前门调整集合。

  (‘frontdoor’, ‘all’): 返回所有的可能的前门调整集合。

• quantity (str, optional, default=None) – 估计因果效应时，感兴趣的量。

返回:

估计的数据中的因果效应。

返回类型:

np.ndarray or float

概率表达式

YLearn能够输出和修改类似如下的概率表达式：

\[P(x, y|z),\]

用户能够定义一个 Prob 的实例，以及改变它的属性.

举例

如一个概率表达式：

\[\sum_{w}P(v|y)[P(w|z)P(x|y)P(u)]\]

它由两个部分组成：一个条件概率:math:P(v|y) 和一个多概率的乘积 \(P(w|z)P(x|y)P(u)\) ，然后这两个部分的积在给定的:math:w 下求和。

首先定义第一个条件概率:math:P(v|y) ：

from ylearn.causal_model.prob import Prob

var = {'v'}
conditional = {'y'} # the conditional set
marginal = {'w'} # sum on w

然后， 继续定义第二个多条件概率的乘积 \(P(w|z)P(x|y)P(u)\)

p1 = Prob(variables={'w'}, conditional={'z'})
p2 = Prob(variables={'x'}, conditional={'y'})
p3 = Prob(variables={'u'})
product = {p1, p2, p3}

最终的结果可以表示为：

P = Prob(variables=var, conditional=conditional, marginal=marginal, product=product)
P.show_latex_expression()

>>> :math:`\sum_w P(v|y)[P(u)][P(w|z)][P(x|y)]`

Prob 的实例还可以输出LaTex代码：

P.parse()

>>> '\\sum_{w}P(v|y)\\left[P(u)\\right]\\left[P(w|z)\\right]\\left[P(x|y)\\right]'

class ylearn.causal_model.prob.Prob(variables=set(), conditional=set(), divisor=set(), marginal=set(), product=set())

一个概率分布表达式如下：

\[\sum_{w}P(v|y)[P(w|z)P(x|y)P(u)].\]

用上述例子来阐明参数的含义：

参数:

• variables (set, default=set()) – The variables (\(v\) in the above example) of the probability.

• conditional (set, default=set()) – The conditional set (\(y\) in the above example) of the probability.

• marginal (set, default=set()) – The sum set (\(w\) in the above example) for marginalizing the probability.

• product (set, default=set()) – If not set(), then the probability is composed of the first probability object \((P(v|y))\) and several other probability objects that are all saved in the set product, e.g., product = {P1, P2, P3} where P1 for \(P(w|z)\), P2 for \(P(x|y)\), and P3 for \(P(u)\) in the above example.

parse()

返回概率分布的表达式

返回:

Expression of the encoded probability

返回类型:

str

show_latex_expression()

显示latex表达式

对于一组变量 \(V\)，它的 因果结构 能够被一个有向无环图（DAG）表示，其中 DAG 中每个节点对应于 \(V\) 中的一个变量；变量间的直接函数关系由DAG中的一个带箭头的连接线表示。用 DAG 表示的因果结构能够精确地说明每一个变量是如何被它的父节点影响的。举个例子， \(X \leftarrow W \rightarrow Y\) 表明 \(W\) 是一个父节点，也是变量 \(X\) 和 \(Y\) 共同的因。更具体一点，对于两个不同的变量 \(V_i\) 和 \(V_j\)，如果它们的函数关系是

\[V_j = f(V_i, \eta_{ij})\]

其中 \(f\) 为函数关系， \(\eta\) 表示噪声,那么用 DAG 来表示这个因果结构时，应该有一个箭头从 \(V_i\) 指向 \(V_j\)。详细的介绍这种因果结构的DAGs可以在 [Pearl] 中找到。

根据 Pearl 的理论，因果效应（也称因果估计量）能够用 \(do-operator\) 表示。例如表达式：

\[P(y|do(x))\]

代表在施加干涉 \(x\) 后 \(y\) 的概率函数。因果结构对于表达和估计感兴趣的因果估计量至关重要。YLearn实现了一个对象 CausalGraph 来支持表示因果结构和对因果结构的相关操作。请参考 因果图 来获得更多细节。

YLearn关心因果推断和机器学习的交叉应用，因此我们假设使用的数据是足够多的观测数据，而不是需要设计随机实验得到的实验数据。对于一个表示因果结构的DAG，因果估计量通常不能被直接的从数据中估计出来，（如平均治疗效应（ATEs））。因为反事实结果是不能够被观测到的。因此有必要在进行任何估计之前，将这些因果估计量转化为其他的能够从数据中估计出来的量，它们被称为统计估计量。把因果估计量转化为对应的统计估计量的过程称为 识别。

支持识别和其他因果结构相关操作的对象是 CausalModel。更多的细节可以在 因果模型 中找到。

在Pearl的因果推断语言中，也有必要把结果表示为概率的语言。为了这个目的，YLearn也实现了一个对象 Prob， 其在 概率表达式 中介绍。

估计器模型：估计因果效应

对于有 \(do\)-operator 的因果效应，用被称为 识别 的方法把它转变为对应的统计估计量之后，因果推断的任务现在变成估计统计估计量， 即转变后的因果效应。在深入到任何具体的因果效应估计方法之前，我们简要的介绍因果效应估计的问题设置。

问题设置

在 因果模型 中介绍了每个因果结构都有对应的被称为因果图的DAG。此外，一个DAG \(G\) 的每一个子父家庭表示一个确定性函数。

\[X_i = F_i (pa_i, \eta_i), i = 1, \dots, n,\]

其中， \(pa_i\) 是 \(x_i\) 在 \(G\) 中的父节点，且 \(\eta_i\) 是随机扰动，表示外生的未在分析中出现的。我们称这些函数为 关于因果结构的 Structural Equation Model 。对于一组满足后门准则（参考 识别）的变量 \(W\)，\(X\) 对 \(Y\) 的因果效应由公式给出

\[P(y|do(x)) = \sum_w P(y| x, w)P(w).\]

在这样的情况下，上述等式有效的变量 \(X\) 也被命名为 “条件可忽略的给定 \(W\)” 在 潜在结果 的框架中。 满足这个条件的变量组 \(W\) 被 称为 调整集合 。在结构化方程模型的语言里，这些关系编码如

\[\begin{split}X & = F_1 (W, \epsilon),\\ Y & = F_2 (W, X, \eta).\end{split}\]

我们的问题可以用结构化方程模型表示。

ATE

具体来说，YLearn中一个尤其重要的因果量是差

\[\mathbb{E}(Y|do(X=X_1)) - \mathbb{E}(Y|do(X=X_0))\]

也被称为 平均治疗效果 (ATE)，其中 \(Y\) 被称为 结果 而 \(X\) 被称为 治疗 。此外，当条件独立（条件可忽略性）成立时，给定一组 变量 \(W\) 对结果 \(Y`\) 和治疗 \(X\) 都有潜在的影响，ATE能够这样估计

\[E(Y|X=x_1, w) - E(Y|X=x_0, w).\]

使用结构化方程模型，我们可以把上述关系描述为

\[\begin{split}X & = F_1 (W, \epsilon) \\ Y & = F_2 (X, W, \eta) \\ \text{ATE} & = \mathbb{E}\left[ F_2(x_1, W, \eta) - F_2(x_0, W, \eta)\right].\end{split}\]

CATE

假如我们给调整集合 \(W`\) 的一个子集的变量分配了特殊的角色并把它们命名为 协变量 \(V\) ，那么，在结构化方程模型 中， CATE （也被称为 异质治疗效果）被定义为

\[\begin{split}X & = F_1 (W, V, \epsilon) \\ Y & = F_2 (X, W, V, \eta) \\ \text{CATE} & = \mathbb{E}\left[ f_2(x_1, W, V, \eta) - f_2(x_0, W, V, \eta)| V =v\right].\end{split}\]

反事实

除了是效应的差的因果估计量，还有一个因果量 反事实 。对于这个量，我们估计如下的因果估计量：

\[\mathbb{E} [Y|do(x), V=v].\]

估计器模型

YLearn实现了几个用于估计因果效应的估计器模型

因果效应的近似边界

许多的估计器模型需要通常无法测试的无混淆条件。一个适用的方法是，在深入具体的估计之前，构建我们的因果效应的上下界。

YLearn中有四个不同的界。我们在下面简单介绍它们。细节请参考 [Neal2020] 。

无假设界

假设

\[\forall x, a \leq Y(do(x)) \leq b,\]

那么我们有

\[\begin{split}\mathbb{E}[Y(do(1)) - Y(do(0))] & \leq \pi \mathbb{E}[Y|X = 1] + (1 - \pi) b - \pi a - (1 - \pi )\mathbb{E}[Y| X = 0]\\ \mathbb{E}[Y(do(1)) - Y(do(0))] & \geq \pi \mathbb{E}[Y|X = 1] + (1 - \pi) a - \pi b - (1 - \pi )\mathbb{E}[Y| X = 0]\end{split}\]

其中 \(\pi\) 是令 \(X=1\) 的概率。

非负单调治疗响应界

假如

\[\forall i, Y(do(1)) \geq Y(do(0)),\]

其意味着 治疗只会帮助 。那么我们有下面的界：

\[\begin{split}\mathbb{E}[Y(do(1)) - Y(do(0))] & \leq \pi \mathbb{E}[Y|X = 1] + (1 - \pi) b - \pi a - (1 - \pi )\mathbb{E}[Y| X = 0]\\ \mathbb{E}[Y(do(1)) - Y(do(0))] & \geq 0\end{split}\]

非正单调治疗响应界

假如

\[\forall i, Y(do(1)) \leq Y(do(0)),\]

其意味着 治疗不会帮助 。那么我们有下面的界：

\[\begin{split}\mathbb{E}[Y(do(1)) - Y(do(0))] & \leq 0\\ \mathbb{E}[Y(do(1)) - Y(do(0))] & \geq \pi \mathbb{E}[Y|X = 1] + (1 - \pi) a - \pi b - (1 - \pi )\mathbb{E}[Y| X = 0].\end{split}\]

最优治疗选择界

假如

\[\begin{split}X = 1 &\implies Y(do(1)) \geq Y(do(0)) \\ X = 0 & \implies Y(do(0)) \geq Y(do(1))\end{split}\]

其意味着 人们总是接受对他们而言最好的治疗 。那么我们有下面的界：

\[\begin{split}\mathbb{E}[Y(do(1)) - Y(do(0))] & \leq \pi \mathbb{E}[Y|X = 1] - \pi a\\ \mathbb{E}[Y(do(1)) - Y(do(0))] & \geq (1 - \pi) a - (1 - \pi )\mathbb{E}[Y| X = 0].\end{split}\]

还有一种最优治疗选择界：

\[\begin{split}\mathbb{E}[Y(do(1)) - Y(do(0))] & \leq \mathbb{E}[Y|X = 1] - \pi a - (1 - \pi)\mathbb{E}[Y|X=0]\\ \mathbb{E}[Y(do(1)) - Y(do(0))] & \geq \pi\mathbb{E}[Y|X = 1] + (1 - \pi) a - \mathbb{E}[Y| X = 0].\end{split}\]

例子

import numpy as np

from ylearn.estimator_model.approximation_bound import ApproxBound
from ylearn.exp_dataset.exp_data import meaningless_discrete_dataset_
from sklearn.ensemble import RandomForestClassifier, RandomForestRegressor

data = meaningless_discrete_dataset_(num=num, confounder_n=3, treatment_effct=[2, 5, -8], random_seed=0)
treatment = 'treatment'
w = ['w_0', 'w_1', 'w_2']
outcome = 'outcome'

bound = ApproxBound(y_model=RandomForestRegressor(), x_model=RandomForestClassifier())
bound.fit(data=data, treatment=treatment, outcome=outcome, covariate=w,)

>>> ApproxBound(y_model=RandomForestRegressor(), x_prob=array([[0.  , 0.99, 0.01],
            [0.  , 0.99, 0.01],
            [1.  , 0.  , 0.  ],
            ...,
            [0.  , 1.  , 0.  ],
            [0.01, 0.99, 0.  ],
            [0.01, 0.99, 0.  ]]), x_model=RandomForestClassifier())

b_l, b_u = bound1.estimate()
b_l.mean()

>>> -7.126728994957785

b_u.mean()

>>> 8.994011617037696

类结构

class ylearn.estimator_model.approximation_bound.ApproxBound(y_model, x_prob=None, x_model=None, random_state=2022, is_discrete_treatment=True, categories='auto')

一个用于估计因果效应上下界的模型。

参数:

• y_model (estimator, optional) – 任何合理的y_model应该实现fit()和predict()方法。

• x_prob (ndarray of shape (c, ), optional, default=None) – 分配给x的对应值的概率数组，其中c是不同治疗类的数量。数组中所有元素都是 正数且和为1。比如，x_prob = array([0.5, 0.5])意味着 x = 0 和 x = 1 的概率为0.5。如果你使用多个治疗，请把这一项设置为None。

• x_model (estimator, optional, default=None) – 用于预测治疗概率的模型。任何合理的x_model应该实现fit()和predict_proba()方法。

• random_state (int, optional, default=2022) –

• is_discrete_treatment (bool, optional, default=True) – True，如果治疗是离散的。

• categories (str, optional, default='auto') –

fit(data, outcome, treatment, covariate=None, is_discrete_covariate=False, **kwargs)

拟合 x_model 和 y_model.

参数:

• data (pandas.DataFrame) – 训练数据。

• outcome (list of str, optional) – 结果的名字。

• treatment (list of str, optional) – 治疗的名字。

• covariate (list of str, optional, default=None) – 协变量的名字。

• is_discrete_covariate (bool, optional, default=False) –

返回:

ApproxBound的拟合的实例。

返回类型:

ApproxBound的实例。

抛出:

ValueError – 当治疗不是离散的，Raise error。

estimate(data=None, treat=None, control=None, y_upper=None, y_lower=None, assump=None)

估计治疗对结果的因果效应的近似界。

参数:

• data (pandas.DataFrame, optional, default=None) – 测试数据。如果为None，模型将会使用训练数据。

• treat (ndarray of str, optional, default=None) – 治疗组的值。比如，当有多个离散的治疗时，array([‘run’, ‘read’])意味着第一个治疗 的治疗值为 ‘run’，第二个治疗是 ‘read’。

• control (ndarray of str, optional, default=None) – 控制组的值。

• y_upper (float, defaults=None) – 结果的上界。

• y_lower (float, defaults=None) – 结果的下界。

• assump (str, optional, default='no-assump') –

  返回界的选项。应该是其中之一

  1. no-assump: 计算无假设界，其结果总是包含0。

  2. non-negative: 治疗总是正的。

  3. non-positive: 治疗总是负的。

  4. optimal: 如果它的效果是正的就采取治疗。

返回:

第一个元素是下界，而第二个元素是上界。注意如果提供了协变量，所有的元素都是表明对应例子的上下界的维度为(n, )的ndarrays，其中n是例子的数量。

返回类型:

tuple

抛出:

Exception – 如果模型没有拟合或者 assump 给的不正确，Raise Exception。

comp_transormer(x, categories='auto')

把离散的治疗正确的转变为独热向量。

参数:

• x (numpy.ndarray, shape (n, x_d)) – 一个包含治疗变量信息的数组。

• categories (str or list, optional, default='auto') –

返回:

转变后的独热变量。

返回类型:

numpy.ndarray

元学习器

元学习器是一种估计模型，旨在当处理手段为离散变量时通过机器学习模型去评估CATE。治疗方案为离散变量的意思也就是当无混淆条件下非1即0。通常来讲，它利用多个可灵活选择的机器学习模型。

YLearn 实现了3个元学习器: S-Learner, T-Learner, and X-Learner.

示例

import numpy as np
from numpy.random import multivariate_normal

from sklearn.ensemble import RandomForestClassifier, GradientBoostingRegressor

import matplotlib.pyplot as plt

from ylearn.estimator_model.meta_learner import SLearner, TLearner, XLearner
from ylearn.estimator_model.doubly_robust import DoublyRobust
from ylearn.exp_dataset.exp_data import binary_data
from ylearn.utils import to_df

# build the dataset
d = 5
n = 2500
n_test = 250

y, x, w = binary_data(n=n, d=d, n_test=n_test)
data = to_df(outcome=y, treatment=x, w=w)
outcome = 'outcome'
treatment = 'treatment'
adjustment = data.columns[2:]

# build the test dataset
treatment_effect = lambda x: (1 if x[1] > 0.1 else 0) * 8

w_test = multivariate_normal(np.zeros(d), np.diag(np.ones(d)), n_test)
delta = 6/n_test
w_test[:, 1] = np.arange(-3, 3, delta)

SLearner

s = SLearner(model=GradientBoostingRegressor())
s.fit(data=data, outcome=outcome, treatment=treatment, adjustment=adjustment) # training
s_pred = s.estimate(data=test_data, quantity=None) # predicting

TLearner

t = TLearner(model=GradientBoostingRegressor())
t.fit(data=data, outcome=outcome, treatment=treatment, adjustment=adjustment) # training
t_pred = t.estimate(data=test_data, quantity=None) # predicting

XLearner

x = XLearner(model=GradientBoostingRegressor())
x.fit(data=data, outcome=outcome, treatment=treatment, adjustment=adjustment) # training
x_pred = x.estimate(data=test_data, quantity=None) # predicting

S-Learner

SLearner 采用一个机器学习模型来评估因果效应。具体来说，我们用机器学习模型 \(f\) 从治疗方案 \(x\) 和调整集 (或者协变量) \(w\) 中拟合一个模型去预测结果 \(y\):

\[y = f(x, w).\]

因果效应 \(\tau(w)\) 被计算为:

\[\tau(w) = f(x=1, w) - f(x=0, w).\]

class ylearn.estimator_model.meta_learner.SLearner(model, random_state=2022, is_discrete_treatment=True, categories='auto', *args, **kwargs)

参数:

• model (estimator, optional) – The base machine learning model for training SLearner. Any model should be some valid machine learning model with fit() and predict() functions.

• random_state (int, default=2022) –

• is_discrete_treatment (bool, default=True) – Treatment must be discrete for SLearner.

• categories (str, optional, default='auto') –

fit(data, outcome, treatment, adjustment=None, covariate=None, treat=None, control=None, combined_treatment=True, **kwargs)

Fit the SLearner in the dataset.

参数:

• data (pandas.DataFrame) – Training dataset for training the estimator.

• outcome (list of str, optional) – Names of the outcome.

• treatment (list of str, optional) – Names of the treatment.

• adjustment (list of str, optional, default=None) – Names of the adjustment set ensuring the unconfoundness,

• covariate (list of str, optional, default=None) – Names of the covariate.

• treat (int, optional) – Label of the intended treatment group

• control (int, optional) – Label of the intended control group

• combined_treatment (bool, optional, default=True) –

  Only modify this parameter for multiple treatments, where multiple discrete treatments are combined to give a single new group of discrete treatment if set as True. When combined_treatment is set to True, then if there are multiple treatments, we can use the combined_treatment technique to covert the multiple discrete classification tasks into a single discrete classification task. For an example, if there are two different binary treatments:

  1. treatment_1: \(x_1 | x_1 \in \{'sleep', 'run'\}\),

  2. treatment_2: \(x_2 | x_2 \in \{'study', 'work'\}\),

  then we can convert these two binary classification tasks into a single classification task with 4 different classes:

  treatment: \(x | x \in \{0, 1, 2, 3\}\),

  where, for example, 1 stands for (‘sleep’ and ‘stuy’).

返回:

The fitted instance of SLearner.

返回类型:

instance of SLearner

estimate(data=None, quantity=None)

Estimate the causal effect with the type of the quantity.

参数:

• data (pandas.DataFrame, optional, default=None) – Test data. The model will use the training data if set as None.

• quantity (str, optional, default=None) –

  Option for returned estimation result. The possible values of quantity include:

  1. ’CATE’ : the estimator will evaluate the CATE;

  2. ’ATE’ : the estimator will evaluate the ATE;

  3. None : the estimator will evaluate the ITE or CITE.

返回:

The estimated causal effects

返回类型:

ndarray

effect_nji(data=None)

Calculate causal effects with different treatment values.

返回:

Causal effects with different treatment values.

返回类型:

ndarray

_comp_transormer(x, categories='auto')

Transform the discrete treatment into one-hot vectors properly.

参数:

• x (numpy.ndarray, shape (n, x_d)) – An array containing the information of the treatment variables.

• categories (str or list, optional, default='auto') –

返回:

The transformed one-hot vectors.

返回类型:

numpy.ndarray

T-Learner

TLearner的问题是当调整集向量为多维时治疗方案向量仅为一维。因此，如果调整集的维度超过1，那么评估结果将总是逼近于0。 TLearner用两个机器学习模型去评估因果效应。具体来讲，令 \(w\) 为调整集（或协变量），我们

1. 分别拟合两个模型 \(f_t(w)\) 对于治疗组 (\(x=\) treat) 和 \(f_0(w)\) 对于控制组 (\(x=\) control):

   \[y_t = f_t(w)\]

其中, \(x=\) treat.

\[y_0 = f_0(w)\]

其中, \(x=\) control.

2. 计算因果效应 \(\tau(w)\) 作为两个模型预测结果的差异:

   \[\tau(w) = f_t(w) - f_0(w).\]

class ylearn.estimator_model.meta_learner.TLearner(model, random_state=2022, is_discrete_treatment=True, categories='auto', *args, **kwargs)

参数:

• model (estimator, optional) – The base machine learning model for training TLearner. Any model should be some valid machine learning model with fit() and predict() functions.

• random_state (int, default=2022) –

• is_discrete_treatment (bool, default=True) – Treatment must be discrete for SLearner.

• categories (str, optional, default='auto') –

fit(data, outcome, treatment, adjustment=None, covariate=None, treat=None, control=None, combined_treatment=True, **kwargs)

Fit the SLearner in the dataset.

参数:

• data (pandas.DataFrame) – Training dataset for training the estimator.

• outcome (list of str, optional) – Names of the outcome.

• treatment (list of str, optional) – Names of the treatment.

• adjustment (list of str, optional, default=None) – Names of the adjustment set ensuring the unconfoundness,

• covariate (list of str, optional, default=None) – Names of the covariate.

• treat (int, optional) – Label of the intended treatment group

• control (int, optional) – Label of the intended control group

• combined_treatment (bool, optional, default=True) –

  Only modify this parameter for multiple treatments, where multiple discrete treatments are combined to give a single new group of discrete treatment if set as True. When combined_treatment is set to True, then if there are multiple treatments, we can use the combined_treatment technique to covert the multiple discrete classification tasks into a single discrete classification task. For an example, if there are two different binary treatments:

  1. treatment_1: \(x_1 | x_1 \in \{'sleep', 'run'\}\),

  2. treatment_2: \(x_2 | x_2 \in \{'study', 'work'\}\),

  then we can convert these two binary classification tasks into a single classification task with 4 different classes:

  treatment: \(x | x \in \{0, 1, 2, 3\}\),

  where, for example, 1 stands for (‘sleep’ and ‘stuy’).

返回:

The fitted instance of TLearner.

返回类型:

instance of TLearner

estimate(data=None, quantity=None)

Estimate the causal effect with the type of the quantity.

参数:

• data (pandas.DataFrame, optional, default=None) – Test data. The model will use the training data if set as None.

• quantity (str, optional, default=None) –

  Option for returned estimation result. The possible values of quantity include:

  1. ’CATE’ : the estimator will evaluate the CATE;

  2. ’ATE’ : the estimator will evaluate the ATE;

  3. None : the estimator will evaluate the ITE or CITE.

返回:

The estimated causal effects

返回类型:

ndarray

effect_nji(data=None)

Calculate causal effects with different treatment values.

返回:

Causal effects with different treatment values.

返回类型:

ndarray

_comp_transormer(x, categories='auto')

Transform the discrete treatment into one-hot vectors properly.

参数:

• x (numpy.ndarray, shape (n, x_d)) – An array containing the information of the treatment variables.

• categories (str or list, optional, default='auto') –

返回:

The transformed one-hot vectors.

返回类型:

numpy.ndarray

X-Learner

TLearner未能完全有效地利用数据，XLearner可以解决这个问题。训练一个XLearner可以分为3步:

1. 与TLearner类似, 我们首先分别训练两个不同的模型对于控制组和治疗组:

   \[\begin{split}& f_0(w) \text{for the control group}\\ & f_1(w) \text{for the treat group}.\end{split}\]

2. 生成两个新数据集 \(\{(h_0, w)\}\) 用控制组, :math:`{(h_1, w)}`用治疗组。 其中

   \[\begin{split}h_0 & = f_1(w) - y_0,\\ h_1 & = y_1 - f_0(w).\end{split}\]

   然后，训练两个机器学习模型在这些数据集中 \(k_0(w)\) 和 \(k_1(w)\)

   \[\begin{split}h_0 & = k_0(w) \\ h_1 & = k_1(w).\end{split}\]

3. 结合以上两个模型得到最终的模型:

   \[g(w) = k_0(w)a(w) + k_1(w)(1 - a(w))\]

   其中, \(a(w)\) 是一个调整 \(k_0\) 和 \(k_1\) 的权重调整系数。

最后, 因果效应 \(\tau(w)\) 通过以下方式评估:

\[\tau(w) = g(w).\]

class ylearn.estimator_model.meta_learner.XLearner(model, random_state=2022, is_discrete_treatment=True, categories='auto', *args, **kwargs)

参数:

• model (estimator, optional) – The base machine learning model for training SLearner. Any model should be some valid machine learning model with fit() and predict() functions.

• random_state (int, default=2022) –

• is_discrete_treatment (bool, default=True) – Treatment must be discrete for SLearner.

• categories (str, optional, default='auto') –

fit(data, outcome, treatment, adjustment=None, covariate=None, treat=None, control=None, combined_treatment=True, **kwargs)

Fit the SLearner in the dataset.

参数:

• data (pandas.DataFrame) – Training dataset for training the estimator.

• outcome (list of str, optional) – Names of the outcome.

• treatment (list of str, optional) – Names of the treatment.

• adjustment (list of str, optional, default=None) – Names of the adjustment set ensuring the unconfoundness,

• covariate (list of str, optional, default=None) – Names of the covariate.

• treat (int, optional) – Label of the intended treatment group

• control (int, optional) – Label of the intended control group

• combined_treatment (bool, optional, default=True) –

  Only modify this parameter for multiple treatments, where multiple discrete treatments are combined to give a single new group of discrete treatment if set as True. When combined_treatment is set to True, then if there are multiple treatments, we can use the combined_treatment technique to covert the multiple discrete classification tasks into a single discrete classification task. For an example, if there are two different binary treatments:

  1. treatment_1: \(x_1 | x_1 \in \{'sleep', 'run'\}\),

  2. treatment_2: \(x_2 | x_2 \in \{'study', 'work'\}\),

  then we can convert these two binary classification tasks into a single classification task with 4 different classes:

  treatment: \(x | x \in \{0, 1, 2, 3\}\),

  where, for example, 1 stands for (‘sleep’ and ‘stuy’).

返回:

The fitted instance of XLearner.

返回类型:

instance of XLearner

estimate(data=None, quantity=None)

Estimate the causal effect with the type of the quantity.

参数:

• data (pandas.DataFrame, optional, default=None) – Test data. The model will use the training data if set as None.

• quantity (str, optional, default=None) –

  Option for returned estimation result. The possible values of quantity include:

  1. ’CATE’ : the estimator will evaluate the CATE;

  2. ’ATE’ : the estimator will evaluate the ATE;

  3. None : the estimator will evaluate the ITE or CITE.

返回:

The estimated causal effects

返回类型:

ndarray

effect_nji(data=None)

Calculate causal effects with different treatment values.

返回:

Causal effects with different treatment values.

返回类型:

ndarray

_comp_transormer(x, categories='auto')

Transform the discrete treatment into one-hot vectors properly.

参数:

• x (numpy.ndarray, shape (n, x_d)) – An array containing the information of the treatment variables.

• categories (str or list, optional, default='auto') –

返回:

The transformed one-hot vectors.

返回类型:

numpy.ndarray

双机器学习

符号

我们使用大写字母表示矩阵，小写字母表示向量。治疗由 \(x\) 表示，结果由 \(y\) 表示，协变量由 \(v\) 表示，且其他的调整集合变量是 \(w\)。 希腊字母用于错误项。

双机器学习（DML）模型 [Chern2016] 适用于当治疗，结果，变量的同时影响治疗和结果的所有的混杂因素都被观察到。令 \(y\) 为结果，\(x\) 为治疗，一个 DML模型解决如下的因果效应估计（CATE估计）：

\[\begin{split}y & = F(v) x + g(v, w) + \epsilon \\ x & = h(v, w) + \eta\end{split}\]

其中 \(F(v)\) 是CATE以 \(v\) 为条件。 此外，为了估计 \(F(v)\)，我们注意到

\[y - \mathbb{E}[y|w, v] = F(v) (x - \mathbb{E}[x|w, v]) + \epsilon.\]

因此通过首先估计 \(\mathbb{E}[y|w, v]\) 和 \(\mathbb{E}[x|w,v]\) 为

\[\begin{split}m(v, w) & = \mathbb{E}[y|w, v]\\ h(v, w) & = \mathbb{E}[x|w,v],\end{split}\]

我们能够得到一个新的数据集： \((\tilde{y}, \tilde{x})\) 其中

\[\begin{split}\tilde{y} & = y - m(v, w) \\ \tilde{x} & = x - h(v, w)\end{split}\]

这样 \(\tilde{y}\) 和 \(\tilde{x}\) 之间的关系是线性的

\[\tilde{y} = F(v) \tilde(x) + \epsilon\]

其能够被线性回归模型简单的建模。

另一方面，在现在的版本， \(F(v)\) 采取形式

\[F_{ij}(v) = \sum_k H_{ijk} \rho_k(v).\]

其中 \(H\) 能够被看作一个秩为3的张量且 \(\rho_k\) 是协变量 \(v\) 的函数，比如，最简单的情况 \(\rho(v) = v\) 。因此， 结果 \(y\) 现在能够被表示为

\[\begin{split}y_i & = \sum_j F_{ij}x_j + g(v, w)_j + \epsilon \\ & = \sum_j \sum_k H_{ijk}\rho_k(v)x_j + g(v, w)_j + \epsilon\end{split}\]

在这个意义上，\(\tilde{y}\) 和 \(\tilde{x}\) 之间的线性回归问题现在成为，

\[\tilde{y}_i = \sum_j \sum_k H_{ijk}\rho_k(v) \tilde{x}_j + \epsilon.\]

实现

在YLearn中，我们实现了一个双机器学习模型如 [Chern2016] 中描述的算法：

1. 令 k (cf_folds in our class) 为一个int. 形成一个k-折随机划分{…, (train_data_i, test_data_i), …, (train_data_k, test_data_k)}。

2. 对于每个i，训练y_model和x_model在train_data_i上，接着评估它们的性能在test_data_i中，其结果会被保存为 \((\hat{y}_k, \hat{x}_k)\) 。 所有的 \((\hat{y}_k, \hat{x}_k)\) 将会合并以提供新的数据集 \((\hat{y}, \hat{x})\) 。

3. 定义差

\[\begin{split}\tilde{y}& = y - \hat{y}, \\ \tilde{x}&= (x - \hat{x}) \otimes v.\end{split}\]

接着形成新的数据集 \((\tilde{y}, \tilde{x})\).

4. 在数据集 \((\tilde{y}, \tilde{x})\) 上执行线性回归，其系数将会被保存到向量 \(f\) 中。给定 \(v\)，估计的CATE将会为

\[f \cdot v.\]

例子

from sklearn.ensemble import RandomForestRegressor

from ylearn.exp_dataset.exp_data import single_continuous_treatment
from ylearn.estimator_model.double_ml import DoubleML

# build the dataset
train, val, treatment_effect = single_continuous_treatment()
adjustment = train.columns[:-4]
covariate = 'c_0'
outcome = 'outcome'
treatment = 'treatment'

dml = DoubleML(x_model=RandomForestRegressor(), y_model=RandomForestRegressor(), cf_fold=3,)
dml.fit(train, outcome, treatment, adjustment, covariate,)

>>> 06-23 14:02:36 I ylearn.e.double_ml.py 684 - _fit_1st_stage: fitting x_model RandomForestRegressor
>>> 06-23 14:02:39 I ylearn.e.double_ml.py 690 - _fit_1st_stage: fitting y_model RandomForestRegressor
>>> DoubleML(x_model=RandomForestRegressor(), y_model=RandomForestRegressor(), yx_model=LinearRegression(), cf_fold=3)

类结构

class ylearn.estimator_model.double_ml.DoubleML(x_model, y_model, yx_model=None, cf_fold=1, adjustment_transformer=None, covariate_transformer=None, random_state=2022, is_discrete_treatment=False, categories='auto')

参数:

• x_model (estimator, optional) – 拟合x的机器学习模型。任何这样的模型应该实现 fit() 和 predict`() （也 predict_proba() 如果x是离散的）方法。

• y_model (estimator, optional) – 为了建模结果训练的机器学习模型。任何合理的y_model应该实现 fit() 和 predict() 方法。

• yx_model (estimator, optional) – 用于拟合基于x的残差的y的残差的机器学习模型。 当前版本只支持线性回归模型。

• cf_fold (int, default=1) – 在第一阶段执行交叉拟合的折的数量。

• adjustment_transformer (transormer, optional, default=None,) – 调整变量的Transformer，其可以被用于生成调整变量的新特征。

• covariate_transformer (transormer, optional, default=None,) – 协变量的Transformer，其可以被用于生成协变量的新特征。

• random_state (int, default=2022) –

• is_discrete_treatment (bool, default=False) – 如果治疗变量是离散的，把这个设为True。

• categories (str, optional, default='auto') –

fit(data, outcome, treatment, adjustment=None, covariate=None, **kwargs)

拟合DoubleML估计器模型。注意训练一个DML有两个阶段，其中我们在 _fit_1st_stage() 和 _fit_2nd_stage() 中实现它们。

参数:

• data (pandas.DataFrame) – 训练估计器的训练数据集。

• outcome (list of str, optional) – 结果的名字。

• treatment (list of str, optional) – 治疗的名字。

• adjustment (list of str, optional, default=None) – 保证无混淆的调整集的名字。

• covariate (list of str, optional, default=None) – 协变量的名字。

返回:

拟合的model

返回类型:

一个DoubleML的实例

estimate(data=None, treat=None, control=None, quantity=None)

用量的类型估计因果效应。

参数:

• data (pandas.DataFrame, optional, default=None) – 用于估计器估计因果效应的测试数据，注意如果data是None，估计器直接估计训练数据中所有的量。

• treat (float or numpy.ndarray, optional, default=None) – 在单个离散治疗的情况下，treat应该是所有可能的治疗值之一的int或者str， 其表示预期的治疗值，在有多个离散治疗的情况下，treat应该是一个列表或者ndarray，其中treat[i]表示第i个预期的治疗值。例如， 当有多个离散治疗，array([‘run’, ‘read’])意味着第一个治疗的治疗值是 ‘run’ ，第二个治疗是 ‘read’ 。在连续治疗值的情况下，治疗应该是一个float或者ndarray。

• quantity (str, optional, default=None) –

  返回的估计结果的选项。量的可能值包括：

  1. ’CATE’ : 估计器将会估计CATE；

  2. ’ATE’ : 估计器将会估计ATE；

  3. None : 估计器将会估计ITE或CITE。

• control (float or numpy.ndarray, optional, default=None) – 这和treat的情况相似。

返回:

估计的因果效应

返回类型:

ndarray

effect_nji(data=None)

用不同的治疗值计算因果效应。

参数:

data (pandas.DataFrame, optional, default=None) – 用于估计器估计因果效应的测试数据，注意如果data是None，估计器会使用训练数据。

返回:

不同治疗值的因果效应。

返回类型:

ndarray

comp_transormer(x, categories='auto')

把离散的治疗正确转变为独热向量。

参数:

• x (numpy.ndarray, shape (n, x_d)) – 包含治疗变量信息的数组。

• categories (str or list, optional, default='auto') –

返回:

转变的独热向量。

返回类型:

numpy.ndarray

双鲁棒

双鲁棒方法（参考 [Funk2010] ）估计因果效应当治疗是离散的且满足无混淆条件。 训练一个双鲁棒模型由3步组成。

1. 令 \(k\) 为一个int。形成一个对数据 \(\{(X_i, W_i, V_i, Y_i)\}_{i = 1}^n\) 的 \(K\)-fold 随机划分，这样

   \[\{(x_i, w_i, v_i, y_i)\}_{i = 1}^n = D_k \cup T_k\]

   其中 \(D_k\) 表示训练数据且 \(T_k\) 表示测试数据且 \(\cup_{k = 1}^K T_k = \{(X_i, W_i, V_i, Y_i)\}_{i = 1}^n\).

2. 对于每个 \(k\), 训练两个模型 \(f(X, W, V)\) 和 \(g(W, V)\) 在 \(D_k\) 上来分别预测 \(y\) 和 \(x\)。接着估计它们在 \(T_k\) 中的性能， 结果保存为 \(\{(\hat{X}, \hat{Y})\}_k\) 。所有的 \(\{(\hat{X}, \hat{Y})\}_k\) 将被合并来给出新的数据集 \(\{(\hat{X}_i, \hat{Y}_i(X, W, V))\}_{i = 1}^n\) 。

3. 对于任何给定的一对治疗组其中 \(X=x\) 和控制组其中 \(X = x_0\) ，我们构建最终数据集 \(\{(V, \tilde{Y}_x - \tilde{Y}_0)\}\) 其中 \(\tilde{Y}_x\) 被定义为

   \[\begin{split}\tilde{Y}_x & = \hat{Y}(X=x, W, V) + \frac{(Y - \hat{Y}(X=x, W, V)) * \mathbb{I}(X=x)}{P[X=x| W, V]} \\ \tilde{Y}_0 & = \hat{Y}(X=x_0, W, V) + \frac{(Y - \hat{Y}(X=x_0, W, V)) * \mathbb{I}(X=x_0)}{P[X=x_0| W, V]}\end{split}\]

   并在这个数据集上训练最终的机器学习模型 \(h(W, V)\) 来预测因果效应 \(\tau(V)\)

   \[\tau(V) = \tilde{Y}_x - \tilde{Y}_0 = h(V).\]

   接着我们可以直接估计因果效应，通过传入协变量 \(V\) 到模型 \(h(V)\) 。

例子

import numpy as np
from numpy.random import multivariate_normal

from sklearn.ensemble import RandomForestClassifier, GradientBoostingRegressor

import matplotlib.pyplot as plt

from ylearn.estimator_model.meta_learner import SLearner, TLearner, XLearner
from ylearn.estimator_model.doubly_robust import DoublyRobust
from ylearn.exp_dataset.exp_data import binary_data
from ylearn.utils import to_df

# build the dataset
d = 5
n = 2500
n_test = 250

y, x, w = binary_data(n=n, d=d, n_test=n_test)
data = to_df(outcome=y, treatment=x, w=w)
outcome = 'outcome'
treatment = 'treatment'
adjustment = data.columns[2:]

# build the test dataset
treatment_effect = lambda x: (1 if x[1] > 0.1 else 0) * 8

w_test = multivariate_normal(np.zeros(d), np.diag(np.ones(d)), n_test)
delta = 6/n_test
w_test[:, 1] = np.arange(-3, 3, delta)

训练 DoublyRobust 模型。

dr = DoublyRobust(
    x_model=RandomForestClassifier(n_estimators=100, max_depth=100, min_samples_leaf=int(n/100)),
    y_model=GradientBoostingRegressor(n_estimators=100, max_depth=100, min_samples_leaf=int(n/100)),
    yx_model=GradientBoostingRegressor(n_estimators=100, max_depth=100, min_samples_leaf=int(n/100)),
    cf_fold=1,
    random_state=2022,
)
dr.fit(data=data, outcome=outcome, treatment=treatment, covariate=adjustment,)
dr_pred = dr.estimate(data=test_data, quantity=None).squeeze()

类结构

class ylearn.estimator_model.doubly_robust.DoublyRobust(x_model, y_model, yx_model, cf_fold=1, random_state=2022, categories='auto')

参数:

• x_model (estimator, optional) – 经过训练的机器学习模型，用于对治疗建模。任何合理的x_model应该实现 fit() 和 predict_proba() 方法。

• y_model (estimator, optional) – 经过训练的机器学习模型，用于使用协变量（可能是调整）和治疗对结果建模。任何合理的y_model应该实现 fit() 和 predict() 方法。

• yx_model (estimator, optional) – 经过在双鲁棒方法的最后阶段训练的机器学习模型，用于使用协变量（可能是调整）对因果效应建模。任何合理的yx_model应该实现 fit() 和 predict() 方法。

• cf_fold (int, default=1) – 在第一阶段执行交叉拟合的折的数量。

• random_state (int, default=2022) –

• categories (str, optional, default='auto') –

fit(data, outcome, treatment, adjustment=None, covariate=None, treat=None, control=None, combined_treatment=True, **kwargs)

拟合DoublyRobust估计器模型。注意训练一个双鲁棒模型有三个阶段，其中我们在 _fit_1st_stage() 和 _fit_2nd_stage() 中实现它们。

参数:

• data (pandas.DataFrame) – 训练估计器的训练数据集。

• outcome (list of str, optional) – 结果的名字。

• treatment (list of str, optional) – 治疗的名字。

• adjustment (list of str, optional, default=None) – 保证无混淆的调整集的名字。

• covariate (list of str, optional, default=None) – 协变量的名字。

• treat (int, optional) – 预期治疗组的标签。如果为None，那么 treat 将会被设置为1。 在单个离散治疗的情况下，treat应该是所有可能的治疗值之一的int或者str， 其表示预期的治疗值，在有多个离散治疗的情况下，treat应该是一个列表或者ndarray，其中treat[i]表示第i个预期的治疗值。例如， 当有多个离散治疗，array([‘run’, ‘read’])意味着第一个治疗的治疗值是 ‘run’ ，第二个治疗是 ‘read’ 。

• control (int, optional) – 预期控制组的标签。这和treat的情况相似。如果是None，那么 control 将会被设置为0。

返回:

拟合的DoublyRobust的实例。

返回类型:

DoublyRobust的实例

estimate(data=None, quantity=None, treat=None, all_tr_effects=False)

用量的类型估计因果效应。

参数:

• data (pandas.DataFrame, optional, default=None) – 测试数据。注意被设置为None，模型会使用训练数据。

• quantity (str, optional, default=None) –

  返回的估计结果的选项。量的可能值包括：

  1. ’CATE’ : 估计器将会估计CATE；

  2. ’ATE’ : 估计器将会估计ATE；

  3. None : 估计器将会估计ITE或CITE。

• treat (float or numpy.ndarray, optional, default=None) – 在单个离散治疗的情况下，treat应该是所有可能的治疗值之一的int或者str， 其表示预期的治疗值，在有多个离散治疗的情况下，treat应该是一个列表或者ndarray，其中treat[i]表示第i个预期的治疗值。例如， 当有多个离散治疗，array([‘run’, ‘read’])意味着第一个治疗的治疗值是 ‘run’ ，第二个治疗是 ‘read’ 。

• all_tr_effects (bool, default=False,) – 如果为True，返回所有的因果效应和所有的 treatments 的值，否则，仅返回 在如果提供了的 treat 中的治疗的因果效应。如果 treat 没提供，那么治疗的值作为拟合估计器模型的值。

返回:

估计的因果效应

返回类型:

ndarray

effect_nji(data=None)

用不同的治疗值计算因果效应。注意这个方法仅将把任何有离散治疗的问题转变为二元治疗。能够使用 _effect_nji_all() 去获得 treatment 取 treat 所有值时的因果效应。

返回:

不同治疗值的因果效应。

返回类型:

ndarray

comp_transormer(x, categories='auto')

把离散的治疗正确转变为独热向量。

参数:

• x (numpy.ndarray, shape (n, x_d)) – 包含治疗变量信息的数组。

• categories (str or list, optional, default='auto') –

返回:

转变的独热向量。

返回类型:

numpy.ndarray

因果树

因果树是一个数据驱动的方法，用来把数据划分为因果效应幅度不同的亚群 [Athey2015] 。这个方法在给定调整集（协变量） \(V\) 无混淆满足时适用。 感兴趣的因果效应是CATE：

\[\tau(v) := \mathbb{}[Y_i(do(X=x_t)) - Y_i(do(X=x_0)) | V_i = v]\]

因为事实上反事实无法被观测到， [Athey2015] 开发了一个诚实的方法，其中损失函数（构建树的准则）被设计为

\[e (S_{tr}, \Pi) := \frac{1}{N_{tr}} \sum_{i \in S_{tr}} \hat{\tau}^2 (V_i; S_{tr}, \Pi) - \frac{2}{N_{tr}} \cdot \sum_{\ell \in \Pi} \left( \frac{\Sigma^2_{S_{tr}^{treat}}(\ell)}{p} + \frac{\Sigma^2_{S_{tr}^{control}}(\ell)}{1 - p}\right)\]

其中 \(N_{tr}\) 是训练集 \(S_{tr}\) 中样本的数量, \(p\) 是训练集中治疗组和控制组样本个数的比，且

\[\begin{split}\hat{\tau}(v) = \frac{1}{\#(\{i\in S_{treat}: V_i \in \ell(v; \Pi)\})} \sum_{ \{i\in S_{treat}: V_i \in \ell(v; \Pi)\}} Y_i \\ - \frac{1}{\#(\{i\in S_{control}: V_i \in \ell(v; \Pi)\})} \sum_{ \{i\in S_{control}: V_i \in \ell(v; \Pi)\}} Y_i.\end{split}\]

例子

import numpy as np
import matplotlib.pyplot as plt

from ylearn.estimator_model.causal_tree import CausalTree
from ylearn.exp_dataset.exp_data import sq_data
from ylearn.utils._common import to_df


# build dataset
n = 2000
d = 10
n_x = 1
y, x, v = sq_data(n, d, n_x)
true_te = lambda X: np.hstack([X[:, [0]]**2 + 1, np.ones((X.shape[0], n_x - 1))])
data = to_df(treatment=x, outcome=y, v=v)
outcome = 'outcome'
treatment = 'treatment'
adjustment = data.columns[2:]

# build test data
v_test = v[:min(100, n)].copy()
v_test[:, 0] = np.linspace(np.percentile(v[:, 0], 1), np.percentile(v[:, 0], 99), min(100, n))
test_data = to_df(v=v_test)

训练 CausalTree 并在测试数据中使用它：

ct = CausalTree(min_samples_leaf=3, max_depth=5)
ct.fit(data=data, outcome=outcome, treatment=treatment, adjustment=adjustment)
ct_pred = ct.estimate(data=test_data)

类结构

class ylearn.estimator_model.causal_tree.CausalTree(*, splitter='best', max_depth=None, min_samples_split=2, min_samples_leaf=1, random_state=2022, max_leaf_nodes=None, max_features=None, min_impurity_decrease=0.0, min_weight_fraction_leaf=0.0, ccp_alpha=0.0, categories='auto')

参数:

• splitter ({"best", "random"}, default="best") – 用于选择每个节点划分的策略。支持的策略为选择最佳划分的”best”和选择最佳随机划分的”random”。

• max_depth (int, default=None) – 树的最大深度。如果为None，那么节点可以一直扩展直到所有的叶子都是纯的或者所有的叶子都包含小于min_samples_split个样本。

• min_samples_split (int or float, default=2) – 划分内部节点所需要的最小的样本数量： - 如果是int，那么考虑 min_samples_split 为最小数量。 - 如果是float, 那么 min_samples_split 是一个分数并且 ceil(min_samples_split * n_samples) 是对于每一个划分最小的样本数量。

• min_samples_leaf (int or float, default=1) –

  在一个叶子节点需要的最小的样本数量。 一个在任意深度的划分点仅当它留下至少 min_samples_leaf 训练样本在它的左右分支时会被考虑。这可能有平滑模型的作用，尤其是在回归中。

  • 如果是int, 那么考虑 min_samples_leaf 为最小数量。

  • 如果是float, 那么 min_samples_leaf 是一个分数并且 ceil(min_samples_leaf * n_samples) 是对于每一个节点最小的样本数量。

• min_weight_fraction_leaf (float, default=0.0) – 在一个叶子节点需要的所有权重总和（所有的输入样本）的最小加权分数。如果sample_weight没有被提供时，样本具有同样的权重。

• max_features (int, float or {"sqrt", "log2"}, default=None) –

  寻找最佳划分时需要考虑的特征数量：

  • 如果是int，那么考虑 max_features 个特征在每个划分。

  • 如果是float，那么 max_features 是一个分数并且 int(max_features * n_features) 个特征在每个划分被考虑。

  • 如果是”sqrt”，那么 max_features=sqrt(n_features) 。

  • 如果是”log2”，那么 max_features=log2(n_features) 。

  • 如果是None，那么 max_features=n_features 。

• random_state (int) – 控制估计器的随机性。

• max_leaf_nodes (int, default to None) – 以最佳优先的方式使用 max_leaf_nodes 生成一棵树。 最佳节点被定义为杂质相对减少。 如果是None，那么叶子节点的数量没有限制。

• 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 被传入。

• categories (str, optional, default='auto') –

fit(data, outcome, treatment, adjustment=None, covariate=None, treat=None, control=None)

基于数据拟合模型来估计因果效应。

参数:

• data (pandas.DataFrame) – 输入样本，用于est_model估计因果效应和用于CEInterpreter拟合。

• outcome (list of str, optional) – 结果的名字。

• treatment (list of str, optional) – 治疗的名字。

• covariate (list of str, optional, default=None) – 协变量向量的名字。

• adjustment (list of str, optional, default=None) – 协变量向量的名字。注意我们可能只需要协变量集合，其通常是调整集合的一个子集。

• treat (int or list, optional, default=None) –

  如果只有一个离散的治疗，那么treat表示治疗组。如果有多个治疗组， 那么treat应该是一个str列表，其长度等于治疗的数量。比如，当有多个离散的治疗时，

  array([‘run’, ‘read’])

  意味着第一个治疗的治疗值为 ‘run’ 且第二个治疗为 ‘read’。

• control (int or list, optional, default=None) – 参考treat。

返回:

拟合的CausalTree

返回类型:

CausalTree的实例

estimate(data=None, quantity=None)

估计数据中治疗对结果的因果效应。

参数:

• data (pandas.DataFrame, optional, default=None) – 如果为None，数据将被设置为训练数据。

• quantity (str, optional, default=None) –

  返回的估计结果的选项。量的可能值包括：

  1. ’CATE’ : 估计器将会估计CATE；

  2. ’ATE’ : 估计器将会估计ATE；

  3. None : 估计器将会估计ITE或CITE。

返回:

量类型的估计的因果效应。

返回类型:

ndarray or float, optional

plot_causal_tree(feature_names=None, max_depth=None, class_names=None, label='all', filled=False, node_ids=False, proportion=False, rounded=False, precision=3, ax=None, fontsize=None)

绘制策略树。 显示的样本计数由任何的可能存在的sample_weights加权。 可视化自动适应轴的大小。 使用 plt.figure 的 figsize 或者 dpi 参数来控制生成的大小。

返回:

List containing the artists for the annotation boxes making up the tree.

返回类型:

annotations : list of artists

decision_path(*, data=None, wv=None)

返回决策路径。

参数:

• wv (numpy.ndarray, default=None) – 输入样本是一个ndarray。 如果是None，那么DataFrame的数据将会被用作输入样本。

• data (pandas.DataFrame, default=None) – 输入样本。数据必须包含用于训练模型的协变量的列。如果为None，训练数据将会被传入作为输入样本。

返回:

Return a node indicator CSR matrix，其中非零元素表示穿过节点的样本。

返回类型:

indicator : shape为(n_samples, n_nodes)的稀疏矩阵

apply(*, data=None, wv=None)

返回每个样本被预测为的叶子的索引。

参数:

• wv (numpy.ndarray, default=None) – 输入样本是一个ndarray。 如果是None，那么DataFrame的数据将会被用作输入样本。

• data (pandas.DataFrame, default=None) – 输入样本。数据必须包含用于训练模型的协变量的列。如果为None，训练数据将会被传入作为输入样本。

返回:

对于v中每个数据点v_i，返回v_i结束在的叶子的索引。叶子在 [0; self.tree_.node_count) 中编号，可能编号有间隙。

返回类型:

v_leaves : array-like of shape (n_samples, )

property feature_importance

返回:

按特征的归一化的总减少标准(Gini importance)。

返回类型:

ndarray of shape (n_features,)

工具变量

工具变量（IV）处理这样的情况：在存在未观察到的混淆变量，其同时影响治疗 \(X\) 和结果 \(Y\) 时，对因果效应进行估计。一组变量 \(Z\) 被称为一组 工具变量 如果对于 任何在 \(Z\) 中的 \(z\) 。

1. \(z\) 对 \(X\) 有因果效应。

2. \(z\) 对 \(Y\) 的因果效应完全由 \(X\) 调节。

3. 从 \(z\) 到 \(Y\) 没有后门路径。

在这样的情况下，我们必须首先找到IV（其可以通过使用 CausalModel 完成，参考 识别 ）。举个例子，变量 \(Z\) 在下面的图中 可以作为一个合理的IV，在存在未观察到的混淆变量 \(U\) 时估计 \(X\) 对 \(Y\) 的因果效应。

Causal graph with IV

YLearn关于IV实现两个不同的方法：deepiv [Hartford] ，对IV使用深度学习模型和IV的无参数模型 [Newey2002] 。

IV框架和问题设置

IV框架的目的是预测结果 \(y\) 的值当治疗 \(x\) 给定时。除此之外，还存在一些协变量向量 \(v\) 其同时影响 \(y\) 和 \(x\)。 还有一些未观察到的混淆因素 \(e\) 其潜在影响 \(y\) ，\(x\) 和 \(v\) 。因果问题的核心部分是估计因果量。

\[\mathbb{E}[y| do(x)]\]

下面的因果图，其中因果关系的集合由函数的集合决定

\[\begin{split}y & = f(x, v) + e\\ x & = h(v, z) + \eta\\ \mathbb{E}[e] & = 0.\end{split}\]

Causal graph with IV and both observed and unobserved confounders

IV框架通过做两步估计解决这个问题：

1. 估计 \(\hat{H}(z, v)\) 其捕获在 \(x\) 和变量 \((z, v)\) 之间的关系。

2. 用预测的结果 \(\hat{H}(z, v)\) 取代 \(x\) 给定 \((v, z)\) 。接着估计 \(\hat{G}(x, v)\) 来构建 \(y\) 和 \((x, v)\) 之间的关系。

最终的因果效应能够被计算。

IV Classes

无参工具变量

两阶段最小平方

当结果 \(y\) ，治疗 \(x\) 和协变量 covariate \(v\) 之间的关系假设是线性的，比如， [Angrist1996] ，

\[\begin{split}y & = \alpha x + \beta v + e \\ x & = \gamma z + \lambda v + \eta,\end{split}\]

那么IV框架变得直接：它首先给定 \(z\) 和 \(v\) 为 \(x\) 训练一个线性模型。接着，在第二阶段，它把 \(x\) 替换为估计值 \(\hat{x}\) 来 为 \(y\) 训练一个线性模型。这个过程被称为两阶段最小平方(2SLS)。

无参IV

移除关于变量之间关系的线性假设，无参IV能够取代线性回归，通过线性投影到一系列有名的基函数 [Newey2002] 。

这个方法和传统的2SLS类似且在找到 \(x\) ， \(v\) ，和 \(z\) 的新特征之后也由两个阶段组成，

\[\begin{split}\tilde{z}_d & = f_d(z)\\ \tilde{v}_{\mu} & = g_{\mu}(v),\end{split}\]

其由一些非线性函数（基函数） \(f_d\) 和 \(g_{\mu}\) 表示。在变换到新的空间后，我们接着

1. 拟合治疗模型：

\[\hat{x}(z, v, w) = \sum_{d, \mu} A_{d, \mu} \tilde{z}_d \tilde{v}_{\mu} + h(v, w) + \eta\]

2. 生成新的治疗x_hat，接着拟合结果模型

\[y(\hat{x}, v, w) = \sum_{m, \mu} B_{m, \mu} \psi_m(\hat{x}) \tilde{v}_{\mu} + k(v, w) + \epsilon.\]

最终因果效应能够被估计。举个例子，给定 \(v\) ，CATE被估计为

\[y(\hat{x_t}, v, w) - y(\hat{x_0}, v, w) = \sum_{m, \mu} B_{m, \mu} (\psi_m(\hat{x_t}) - \psi_m(\hat{x_0})) \tilde{v}_{\mu}.\]

YLearn在类 NP2SLS 中实现了这个过程。

类结构

class ylearn.estimator_model.iv.NP2SLS(x_model=None, y_model=None, random_state=2022, is_discrete_treatment=False, is_discrete_outcome=False, categories='auto')

参数:

• x_model (estimator, optional, default=None) – 为了建模治疗的机器学习模型。任何合理的x_model应该实现 fit 和 predict 方法，默认是None。

• y_model (estimator, optional, default=None) – 为了建模结果的机器学习模型。任何合理的y_model应该实现 fit 和 predict 方法，默认是None。

• random_state (int, default=2022) –

• is_discrete_treatment (bool, default=False) –

• is_discrete_outcome (bool, default=False) –

• categories (str, optional, default='auto') –

fit(data, outcome, treatment, instrument, is_discrete_instrument=False, treatment_basis=('Poly', 2), instrument_basis=('Poly', 2), covar_basis=('Poly', 2), adjustment=None, covariate=None, **kwargs)

拟合NP2SLS。注意当treatment_basis和instrument_basis都有degree 1的时候，我们实际在做2SLS。

参数:

• data (DataFrame) – 模型的训练数据集。Training data for the model.

• outcome (str or list of str, optional) – 结果的名字。

• treatment (str or list of str, optional) – 治疗的名字。

• covariate (str or list of str, optional, default=None) – 协变量向量的名字。

• instrument (str or list of str, optional) – 工具变量的名字。

• adjustment (str or list of str, optional, default=None) – 调整变量的名字。Names of the adjustment variables.

• treatment_basis (tuple of 2 elements, optional, default=('Poly', 2)) – 转换原来的治疗向量的选项。第一个元素表示转换的基函数，第二个表示degree。现在第一个元素只支持’Poly’。

• instrument_basis (tuple of 2 elements, optional, default=('Poly', 2)) – 转换原来的工具向量的选项。第一个元素表示转换的基函数，第二个表示degree。现在第一个元素只支持’Poly’。

• covar_basis (tuple of 2 elements, optional, default=('Poly', 2)) – 转换原来的协变量向量的选项。第一个元素表示转换的基函数，第二个表示degree。现在第一个元素只支持’Poly’。

• is_discrete_instrument (bool, default=False) –

estimate(data=None, treat=None, control=None, quantity=None)

估计数据中治疗对结果的因果效应。

参数:

• data (pandas.DataFrame, optional, default=None) – 如果为None，数据将会被设置为训练数据。

• quantity (str, optional, default=None) –

  返回的估计结果的选项。量的可能值包括：

  1. ’CATE’ : 估计器将会估计CATE；

  2. ’ATE’ : 估计器将会估计ATE；

  3. None : 估计器将会估计ITE或CITE。

• treat (float, optional, default=None) – 施加干涉时治疗的值。如果是None，那么treat将会被设置为1。

• control (float, optional, default=None) – 治疗的值，这样治疗的效果是 \(y(do(x=treat)) - y (do(x = control))\) 。

返回:

用量的类型估计的因果效应。

返回类型:

ndarray or float, optional

effect_nji(data=None)

用不同的治疗值计算因果效应。

参数:

data (pandas.DataFrame, optional, default=None) – 给估计器估计因果效应的测试数据，注意如果data是None，估计器将会使用训练数据。

返回:

用不同的治疗值的因果效应。

返回类型:

ndarray

例子

pass

DeepIV

DeepIV，开发于 [Hartford] ，是一个在存在未观察到的混淆因素的情况下，估计治疗和结果变量之间因果效应的方法。当工具变量（IV）存在时，它应用深度 学习方法来准确表征治疗和结果之间的因果关系。由于深度学习模型的表示力，它没有假设因果关系的任何参数形式。

训练一个DeepIV有两步，类似于正常IV方法的估计过程。具体的，我们

1. 训练一个神经网络，我们将其称为 治疗网络 \(F(Z, V)\) ，来估计治疗 \(X\) 的分布，给定IV \(Z\) 和协变量 \(V\) 。

2. 训练另一个神经网络，我们将其称为 结果网络 \(H(X, V)\) ，来估计结果 \(Y\) 给定治疗 \(X\) 和协变量 \(V\)。

最终的因果效应接着可以被结果网络 \(H(X, W)\) 估计。举个例子，CATE \(\tau(v)\) 被这样估计

\[\tau(v) = H(X=x_t, V=v) - H(X=x_0, W=v).\]

类结构

class ylearn.estimator_model.deepiv.DeepIV(x_net=None, y_net=None, x_hidden_d=None, y_hidden_d=None, num_gaussian=5, is_discrete_treatment=False, is_discrete_outcome=False, is_discrete_instrument=False, categories='auto', random_state=2022)

参数:

• x_net (ylearn.estimator_model.deepiv.Net, optional, default=None) – 表示对于连续的治疗的混合密度网络或者是对于离散的治疗的常见的分类网络。如果是 None，默认的神经网络将被使用。参考 ylearn.estimator_model.deepiv.Net 。

• y_net (ylearn.estimator_model.deepiv.Net, optional, default=None) – 表示结果网络。如果是None，默认的神经网络将被使用。

• x_hidden_d (int, optional, default=None) – DeepIV默认的x_net的隐藏层的维度。

• y_hidden_d (int, optional, default=None) – DeepIV默认的y_net的隐藏层的维度。

• is_discrete_treatment (bool, default=False) –

• is_discrete_instrument (bool, default=False) –

• is_discrete_outcome (bool, default=False) –

• num_gaussian (int, default=5) – 使用混合密度网络时的高斯数，当治疗是离散的时候，其将被直接忽略。

• random_state (int, default=2022) –

• categories (str, optional, default='auto') –

fit(data, outcome, treatment, instrument=None, adjustment=None, approx_grad=True, sample_n=None, y_net_config=None, x_net_config=None, **kwargs)

训练DeepIV模型。

参数:

• data (pandas.DataFrame) – 训练估计器的训练数据集。

• outcome (list of str, optional) – 结果的名字。

• treatment (list of str, optional) – 治疗的名字。

• instrument (list of str, optional) – IV的名字。DeepIV必须提供。

• adjustment (list of str, optional, default=None) – 保证无混淆的调整集的名字，在当前版本其也可以被看作协变量。

• approx_grad (bool, default=True) – 是否使用近似梯度，和 [Hartford] 中一样。

• sample_n (int, optional, default=None) – 当使用approx_grad技术时，新样本的次数。

• x_net_config (dict, optional, default=None) – x_net的配置。

• y_net_config (dict, optional, default=None) – y_net的配置。

返回:

训练的DeepIV模型

返回类型:

DeepIV的实例

estimate(data=None, treat=None, control=None, quantity=None, marginal_effect=False, *args, **kwargs)

用量的类型估计因果效应。

参数:

• data (pandas.DataFrame, optional, default=None) – 测试数据。注意被设置为None，模型会使用训练数据。

• quantity (str, optional, default=None) –

  返回的估计结果的选项。量的可能值包括：

  1. ’CATE’ : 估计器将会估计CATE；

  2. ’ATE’ : 估计器将会估计ATE；

  3. None : 估计器将会估计ITE或CITE。

• treat (int, optional, default=None) – 治疗的值，默认是None。如果是None，那么模型会把treat设置为1。

• control (int, optional, default=None) – 控制的值，默认是None。如果是None，那么模型会把control设置为1。

返回:

估计的因果效应

返回类型:

torch.tensor

effect_nji(data=None)

用不同的治疗值计算因果效应。

返回:

不同治疗值的因果效应。

返回类型:

ndarray

comp_transormer(x, categories='auto')

把离散的治疗正确转变为独热向量。

参数:

• x (numpy.ndarray, shape (n, x_d)) – 包含治疗变量信息的数组。

• categories (str or list, optional, default='auto') –

返回:

转变的独热向量。

返回类型:

numpy.ndarray

给估计的因果效应打分

用于估计因果效应的估计器模型不能被简单的评价，因为事实上真实的效应不能被直接观察到。这和平常的，结果可以用比如说损失函数的值简单评价的机器学习任务不同。

[Schuler] 的作者提出了一个框架，一个由 [Nie] 表明的模式，来评估不同的估计器模型估计的因果效应。粗略的说，这个框架是双机器学习方法的直接应用。 具体的说，对于一个因果效应模型 ce_model() （在训练集上训练好的），等待被评价，我们

1. 在通常和训练集不同的验证集中，训练一个模型 y_model() 来估计结果 \(y\) 和一个 x_model() 来估计治疗 \(x\) ；

2. 在验证集 \(D_{val}\) 中，令 \(\tilde{y}\) 和 \(\tilde{x}\) 表示差

   \[\begin{split}\tilde{y} & = y - \hat{y}(v), \\ \tilde{x} & = x - \hat{x}(v)\end{split}\]

   其中 \(\hat{y}\) 和 \(\hat{x}\) 是在 \(D_{val}\) 中估计的结果和治疗基于协变量 \(v\) 。 此外，令

   \[\tau(v)\]

   表明在 \(D_{val}\) 中由 ce_model() 估计的因果效应，那么对于ce_model因果效应的度量标准这样计算。

   \[E_{V}[(\tilde{y} - \tilde{x} \tau(v))^2].\]

例子

from sklearn.ensemble import RandomForestRegressor

from ylearn.exp_dataset.exp_data import single_binary_treatment
from ylearn.estimator_model.meta_learner import TLearner

train, val, te = single_binary_treatment()
rloss = RLoss(
    x_model=RandomForestClassifier(),
    y_model=RandomForestRegressor(),
    cf_fold=1,
    is_discrete_treatment=True
)
rloss.fit(
    data=val,
    outcome=outcome,
    treatment=treatment,
    adjustment=adjustment,
    covariate=covariate,
)

est = TLearner(model=RandomForestRegressor())
est.fit(
    data=train,
    treatment=treatment,
    outcome=outcome,
    adjustment=adjustment,
    covariate=covariate,
)

rloss.score(est)

>>> 0.20451977

类结构

class ylearn.estimator_model.effect_score.RLoss(x_model, y_model, yx_model=None, cf_fold=1, adjustment_transformer=None, covariate_transformer=None, random_state=2022, is_discrete_treatment=False, categories='auto')

参数:

• x_model (estimator, optional) – 拟合x的机器学习模型。任何这样的模型应该实现 fit() 和 predict`() （也 predict_proba() 如果x是离散的）方法。

• y_model (estimator, optional) – 为了建模结果训练的机器学习模型。任何合理的y_model应该实现 fit() 和 predict() 方法。

• yx_model (estimator, optional) – 用于拟合基于x的残差的y的残差的机器学习模型。 当前版本只支持线性回归模型。

• cf_fold (int, default=1) – 在第一阶段执行交叉拟合的折的数量。

• adjustment_transformer (transormer, optional, default=None,) – 调整变量的Transformer，其可以被用于生成调整变量的新特征。

• covariate_transformer (transormer, optional, default=None,) – 协变量的Transformer，其可以被用于生成协变量的新特征。

• random_state (int, default=2022) –

• is_discrete_treatment (bool, default=False) – 如果治疗变量是离散的，把这个设为True。

• categories (str, optional, default='auto') –

fit(data, outcome, treatment, adjustment=None, covariate=None, combined_treatment=True, **kwargs)

拟合RLoss估计器模型。注意训练一个DML有两个阶段，其中我们在 _fit_1st_stage() 和 _fit_2nd_stage() 中实现它们。

参数:

• data (pandas.DataFrame) – 训练估计器的训练数据集。

• outcome (list of str, optional) – 结果的名字。

• treatment (list of str, optional) – 治疗的名字。

• adjustment (list of str, optional, default=None) – 保证无混淆的调整集的名字。

• covariate (list of str, optional, default=None) – 协变量的名字。

• combined_treatment (bool, default=True) –

  当combined_treatment被设置为True时，那么如果有多个治疗，我们能使用combined_treatment技术 来转变多个离散分类任务成为一个离散分类任务，比如，如果有两个不同的二元治疗：

  \[\begin{split}treatment_1 &: x_1 | x_1 \in \{'sleep', 'run'\}, \\ treatment_2 &: x_2 | x_2 \in \{'study', 'work'\},\end{split}\]

  那么我们能够转变这两个二元分类任务成为一个有四个不同类的分类任务。

  \[treatment: x | x \in \{0, 1, 2, 3\},\]

  其中，比如，1表示(‘sleep’ and ‘study’)。

返回:

RLoss的实例

返回类型:

拟合的RLoss模型用于在验证集中评价其他的估计模型。

score(test_estimator, treat=None, control=None)

用量的类型估计因果效应。

参数:

• data (pandas.DataFrame, optional, default=None) – 用于估计器估计因果效应的测试数据，注意如果data是None，估计器直接估计训练数据中所有的量。

• treat (float or numpy.ndarray, optional, default=None) – 在单个离散治疗的情况下，treat应该是所有可能的治疗值之一的int或者str， 其表示预期的治疗值，在有多个离散治疗的情况下，treat应该是一个列表或者ndarray，其中treat[i]表示第i个预期的治疗值。例如， 当有多个离散治疗，array([‘run’, ‘read’])意味着第一个治疗的治疗值是 ‘run’ ，第二个治疗是 ‘read’ 。在连续治疗值的情况下，治疗应该是一个float或者ndarray。

• control (float or numpy.ndarray, optional, default=None) – 这和treat的情况相似。

返回:

test_estimator的分数

返回类型:

float

effect_nji(data=None)

用不同的治疗值计算因果效应。

参数:

data (pandas.DataFrame, optional, default=None) – 用于估计器估计因果效应的测试数据，注意如果data是None，估计器会使用训练数据。

返回:

不同治疗值的因果效应。

返回类型:

ndarray

comp_transormer(x, categories='auto')

把离散的治疗正确转变为独热向量。

参数:

• x (numpy.ndarray, shape (n, x_d)) – 包含治疗变量信息的数组。

• categories (str or list, optional, default='auto') –

返回:

转变的独热向量。

返回类型:

numpy.ndarray

对

\[\mathbb{E}[F_2(x_1, W, \eta) - F_2(x_0, W, \eta)]\]

在ATE中和

\[\mathbb{E}[F_2(x_1, W, V, \eta) - F_2(x_0, W, V, \eta)]\]

在CATE中的估计将会成为YLearn中不同的合适的 估计器模型 的任务。YLearn中概念 EstimatorModel 就是为这个目的设计的

一个常见的 EstimatorModel 应该有如下结构：

class BaseEstModel:
    """
    Base class for various estimator model.

    Parameters
    ----------
    random_state : int, default=2022
    is_discrete_treatment : bool, default=False
        Set this to True if the treatment is discrete.
    is_discrete_outcome : bool, default=False
        Set this to True if the outcome is discrete.
    categories : str, optional, default='auto'

    """
    def fit(
        self,
        data,
        outcome,
        treatment,
        **kwargs,
    ):
        """Fit the estimator model.

        Parameters
        ----------
        data : pandas.DataFrame
            The dataset used for training the model

        outcome : str or list of str, optional
            Names of the outcome variables

        treatment : str or list of str
            Names of the treatment variables

        Returns
        -------
        instance of BaseEstModel
            The fitted estimator model.
        """

    def estimate(
        self,
        data=None,
        quantity=None,
        **kwargs
    ):
        """Estimate the causal effect.

        Parameters
        ----------
        data : pd.DataFrame, optional
            The test data for the estimator to evaluate the causal effect, note
            that the estimator directly evaluate all quantities in the training
            data if data is None, by default None

        quantity : str, optional
            The possible values of quantity include:
                'CATE' : the estimator will evaluate the CATE;
                'ATE' : the estimator will evaluate the ATE;
                None : the estimator will evaluate the ITE or CITE, by default None

        Returns
        -------
        ndarray
            The estimated causal effect with the type of the quantity.
        """

    def effect_nji(self, data=None, *args, **kwargs):
        """Return causal effects for all possible values of treatments.

        Parameters
        ----------
        data : pd.DataFrame, optional
            The test data for the estimator to evaluate the causal effect, note
            that the estimator directly evaluate all quantities in the training
            data if data is None, by default None
        """

用法

可以在以下过程中应用任何 EstimatorModel

1. 对于 pandas.DataFrame 形式的数据，找到 治疗 ， 结果 ， 调整 ，和 协变量 的名字。

2. 把数据和治疗，结果，调整集合，协变量的名字传入 EstimatorModel 的 fit() 方法并调用它。

3. 调用 estimate() 方法在测试数据上使用拟合的 EstimatorModel。

因果发现：探索数据中的因果结构

No-Tears 算法

No-Tears 揭示了有向无环图 (DAG) 结构的问题可以通过在具有强制执行无环条件的约束的实矩阵上制定连续优化问题来解决 [Zheng2018]. 具体地说，对于给定的向量 \(x \in \mathbb{R}^d\) ，存在一个矩阵 \(V\) ，满足某个噪声向量 \(x = Vx + \eta\) ，使 :math:`eta in mathbb{R}^d`的优化问题可以描述如下:

\[\begin{split}\min_{W \in \mathbb{R}^{d\times d}} & F(W) \\ s.t. \quad & h(W) = 0,\end{split}\]

其中， \(F(W)\) 是一个衡量 \(\|x - Wx\|\) 的连续方程；

此外，

\[h(W) = tr\left( e^{W \circ W} \right)\]

其中 \(\circ\) 是阿达玛乘积（Hadamard product）。整个公式可以通过一些优化技术来解决，比如梯度下降。

NO-TEARS 算法的类是 CausalDiscovery.

举例

import pandas as pd

from ylearn.exp_dataset.gen import gen
from ylearn.causal_discovery import CausalDiscovery

X = gen()
X = pd.DataFrame(X, columns=[f'x{i}' for i in range(X.shape[1])])
cd = CausalDiscovery(hidden_layer_dim=[3])
est = cd(X, threshold=0.01, return_dict=True)

print(est)

>>> OrderedDict([('x0', []), ('x1', ['x0', 'x2', 'x3', 'x4']), ('x2', ['x0']), ('x3', ['x0', 'x2', 'x4']), ('x4', ['x0', 'x2'])])

在因果推断任务中，首先要找到潜在的因果关系，即所谓的因果结构。理论上，这些关系能够通过设计随机实验或者施加干涉被揭露。 然而，现实中这些方法的代价过于昂贵，有些甚至不可行。因此，近年来许多通过直接利用观测数据来分析因果结构的技术被提出来，如 PC算法(参考 [Spirtes2001]) ，No-Tears算法(参考 [Zheng2018]）。这些技术称为**因果发现** 。

YLearn因果发现实现了一个基于分数的 No-Tears 算法。之后会陆续加入更多的方法。

策略：选择最佳选项

在诸如策略评估的任务中，比如， [Athey2020] ，除了因果效应，我们可能也对其他的问题感兴趣。例如:是否一个样例应该被分配一个治疗方案，如果答案是肯定的，哪一个选项 是所有可能的治疗值中最好的。YLearn为这样的目的实现了 PolicyTree 。给定一个训练好的估计器模型或者估计的因果效应，它通过构建一个 目标是为每一个样例最大化因果效应的决策树模型，为每一个样例找到最优的策略。

训练树的准则是

\[S = \sum_i\sum_k g_{ik}e_{ki}\]

其中 \(g_{ik} = \phi(v_i)_k\) ，并且有 \(\phi: \mathbb{R}^D \to \mathbb{R}^K\) 是一个映射，从 \(v_i\in \mathbb{R}^D\) 到 一个仅有一个非零元素的在 \(\mathbb{R}^K\) 中的基向量，并且 \(e_{ki}\) 表明 对样本 \(i\) 采取治疗 \(k\)-th 值的因果效应。

参见

sklearn中 BaseDecisionTree 。

注意：可以使用 PolicyInterpreter 来解释策略模型的结果。

例子

import numpy as np

from ylearn.policy.policy_model import PolicyTree
from ylearn.utils._common import to_df

# build dataset
v = np.random.normal(size=(1000, 10))
y = np.hstack([v[:, [0]] < 0, v[:, [0]] > 0])

data = to_df(v=v)
covariate = data.columns

est = PolicyTree(criterion='policy_reg')
est.fit(data=data, covariate=covariate, effect_array=y.astype(float))

>>> 06-23 14:53:14 I ylearn.p.policy_model.py 452 - Start building the policy tree with criterion PRegCriteria
>>> 06-23 14:53:14 I ylearn.p.policy_model.py 468 - Building the policy tree with splitter BestSplitter
>>> 06-23 14:53:14 I ylearn.p.policy_model.py 511 - Building the policy tree with builder DepthFirstTreeBuilder
>>> <ylearn.policy.policy_model.PolicyTree at 0x7ff1ee5f2eb0>

Class Structures

class ylearn.policy.policy_model.PolicyTree(*, criterion='policy_reg', splitter='best', max_depth=None, min_samples_split=2, min_samples_leaf=1, random_state=2022, max_leaf_nodes=None, max_features=None, min_impurity_decrease=0.0, ccp_alpha=0.0, min_weight_fraction_leaf=0.0)

参数:

• criterion ({'policy_reg'}, default="'policy_reg'") –

  The function to measure the quality of a split. The criterion for training the tree is (in the Einstein notation)

  \[S = \sum_i g_{ik} e^k_{i},\]

  where \(g_{ik} = \phi(v_i)_k\) is a map from the covariates, \(v_i\), to a basis vector which has only one nonzero element in the \(R^k\) space. By using this criterion, the aim of the model is to find the index of the treatment which will render the max causal effect, i.e., finding the optimal policy.

• splitter ({"best", "random"}, default="best") – The strategy used to choose the split at each node. Supported strategies are “best” to choose the best split and “random” to choose the best random split.

• max_depth (int, default=None) – The maximum depth of the tree. If None, then nodes are expanded until all leaves are pure or until all leaves contain less than min_samples_split samples.

• min_samples_split (int or float, default=2) – The minimum number of samples required to split an internal node: - If int, then consider min_samples_split as the minimum number. - If float, then min_samples_split is a fraction and ceil(min_samples_split * n_samples) are the minimum number of samples for each split.

• min_samples_leaf (int or float, default=1) –

  The minimum number of samples required to be at a leaf node. A split point at any depth will only be considered if it leaves at least min_samples_leaf training samples in each of the left and right branches. This may have the effect of smoothing the model, especially in regression.

  • If int, then consider min_samples_leaf as the minimum number.

  • If float, then min_samples_leaf is a fraction and ceil(min_samples_leaf * n_samples) are the minimum number of samples for each node.

• min_weight_fraction_leaf (float, default=0.0) – The minimum weighted fraction of the sum total of weights (of all the input samples) required to be at a leaf node. Samples have equal weight when sample_weight is not provided.

• max_features (int, float or {"sqrt", "log2"}, default=None) –

  The number of features to consider when looking for the best split:

  • If int, then consider max_features features at each split.

  • If float, then max_features is a fraction and int(max_features * n_features) features are considered at each split.

  • If “sqrt”, then max_features=sqrt(n_features).

  • If “log2”, then max_features=log2(n_features).

  • If None, then max_features=n_features.

• random_state (int) – Controls the randomness of the estimator.

• max_leaf_nodes (int, default to None) – Grow a tree with max_leaf_nodes in best-first fashion. Best nodes are defined as relative reduction in impurity. If None then unlimited number of leaf nodes.

• min_impurity_decrease (float, default=0.0) –

  A node will be split if this split induces a decrease of the impurity greater than or equal to this value. The weighted impurity decrease equation is the following

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

  where N is the total number of samples, N_t is the number of samples at the current node, N_t_L is the number of samples in the left child, and N_t_R is the number of samples in the right child. N, N_t, N_t_R and N_t_L all refer to the weighted sum, if sample_weight is passed.

fit(data, covariate, *, effect=None, effect_array=None, est_modle=None, sample_weight=None)

Fit the PolicyInterpreter model to interpret the policy for the causal effect estimated by the est_model on data. One has several options for passing the causal effects, which usually is a vector of (n, j, i) where n is the number of the examples, j is the dimension of the outcome, and i is the number of possible treatment values or the dimension of the treatment:

1. Only pass est_model. Then est_model will be used to generate the causal effects.

2. Only pass effect_array which will be set as the causal effects and effect and est_model will be ignored.

3. Only pass effect. This usually is a list of names of the causal effect in data which will then be used as the causal effects for training the model.

参数:

• data (pandas.DataFrame) – The input samples for the est_model to estimate the causal effects and for the CEInterpreter to fit.

• est_model (estimator_model) – est_model should be any valid estimator model of ylearn which was already fitted and can estimate the CATE. If effect=None and effect_array=None, then est_model can not be None and the causal effect will be estimated by the est_model.

• covariate (list of str, optional, default=None) – Names of the covariate.

• effect (list of str, optional, default=None) – Names of the causal effect in data. If effect_array is not None, then effect will be ignored.

• effect_array (numpy.ndarray, default=None) – The causal effect that waited to be fitted by PolicyTree. If this is not provided and est_model is None, then effect can not be None.

返回:

Fitted PolicyModel

返回类型:

instance of PolicyModel

predict_ind(data=None)

Estimate the optimal policy for the causal effects of the treatment on the outcome in the data, i.e., return the index of the optimal treatment.

参数:

data (pandas.DataFrame, optional, default=None) – The test data in the form of the DataFrame. The model will only use this if v is set as None. In this case, if data is also None, then the data used for trainig will be used.

返回:

The index of the optimal treatment dimension.

返回类型:

ndarray or int, optional

predict_opt_effect(data=None)

Estimate the value of the optimal policy for the causal effects of the treatment on the outcome in the data, i.e., return the value of the causal effects when taking the optimal treatment.

参数:

data (pandas.DataFrame, optional, default=None) – The test data in the form of the DataFrame. The model will only use this if v is set as None. In this case, if data is also None, then the data used for trainig will be used.

返回:

The estimated causal effect with the optimal treatment value.

返回类型:

ndarray or float, optional

apply(*, v=None, data=None)

Return the index of the leaf that each sample is predicted as.

参数:

• v (numpy.ndarray, default=None) – The input samples as an ndarray. If None, then the DataFrame data will be used as the input samples.

• data (pandas.DataFrame, default=None) – The input samples. The data must contains columns of the covariates used for training the model. If None, the training data will be passed as input samples.

返回:

For each datapoint v_i in v, return the index of the leaf v_i ends up in. Leaves are numbered within [0; self.tree_.node_count), possibly with gaps in the numbering.

返回类型:

v_leaves : array-like of shape (n_samples, )

decision_path(*, v=None, data=None)

Return the decision path.

参数:

• v (numpy.ndarray, default=None) – The input samples as an ndarray. If None, then the DataFrame data will be used as the input samples.

• data (pandas.DataFrame, default=None) – The input samples. The data must contains columns of the covariates used for training the model. If None, the training data will be passed as input samples.

返回:

Return a node indicator CSR matrix where non zero elements indicates that the samples goes through the nodes.

返回类型:

indicator : sparse matrix of shape (n_samples, n_nodes)

get_depth()

Return the depth of the policy tree. The depth of a tree is the maximum distance between the root and any leaf.

返回:

The maximum depth of the tree.

返回类型:

int

get_n_leaves()

Return the number of leaves of the policy tree.

返回:

Number of leaves

返回类型:

int

property feature_importance

Return the feature importances. The importance of a feature is computed as the (normalized) total reduction of the criterion brought by that feature. It is also known as the Gini importance. Warning: impurity-based feature importances can be misleading for high cardinality features (many unique values). See sklearn.inspection.permutation_importance() as an alternative.

返回:

Normalized total reduction of criteria by feature (Gini importance).

返回类型:

ndarray of shape (n_features,)

property n_features_

返回:

number of features

返回类型:

int

plot(*, feature_names=None, max_depth=None, class_names=None, label='all', filled=False, node_ids=False, proportion=False, rounded=False, precision=3, ax=None, fontsize=None)

Plot the PolicyTree. The sample counts that are shown are weighted with any sample_weights that might be present. The visualization is fit automatically to the size of the axis. Use the figsize or dpi arguments of plt.figure to control the size of the rendering.

返回:

List containing the artists for the annotation boxes making up the tree.

返回类型:

annotations : list of artists

解释器：解释因果效应

为了解释由不同的估计模型估计的因果效应，当前版本的YLearn为了因果效应的可解释性实现了树模型 CEInterpreter 并且为了策略估计的可解释性 实现了 PolicyInterpreter 。

CEInterpreter

对于由一个估计模型估计的CATE \(\tau(v)\) ，比如， 双机器学习模型， CEInterpreter 解释 由构建的一个用于建模 \(\tau(v)\) 和谐变量 \(v\) 之间关系的决策树得到的结果。然后能够使用拟合树模型的决策规则 来分析 \(\tau(v)\)。

类结构

class ylearn.effect_interpreter.ce_interpreter.CEInterpreter(*, criterion='squared_error', splitter='best', max_depth=None, min_samples_split=2, min_samples_leaf=1, random_state=2022, max_leaf_nodes=None, max_features=None, min_impurity_decrease=0.0, min_weight_fraction_leaf=0.0, ccp_alpha=0.0, categories='auto')

参数:

• criterion ({"squared_error", "friedman_mse", "absolute_error", "poisson"}, default="squared_error") – 用于测量划分的质量的函数。 支持的准则为”squared_error”用于均方误差，其等价于把方差减少作为特征选择的准则并且使用每一个终端节点的平均值最小化L2误差。”friedman_mse”为 潜在的划分用均方误差和Friedman的改进分数。”absolute_error”用于平均绝对误差，其通过使用每一个终端节点的中位数最小化L1误差。”poisson”使用减少泊松偏差来寻找划分。

• splitter ({"best", "random"}, default="best") – 用于在每个节点选择划分的策略。支持的策略”best”用于选择最佳划分，”random”用于选择最佳随机划分。

• max_depth (int, default=None) – 树的最大深度。如果为None，那么节点可以一直扩展直到所有的叶子都是纯的或者所有的叶子都包含小于min_samples_split个样本。

• min_samples_split (int or float, default=2) – 划分内部节点所需要的最小的样本数量： - 如果是int，那么考虑 min_samples_split 为最小数量。 - 如果是float, 那么 min_samples_split 是一个分数并且 ceil(min_samples_split * n_samples) 是对于每一个划分最小的样本数量。

• min_samples_leaf (int or float, default=1) –

  在一个叶子节点需要的最小的样本数量。 一个在任意深度的划分点仅当它留下至少 min_samples_leaf 训练样本在它的左右分支时会被考虑。这可能有平滑模型的作用，尤其是在回归中。

  • 如果是int, 那么考虑 min_samples_leaf 为最小数量。

  • 如果是float, 那么 min_samples_leaf 是一个分数并且 ceil(min_samples_leaf * n_samples) 是对于每一个节点最小的样本数量。

• min_weight_fraction_leaf (float, default=0.0) – 在一个叶子节点需要的所有权重总和（所有的输入样本）的最小加权分数。如果sample_weight没有被提供时，样本具有同样的权重。

• max_features (int, float or {"sqrt", "log2"}, default=None) –

  寻找最佳划分时需要考虑的特征数量：

  • 如果是int，那么考虑 max_features 个特征在每个划分。

  • 如果是float，那么 max_features 是一个分数并且 int(max_features * n_features) 个特征在每个划分被考虑。

  • 如果是”sqrt”，那么 max_features=sqrt(n_features) 。

  • 如果是”log2”，那么 max_features=log2(n_features) 。

  • 如果是None，那么 max_features=n_features 。

• random_state (int) – 控制估计器的随机性。

• max_leaf_nodes (int, default to None) – 以最佳优先的方式使用 max_leaf_nodes 生成一棵树。 最佳节点被定义为杂质相对减少。 如果是None，那么叶子节点的数量没有限制。

• 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 被传入。

fit(data, est_model, **kwargs)

拟合CEInterpreter模型来解释基于数据和est_model估计的因果效应。

参数:

• data (pandas.DataFrame) – 输入样本，用于est_model估计因果效应和用于CEInterpreter拟合。

• est_model (estimator_model) – est_model应该为ylearn的任何合理的估计器模型且已经拟合过了并且能够估计CATE。

返回:

Fitted CEInterpreter

返回类型:

CEInterpreter的实例

interpret(*, v=None, data=None)

在测试数据中解释拟合的模型。

参数:

• v (numpy.ndarray, optional, default=None) – ndarray形式的测试协变量。如果这被给出，那么数据将会被忽略并且模型会使用这个作为测试数据。

• data (pandas.DataFrame, optional, default=None) – DataFrame形式的测试数据。模型将仅使用这个如果v被设置为None。在这种情况下，如果数据也是None，那么训练的数据将会被使用。

返回:

对所有的样例解释的结果。

返回类型:

dict

plot(*, feature_names=None, max_depth=None, class_names=None, label='all', filled=False, node_ids=False, proportion=False, rounded=False, precision=3, ax=None, fontsize=None)

绘制拟合的树模型。 显示的样本计数由任何的可能存在的sample_weights加权。 可视化自动适应轴的大小。 使用 plt.figure 的 figsize 或者 dpi 参数来控制生成的大小。

返回:

List containing the artists for the annotation boxes making up the tree.

返回类型:

annotations : list of artists

例子

pass

PolicyInterpreter

PolicyInterpreter 能够被用于解释由一个实例 PolicyTree 返回的策略。通过给不同的样例分配不同的策略， 它的目标是最大化一个子群的因果效应并把它们与那些有负的因果效应的分开。

例子

我们构建了一个数据集，其中给定协变量 \(v\) 和二元的治疗方案 \(x\)， 接受治疗的因果效应 \(y\) 是正的如果 \(v\) 的第一个纬度是正的，反之是负的。 PolicyInterpreter 的目标是帮助每个个体决定是否采取治疗，等价于因果效应是否是正的。

import numpy as np
from ylearn.utils import to_df

# build dataset
v = np.random.normal(size=(1000, 10))
y = np.hstack([v[:, [0]] < 0, v[:, [0]] > 0])

data = to_df(v=v)
covariate = data.columns

# train the `PolicyInterpreter`
from ylearn.effect_interpreter.policy_interpreter import PolicyInterpreter
pit = PolicyInterpreter(max_depth=2)
pit.fit(data=data, est_model=None, covariate=covariate, effect_array=y.astype(float))

pit_result = pit.interpret()

>>> 06-02 17:06:49 I ylearn.p.policy_model.py 448 - Start building the policy tree with criterion PRegCriteria
>>> 06-02 17:06:49 I ylearn.p.policy_model.py 464 - Building the policy tree with splitter BestSplitter
>>> 06-02 17:06:49 I ylearn.p.policy_model.py 507 - Building the policy tree with builder DepthFirstTreeBuilder

解释的结果:

for i in range(57, 60):
    print(f'the policy for the sample {i}\n --------------\n' + pit_result[f'sample_{i}'] + '\n')

>>> the policy for the sample 57
>>> --------------
>>> decision node 0: (covariate [57, 0] = -0.0948629081249237) <= 8.582111331634223e-05
>>> decision node 1: (covariate [57, 8] = 1.044342041015625) > -2.3793461322784424
>>> The recommended policy is treatment 0 with value 1.0

>>> the policy for the sample 58
>>> --------------
>>> decision node 0: (covariate [58, 0] = 0.706959068775177) > 8.582111331634223e-05
>>> decision node 4: (covariate [58, 5] = 0.9160318374633789) > -2.575441598892212
>>> The recommended policy is treatment 1 with value 1.0

类结构

class ylearn.interpreter.policy_interpreter.PolicyInterpreter(*, criterion='policy_reg', splitter='best', max_depth=None, min_samples_split=2, min_samples_leaf=1, random_state=2022, max_leaf_nodes=None, max_features=None, min_impurity_decrease=0.0, ccp_alpha=0.0, min_weight_fraction_leaf=0.0)

参数:

• criterion ({'policy_reg'}, default="'policy_reg'") –

  该函数用于测量划分的质量。训练树的准则是(使用Einstein notation)

  \[S = \sum_i g_{ik} y^k_{i},\]

  其中， \(g_{ik} = \phi(v_i)_k\) 是一个映射，从协变量， \(v_i\)，到一个有且仅有一个非零元素的在 \(R^k\) 空间中的基向量。 通过使用这个准则，模型的目标是找到能够生成最大因果效应的治疗的索引，等价于找到最优的策略。

• splitter ({"best", "random"}, default="best") – 用于选择每个节点划分的策略。支持的策略是”best”来选择最优划分和”random”来选择最优随机划分。

• max_depth (int, default=None) – 树的最大深度。如果为None，那么节点一直扩展直到所有的叶子都是纯的或者所有的叶子都包含小于min_samples_split个样本。

• min_samples_split (int or float, default=2) – 划分内部节点所需要的最小的样本数量： - 如果是int，那么考虑 min_samples_split 为最小数量。 - 如果是float, 那么 min_samples_split 是一个分数并且 ceil(min_samples_split * n_samples) 是对于每一个划分最小的样本数量。

• min_samples_leaf (int or float, default=1) –

  在一个叶子节点需要的最小的样本数量。 一个在任意深度的划分点仅当它留下至少 min_samples_leaf 训练样本在它的左右分支时会被考虑。这可能有平滑模型的作用，尤其是在回归中。

  • 如果是int, 那么考虑 min_samples_leaf 为最小数量。

  • 如果是float, 那么 min_samples_leaf 是一个分数并且 ceil(min_samples_leaf * n_samples) 是对于每一个节点最小的样本数量。

• min_weight_fraction_leaf (float, default=0.0) – 在一个叶子节点需要的所有权重总和（所有的输入样本）的最小加权分数。如果sample_weight没有被提供时，样本具有同样的权重。

• max_features (int, float or {"sqrt", "log2"}, default=None) –

  寻找最佳划分时需要考虑的特征数量：

  • 如果是int，那么考虑 max_features 个特征在每个划分。

  • 如果是float，那么 max_features 是一个分数并且 int(max_features * n_features) 个特征在每个划分被考虑。

  • 如果是”sqrt”，那么 max_features=sqrt(n_features) 。

  • 如果是”log2”，那么 max_features=log2(n_features) 。

  • 如果是None，那么 max_features=n_features 。

• random_state (int) – 控制估计器的随机性。

• max_leaf_nodes (int, default to None) – 以最佳优先的方式使用 max_leaf_nodes 生成一棵树。 最佳节点被定义为杂质相对减少。 如果是None，那么叶子节点的数量没有限制。

• 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 被传入。

fit(data, est_model, *, covariate=None, effect=None, effect_array=None)

拟合PolicyInterpreter模型来解释基于数据和est_model估计的因果效应的策略。

参数:

• data (pandas.DataFrame) – 输入样本，用于est_model估计因果效应和用于CEInterpreter拟合。

• est_model (estimator_model) – est_model应该为ylearn的任何合理的估计器模型且已经拟合过了并且能够估计CATE。

• covariate (list of str, optional, default=None) – 协变量的名字。

• effect (list of str, optional, default=None) – 在 data 中因果效应的名字。如果 effect_array 不是None，那么 effect 将会被忽略。

• effect_array (numpy.ndarray, default=None) – 等待被 PolicyInterpreter 解释的因果效应。如果这没有被提供，那么 effect 不能是None.

返回:

Fitted PolicyInterpreter

返回类型:

PolicyInterpreter的实例

interpret(*, data=None)

在测试数据中解释拟合的模型。

参数:

data (pandas.DataFrame, optional, default=None) – DataFrame形式的测试数据。模型将仅使用这个如果v被设置为None。在这种情况下，如果数据也是None，那么训练的数据将会被使用。

返回:

对所有的样例解释的结果。

返回类型:

dict

plot(*, feature_names=None, max_depth=None, class_names=None, label='all', filled=False, node_ids=False, proportion=False, rounded=False, precision=3, ax=None, fontsize=None)

绘制树模型。 显示的样本计数由任何的可能存在的sample_weights加权。 可视化自动适应轴的大小。 使用 plt.figure 的 figsize 或者 dpi 参数来控制生成的大小。

返回:

List containing the artists for the annotation boxes making up the tree.

返回类型:

annotations : list of artists

Why: 一个一体化的因果学习API

想要轻松使用YLearn？尝试一体化的API Why!

Why 是一个封装了YLearn中几乎所有东西的API，比如 识别因果效应 和 给一个训练好的估计器模型打分。它提供给用户一个简单且有效的方式来使用 我们的包：能够直接传入你仅有的东西，数据到 Why 中并使用它的多个方法，而不是学习多个概念，比如在能够找到藏在你的数据中有趣的信息之前学习调整集合。 Why 被设计成能够执行因果推断的完整流程：给出数据，它首先尝试发现因果图，如果没有提供的话。接着它尝试找到可能作为治疗的变量和识别因果效应。在此之后，一个 合适的估计器模型将被训练用以估计因果效应。最终，估计对于每一个个体最佳的选项的策略。

Why 能够帮助因果推断的完整流程的几乎每一个部分。

使用示例

本节我们使用sklearn数据集 california_housing 演示如何使用 Why ，可通过如下代码准备数据集：

from sklearn.datasets import fetch_california_housing

housing = fetch_california_housing(as_frame=True)
data = housing.frame
outcome = housing.target_names[0]
data[outcome] = housing.target

其中变量 data 就是我们准备好的数据集。

通过缺省参数使用 Why

最简单的使用 Why 的方式是使用缺省参数创建一个 Why 对象，并且是在 fit 时只提供数据集 data 和输出结果的名称 outcome 。

from ylearn import Why

why = Why()
why.fit(data, outcome)

print('identified treatment:',why.treatment_)
print('identified adjustment:',why.adjustment_)
print('identified covariate:',why.covariate_)
print('identified instrument:',why.instrument_)

print(why.causal_effect())

输出：

identified treatment: ['MedInc', 'HouseAge']
identified adjustment: None
identified covariate: ['AveRooms', 'AveBedrms', 'Population', 'AveOccup', 'Latitude', 'Longitude']
identified instrument: None
              mean       min       max       std
MedInc    0.411121 -0.198831  1.093134  0.064856
HouseAge -0.000385 -0.039162  0.114263  0.005845

通过用户指定的treatment使用Why

在 fit Why 对象时，可通过参数 treatment 设置实际业务所要求的treatment：

from ylearn import Why

why = Why()
why.fit(data, outcome, treatment=['AveBedrms', ])

print('identified treatment:',why.treatment_)
print('identified adjustment:',why.adjustment_)
print('identified covariate:',why.covariate_)
print('identified instrument:',why.instrument_)

print(why.causal_effect())

输出：

identified treatment: ['AveBedrms']
identified adjustment: None
identified covariate: ['MedInc', 'HouseAge', 'AveRooms', 'Population', 'AveOccup', 'Latitude', 'Longitude']
identified instrument: None
               mean       min        max       std
AveBedrms  0.197422 -0.748971  10.857963  0.169682

在不fit Why 对象的情况下识别潜在的treatment

我们可以直接调用 Why 对象的 identify 方法识别潜在的treatment、adjustment、covariate和instrument，该方法返回一个由四个元素构成的tuple。

why = Why()
r=why.identify(data, outcome)

print('identified treatment:',r[0])
print('identified adjustment:',r[1])
print('identified covariate:',r[2])
print('identified instrument:',r[3])

输出：

identified treatment: ['MedInc', 'HouseAge']
identified adjustment: None
identified covariate: ['AveRooms', 'AveBedrms', 'Population', 'AveOccup', 'Latitude', 'Longitude']
identified instrument: None

类结构

class ylearn._why.Why(discrete_outcome=None, discrete_treatment=None, identifier='auto', discovery_model=None, discovery_options=None, estimator='auto', estimator_options=None, random_state=None)

一个一体化的因果学习API。

param bool, default=None discrete_outcome:

如果是True则强制将结果看作是离散变量，如果是False则强制将结果看作是连续变量， 如果是None则在fit时自动推断。

param bool, default=None discrete_treatment:

如果是True则强制将treatment看作是离散变量，如果是False则强制将treatment看作是连续变量， 如果是None则在fit时自动推断。

param str or Identifier, default=auto’ identifier:

可用的选项： ‘auto’ 或 ‘discovery’ 或 ‘gcastle’ 或 ‘pgm’

param dict, optional, default=None identifier_options:

参数（键值对）来初始化 identifier

param str, optional, default=’auto’ estimator:

EstimatorModel的名字。 也可以传入一个合理的估计器模型的实例。

param dict, optional, default=None estimator_options:

参数（键值对）来初始化估计器模型

param callable, optional, default=None fn_cost:

成本函数，基于成本对因果效应进行调整。

param str, default=’effect’ effect_name:

在基于成本对因果效应进行调整时，传递给fn_cost的因果效应在DataFrame中的列名。仅当fn_cost不为None时生效。

param int, optional, default=None random_state:

随机种子

feature_names_in_

在 fit 时看到的特征的名字的列表

outcome_

结果的名字

treatment_

在 fit 时识别的治疗的名字的列表

adjustment_

在 fit 时识别的调整的名字的列表

covariate_

在 fit 时识别的协变量的名字的列表

instrument_

在 fit 时识别的工具的名字的列表

identifier_

identifier 对象或者None。用于识别治疗/调整/协变量/工具，如果在 fit 时没有被指明

y_encoder_

LabelEncoder 对象或者None。当outcome是类别型时，对outcome进行编码.

preprocessor_

在 fit 时预处理数据的`Pipeline` 对象

estimators_

对于每个治疗的估计器字典，其中键是治疗的名字，值是 EstimatorModel 对象

fit(data, outcome, *, treatment=None, adjustment=None, covariate=None, instrument=None, treatment_count_limit=None, copy=True, **kwargs)

拟合Why对象，包括如下步骤：

1. 如果outcome不是数值型变量的话，则对其进行编码(LabelEncoder)

2. 识别treatment、adjustment、covariate和instrument

3. 如果treatment是离散变量的话，则对其进行编码(LabelEncoder)

4. 预处理数据

5. 拟合因果估计器

参数:

• data (pandas.DataFrame, required) – 拟合用的数据集

• outcome (str, required) – 输出结果outcome的名称.

• treatment (list of str, optional) – treatment名称列表。如果是str类型则会补被尝试用逗号分隔成列表；如果是None的话则Why会尝试自动识别潜在的treatment。

• adjustment (list of str, optional) – adjustment名称列表。如果是str类型则会补被尝试用逗号分隔成列表；如果是None的话则Why会尝试自动识别潜在的adjustment。

• covariate (list of str, optional) – covariate名称列表。如果是str类型则会补被尝试用逗号分隔成列表；如果是None的话则Why会尝试自动识别潜在的covariate。

• instrument (list of str, optional) – instrument名称列表。如果是str类型则会补被尝试用逗号分隔成列表；如果是None的话则Why会尝试自动识别潜在的instrument。

• treatment_count_limit (int, optional) – 自动识别时treatment的个数限制，缺省是 min(5, 特征总数的10%)。

• copy (bool, default=True) – 是否创建data的数据复本。

返回:

拟合的 Why 对象。

返回类型:

Why

identify(data, outcome, *, treatment=None, adjustment=None, covariate=None, instrument=None, treatment_count_limit=None)

识别潜在的treatment、adjustment、covariate和instrument。

返回:

识别的treatment、adjustment、covariate和instrument

Rtypes:

tuple

causal_graph()

获得识别的因果图。

返回:

识别的因果图

返回类型:

CausalGraph 的实例

causal_effect(test_data=None, treatment=None, treat=None, control=None, target_outcome=None, quantity='ATE', return_detail=False, **kwargs)

估计因果效应。

参数:

• test_data (pandas.DataFrame, optional) – 用于评估因果效应的数据集。如果是None的话则使用fit时的数据集。

• treatment (str or list, optional) – treatment名称或列表。应当是属性 treatment_ 的子集。缺省是属性 **treatment_**的所有元素。

• treat (treatment value or list or ndarray or pandas.Series, default None) – 对于单个离散的treatment，treat应当是treatment所有可能值中的一个；对于多个离散的treatment，treat应当是由每个treatment的值组成的一个列表（list）；对于连续性treatment,treat应当是与test_data行数相同的ndarray或pandas.Series。缺省是None，由Why自行推断。

• control (treatment value or list or ndarray or pandas.Series, default None) – 与treat类似。

• target_outcome (outcome value, optional) – 仅当outcome是离散型是生效。缺省是属性 y_encoder_.classes_ 中的最后一个元素。

• quantity (str, optional, default 'ATE', optional) – ‘ATE’ or ‘ITE’, 缺省是 ‘ATE’。

• return_detail (bool, default False) – 是否在返回结果中包括因果效应的详细数据(detail)

返回:

所有治疗的因果效应。当quantity=’ATE’时，返回结果的DataFrame包括如下列:

• mean: 因果效应的均值

• min: 因果效应的最小值

• max: 因果效应的最大值

• detail (当 return_detail=True时 ): 以ndarray表示的因果效应的详细数据。

当quantity=’ITE’时，返回结果是由个体因果效应组成的DataFrame。

返回类型:

pandas.DataFrame

individual_causal_effect(test_data, control=None, target_outcome=None)

为每一个个体估计因果效应。

参数:

• test_data (pandas.DataFrame, optional) – 用于评估因果效应的数据集。如果是None的话则使用fit时的数据集。

• control (treatment value or list or ndarray or pandas.Series, default None) – 对于单个离散的treatment，control应当是treatment所有可能值中的一个；对于多个离散的treatment，control应当是由每个treatment的值组成的一个列表（list）；对于连续性treatment,control应当是与test_data行数相同的ndarray或pandas.Series。缺省是None，由Why自行推断。

• target_outcome (outcome value, optional) – 仅当outcome是离散型是生效。缺省是属性 y_encoder_.classes_ 中的最后一个元素。

返回:

对于每一个治疗，个体的因果效应。

返回类型:

pandas.DataFrame

whatif(test_data, new_value, treatment=None)

获得反事实预测当治疗从它的对应的观测变为new_value。

参数:

• test_data (pandas.DataFrame, required) – 用于反事实预测的数据集。

• new_value (ndarray or pd.Series, required) – 与test_data行数相同的新的值。

• treatment (str, default None) – treatment名称。缺省使用 treatment_ 的第一个元素。

返回:

反事实预测结果

返回类型:

pandas.Series

score(test_data=None, treat=None, control=None, scorer='auto')

返回:

估计器模型的分数

返回类型:

float

policy_interpreter(test_data, treatment=None, control=None, target_outcome=None, **kwargs)

获得策略解释器

参数:

• test_data (pandas.DataFrame, required) – 用于评估的数据集。

• treatment (str or list, optional) – treatment名称，缺省是 treatment_ 的前两个元素。

• control (treatment value or list or ndarray or pandas.Series) – 对于单个离散的treatment，control应当是treatment所有可能值中的一个；对于多个离散的treatment，control应当是由每个treatment的值组成的一个列表（list）；对于连续性treatment, control应当是与test_data行数相同的ndarray或pandas.Series。缺省是None，由Why自行推断。

• target_outcome (outcome value, optional) – 仅当outcome是离散型是生效。缺省是属性 y_encoder_.classes_ 中的最后一个元素。

• kwargs (dict) – 用于初始化PolicyInterpreter的参数。

返回:

拟合的 PolicyInterpreter 的实例。

返回类型:

PolicyInterpreter 的实例

uplift_model(test_data, treatment=None, treat=None, control=None, target_outcome=None, name=None, random=None)

获取uplift model（针对一个treatment）

param pandas.DataFrame, required test_data:

The test data to evaluate.

param str or list, optional treatment:

Treatment name. If str, it should be one of the fitted attribute treatment_. If None, the first element in the attribute treatment_ is used.

param treatment value, optional treat:

缺省是treatment对应的编码器的 classes_ 的最后一个值。

param treatment value, optional control:

缺省是treatment对应的编码器的 classes_ 的第一个值。

param outcome value, optional target_outcome:

仅当outcome是离散型是生效。缺省是属性 y_encoder_.classes_ 中的最后一个元素。

param str name:

Lift名称。缺省使用treat值。

param str, default None random:

随机生成数据的Lift名称，缺省不生成随机数据。

returns:

The fitted instance of UpliftModel.

rtype:

instance of UpliftModel

plot_causal_graph()

绘制因果关系图。

plot_policy_interpreter(test_data, treatment=None, control=None, **kwargs)

绘制解释器。

参考文献

[Pearl]

10. Pearl. Causility : models, reasoning, and inference.

[Shpitser2006]

19. Shpitser and J. Pearl. Identification of Joint Interventional Distributions in Recursive Semi-Markovian Causal Models.

[Neal2020]

2. Neal. Introduction to Causal Inference.

[Funk2010]

13. Funk, et al. Doubly Robust Estimation of Causal Effects.

[Chern2016]

22. Chernozhukov, et al. Double Machine Learning for Treatment and Causal Parameters. arXiv:1608.00060.

[Athey2015]

19. Athey and G. Imbens. Recursive Partitioning for Heterogeneous Causal Effects. arXiv: 1504.01132.

[Schuler]

1. Schuler, et al. A comparison of methods for model selection when estimating individual treatment effects. arXiv:1804.05146.

[Nie]

X. Nie, et al. Quasi-Oracle estimation of heterogeneous treatment effects. arXiv: 1712.04912.

[Hartford]

10. Hartford, et al. Deep IV: A Flexible Approach for Counterfactual Prediction. ICML 2017.

[Newey2002]

23. Newey and J. Powell. Instrumental Variable Estimation of Nonparametric Models. Econometrica 71, no. 5 (2003): 1565–78.

[Kunzel2019]

19. Kunzel2019, et al. Meta-Learners for Estimating Heterogeneous Treatment Effects using Machine Learning.

[Angrist1996]

10. Angrist, et al. Identification of causal effects using instrumental variables. Journal of the American Statistical Association.

[Athey2020]

19. Athey and S. Wager. Policy Learning with Observational Data. arXiv: 1702.02896.

[Spirtes2001]

16. Spirtes, et al. Causation, Prediction, and Search.

[Zheng2018]

24. Zheng, et al. DAGs with NO TEARS: Continuous Optimization for Structure Learning. arXiv: 1803.01422.

Indices and tables

• 索引

• 模块索引

• 搜索页面