dowhy.gcm 包#

子包#

子模块#

dowhy.gcm.anomaly 模块#

dowhy.gcm.anomaly.anomaly_scores(causal_model: ~dowhy.gcm.causal_models.ProbabilisticCausalModel, anomaly_data: ~pandas.core.frame.DataFrame, num_samples_conditional: int = 10000, num_samples_unconditional: int = 10000, anomaly_scorer_factory: ~typing.Callable[[], ~dowhy.gcm.anomaly_scorer.AnomalyScorer] = <class 'dowhy.gcm.anomaly_scorers.RescaledMedianCDFQuantileScorer'>) → Dict[Any, ndarray][来源]#

dowhy.gcm.anomaly.attribute_anomalies(causal_model: InvertibleStructuralCausalModel, target_node: Any, anomaly_samples: DataFrame, anomaly_scorer: AnomalyScorer | None = None, attribute_mean_deviation: bool = False, num_distribution_samples: int = 3000, shapley_config: ShapleyConfig | None = None) → Dict[Any, ndarray][source]#

估计上游节点对anomaly_samples中每个样本的target_node异常分数的贡献。默认情况下，异常分数基于信息理论（IT）分数 -log(P(g(X) >= g(x)))，其中g是anomaly_scorer，X是从target_node的边际分布中抽取的样本，x是anomaly_samples中target_node的观测值。如果 attribute_mean_deviation设置为True，则估计对g(x) - E[g(X)]的贡献，即给定评分函数的特征相关性。底层算法利用给定anomaly_samples的上游节点（包括target_node本身）的重构噪声。通过这种方式，可以估计异常分数中有多少可以由上游异常相对于异常噪声值来解释。

注意：此函数要求噪声可以从样本中恢复，即非根节点的因果模型需要是可逆噪声模型（例如加性噪声模型）。

相关论文： Janzing, D., Budhathoki, K., Minorics, L., & Bloebaum, P. (2019). 基于因果结构的异常值根因分析 https://arxiv.org/abs/1912.02724

Parameters:

causal_model – 拟合的 InvertibleStructuralCausalModel。
target_node – 为其估计贡献的目标节点。
anomaly_samples – 用于估计贡献的异常观测值。
anomaly_scorer – 异常评分器 g。如果未提供，则使用 MedianCDFQuantileScorer。
attribute_mean_deviation – 如果设置为False，贡献度将基于IT分数进行估计；如果设置为True，贡献度将基于特征与给定评分函数的相关性。
num_distribution_samples – 从X（目标的边际分布）中抽取的样本数量。这些样本用于在IT分数的情况下评估尾部概率（当attribute_mean_deviation为False时），或在特征相关性的情况下作为随机化的样本（当attribute_mean_deviation为True时）。
shapley_config – ShapleyConfig 用于Shapley估计器。

Returns:

一个字典，为每个上游节点（包括目标节点本身）分配一个numpy数组。数组的第i个条目表示相应节点对异常样本中第i个观测值的异常分数的贡献。

dowhy.gcm.anomaly.attribute_anomaly_scores(anomaly_samples: ndarray, distribution_samples: ndarray, anomaly_scoring_func: Callable[[ndarray], ndarray], attribute_mean_deviation: bool, shapley_config: ShapleyConfig | None = None) → ndarray[source]#

估计anomaly_samples中每个样本的特征对通过anomaly_scoring_func获得的异常分数的贡献。如果attribute_mean_deviation设置为False，则异常分数基于信息理论（IT）分数-log(P(g(X) >= g(x)))，其中g是anomaly_scoring_func，X是从target_node的边际分布中抽取的样本，x是anomaly_samples中target_node的观察值。如果attribute_mean_deviation设置为True，则估计对g(x) - E[g(X)]的贡献，即给定评分器的特征相关性。

请注意，异常评分函数需要处理数据的维度和模态。一个用于多维连续数据的函数示例如下：

密度估计器 = GaussianMixtureDensityEstimator() 密度估计器.fit(原始观测值) 异常评分函数 = lambda x, y: 估计逆密度分数(x, y, 密度估计器)

相关论文： Janzing, D., Budhathoki, K., Minorics, L., & Bloebaum, P. (2022). 基于因果结构的异常值根因分析 https://arxiv.org/abs/1912.02724

Parameters:

anomaly_samples – 用于估计贡献的样本x。只要anomaly_scoring_func支持，这些样本的维度并不重要。
distribution_samples – 来自（非异常）分布 X 的样本。
anomaly_scoring_func – 一个函数 g，它接受来自 X 的样本作为输入并返回异常分数。
attribute_mean_deviation – 如果设置为False，贡献度将基于IT分数进行估计；如果设置为True，贡献度将基于特征与给定评分函数的相关性。
shapley_config – ShapleyConfig 用于Shapley估计器。

Returns:

一个numpy数组，包含每个样本在anomaly_samples中对异常分数的特征贡献。

dowhy.gcm.anomaly.conditional_anomaly_scores(parent_samples: ~numpy.ndarray, target_samples: ~numpy.ndarray, causal_mechanism: ~dowhy.gcm.causal_mechanisms.ConditionalStochasticModel, anomaly_scorer_factory: ~typing.Callable[[], ~dowhy.gcm.anomaly_scorer.AnomalyScorer] = <class 'dowhy.gcm.anomaly_scorers.MedianCDFQuantileScorer'>, num_samples_conditional: int = 10000) → ndarray[source]#

基于因果模型的预期结果估计条件异常分数。

Parameters:

parent_samples – 目标节点的所有父节点的样本。
target_samples – 来自目标节点的样本。
causal_mechanism – 目标节点的因果机制。
anomaly_scorer_factory – 一个可调用对象，返回一个异常评分器。
num_samples_conditional – 从基于给定父样本的条件分布中抽取的样本数量。样本越多，结果越准确。

Returns:

target_samples中每个样本的条件异常分数。

dowhy.gcm.anomaly_scorer 模块#

class dowhy.gcm.anomaly_scorer.AnomalyScorer[source]#

基础类：ABC

abstract fit(X: ndarray) → None[source]#

将异常评分器适配到给定数据。根据评分器的定义，这可能意味着不同的事情，例如将（参数化）分布适配到数据或估计某些属性，如均值、方差、中位数等，这些属性用于计算评分。

Parameters:: X – 来自基础数据分布的样本。

abstract score(X: ndarray) → ndarray[来源]#

dowhy.gcm.anomaly_scorers 模块#

该模块包含不同异常评分器的实现。

class dowhy.gcm.anomaly_scorers.ITAnomalyScorer(anomaly_scorer: AnomalyScorer)[来源]#

基础类：AnomalyScorer

将任何异常评分器转换为信息理论（IT）评分。这意味着，给定一个评分器 S(x)，一个异常观测值 x 和来自 X 分布的样本，这个评分器类表示：

分数(x) = -log(P(S(X) >= S(x)))

这是，与基于异常观测x获得的分数相比，从X中（随机）样本获得相同或更高分数的概率的负对数。通过这种方式，任意不同的异常评分器的分数成为可比较的信息理论量。新的分数-log(P(S(X) >= S(x)))也可以被视为“分数越高，异常事件越罕见”。例如，如果我们有S(x) = c，但在X中的所有样本中观察到相同或更高的分数占50%甚至100%，那么这并不是一个真正罕见的事件，因此，也不是异常。如上所述，将其转换为IT分数使得具有潜在完全不同缩放的任意不同异常评分器具有可比性。例如，可以将隔离森林的IT分数与z分数进行比较。

For more details about IT scores, see:: 基于因果结构的异常值根本原因分析 Kailash Budhathoki, Patrick Bloebaum, Lenon Minorics, Dominik Janzing (2022)

分数越高，观察结果越有可能是异常。

fit(X: ndarray) → None[source]#

Parameters:: X – 来自基础数据分布的样本。

score(X: ndarray) → ndarray[source]#

class dowhy.gcm.anomaly_scorers.InverseDensityScorer(density_estimator: DensityEstimator | None = None)[来源]#

基础类: AnomalyScorer

基于1 / p(x)估计异常分数，其中x是要评分的数据。密度值p(x)使用给定的密度估计器进行估计。如果未给出，默认使用高斯混合模型。

注意：给定的密度估计器需要支持数据类型，即如果数据包含分类值，密度估计器需要能够处理这些值。默认的高斯模型只能处理数值数据。

注意：如果密度 p(x) 为 0，可能会返回 nan 或 inf。

fit(X: ndarray) → None[来源]#

Parameters:: X – 来自基础数据分布的样本。

score(X: ndarray) → ndarray[source]#

class dowhy.gcm.anomaly_scorers.MeanDeviationScorer[来源]#

基础类：AnomalyScorer

Given an anomalous observation x and samples from the distribution of X, this score represents:: score(x) = |x - E[X]| / std[X]

这根据给定样本到X均值的距离并使用X的标准差进行缩放来评分。这也等同于高斯变量中的Z分数。

分数越高，观测值与X均值的偏差越大。

fit(X: ndarray) → None[来源]#

Parameters:: X – 来自基础数据分布的样本。

score(X: ndarray) → ndarray[来源]#

class dowhy.gcm.anomaly_scorers.MedianCDFQuantileScorer[来源]#

基础类: AnomalyScorer

Given an anomalous observation x and samples from the distribution of X, this score represents:: score(x) = 1 - 2 * min[P(X > x) + P(X = x) / 2, P(X < x) + P(X = x) / 2]

在这里，值x被视为X的一部分用于计算。

在这里，两个NaN值被认为是相等的。

它根据x相对于X分布的分位数对观测值进行评分。这里，如果样本x位于分布的尾部，我们希望有一个较大的评分。由于我们事先不知道样本是落在X中位数的左侧还是右侧，我们估计两侧的分位数并取最小值。这里，这些概率是通过计数来估计的，由于一半的样本位于中位数的一侧，我们需要将其乘以2以获得双侧分位数。例如：

X = [-3, -2, -1, 0, 1, 2, 3] x = 2.5

Then, x falls in the right sided-quantile and only one sample in X is larger than x. Therefore, we get: P(X > x) = 1 / 8 P(X < x) = 6 / 8 P(X = x) = 1 / 8

我们在这里除以8，因为我们考虑了x本身。这给了我们一个分数：

1 - 2 * min[P(X > x) + P(X = x) / 2, P(X < x) + P(X = x) / 2] = 1 - 3 / 8 = 0.625

注意：对于相等的样本，我们将计数的一半贡献给左侧，另一半贡献给右侧。注意：对于统计上更严格但也更保守的版本，请参见RankBasedAnomalyScorer。

fit(X: ndarray) → None[source]#

Parameters:: X – 来自基础数据分布的样本。

score(X: ndarray) → ndarray[来源]#

class dowhy.gcm.anomaly_scorers.MedianDeviationScorer[来源]#

基础类: AnomalyScorer

Given an anomalous observation x and samples from the distribution of X, this score represents:: score(x) = |x - med[X]| / mad[X]

根据给定样本与X的中位数的距离，并通过X的中位数绝对偏差进行缩放来评分。

分数越高，观测值与X中位数的偏差越大。

fit(X: ndarray) → None[来源]#

Parameters:: X – 来自基础数据分布的样本。

score(X: ndarray) → ndarray[来源]#

class dowhy.gcm.anomaly_scorers.RankBasedAnomalyScorer[source]#

基础类: AnomalyScorer

类似于RescaledMedianCDFQuantileScorer，但这个评分器更直接基于排名和可交换性的假设。

该评分器通过评估测试样本在训练样本（以及给定样本）中的排名来计算异常分数。对于每个测试样本，评分器计算其从上到下的排名（大于或等于它的样本数量）和从下到上的排名（小于或等于它的样本数量）。然后，在可交换性的假设下，基于这些排名计算p值。p值表示观察到与观察到的排名一样极端或更极端的排名的概率。

具体来说，p值的计算为以下三个值中的最小值： 1. 上方秩的两倍除以样本总数。 2. 下方秩的两倍除以样本总数。 3. 1（确保p值最多为1）。

该方法是非参数的，并且不对数据的底层分布做出任何假设。

异常分数随后被计算为该p值的负对数（即它是一个信息论（IT）分数）。较高的异常分数表示较低的概率，因此，更有可能是异常。

For example:: X = [-3, -2, -1, 0, 1, 2, 3] x = 2.5
Then,: p(X >= x) = 2 / 8 P(X <= x) = 7 / 8

请注意，我们在这两种情况下都将样本x本身视为相等。这给出了p值：

-log(min[1, 2 * 7 / 8, 2 * 2 / 8]) = -log(4 / 8) = 0.69314718

fit(X: ndarray) → None[来源]#

Parameters:: X – 来自基础数据分布的样本。

score(X: ndarray) → ndarray[来源]#

class dowhy.gcm.anomaly_scorers.RescaledMedianCDFQuantileScorer[源代码]#

基础类: AnomalyScorer

Given an anomalous observation x and samples from the distribution of X, this score represents:: score(x) = -log(2 * min[P(X > x) + P(X = x) / 2, P(X < x) + P(X = x) / 2])

在这里，两个NaN值被认为是相等的。

这是通过计算负对数概率 -log(1 - s) 获得的分数 s 的重新缩放版本，由 MedianCDFQuantileScorer 获得。这样做的好处是放大了概率中的小差异，尤其是当它们接近 0 时。例如，概率 0.02 和 0.01 之间的差异看起来很小且不显著，但重新缩放后的差异会显著增大：-log(0.02) - log(0.01) −= 8.5

分数越高，样本来自X分布的可能性越小。

fit(X: ndarray) → None[source]#

Parameters:: X – 来自基础数据分布的样本。

score(X: ndarray) → ndarray[来源]#

dowhy.gcm.auto 模块#

class dowhy.gcm.auto.AssignmentQuality(value)[source]#

基础类：Enum

一个枚举。

BEST = 3#

BETTER = 2#

GOOD = 1#

class dowhy.gcm.auto.AutoAssignmentSummary[source]#

基础类：object

用于记录和存储自动分配过程信息的摘要类。

add_model_performance(node, model: str, performance: str, metric_name: str)[source]#

add_node_log_message(node: Any, message: str)[source]#

dowhy.gcm.auto.assign_causal_mechanism_node(causal_model: ProbabilisticCausalModel, node: str, based_on: DataFrame, quality: AssignmentQuality) → List[Tuple[Callable[[], PredictionModel], float, str]][来源]#

dowhy.gcm.auto.assign_causal_mechanisms(causal_model: ProbabilisticCausalModel, based_on: DataFrame, quality: AssignmentQuality = AssignmentQuality.GOOD, override_models: bool = False) → AutoAssignmentSummary[来源]#

自动为节点分配适当的因果机制。如果节点已经分配了因果机制并且override_models设置为False，此函数仅根据图结构验证分配。即，验证检查根节点是否分配了StochasticModels，非根节点是否分配了ConditionalStochasticModels。

以下类型的因果机制被考虑用于自动选择：

如果是根节点：一个经验分布，即通过从提供的数据中随机抽样来表示分布。这提供了一种灵活且非参数化的方式来建模边缘分布，并且适用于所有类型的数据模式。

如果非根节点且数据是连续的：加性噪声模型（ANM）的形式为 X_i = f(PA_i) + N_i，其中 PA_i 是 X_i 的父节点，未观测到的噪声 N_i 被假设为与 PA_i 独立。为了选择最佳的 f 模型，评估了不同的回归模型，并选择具有最小均方误差的模型。请注意，在这里最小化均方误差等同于选择最佳的 ANM。更多详情请参阅以下论文：

Hoyer, P., Janzing, D., Mooij, J. M., Peters, J., & Schölkopf, B. (2008). 使用加性噪声模型进行非线性因果发现。神经信息处理系统进展, 21

如果节点不是根节点且数据是离散的：离散加性噪声模型与非离散ANMs的定义几乎相同，但有一个额外的约束条件，即返回离散值。请注意，这里的“离散”指的是有顺序的数值。如果数据是分类的，考虑将它们表示为字符串以确保正确的模型选择。详情请参阅以下论文：

Peters, J., Janzing, D., & Scholkopf, B. (2011). 使用加性噪声模型对离散数据进行因果推断。 IEEE Transactions on Pattern Analysis and Machine Intelligence, 33(12), 2436-2450.

如果非根节点且数据是分类的：基于分类器的功能因果模型，即 X_i = f(PA_i, N_i)。这里，N_i 遵循 [0, 1] 上的均匀分布，并用于使用分类模型生成的条件概率分布随机抽样一个类别（分类）。这里，使用（负）F1 分数评估不同的模型类别，并选择表现最佳的模型类别。

当前的模型库是：

With “GOOD” quality:

数值型： - 线性回归器 - 带多项式特征的线性回归器 - 直方图梯度提升回归器

分类： - Logistic Regressor - 带有多项式特征的Logistic Regressor - Histogram Gradient Boost Classifier

With “BETTER” quality:

数值型： - 线性回归器 - 带多项式特征的线性回归器 - 梯度提升回归器 - 岭回归器 - Lasso回归器 - 随机森林回归器 - 支持向量回归器 - 极端树回归器 - KNN回归器 - Ada Boost回归器

分类： - 逻辑回归器 - 带多项式特征的逻辑回归器 - 直方图梯度提升分类器 - 随机森林分类器 - 额外树分类器 - 支持向量分类器 - KNN分类器 - 高斯朴素贝叶斯分类器 - Ada Boost分类器

使用“最佳”质量：基于AutoGluon的自动机器学习模型（可选依赖项，需要安装）。

Parameters:

causal_model – 要为其节点分配因果模型的因果模型。
based_on – 基于给定图节点联合采样的数据。
quality –

AssignmentQuality 用于自动模型选择和模型准确性。这会改变
预测模型的类型和选择所花费的时间。请参阅文档字符串以获取潜在模型的列表。质量选项包括：
- AssignmentQuality.GOOD: 仅评估一小部分模型。
  模型选择速度：快模型训练速度：快模型推理速度：快模型准确性：中等
- AssignmentQuality.BETTER: 评估更多的模型。
  模型选择速度：中等模型训练速度：快模型推理速度：快模型准确性：良好
- AssignmentQuality.BEST: 使用由 AutoGluon 包装器定义的默认设置的 AutoGluon（自动机器学习）模型。虽然模型选择本身很快，但训练和推理速度可能比其他选项慢得多。注意：这需要可选的 autogluon.tabular 依赖项。模型选择速度：即时模型训练速度：慢模型推理速度：慢-中等模型准确性：最佳
override_models – 如果设置为True，现有的机制分配将被自动选择的机制替换。如果设置为False，分配的机制仅根据图结构进行验证。

Returns:

一个包含模型选择过程细节的摘要对象。

dowhy.gcm.auto.find_best_model(prediction_model_factories: List[Callable[[], PredictionModel]], X: ndarray, Y: ndarray, metric: Callable[[ndarray, ndarray], float] | None = None, max_samples_per_split: int = 20000, model_selection_splits: int = 5, n_jobs: int | None = None) → Tuple[Callable[[], PredictionModel], List[Tuple[Callable[[], PredictionModel], float, str]]][source]#

dowhy.gcm.auto.has_linear_relationship(X: ndarray, Y: ndarray, max_num_samples: int = 3000) → bool[source]#

dowhy.gcm.auto.select_model(X: ndarray, Y: ndarray, model_selection_quality: AssignmentQuality) → Tuple[PredictionModel | ClassificationModel, List[Tuple[Callable[[], PredictionModel], float, str]]][source]#

dowhy.gcm.causal_mechanisms 模块#

该模块实现了不同的因果机制。

class dowhy.gcm.causal_mechanisms.AdditiveNoiseModel(prediction_model: PredictionModel, noise_model: StochasticModel | None = None)[source]#

基础类：PostNonlinearModel

Represents the continuous functional causal model of the form: Y = f(X) + N,

其中X是输入（通常是Y的直接因果父母），噪声N被假定为与X独立。这是PostNonlinearModel的一个特殊实例，其中函数g是恒等函数。

给定来自 (X, Y) 的联合样本，可以通过首先训练模型 f（例如使用最小二乘回归）然后通过 N = Y - f(X) 重建 N 来拟合此模型，即使用残差。

Parameters:

prediction_model – 预测模型 f。
invertible_function – 可逆函数 g。
noise_model – 用于描述噪声N分布的StochasticModel。

clone()[来源]#

class dowhy.gcm.causal_mechanisms.ClassifierFCM(classifier_model: ClassificationModel | None = None)[source]#

基础类: FunctionalCausalModel, ProbabilityEstimatorModel

Represents the categorical functional causal model of the form: Y = f(X, N),

其中 X 是输入（通常是 Y 的直接因果父节点），这里的噪声 N 在 [0, 1] 上均匀分布。该模型主要基于输出概率的标准分类模型。为了在给定输入 x 的情况下生成一个新的随机样本，返回值 y 是基于类别概率 p(y | x) 均匀采样的。在这里，噪声用于通过使用由给定输入定义的累积分布函数使此采样过程具有确定性。

property classifier_model: ClassificationModel#

clone()[来源]#

draw_noise_samples(num_samples: int) → ndarray[来源]#

返回在[0, 1]上均匀采样的值。

Parameters:: num_samples – 噪声样本的数量。
Returns:: 在[0, 1]上的噪声样本。

estimate_probabilities(parent_samples: ndarray) → ndarray[source]#

返回给定parent_samples的类别概率。

Parameters:: parent_samples – 来自输入X的样本。
Returns:: 一个 nxd 的 numpy 矩阵，其中包含每个样本的类别概率，其中 n 是样本数量，d 是类别数量。在这里，数组条目 A[i][j] 对应于第 i 个样本，表示第 j 个类别的概率。

evaluate(parent_samples: ndarray, noise_samples: ndarray) → ndarray[source]#

评估模型 Y = f(X, N)，其中 X 是父样本，N 是噪声样本。在这里，累积分布函数由父样本定义。例如，假设我们有 2 个类别，n = 0.7，并且输入 x 的 p(y = 0| x) = 0.6 和 p(y = 1| x) = 0.4，那么我们得到的返回值是 y = 1。这是因为 p(y = 0| x) < n <= 1.0，即 n 落在由 p(y = 1| x) 跨越的区间内。

Parameters:

parent_samples – 来自输入X的样本。
noise_samples – 来自[0, 1]区间噪声的样本。

Returns:

基于输入和噪声的类别标签 Y。

fit(X: ndarray, Y: ndarray) → None[source]#

拟合基础分类模型。

Parameters:

X – 输入样本。
Y – 目标标签。

Returns:

无

get_class_names(class_indices: ndarray) → List[str][source]#

class dowhy.gcm.causal_mechanisms.ConditionalStochasticModel[source]#

基础类：ABC

条件随机模型代表了一种用于图形因果模型中非根节点的因果机制的模型。

abstract clone()[来源]#

abstract draw_samples(parent_samples: ndarray) → ndarray[source]#: 为拟合模型绘制样本。

abstract fit(X: ndarray, Y: ndarray) → None[source]#: 根据数据拟合模型。

class dowhy.gcm.causal_mechanisms.DiscreteAdditiveNoiseModel(prediction_model: PredictionModel, noise_model: StochasticModel | None = None)[source]#

基础类：AdditiveNoiseModel

实现了一个离散的ANM。也就是说，它遵循形式为Y = f(X) + N的普通ANM，其中假设N与X独立，并且f被强制输出离散值。为了允许灵活的模型，f可以是任何回归模型，输出将相应地四舍五入为离散值。请注意，这仍然是一个有效的加性噪声模型，但假设Y可以取任何整数值。

Parameters:

prediction_model – 预测模型 f。
invertible_function – 可逆函数 g。
noise_model – 用于描述噪声N分布的StochasticModel。

clone()[来源]#

estimate_noise(target_samples: ndarray, parent_samples: ndarray) → ndarray[source]#

根据 (X, Y) 的样本重建噪声。这是通过以下步骤完成的：

通过 g 的逆变换 Y：g^-1(Y) = f(X) + N

返回残差 g^-1(Y) - f(X)

Parameters:

target_samples – 来自输入X的样本。
parent_samples – 来自目标 Y 的样本。

Returns:

基于给定样本重建的噪声。

evaluate(parent_samples: ndarray, noise_samples: ndarray) → ndarray[source]#

评估给定样本（X, N）的后非线性模型。这是通过以下方式完成的：

评估 f(X)

评估 f(X) + N

返回 g(f(X) + N)

Parameters:

parent_samples – 来自输入X的样本。
noise_samples – 来自噪声N的样本。

Returns:

基于给定样本的Y值。

fit(X: ndarray, Y: ndarray) → None[来源]#

拟合形式为 Y = g(f(X) + N) 的后非线性模型。这里，给定来自 (X, Y) 的样本，它包括三个步骤：

通过 g 的逆变换 Y：g^-1(Y) = f(X) + N

在 (X, g^-1(Y)) 上拟合模型 f

基于残差 N = g^-1(Y) - f(X) 重构 N

请注意，如果模型假设成立，这里的噪声可以唯一推断出来。

Parameters:

X – 来自输入X的样本。
Y – 目标 Y 的样本。

Returns:

无

class dowhy.gcm.causal_mechanisms.FunctionalCausalModel[source]#

基础类: ConditionalStochasticModel

表示一个功能因果模型（FCM），这是一种特定类型的条件随机模型，其定义为：

Y := f(X, N), N: 噪声

abstract draw_noise_samples(num_samples: int) → ndarray[来源]#

draw_samples(parent_samples: ndarray) → ndarray[来源]#: 为拟合模型绘制样本。

abstract evaluate(parent_samples: ndarray, noise_samples: ndarray) → ndarray[source]#

class dowhy.gcm.causal_mechanisms.InvertibleFunctionalCausalModel[源代码]#

基础类: FunctionalCausalModel, ABC

abstract estimate_noise(target_samples: ndarray, parent_samples: ndarray) → ndarray[source]#

class dowhy.gcm.causal_mechanisms.PostNonlinearModel(prediction_model: PredictionModel, noise_model: StochasticModel, invertible_function: InvertibleFunction)[来源]#

基础类：InvertibleFunctionalCausalModel

Represents an post nonlinear FCM, i.e. models of the form:: Y = g(f(X) + N),

其中 X 是目标节点 Y 的父节点，f 是一个期望从父节点 X 接收输入的任意预测模型，N 是一个噪声变量，g 是一个可逆函数。

Parameters:

prediction_model – 预测模型 f。
invertible_function – 可逆函数 g。
noise_model – 用于描述噪声N分布的StochasticModel。

clone()[来源]#

draw_noise_samples(num_samples: int) → ndarray[来源]#

从噪声分布N中抽取样本。

Parameters:: num_samples – 噪声样本的数量。
Returns:: 一个包含来自噪声的num_samples样本的numpy数组。

estimate_noise(target_samples: ndarray, parent_samples: ndarray) → ndarray[来源]#

根据 (X, Y) 的样本重建噪声。这是通过以下步骤完成的：

通过 g 的逆变换 Y：g^-1(Y) = f(X) + N

返回残差 g^-1(Y) - f(X)

Parameters:

target_samples – 来自输入X的样本。
parent_samples – 来自目标 Y 的样本。

Returns:

基于给定样本重建的噪声。

evaluate(parent_samples: ndarray, noise_samples: ndarray) → ndarray[来源]#

评估给定样本（X, N）的后非线性模型。这是通过以下方式完成的：

评估 f(X)

评估 f(X) + N

返回 g(f(X) + N)

Parameters:

parent_samples – 来自输入X的样本。
noise_samples – 来自噪声N的样本。

Returns:

基于给定样本的Y值。

fit(X: ndarray, Y: ndarray) → None[来源]#

拟合形式为 Y = g(f(X) + N) 的后非线性模型。这里，给定来自 (X, Y) 的样本，它包括三个步骤：

通过 g 的逆变换 Y：g^-1(Y) = f(X) + N

在 (X, g^-1(Y)) 上拟合模型 f

基于残差 N = g^-1(Y) - f(X) 重构 N

请注意，如果模型假设成立，这里的噪声可以唯一推断出来。

Parameters:

X – 来自输入X的样本。
Y – 目标 Y 的样本。

Returns:

无

property invertible_function: InvertibleFunction#

property noise_model: StochasticModel#

property prediction_model: PredictionModel#

class dowhy.gcm.causal_mechanisms.ProbabilityEstimatorModel[source]#

基础类：ABC

abstract estimate_probabilities(parent_samples: ndarray) → ndarray[来源]#

class dowhy.gcm.causal_mechanisms.StochasticModel[来源]#

基础类：ABC

随机模型代表用于图形因果模型中根节点的因果机制的模型。

abstract clone()[来源]#

abstract draw_samples(num_samples: int) → ndarray[来源]#: 为拟合模型绘制样本。

abstract fit(X: ndarray) → None[来源]#: 根据数据拟合模型。

dowhy.gcm.causal_models 模块#

该模块定义了图形因果模型（GCMs）的基本类。

class dowhy.gcm.causal_models.InvertibleStructuralCausalModel(graph: ~dowhy.graph.DirectedGraph | None = None, graph_copier: ~typing.Callable[[~dowhy.graph.DirectedGraph], ~dowhy.graph.DirectedGraph] = <class 'networkx.classes.digraph.DiGraph'>, remove_existing_mechanisms: bool = False)[source]#

基础类：StructuralCausalModel

表示一个可逆的结构图形因果模型，例如counterfactual_samples()所要求的。这是StructuralCausalModel的一个子类，并对因果机制类有进一步的限制。在这里，非根节点的机制需要相对于噪声是可逆的，例如PostNonlinearModel。

Parameters:

graph – 可选的图形对象，用作因果图。
graph_copier – 可选函数，可以复制因果图。默认为 networkx.DiGraph 构造函数。
remove_existing_mechanisms – 如果为True，则移除已分配给节点的现有因果机制（如果存在）。否则，不修改图。

causal_mechanism(node: Any) → StochasticModel | InvertibleFunctionalCausalModel[source]#

返回因果图中节点的生成因果模型。

Parameters:: node – 要分配因果模型的目标节点。
Returns:: 此节点的因果机制。根节点类型为 StochasticModel，而非根节点类型为 ConditionalStochasticModel。

set_causal_mechanism(target_node: Any, mechanism: StochasticModel | InvertibleFunctionalCausalModel) → None[source]#

分配因果图中节点的生成因果模型。

Parameters:

node – 要分配因果模型的目标节点。
mechanism – 要分配的因果机制。根节点必须是 StochasticModel，而非根节点必须是 ConditionalStochasticModel。

class dowhy.gcm.causal_models.ProbabilisticCausalModel(graph: ~dowhy.graph.DirectedGraph | None = None, graph_copier: ~typing.Callable[[~dowhy.graph.DirectedGraph], ~dowhy.graph.DirectedGraph] = <class 'networkx.classes.digraph.DiGraph'>, remove_existing_mechanisms: bool = False)[源代码]#

基础类：object

表示一个概率图形因果模型，即它结合了因果关系的图形表示和描述数据生成过程的每个节点的相应因果机制。因果机制可以是任何一般的随机模型。

Parameters:

graph – 可选的图形对象，用作因果图。
graph_copier – 可选函数，可以复制因果图。默认为 networkx.DiGraph 构造函数。
remove_existing_mechanisms – 如果为True，则移除已分配给节点的现有因果机制（如果存在）。否则，不修改图。

causal_mechanism(node: Any) → StochasticModel | ConditionalStochasticModel[source]#

返回因果图中节点的生成因果模型。

Parameters:: node – 要分配因果模型的目标节点。
Returns:: 此节点的因果机制。根节点类型为 StochasticModel，而非根节点类型为 ConditionalStochasticModel。

clone()[source]#: 克隆因果模型，但保持因果机制未训练。

set_causal_mechanism(node: Any, mechanism: StochasticModel | ConditionalStochasticModel) → None[来源]#

分配因果图中节点的生成因果模型。

Parameters:

node – 要分配因果模型的目标节点。
mechanism – 要分配的因果机制。根节点必须是 StochasticModel，而非根节点必须是 ConditionalStochasticModel。

class dowhy.gcm.causal_models.StructuralCausalModel(graph: ~dowhy.graph.DirectedGraph | None = None, graph_copier: ~typing.Callable[[~dowhy.graph.DirectedGraph], ~dowhy.graph.DirectedGraph] = <class 'networkx.classes.digraph.DiGraph'>, remove_existing_mechanisms: bool = False)[来源]#

基础类：ProbabilisticCausalModel

表示一个结构因果模型（SCM），例如由counterfactual_samples()所需。与ProbabilisticCausalModel相比，SCM通过功能因果模型描述非根节点的数据生成过程。

Parameters:

graph – 可选的图形对象，用作因果图。
graph_copier – 可选函数，可以复制因果图。默认为 networkx.DiGraph 构造函数。
remove_existing_mechanisms – 如果为True，则移除已分配给节点的现有因果机制（如果存在）。否则，不修改图。

causal_mechanism(node: Any) → StochasticModel | FunctionalCausalModel[source]#

返回因果图中节点的生成因果模型。

Parameters:: node – 要分配因果模型的目标节点。
Returns:: 此节点的因果机制。根节点类型为 StochasticModel，而非根节点类型为 ConditionalStochasticModel。

set_causal_mechanism(node: Any, mechanism: StochasticModel | FunctionalCausalModel) → None[source]#

分配因果图中节点的生成因果模型。

Parameters:

node – 要分配因果模型的目标节点。
mechanism – 要分配的因果机制。根节点必须是 StochasticModel，而非根节点必须是 ConditionalStochasticModel。

dowhy.gcm.causal_models.clone_causal_models(source: HasNodes, destination: HasNodes)[source]#

dowhy.gcm.causal_models.validate_causal_dag(causal_graph: DirectedGraph) → None[源代码]#

dowhy.gcm.causal_models.validate_causal_graph(causal_graph: DirectedGraph) → None[源代码]#

dowhy.gcm.causal_models.validate_causal_model_assignment(causal_graph: DirectedGraph, target_node: Any) → None[source]#

dowhy.gcm.causal_models.validate_local_structure(causal_graph: DirectedGraph, node: Any) → None[源代码]#

dowhy.gcm.causal_models.validate_node(causal_graph: DirectedGraph, node: Any) → None[source]#

dowhy.gcm.causal_models.validate_node_has_causal_model(causal_graph: HasNodes, node: Any) → None[来源]#

dowhy.gcm.confidence_intervals 模块#

该模块提供了通过自举法估计置信区间的功能。

dowhy.gcm.confidence_intervals.confidence_intervals(estimation_func: ~typing.Callable[[], ~numpy.ndarray] | ~typing.Callable[[], ~typing.Dict[~typing.Any, float]], confidence_level: float = 0.95, num_bootstrap_resamples: int = 20, bootstrap_results_summary_func: ~typing.Callable[[~numpy.ndarray], ~numpy.ndarray] = <function estimate_geometric_median>, n_jobs: int = 1) → Tuple[ndarray | Dict[Any, ndarray], ndarray | Dict[Any, ndarray]][source]#

基于调用给定estimation_func生成的输出估计置信区间。由于每次重复都会产生一个结果，所有结果可以通过summary_method_of_bootstrap_results中定义的方法进行汇总。例如，summary_method_of_bootstrap_results = lambda x: numpy.mean(x, axis=0) 以获取所有运行的平均值。默认情况下，返回几何中位数。

目前，置信区间是根据结果的第n个估计分位数（无偏差校正）经验估计的，其中分位数由给定的置信水平确定。

注意：假设estimation_func的输出是成对独立的。对于estimation_func的多维输出，这种假设可能不成立，应予以注意。例如，在评估像X -> Y -> Z这样的图中的干预结果时，尽管X、Y和Z之间存在强依赖关系，但它们的置信区间是独立估计的。如果estimation_func返回一维结果，例如在估计直接箭头强度时，则应该没有问题。

使用numpy数组输出的示例：

>>> def estimation_func() -> np.ndarray:
>>>     return direct_arrow_strength_of_model(causal_model, parent_data)
>>>
>>> arrow_strengths, confidence_intervals = confidence_intervals(estimation_func)

使用字典输出的示例：

>>> def estimation_func() -> Dict[Any, float]:
>>>     return distribution_change(
>>>             causal_dag, original_observations, outlier_observations, 'X3')
>>>
>>> mean_contributions, confidence_intervals = confidence_intervals(estimation_func)

关于通过自举法估计置信区间的更多详细信息可以在这里找到。

Parameters:

estimation_func – 生成非确定性输出的函数，用于估计置信区间。
confidence_level – 区间的置信水平。
num_bootstrap_resamples – 由 estimation_func 生成的样本数量，即被调用的次数。数量越高，结果和区间越准确，但运行时间越慢。
bootstrap_results_summary_func – 该函数接受一个包含所有结果的numpy数组作为输入，并返回一个（可能是多维的）值/向量。例如，所有结果的平均值或中位数。
n_jobs – 并行任务的数量。每次重复都可以并行估计。然而，由于库中的许多其他函数已经在并行运行（例如分布变化），因此默认情况下设置为1。只有在确定 estimation_func 内部没有并行运行（例如在执行干预时），才应将其设置为不同的值。

Returns:

一个元组（基于summary_method_of_bootstrap_results的所有重复的汇总结果，每个维度/变量的置信区间）

dowhy.gcm.confidence_intervals.estimate_geometric_median(X: ndarray) → ndarray[来源]#

dowhy.gcm.confidence_intervals_cms 模块#

该模块提供了通过自举拟合和采样来估计置信区间的功能。

dowhy.gcm.confidence_intervals_cms.fit_and_compute(f: Callable[[ProbabilisticCausalModel | StructuralCausalModel | InvertibleStructuralCausalModel, Any], Dict[Any, ndarray | float]], causal_model: ProbabilisticCausalModel | StructuralCausalModel | InvertibleStructuralCausalModel, bootstrap_training_data: DataFrame, bootstrap_data_subset_size_fraction: float = 0.75, auto_assign_quality: AssignmentQuality | None = None, *args, **kwargs)[source]#

一个方便的函数，专门用于计算因果查询的置信区间。此函数专门用于引导训练和采样。

示例用法：

>>> scores_median, scores_intervals = gcm.confidence_intervals(
>>>     gcm.fit_and_compute(gcm.arrow_strength,
>>>                         causal_model,
>>>                         bootstrap_training_data=data,
>>>                         target_node='Y'))

Parameters:

f – 要执行的因果查询。因果查询是一个以图形因果模型作为第一个参数，并接受任意数量剩余参数的函数。它必须返回一个包含类似归因数据的字典。
causal_model – 一个用于执行因果查询的图形因果模型。它不需要被拟合。
bootstrap_training_data – 用于拟合的训练数据。在每次调用fit时，会从该数据集中随机抽取一个子集使用。
bootstrap_data_subset_size_fraction – 该分数定义了子集相对于总训练数据的大小比例。
auto_assign_quality – 如果提供了质量，则给定因果模型中的现有因果机制将被基于提供的AssignmentQuality自动推断的新机制覆盖。如果未提供（即None），则使用现有的已分配机制。
args – 参数直接传递给因果查询。
kwargs – 关键字参数直接传递给因果查询。

Returns:

一个包含（1）因果查询结果的中位数和（2）置信区间的元组。

dowhy.gcm.config 模块#

dowhy.gcm.config.disable_progress_bars()[source]#

dowhy.gcm.config.enable_progress_bars()[source]#

dowhy.gcm.config.set_default_n_jobs(n_jobs: int) → None[source]#

dowhy.gcm.constant 模块#

dowhy.gcm.density_estimator 模块#

class dowhy.gcm.density_estimator.DensityEstimator[源代码]#

基础类：ABC

abstract density(X: ndarray) → ndarray[来源]#: 返回每个输入的密度。

abstract fit(X: ndarray) → None[来源]#

dowhy.gcm.density_estimators 模块#

该模块包含不同密度估计器的实现。

class dowhy.gcm.density_estimators.GaussianMixtureDensityEstimator(num_components: int | None = None)[来源]#

基础类：DensityEstimator

表示基于高斯混合模型的密度估计器。该估计器内部使用sklearn的BayesianGaussianMixture模型。

density(X: ndarray) → ndarray[source]#: 返回每个输入的密度。

fit(X: ndarray) → None[来源]#

class dowhy.gcm.density_estimators.KernelDensityEstimator1D[源代码]#

基础类：DensityEstimator

表示一个基于核的密度估计器。该估计器内部使用了sklearn的KernelDensity类。

density(X: ndarray) → ndarray[source]#: 返回每个输入的密度。

fit(X: ndarray) → None[source]#

dowhy.gcm.distribution_change 模块#

该模块定义了用于归因分布变化的函数。

dowhy.gcm.distribution_change.distribution_change(causal_model: ~dowhy.gcm.causal_models.ProbabilisticCausalModel, old_data: ~pandas.core.frame.DataFrame, new_data: ~pandas.core.frame.DataFrame, target_node: ~typing.Any, invariant_nodes: ~typing.List[~typing.Any] | None = None, num_samples: int = 2000, difference_estimation_func: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray], float] = <function auto_estimate_kl_divergence>, independence_test: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray], float] = <function kernel_based>, conditional_independence_test: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray, ~numpy.ndarray], float] = <function kernel_based>, mechanism_change_test_significance_level: float = 0.05, mechanism_change_test_fdr_control_method: str | None = 'fdr_bh', auto_assignment_quality: ~dowhy.gcm.auto.AssignmentQuality | None = None, return_additional_info: bool = False, shapley_config: ~dowhy.gcm.shapley.ShapleyConfig | None = None, graph_factory: ~typing.Callable[[~typing.Any], ~dowhy.graph.DirectedGraph] = <class 'networkx.classes.digraph.DiGraph'>) → Dict[Any, float] | Tuple[Dict[Any, float], Dict[Any, bool], ProbabilisticCausalModel, ProbabilisticCausalModel][source]#

将目标节点边际分布的变化归因于因果DAG中上游节点。

请注意，此方法创建了两个因果DAG的副本。一个因果DAG的因果模型是从旧数据中学习的，而另一个DAG的因果模型是从新数据中学习的。

研究论文: Kailash Budhathoki, Dominik Janzing, Patrick Bloebaum, Hoiyi Ng. 为什么分布发生了变化？. 第24届国际人工智能与统计会议论文集, PMLR 130:1666-1674, 2021.

Parameters:

causal_model – 参考因果模型。
old_data – 来自‘旧’分布的联合样本。
new_data – 来自‘新’分布的联合样本。
target_node – 用于归因边际分布变化的目标节点。
invariant_nodes – 无论分析的数据集如何变化，机制保持不变的节点列表。
num_samples – 用于估计Shapley值的样本数量。这可能对运行时间和准确性有显著影响。
difference_estimation_func – 用于量化分布变化的函数。该函数应期望两个输入，这两个输入代表来自两个不同分布的样本，例如平均值的差异。
independence_test – 无条件独立性测试。这用于识别根节点中的机制变化。
conditional_independence_test – 条件独立性测试。这用于识别非根节点中的机制变化。
mechanism_change_test_significance_level – 用于拒绝节点因果机制未发生变化的零假设的显著性水平。
mechanism_change_test_fdr_control_method – 机制变化测试的假发现率控制方法。更多选项，请查看 statsmodels 手册。
auto_assignment_quality – 如果设置为 None，则使用给定因果模型中的分配模型来处理旧图和新图。但是，它们会在给定数据上重新拟合。如果设置为有效的分配质量，则会根据各自的数据自动为新图和旧图分配新模型。
return_additional_info – 如果设置为True，将返回三个额外的项目：一个指示每个节点的机制是否改变的字典，从旧数据中学到的因果DAG，以及从新数据中学到的因果DAG。
shapley_config – Shapley估计器的配置。
graph_factory – 允许在需要使用不同于networkx.DiGraph的图类时进行自定义。此函数必须复制节点和边。节点的属性将在复制中被覆盖，因此算法与此工厂的属性复制行为无关。

Returns:

默认情况下，如果return_additional_info设置为False，则仅返回包含每个上游节点贡献的字典。如果return_additional_info设置为True，则返回三个额外的项目：一个指示每个节点的机制是否发生变化的字典，从旧数据中学到的因果DAG，以及从新数据中学到的因果DAG。

dowhy.gcm.distribution_change.distribution_change_of_graphs(causal_model_old: ~dowhy.gcm.causal_models.ProbabilisticCausalModel, causal_model_new: ~dowhy.gcm.causal_models.ProbabilisticCausalModel, target_node: ~typing.Any, num_samples: int = 2000, difference_estimation_func: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray], float] = <function auto_estimate_kl_divergence>, shapley_config: ~dowhy.gcm.shapley.ShapleyConfig | None = None, graph_factory: ~typing.Callable[[~typing.Any], ~dowhy.graph.DirectedGraph] = <class 'networkx.classes.digraph.DiGraph'>) → Dict[Any, float][source]#

将目标节点的边际分布变化归因于基于“旧”和“新”因果图生成的分布的上游节点。假设这些图表示相同的因果结构，并且分别在相应的数据上进行了拟合。

注意：此方法会创建给定因果模型的副本，即原始对象不会被修改。

相关论文: Budhathoki, K., Janzing, D., Bloebaum, P., & Ng, H. (2021). 为什么分布发生了变化? arXiv 预印本 arXiv:2102.13384.

Parameters:

causal_model_old – 在“旧”数据上拟合的ProbabilisticCausalModel。
causal_model_new – 在‘新’数据上拟合的ProbabilisticCausalModel。
target_node – 用于归因边际分布变化的感兴趣节点。
num_samples – 用于估计的样本数量。这可能对运行时间和准确性有显著影响。
difference_estimation_func – 用于量化分布变化的函数。该函数应期望两个输入，这两个输入代表来自两个不同分布的样本。一个例子可能是KL散度。
shapley_config – Shapley估计器的配置。
graph_factory – 允许在需要使用不同于networkx.DiGraph的图类时进行自定义。此函数必须复制节点和边。节点的属性将在复制中被覆盖，因此算法与此工厂的属性复制行为无关。

Returns:

一个包含上游节点对目标节点边际分布变化贡献的字典。

dowhy.gcm.distribution_change.estimate_distribution_change_scores(causal_model: ~dowhy.gcm.causal_models.ProbabilisticCausalModel, original_data: ~pandas.core.frame.DataFrame, new_data: ~pandas.core.frame.DataFrame, difference_estimation_func: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray], ~numpy.ndarray | float] = <function auto_estimate_kl_divergence>, max_num_evaluation_samples: int = 1000, num_joint_samples: int = 500, early_stopping_percentage: float = 0.01, independence_test: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray], float] = <function kernel_based>, conditional_independence_test: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray, ~numpy.ndarray], float] = <function kernel_based>, mechanism_change_test_significance_level: float = 0.05, mechanism_change_test_fdr_control_method: str | None = 'fdr_bh') → Dict[Any, float][source]#

给定来自给定因果图模型的联合分布的新观测样本和原始样本，该方法估计每个节点的得分，以量化节点分布的变化程度。为此，它首先检查底层因果机制是否发生了变化，如果发生了变化，则估计新分布和原始分布之间的差异。该得分基于提供的difference_estimation_func测量的量，如果未检测到机制变化，则得分为0。

请注意，对于每个父样本，基于原始和新的因果机制生成num_joint_samples个条件样本，并通过给定的difference_estimation_func函数进行评估。然后，这些结果在多个不同的父样本上进行平均。

Parameters:

causal_model – 基于原始数据的底层因果模型。
original_data – 原始数据的样本。
new_data – 来自新数据的样本。
difference_estimation_func – 用于量化分布变化的函数。该函数应期望两个输入，这两个输入代表来自两个不同分布的样本。一个例子可能是KL散度。
max_num_evaluation_samples – 用于评估分布差异的（父）样本的最大数量。
num_joint_samples – 每个父样本在节点中生成的样本数量。
early_stopping_percentage – 如果多次连续运行之间的百分比变化低于此阈值，则在评估所有max_num_evaluation_samples之前停止评估。
independence_test – 无条件独立性测试。这用于识别根节点中的机制变化。
conditional_independence_test – 条件独立性测试。这用于识别非根节点中的机制变化。
mechanism_change_test_significance_level – 用于拒绝节点因果机制未发生变化的零假设的显著性水平。
mechanism_change_test_fdr_control_method –
机制变化测试的假发现率控制方法。更多选项，请查看 statsmodels 手册。

Returns:

一个为因果图中的每个节点分配分数的字典。

dowhy.gcm.distribution_change.mechanism_change_test(target_original_data: ~numpy.ndarray, target_new_data: ~numpy.ndarray, parents_original_data: ~numpy.ndarray | None = None, parents_new_data: ~numpy.ndarray | None = None, independence_test: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray], float] = <function kernel_based>, conditional_independence_test: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray, ~numpy.ndarray], float] = <function kernel_based>) → float[source]#

估计一个p值，用于原假设，即原始数据和新数据是由相同的机制生成的。在这里，我们检查二进制标签之间的依赖性，这些标签指示样本是来自原始数据集还是新数据集。如果这些标签不能提供信息来确定样本是来自原始/新分布，那么机制可能没有改变。

对于非根节点，需要来自父变量的样本作为条件变量。也就是说，测试数据在给定父样本的情况下由相同机制生成的零假设。通过这种方式，我们纳入了可能影响父节点但不影响目标节点本身的上游变化。

Parameters:

target_original_data – 原始数据集中节点的样本。
target_new_data – 新数据集中节点的样本。
parents_original_data – 来自原始数据集中节点父节点的样本。
parents_new_data – 来自新数据集的节点父样本。
independence_test – 无条件独立性测试。这用于识别没有父节点的节点中的机制变化。
conditional_independence_test – 条件独立性测试。这用于识别具有父节点的节点中的机制变化。

Returns:

零假设的p值，即机制没有改变。

dowhy.gcm.divergence 模块#

dowhy.gcm.divergence.auto_estimate_kl_divergence(X: ndarray, Y: ndarray) → float[来源]#

dowhy.gcm.divergence.estimate_kl_divergence_categorical(X: ndarray, Y: ndarray) → float[来源]#

dowhy.gcm.divergence.estimate_kl_divergence_continuous_clf(samples_P: ~numpy.ndarray, samples_Q: ~numpy.ndarray, n_splits: int = 5, classifier_model: ~dowhy.gcm.auto.AssignmentQuality | ~typing.Callable[[], ~dowhy.gcm.ml.classification.ClassificationModel] = functools.partial(<function create_logistic_regression_classifier>, max_iter=10000), epsilon: float = 2.220446049250313e-16) → float[来源]#

基于分类器给出的概率估计KL散度。这是：

D_f(P || Q) = int f(p(x)/q(x)) q(x) dx ~= -1/N sum_x log(p(Y = 1 | x) / (1 - p(Y = 1 | x)))

在这里，KL散度可以通过概率的对数比率来近似预测样本是来自分布P还是Q。

Parameters:

samples_P – 从P中抽取的样本。样本数量可以与Q不同。
samples_Q – 从Q中抽取的样本。样本数量可以与P不同。
n_splits – 训练和测试数据的拆分次数。分类器在训练数据上进行训练，并在测试数据上进行评估以获得概率。
classifier_model – 用于估计对数比率的概率。这可以是ClassificationModel或AssignmentQuality。在后一种情况下，将根据训练集上的最佳性能自动选择模型。
epsilon – 如果概率为1或0，此值将用于裁剪，即0变为epsilon，1变为1-epsilon。

Returns:

KL散度D(P||Q)的估计值。

dowhy.gcm.divergence.estimate_kl_divergence_continuous_knn(X: ndarray, Y: ndarray, k: int = 1, remove_common_elements: bool = True, n_jobs: int = 1) → float[source]#

使用k-近邻法估计KL散度（Wang等，2009）。

虽然在理论上，这可以处理多维输入，但对于超过一维的数据，请考虑使用 estimate_kl_divergence_continuous_clf。

Q. Wang, S. R. Kulkarni, 和 S. Verdú, “通过k近邻距离进行多维密度散度估计”, IEEE信息论汇刊, 卷55, 期5, 页2392-2405, 2009年5月.

Parameters:

X – (N_1,D) 从分布 P_X 中抽取的样本
Y – (N_2,D) 从分布 P_Y 中抽取的样本
k – 要考虑的邻居数量。
remove_common_elements – 如果为true，则移除X和Y中的共同值。否则，如果k设置为1，这些值的KNN距离将为零，这将导致除以零错误。
n_jobs – 用于最近邻模型的并行作业数量。-1 表示使用所有可用的核心。请注意，在大多数应用中，并行化反而会引入更多的开销，导致运行时间变慢。

返回值: D(P_X||P_Y) 的估计值。

dowhy.gcm.divergence.estimate_kl_divergence_of_probabilities(X: ndarray, Y: ndarray) → float[source]#: 估计X和Y中每对概率向量（按行）之间的Kullback-Leibler散度，并返回所有结果的平均值。

dowhy.gcm.divergence.is_probability_matrix(X: ndarray) → bool[来源]#

dowhy.gcm.falsify 模块#

该模块提供了根据观察数据伪造用户给定的DAG的功能。

class dowhy.gcm.falsify.EvaluationResult(summary: dict, significance_level: float, suggestions: dict | None = None)[source]#

基础类：object

包含使用节点置换测试伪造图的评估结果的Dataset类。

…

属性#

summarydict: 包含评估摘要的字典。
significance_levelfloat: 基于我们用来否定给定DAG的显著性水平
falsifiablebool: 给定的DAG是否可证伪。
falsifiedbool: 给定的DAG是否被伪造。

significance_level: float#

suggestions: dict | None = None#

summary: dict#

update_significance_level(significance_level: float)[来源]#: 更新显著性水平以决定是否伪造给定的DAG。

class dowhy.gcm.falsify.FalsifyConst(value)[source]#

基础类：Enum

一个枚举。

F_GIVEN_VIOLATIONS = 7#

F_PERM_VIOLATIONS = 8#

GIVEN_VIOLATIONS = 5#

LOCAL_VIOLATION_INSIGHT = 9#

MEC = 16#

METHOD = 10#

N_TESTS = 2#

N_VIOLATIONS = 1#

PERM_GRAPHS = 15#

PERM_VIOLATIONS = 6#

P_VALUE = 3#

P_VALUES = 4#

VALIDATE_CM = 14#

VALIDATE_LMC = 11#

VALIDATE_PD = 13#

VALIDATE_TPA = 12#

dowhy.gcm.falsify.apply_suggestions(causal_graph: DirectedGraph, evaluation_result: EvaluationResult, edges_to_keep: List[Tuple[Any, Any]] | None = None)[source]#

dowhy.gcm.falsify.falsify_graph(causal_graph: ~dowhy.graph.DirectedGraph, data: ~pandas.core.frame.DataFrame, suggestions: bool = False, independence_test: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray], float] = <function kernel_based>, conditional_independence_test: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray, ~numpy.ndarray], float] = <function kernel_based>, significance_level: float = 0.05, significance_ci: float = 0.05, n_permutations: int | None = None, show_progress_bar: bool | None = None, n_jobs: int | None = None, plot_histogram: bool = False, plot_kwargs: ~typing.Dict | None = None, allow_data_subset: bool = True) → EvaluationResult[源代码]#

使用观测数据伪造给定的DAG。

该方法返回一个置换测试的结果，以使用观测数据来否定用户给定的DAG。为此，我们通过测试图中隐含的局部马尔可夫条件（LMC）的违反情况来构建测试统计量，使用条件独立性（CI）测试。零假设是给定图的随机节点置换的LMC违反次数。我们的测试可以解释为给定图在其所蕴含的CIs方面是否显著优于随机图。为了确定给定图是否可以通过我们的指标被否定，我们实施了第二个测试，该测试报告给定图在其所蕴含的CIs方面是否足够“特征”。为此，我们计算有多少随机节点置换与给定图处于相同的马尔可夫等价类（MEC）中，并得出结论，只有当与给定图处于相同MEC的置换DAG的比例“合理”小时，给定图才是可被否定的。

The returned EvaluationResult object has two attributes: falsified and falsifiable:: falsifiable: 给定的图位于与 >= 1-significance_level 的置换 DAG 不同的 MEC 中 falsified: 给定的图是可证伪的，并且违反的 LMC 少于 >= 1-significance_level 的

置换的有向无环图

默认情况下，我们只运行1 / significance_level次排列，因为这些足以在给定的significance_level下以I型错误概率significance_level来否定一个图。如果您对p值的更精确估计感兴趣，或者希望绘制直方图以查看给定的DAG与随机节点排列的比较情况，您应该将n_permutations设置为更大的值（例如100或1000）。如果n_permutations=-1，我们将在所有n_nodes!排列上进行测试（如果plot_histogram=True，则为默认值）。

此外，此方法允许向用户返回建议（suggestions=True）。这是通过测试因果最小性的违反情况来完成的，使用validate_cm。

Related paper:: Eulig, E., Mastakouri, A. A., Blöbaum, P., Hardt, M., & Janzing, D. (2023). 使用基于排列的测试来伪造因果图。 https://arxiv.org/abs/2305.09565

Parameters:

causal_graph – 一个有向无环图（DAG）。
data – DAG中变量的观测值。
suggestions – 向用户提供建议。目前，建议的唯一来源是通过验证因果最小性（使用 validate_cm）。
independence_test – 用于检查成对独立性的独立性测试。
conditional_independence_test – 使用的条件独立性测试。
significance_level – 置换检验的显著性水平。
significance_ci – （条件）独立性测试的显著性水平。
n_permutations – 要执行的排列次数。如果为-1，则使用所有n_nodes!排列。
show_progress_bar – 是否在排列过程中显示进度条。
n_jobs – 用于并行执行（条件）独立性测试的作业数量。
plot_histogram – 绘制排列基线结果的直方图。
plot_kwargs – 传递给 plot_evaluation_results 的额外绘图参数。
allow_data_subset – 如果为True，即使数据仅适用于节点的子集，也会执行评估。如果为False，如果并非所有节点都有可用数据，则会引发错误。

Returns:

评估结果

dowhy.gcm.falsify.plot_evaluation_results(evaluation_result, figsize=(8, 3), bins=None, title='', savepath='', display=True)[source]#

dowhy.gcm.falsify.plot_local_insights(causal_graph: DirectedGraph, evaluation_result: EvaluationResult | Dict, method: str | None = FalsifyConst.VALIDATE_LMC)[来源]#: 对于给定的图和评估结果，绘制局部违规情况。 :param causal_graph: DiGraph :param evaluation_result: EvaluationResult :param method: 用于绘制违规情况的方法

dowhy.gcm.falsify.run_validations(causal_graph: ~dowhy.graph.DirectedGraph, data: ~pandas.core.frame.DataFrame, methods: ~typing.Callable | ~typing.Tuple[~typing.Callable, ...] | ~typing.List[~typing.Callable] | None = functools.partial(<function validate_lmc>, independence_test=<function kernel_based>, conditional_independence_test=<function kernel_based>)) → Dict[str, Dict][source]#

使用观测数据和一些给定的方法验证给定的因果图。如果提供了方法，它们必须封装在一个部分对象中，并带有各自的参数。例如，如果想要测试局部马尔可夫条件和成对依赖关系（无条件忠实性），则调用

run_validations(G, data, methods=(
partial(validate_lmc, independence_test=…, conditional_independence_test=…), partial(validate_pd, independence_test=…), )

)

Parameters:

causal_graph – 一个有向无环图（DAG）。
data – DAG中变量的观测值。
methods – 使用wrap_partial包装的方法函数。例如 wrap_partial(validate_lmc, data=data, independence_test=…, conditional_independence_test=…). 如果没有提供方法，我们将使用提供给run_validations的可选关键字参数运行validate_lmc。

Returns:

验证摘要以字典形式显示。

dowhy.gcm.falsify.validate_cm(causal_graph: ~dowhy.graph.DirectedGraph, data: ~pandas.core.frame.DataFrame, p_values_memory: ~dowhy.gcm.falsify._PValuesMemory | None = None, independence_test: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray], float] = <function kernel_based>, conditional_independence_test: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray, ~numpy.ndarray], float] = <function kernel_based>, significance_level: float = 0.05, n_jobs: int | None = None) → Dict[str, int | Dict[tuple, float]][source]#

用于测试DAG的因果最小性的函数（参见[1]，命题6.36）。 [1] J. Peters, D. Janzing, 和 B. Schölkopf, 《因果推理的元素：基础与学习算法》。美国马萨诸塞州剑桥：麻省理工学院出版社，2017年。

Parameters:

causal_graph – 一个有向无环图（DAG）。
data – DAG中变量的观测值。
p_values_memory – _PValuesMemory 对象，用于存储先前执行的测试结果。
independence_test – 使用的独立性测试。
conditional_independence_test – 使用的条件独立性测试。
significance_level – 独立性检验的显著性水平。
n_jobs – 用于并行执行（条件）独立性测试的作业数量。

Returns:

验证摘要以字典形式显示。

dowhy.gcm.falsify.validate_lmc(causal_graph: ~dowhy.graph.DirectedGraph, data: ~pandas.core.frame.DataFrame, p_values_memory: ~dowhy.gcm.falsify._PValuesMemory | None = None, independence_test: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray], float] = <function kernel_based>, conditional_independence_test: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray, ~numpy.ndarray], float] = <function kernel_based>, significance_level: float = 0.05, include_unconditional: bool = True, n_jobs: int | None = None) → Dict[str, int | Dict[str, float]][source]#

验证给定有向图的局部马尔可夫条件。返回每个节点的违规次数和p值。

Parameters:

causal_graph – 一个有向无环图（DAG）。
data – DAG中变量的观测值。
p_values_memory – _PValuesMemory 实例，用于存储先前执行的测试结果。
independence_test – 用于无条件独立性检验的测试（仅在 include_unconditional=True 时使用）
conditional_independence_test – 用于检查局部马尔可夫条件的条件独立性测试。
significance_level – （条件）独立性检验的显著性水平。
include_unconditional – 同时测试根节点的无条件独立性。
n_jobs – 用于并行执行（条件）独立性测试的作业数量。

Returns:

验证结果包含图中违规的数量以及每个元组（节点，非后代）的p值/违规情况

dowhy.gcm.falsify.validate_pd(causal_graph: ~dowhy.graph.DirectedGraph, data: ~pandas.core.frame.DataFrame, p_values_memory: ~dowhy.gcm.falsify._PValuesMemory | None = None, n_pairs: int = -1, independence_test: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray], float] = <function kernel_based>, significance_level: float = 0.05, adjacent_only: bool = False, n_jobs: int | None = None) → Dict[str, int | Dict[tuple, float]][source]#

验证给定因果图和数据的成对依赖关系（pd）。测试每个节点是否与其所有祖先在统计上依赖。

Parameters:

causal_graph – 一个有向无环图（DAG）。
data – DAG中变量的观测值。
p_values_memory – _PValuesMemory 对象，用于存储先前执行的测试结果。
n_pairs – 评估DAG中n_pairs <= 所有对的依赖关系。如果n_pairs=-1，则评估所有（祖先，节点）对的依赖关系（默认）。
independence_test – 用于检查成对依赖关系的独立性测试。
significance_level – 独立性检验的显著性水平。
adjacent_only – 仅测试相邻节点对。
n_jobs – 用于并行执行（条件）独立性测试的作业数量。

Returns:

摘要字典：{n_violations: int, n_tests: int, p_values: {(ancestor, node): float, …}}

dowhy.gcm.falsify.validate_tpa(causal_graph: DirectedGraph, causal_graph_reference: DirectedGraph, include_unconditional: bool = True) → Dict[str, int][source]#

图形标准用于评估在causal_graph中哪些成对父代d-分离（父代三元组）被违反，假设causal_graph_reference是真实图。如果没有违反，则两个图位于相同的马尔可夫等价类中。具体来说，我们测试：

X _|_G’ Y | Z 和 X _/|_G Y | Z 对于 Y 在 ND{X}^G’ 中，Z = PA{X}^G

Parameters:

causal_graph – 用于评估父级d-分离的因果图（G’）
causal_graph_reference – 用于测试d-分离是否成立的因果图（G）
include_unconditional – 同时测试根节点的无条件独立性。

Returns:

验证摘要，包含由causal_graph暗示的d-分离数量以及这些在图形causal_graph_reference中被违反的次数。

dowhy.gcm.feature_relevance 模块#

该模块允许估计输入特征相对于给定模型的相关性。虽然这些模型可以是黑箱预测模型，但也可以解释与直接父节点相关的因果机制。在这些情况下，可以引入噪声来表示生成过程中无法由父节点解释的部分。

dowhy.gcm.feature_relevance.feature_relevance_distribution(prediction_method: Callable[[ndarray], ndarray], feature_samples: ndarray, subset_scoring_func: Callable[[ndarray, ndarray], ndarray | float], max_num_samples_randomization: int = 5000, max_num_baseline_samples: int = 500, max_batch_size: int = 100, randomize_features_jointly: bool = True, shapley_config: ShapleyConfig | None = None) → ndarray[source]#

根据给定的prediction_method估计输入特征的人口特征相关性。该方法通过比较在特定特征被随机化时prediction_method的输出与没有特征被随机化时的输出，使用feature_samples中提供的所有样本。subset_scoring_func定义了这些预测如何进行比较。例如，偏差的方差。

如果随机预测应该与原始数据进行比较，这可以通过设置函数来定义（并且可以），通过忽略第二个输入参数（使用所有特征的预测值）。相反，可以使用原始数据。

注意：分布级别的相关性是通过对应用于多个样本的集合函数的结果取期望来估计的。由于Shapley值估计的线性性，这等同于对Shapley值取期望。

相关论文： Janzing, D., Minorics, L., & Bloebaum, P. (2020). 可解释AI中的特征相关性量化：一个因果问题。在国际人工智能与统计会议上（第2907-2916页）。PMLR。

Parameters:

prediction_method – 一个可调用对象，预期会返回给定样本的预测结果。
feature_samples – 来自联合分布的样本。
subset_scoring_func – 用于基于模型结果估计感兴趣量的集合函数。此函数期望两个输入；某些特征被置换时预测模型对某些样本的结果，以及当没有特征被置换时模型对相同样本的结果。集合函数表示样本之间的比较，例如，偏差的方差。然后将其用作在估计Shapley值时作为联盟游戏中的“特征函数”。
max_num_samples_randomization – 用于随机化不在子集中的特征的最大样本数。考虑增加此数以获得更准确的结果（如果有足够的样本可用），或减少它以降低内存消耗并加快运行时间。
max_num_baseline_samples – 评估集合函数的最大样本数。这些样本用作子集中特征的固定观察值。例如，在将均值作为set_function_summary_func的情况下，这定义了用于估计均值的最大样本数。考虑增加此数以获得更准确的结果（如果有足够的样本可用），或减少它以降低内存消耗并加快运行时间。
max_batch_size – 用于估计预测的最大批次大小。这对整体内存使用有显著影响。如果设置为-1，则所有样本将在一个批次中使用。
randomize_features_jointly – 如果设置为True，不在子集中的特征将联合排列。请注意，这仍然代表一个干预分布。如果设置为False，不在子集中的特征将独立排列。注意：链接的出版物中的理论假设此设置为True。
shapley_config – Shapley估计器的配置。

Returns:

一个包含每个输入特征相关性的numpy数组。

dowhy.gcm.feature_relevance.feature_relevance_sample(prediction_method: Callable[[ndarray], ndarray], feature_samples: ndarray, baseline_samples: ndarray, subset_scoring_func: Callable[[ndarray, ndarray], ndarray | float], baseline_target_values: ndarray | None = None, average_set_function: bool = False, max_batch_size: int = 100, randomize_features_jointly: bool = True, shapley_config: ShapleyConfig | None = None) → ndarray[source]#

估计预测方法对baseline_noise_samples中每个样本的特征相关性。此方法使用feature_samples中提供的所有样本作为“背景”样本。也就是说，它们应该代表输入特征的联合分布的样本。subset_scoring_func定义了当某些特征被随机化时预测方法的输出与没有特征被随机化时的输出之间的比较。最常见的函数是期望值之间的差异。

相关论文： Janzing, D., Minorics, L., & Bloebaum, P. (2020). 可解释AI中的特征相关性量化：一个因果问题。在国际人工智能与统计会议上（第2907-2916页）。PMLR。

Parameters:

prediction_method – 一个可调用对象，预期会返回给定样本的预测结果。
feature_samples – 来自联合分布的样本。这些样本被用作“背景样本”，以随机化不在子集中的特征。
baseline_samples – 需要估计特征相关性的样本。
subset_scoring_func – 用于根据模型结果估计感兴趣量的集合函数。此函数期望两个输入；某些特征被置换时预测模型对某些样本的结果，以及当没有特征被置换时模型对相同样本的结果。回归模型的典型选择将是期望之间的差异。然后，这被用作估计Shapley值时的联盟游戏中的“特征函数”。
baseline_target_values – 这些基线值与预测方法的子集特定结果进行比较。如果设置为 None（默认），基线值是给定 prediction_method 应用于 baseline_noise_samples 的结果，即空子集的结果。
max_batch_size – 用于估计预测的最大批次大小。这对整体内存使用有显著影响。如果设置为-1，则所有样本将在一个批次中使用。
average_set_function – 如果设置为True，则使用应用于每个感兴趣样本的集合函数的平均结果来估计Shapley值。如果设置为False，则分别估计每个感兴趣样本的Shapley值。
randomize_features_jointly – 如果设置为True，不在子集中的特征将联合排列。请注意，这仍然代表一个干预分布。如果设置为False，不在子集中的特征将独立排列。注意：链接的出版物中的理论假设此设置为True。
shapley_config – Shapley估计器的配置。

Returns:

一个numpy数组，包含baseline_noise_samples中每个样本的特征相关性。

dowhy.gcm.feature_relevance.parent_relevance(causal_model: StructuralCausalModel, target_node: Any, parent_samples: DataFrame | None = None, subset_scoring_func: Callable[[ndarray, ndarray], ndarray | float] | None = None, num_samples_randomization: int = 5000, num_samples_baseline: int = 500, max_batch_size: int = 100, shapley_config: ShapleyConfig | None = None) → Tuple[Dict[Any, Any], ndarray][source]#

估计给定目标节点的直接父节点基于分布的相关性。这是指直接父节点作为目标节点基础因果模型的输入特征的相关性。在这里，未观察到的噪声也被视为直接父节点（输入）。用于估计的样本是从给定的因果图中抽取的。

默认情况下，使用的subset_scoring_func基于Y和Y’之间的方差，其中Y是因果模型的输出，Y’是当某些特征被随机化时模型的输出。在连续数据的情况下，特征相关性加起来等于Var(Y - Y’)。

注意：基于分布的特征相关性不能直接与单个样本的特征相关性进行比较。如果需要这样做，则需要相应地定义集合函数。

相关论文： Janzing, D., Minorics, L., & Bloebaum, P. (2020). 可解释AI中的特征相关性量化：一个因果问题。在国际人工智能与统计会议上（第2907-2916页）。PMLR。

Parameters:

causal_model – 拟合的结构因果模型。
target_node – 具有因果模型的节点。
parent_samples – 给定目标节点的父节点的样本。如果未提供，则根据图生成新样本。这些样本用于随机化不在子集中的特征。
subset_scoring_func – 用于根据模型结果估计感兴趣量的集合函数。此函数期望两个输入；如果某些特征被置换，因果模型对某些样本的结果，以及当没有特征被置换时，模型对相同样本的结果。集合函数表示样本之间的比较，例如，偏差的方差。然后将其用作估计Shapley值时的联盟游戏中的“特征函数”。
num_samples_randomization – 用于评估集合函数的背景父样本数量。如果未提供parent_samples，这表示从父节点的联合分布中生成的样本数量，并用于随机化不在子集中的特征。考虑增加此数量以获得更准确的结果，或减少它以降低内存消耗并加快运行时间。
num_samples_baseline – 用于评估集合函数的样本数量。这些样本用作子集中父节点的固定观察值。考虑增加此数量以获得更准确的结果，或减少它以降低内存消耗并加快运行时间。
max_batch_size – 用于一次性估计多个预测的最大批次大小。这对整体内存使用有显著影响。如果设置为-1，则所有样本将在一个批次中使用。
shapley_config – ShapleyConfig 用于Shapley估计器。

Returns:

有两个返回值。一个字典，包含给定目标节点的每个直接父节点的特征相关性，以及噪声的特征相关性。

dowhy.gcm.fitting_sampling 模块#

该模块提供了拟合概率因果模型并从中抽取样本的功能。

dowhy.gcm.fitting_sampling.draw_samples(causal_model: ProbabilisticCausalModel, num_samples: int) → DataFrame[source]#

从给定的图形因果模型中绘制新的联合样本。这是通过首先从根节点生成随机样本，然后通过图传播因果下游效应来完成的。

Parameters:

causal_model – 新样本是基于给定的因果模型生成的。
num_samples – 要抽取的样本数量。

Returns:

一个pandas数据框，其中列对应于图中的节点，行对应于绘制的联合样本。

dowhy.gcm.fitting_sampling.fit(causal_model: ProbabilisticCausalModel, data: DataFrame, return_evaluation_summary: bool = False)[source]#

将每个节点的因果机制拟合到数据中。这是通过遍历图中的节点并调用相应的拟合函数，将分配给它们的因果机制单独拟合到数据中来完成的。由于模块化假设，我们可以独立于其他机制拟合图中的每个机制。对于根节点，训练数据是提供的数据中的相应列。对于非根节点，数据基于节点的父节点和节点本身。在拟合节点之前，此函数首先验证分配的机制是否有效，即根节点是否遵循StochasticModel，非根节点是否遵循ConditionalStochasticModel。

拟合因果机制的细节取决于它们的实现。例如，如果一个节点遵循加性噪声模型 X_i = f_i(PA_i) + N_i，其中 N_i 是未观察到的噪声，拟合涉及将函数 f_i（可以是任何 scikit-learn 回归器）拟合到数据，并根据残差 X_i - f_i(PA_i) 对分布 N_i 进行建模。有关如何拟合每个单独机制的更多详细信息，请参阅相应的文档，因为这些是单独的实现细节。

此函数可选择性地返回通过交叉验证评估的因果机制的不同指标的摘要。请注意，这将使用evaluate_causal_model方法。对于更详细和广泛的评估，请考虑直接使用evaluate_causal_model方法。

Parameters:

causal_model – 包含将要拟合节点的机制的因果模型。
data – 因果模型中节点的观测数据。
return_evaluation_summary – 如果为True，则返回使用evaluate_causal_model方法拟合机制的性能摘要。如果为False，则不返回任何内容。

Returns:

可选地，一个CausalModelEvaluationResult通过交叉验证总结因果机制的表现。

dowhy.gcm.fitting_sampling.fit_causal_model_of_target(causal_model: ProbabilisticCausalModel, target_node: Any, training_data: DataFrame) → None[来源]#

仅基于训练数据拟合给定目标节点的因果机制。

Parameters:

causal_model – 包含目标节点的因果模型。
target_node – 机制所针对的目标节点。
training_data – 用于拟合因果机制的训练数据。

Returns:

无

dowhy.gcm.influence 模块#

该模块提供了估计因果影响的函数。

dowhy.gcm.influence.arrow_strength(causal_model: ProbabilisticCausalModel, target_node: Any, parent_samples: DataFrame | None = None, num_samples_conditional: int = 2000, max_num_runs: int = 5000, tolerance: float = 0.01, n_jobs: int = -1, difference_estimation_func: Callable[[ndarray, ndarray], ndarray | float] | None = None) → Dict[Tuple[Any, Any], float][source]#

计算指向目标节点的每条边的因果强度。边的强度通过原始图和插补图中目标节点的条件分布之间的距离来量化，其中边已被移除，并且目标节点被输入源节点观测值的随机排列。有关此API背后的更多科学细节，请参阅以下研究论文。

研究论文: Dominik Janzing, David Balduzzi, Moritz Grosse-Wentrup, Bernhard Schölkopf. 量化因果影响. 统计学年鉴, 卷41, 第5期, 2324-2358, 2013.

Parameters:

causal_model – 我们为其目标节点计算传入边强度的概率因果模型。
target_node – 要计算其入边强度的目标节点。
parent_samples – 可选的来自目标节点父节点的样本。如果未提供，则基于提供的因果模型生成。提供观测数据有助于缓解图中的错误指定，例如根节点或混杂因素之间缺失的交互。
num_samples_conditional – 用于估计分布之间距离的样本大小。样本越多，准确性越高。
max_num_runs – 最大重采样次数，用于估计并报告平均强度。
tolerance – 如果连续两次运行中估计强度的百分比变化低于指定的容差，算法将在达到最大运行次数之前终止。值为0.01表示变化小于1%。然而，为了最小化随机性的影响，必须至少有三次连续运行的变化低于阈值。
n_jobs – 并行运行的作业数量。设置为-1以使用所有处理器。
difference_estimation_func – 可选：如何测量两个分布之间的距离。默认情况下，对于连续目标节点估计方差的差异，对于分类目标节点估计KL散度。

Returns:

每条边的因果强度。

dowhy.gcm.influence.arrow_strength_of_model(conditional_stochastic_model: ConditionalStochasticModel, input_samples: ndarray, num_samples_from_conditional: int = 2000, max_num_runs: int = 5000, tolerance: float = 0.01, n_jobs: int = -1, difference_estimation_func: Callable[[ndarray, ndarray], ndarray | float] | None = None, input_subsets: List[List[int]] | None = None) → ndarray[source]#

dowhy.gcm.influence.intrinsic_causal_influence(causal_model: StructuralCausalModel, target_node: Any, prediction_model: PredictionModel | ClassificationModel | str = 'approx', attribution_func: Callable[[ndarray, ndarray], float] | None = None, num_training_samples: int = 100000, num_samples_randomization: int = 250, num_samples_baseline: int = 1000, max_batch_size: int = -1, auto_assign_quality: AssignmentQuality = AssignmentQuality.GOOD, shapley_config: ShapleyConfig | None = None) → Dict[Any, float][来源]#

计算目标节点的每个上游噪声项（包括目标本身的噪声）对目标的统计属性（例如均值、方差）的因果贡献。我们将这种贡献称为内在的，因为根据定义，噪声项不会继承观察到的父节点的属性。每个噪声项的贡献就是相应节点的内在因果贡献。更多科学细节，请参考下面的论文。

研究论文: Janzing 等人. 通过结构保持干预量化因果贡献. arXiv:2007.00714, 2021.

Parameters:

causal_model – 用于计算其祖先内在因果影响的结构因果模型的目标节点。
target_node – 目标节点，其统计属性将被归因。
prediction_model – 用于估计祖先噪声项子集与目标节点之间函数关系的预测模型。这可以是PredictionModel的实例，字符串'approx'或字符串'exact'。使用'exact'时，通过将给定的噪声输入传播到图中，直接利用图中的基础因果模型，这确保了生成的样本遵循拟合模型。相比之下，'approx'方法涉及基于从图中采样的数据选择和训练合适的模型。这可能会导致与拟合模型结果的偏差，但在某些设置中更快且更稳健。
attribution_func – 可选的归因函数，用于衡量目标节点的统计属性。此函数期望两个输入；某些特征随机化后的预测（即来自噪声节点的样本）和没有特征随机化的基线。如果对不确定性度量（如熵或方差）感兴趣，通常可以忽略基线预测，但如果要基于残差进行估计，则基线预测可能相关。默认情况下，如果预测模型是分类器，则使用熵，否则使用方差。
num_training_samples – 从图形因果模型中抽取的用于拟合预测模型的样本数量（如有必要）。
num_samples_randomization – 从图形因果模型中抽取的噪声样本数量，用于评估集合函数。在这里，这些样本是用于随机化不在子集中的特征的噪声分布的样本。
num_samples_baseline – 从图形因果模型中抽取的用于评估集合函数的噪声样本数量。在这里，这些样本被用作子集中特征的固定观测值。
max_batch_size – 用于从评估样本中估计预测的最大批量大小。这对整体内存使用有显著影响。如果设置为-1，则所有样本将在一个批次中使用。
auto_assign_quality – 为‘approx’预测模型选项自动分配质量。
shapley_config – ShapleyConfig 用于Shapley估计器。

Returns:

每个祖先节点对目标节点的attribution_func定义的统计属性的内在因果贡献。

dowhy.gcm.influence.intrinsic_causal_influence_sample(causal_model: InvertibleStructuralCausalModel, target_node: Any, baseline_samples: DataFrame, noise_feature_samples: DataFrame | None = None, prediction_model: PredictionModel | ClassificationModel | str = 'approx', subset_scoring_func: Callable[[ndarray, ndarray], ndarray | float] | None = None, num_noise_feature_samples: int = 5000, max_batch_size: int = 100, auto_assign_quality: AssignmentQuality = AssignmentQuality.GOOD, shapley_config: ShapleyConfig | None = None) → List[Dict[Any, Any]][source]#

估计上游节点对指定目标节点的内在因果影响，使用提供的基线样本作为参考。在这种情况下，观察值归因于上游节点中存在的噪声因素。与内在因果影响相比，该方法量化了单个观察值的影响，而不是分布的影响。请注意，当前实现仅支持非分类数据，因为需要重建噪声项。

研究论文: Janzing 等人. 通过结构保持干预量化因果贡献. arXiv:2007.00714, 2021.

Parameters:

causal_model – 拟合的可逆结构因果模型。
target_node – 感兴趣的节点。
baseline_samples – 需要估计影响的样本。
noise_feature_samples – 可选的上游节点的噪声样本，用作“背景”样本。如果未提供，则根据图生成新的噪声样本。这些样本用于随机化不在子集中的特征。
prediction_model – 用于估计祖先噪声项子集与目标节点之间函数关系的预测模型。这可以是PredictionModel的实例，字符串'approx'或字符串'exact'。使用'exact'时，通过将给定的噪声输入传播到图中，直接利用图中的基础因果模型，这确保了生成的样本遵循拟合模型。相比之下，'approx'方法涉及基于从图中采样的数据选择和训练合适的模型。这可能会导致与拟合模型结果的偏差，但在某些设置中更快且更稳健。
subset_scoring_func – 用于基于估计感兴趣量的集合函数。此函数期望两个输入；某些特征被置换时模型对某些样本的结果和没有特征被置换时模型对相同样本的结果。默认情况下，估计这些样本均值的差异。
num_noise_feature_samples – 如果没有给出 noise_feature_samples，则从图中抽取噪声样本。此参数表示抽取的数量。
max_batch_size – 用于一次性估计多个预测的最大批次大小。这对整体内存使用有显著影响。如果设置为-1，则所有样本将在一个批次中使用。
auto_assign_quality – 为‘approx’预测模型选项自动分配质量。
shapley_config – ShapleyConfig 用于Shapley估计器。

Returns:

一个字典列表，表示节点对特定样本目标的固有因果影响。也就是说，每个字典属于一个基线样本。

dowhy.gcm.model_evaluation 模块#

class dowhy.gcm.model_evaluation.CausalModelEvaluationResult(mechanism_performances: Dict[str, dowhy.gcm.model_evaluation.MechanismPerformanceResult] | NoneType = None, pnl_assumptions: Dict[Any, Tuple[float, str, float | NoneType]] | NoneType = None, graph_falsification: dowhy.gcm.falsify.EvaluationResult | NoneType = None, overall_kl_divergence: float | NoneType = None, plot_falsification_histogram: bool = True)[来源]#

基础类：object

graph_falsification: EvaluationResult | None = None#

mechanism_performances: Dict[str, MechanismPerformanceResult] | None = None#

overall_kl_divergence: float | None = None#

plot_falsification_histogram: bool = True#

pnl_assumptions: Dict[Any, Tuple[float, str, float | None]] | None = None#

class dowhy.gcm.model_evaluation.EvaluateCausalModelConfig(mechanism_evaluation_kfolds: int = 5, baseline_models_regression: ~typing.List[~typing.Callable[[], ~dowhy.gcm.ml.prediction_model.PredictionModel]] | None = None, baseline_models_classification: ~typing.List[~typing.Callable[[], ~dowhy.gcm.ml.prediction_model.PredictionModel]] | None = None, independence_test_invertible: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray], float] = functools.partial(<function kernel_based>, use_bootstrap=False), significance_level_invertible: float = 0.05, fdr_control_method_invertible: str | None = 'bonferroni', bootstrap_runs_invertible: int = 5, max_num_permutations_falsify: int = 50, independence_test_falsify: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray], float] = functools.partial(<function kernel_based>, use_bootstrap=False, max_num_samples_run=500), conditional_independence_test_falsify: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray, ~numpy.ndarray], float] = functools.partial(<function kernel_based>, use_bootstrap=False, max_num_samples_run=500), falsify_graph_significance_level: float = 0.2, n_jobs: int | None = None)[source]#

基础类：object

因果模型评估的配置。

因果模型评估方法的参数。有关更多详细信息，请参阅参数描述。

Parameters:

mechanism_evaluation_kfolds – 用于评估因果机制的折叠次数。
baseline_models_regression – 用于连续节点的基线模型。图中分配给节点的因果机制与使用这些基线回归模型的加性噪声模型进行比较。
baseline_models_classification – 分类节点的基线模型。图中节点的因果机制将与这些基线模型进行比较。
independence_test_invertible – 一种用于测试输入与可逆因果机制的估计噪声之间独立性的方法。这用于评估所做的模型假设是否成立。
significance_level_invertible – 用于拒绝输入和残差独立这一零假设的显著性水平。
fdr_control_method_invertible – 在进行多重假设检验时的错误发现率控制方法。请注意，我们可以假设这些检验是独立的。
bootstrap_runs_invertible – 独立性测试仅在少量样本子集上运行。此参数指示应在多少个子集上执行测试。使用家族错误控制方法汇总得到的p值。
max_num_permutations_falsify – 用于伪造给定图结构的排列次数。
independence_test_falsify – 一种用于测试两个变量之间独立性的方法，用于证伪给定的图结构。注意，变量可以是多元的。
conditional_independence_test_falsify – 一种用于测试两个变量在给定第三个变量条件下的独立性的方法，用于证伪给定的图结构。注意，这些变量可以是多元的。
falsify_graph_significance_level – 基于置换测试拒绝给定图的显著性水平。这里的默认值0.2高于通常的0.05。考虑降低它以更严格地否定图。
n_jobs – 并行任务的数量。每当评估方法支持并行化时，就会使用此参数。

class dowhy.gcm.model_evaluation.MechanismPerformanceResult(node_name: Any, is_root: bool, crps: float | NoneType, kl_divergence: float | NoneType, mse: float | NoneType, nmse: float | NoneType, r2: float | NoneType, f1: float | NoneType, count_better_performance: int | NoneType, best_baseline_model: str | NoneType, total_number_baselines: int, best_baseline_performance: float | NoneType)[source]#: 基础类：object

dowhy.gcm.model_evaluation.crps(X: ndarray, Y: ndarray, conditional_sampling_method: Callable[[ndarray], ndarray], num_conditional_samples: int = 100, normalize: bool = True) → float[source]#

基于给定的数据和生成过程估计（归一化的）连续排名概率评分（CRPS）。这用于检查概率预测的校准。

Parameters:

X – 输入特征的观测值。
Y – 对应目标值的观测结果。
conditional_sampling_method – 从X的输入样本中采样条件的方法。
num_conditional_samples – 应从条件中抽取的样本数量，用于估计CRPS。
normalize – 如果为True，则在连续情况下，目标值将通过预期Y值的标准差进行归一化。通过这种方式，CRPS在不同尺度之间变得可比较。

Returns:

连续排名概率评分。

dowhy.gcm.model_evaluation.evaluate_causal_model(causal_model: ProbabilisticCausalModel, data: DataFrame, max_num_samples: int = -1, evaluate_causal_mechanisms: bool = True, compare_mechanism_baselines: bool = False, evaluate_invertibility_assumptions: bool = True, evaluate_overall_kl_divergence: bool = True, evaluate_causal_structure: bool = True, config: EvaluateCausalModelConfig | None = None) → CausalModelEvaluationResult[源代码]#

通过运行不同的评估来评估给定的因果模型。

因果机制评估：因果机制的质量通过k折交叉验证进行评估。这意味着模型需要从头开始多次训练，对于较大的模型来说，这可能会花费相当长的时间。在每一折中，模型通过不同的指标进行评估。对于所有模型，都会估计由标准差归一化的连续排名概率评分（CRPS），这是一个重要的指标，可以提供模型性能及其校准的见解。此外，如果节点是数值型的，则计算均方误差（MSE）、归一化MSE（由方差归一化）和R2系数。对于分类节点，则计算F1分数。可选地，将机制的CRPS与基线模型进行比较，以查看是否有基线模型表现显著更好。

可逆功能因果模型假设的评估：可逆因果机制依赖于输入与重构噪声独立的假设。也就是说，假设没有隐藏的混杂因素，噪声应该与节点的父节点独立。这可以通过测试重构噪声与使用的输入样本之间的统计独立性来评估。

生成分布的评估：使用KL散度将因果模型生成的分布与观测数据进行比较。为了避免估计高维数据的KL散度，我们通过计算每个节点的个体边际KL散度的平均KL散度来近似它。

因果图结构的评估：因果图结构通过运行一种方法来验证图的可证伪性进行评估。该方法涉及进行独立性测试，对于更广泛的图可能会消耗大量时间。结果提供了图是否被拒绝的指示。需要注意的是，未被拒绝的图并不能保证其正确性。它仅意味着评估没有找到足够的证据来根据提供的数据反驳因果图。然而，被拒绝的图可能表明其结构存在潜在问题。

这些评估方法的结果应谨慎解释，不应过度解释不良拟合。尽管如此，结果可以提供对因果模型性能的洞察以及潜在的改进领域。

Parameters:

causal_model – 要评估的因果模型。
data – 用于评估的数据。
max_num_samples – 用于评估的最大样本数。如果运行时间过慢，考虑将其设置为较小的值。默认值-1表示使用所有样本。
evaluate_causal_mechanisms – 如果为True，则评估因果机制。
compare_mechanism_baselines – 如果为True，则将因果机制与基线模型进行比较，以查看是否存在表现显著更好的模型选择。如果为False，则跳过此比较。如果evaluate_causal_mechanisms为False，则忽略此选项。
evaluate_invertibility_assumptions – 如果为True，则测试由可逆因果机制表示的模型假设。
evaluate_overall_kl_divergence – 如果为True，则估计生成数据与观测数据之间的KL散度。
evaluate_causal_structure – 如果为True，则评估因果图结构。

Returns:

评估的总结。

dowhy.gcm.model_evaluation.nmse(y_true: ndarray, y_pred: ndarray, squared: bool = False) → float[source]#

基于给定样本估计归一化均方误差（NMSE）。这是通过观测值的方差归一化的均方根误差。

Parameters:

y_true – 观测值。
y_pred – 预测值。
squared – 如果为True，返回归一化的MSE；如果为False，返回归一化的RMSE。

Returns:

归一化的均方误差。

dowhy.gcm.shapley 模块#

该模块提供了用于Shapley值估计的功能。

class dowhy.gcm.shapley.ShapleyApproximationMethods(value)[来源]#

基础类：Enum

自动：当玩家数量低于6时使用EXACT，否则使用EARLY_STOPPING。 EXACT：生成所有可能的子集，并使用相应的子集权重估计Shapley值。 EXACT_FAST：生成所有可能的子集，并通过加权最小二乘回归估计Shapley值。这可以

速度更快，但根据集合函数的不同，数值上可能不太稳定。

SUBSET_SAMPLING: Randomly samples subsets and estimate Shapley values via weighed least squares regression. Here,: 仅使用一定数量的随机抽取子集。
EARLY_STOPPING: Estimate Shapley values based on a few randomly generated permutations. Stop the estimation process: 当Shapley值在运行之间平均变化不大时。
PERMUTATION: Estimates Shapley values based on a fixed number of randomly generated permutations. By fine tuning: 超参数，由于更好地利用了并行化，这可能比早期停止方法更快。

AUTO = (0,)#

EARLY_STOPPING = (3,)#

EXACT = (1,)#

EXACT_FAST = (2,)#

PERMUTATION = (4,)#

SUBSET_SAMPLING = (5,)#

class dowhy.gcm.shapley.ShapleyConfig(approximation_method: ShapleyApproximationMethods = ShapleyApproximationMethods.AUTO, num_permutations: int = 25, num_subset_samples: int = 5000, min_percentage_change_threshold: float = 0.05, n_jobs: int | None = None)[source]#

基础类：object

用于估计Shapley值的配置。

Parameters:

approximation_method – 近似方法的类型（参见 ShapleyApproximationMethods）。
num_permutations – 用于近似Shapley值的排列次数。此值仅用于PERMUTATION和EARLY_STOPPING。在这两种情况下，它表示评估的最大排列次数。请注意，如果Shapley值的变化低于min_percentage_change_threshold，EARLY_STOPPING可能会在达到排列次数之前停止。
num_subset_samples – 用于SUBSET_SAMPLING方法的子集数量。此值在其他情况下不使用。
min_percentage_change_threshold – 此参数仅与EARLY_STOPPING相关，表示在两次运行之间Shapley值的百分比变化的最小要求，以便估计停止。例如，如果值为0.01，则如果每次运行中所有Shapley值的变化小于0.01，则估计将停止。为了减轻随机性的影响，变化需要至少在连续2次运行中保持在阈值以下。
n_jobs – 并行任务的数量。

dowhy.gcm.shapley.estimate_shapley_values(set_func: Callable[[ndarray], float | ndarray], num_players: int, shapley_config: ShapleyConfig | None = None) → ndarray[来源]#

基于提供的集合函数估计Shapley值。这里的集合函数通过获取一组（子集）玩家并返回某个效用值来定义。这是在将第i个玩家的价值归因于玩家子集S的背景下进行的，通过评估v(S u {i}) - v(S)，其中v是集合函数，i不在S中。虽然我们在这里使用术语“玩家”，但这通常是指某个特征/变量。

集合函数的输入是一个二进制向量，指示哪些玩家是集合的一部分。例如，给定4个玩家（1,2,3,4）和一个仅包含玩家1,2,4的子集，则这由向量[1, 1, 0, 1]表示。该函数预计将根据此输入返回一个数值。

注意：集合函数可以是任意的，并且可以类似于计算复杂的操作。请记住，Shapley值的估计可能会变得计算成本高昂，并且需要大量内存。如果运行时间太慢，请考虑更改默认配置。

Parameters:

set_func – 一个期望输入为二进制向量的集合函数，该向量指定哪些玩家是子集的一部分。
num_players – 玩家总数。
shapley_config – 一个配置对象，用于指示近似方法和其他参数。如果未提供，则使用默认配置。为了更快的运行速度或更准确的结果，请考虑创建自定义配置。

Returns:

一个表示每个玩家的Shapley值的numpy数组，即Shapley值的数量与玩家数量相同。第i个条目属于第i个玩家。在这里，集合函数定义了哪个索引属于哪个玩家，并负责保持其一致性。

dowhy.gcm.stats 模块#

dowhy.gcm.stats.estimate_ftest_pvalue(X_training_a: ndarray, X_training_b: ndarray, Y_training: ndarray, X_test_a: ndarray, X_test_b: ndarray, Y_test: ndarray) → float[source]#

估计零假设的p值，即使用较少的参数可以实现相同的回归误差。这意味着，在具有d个特征的数据集A上训练的线性模型相对于特征数量的性能（以平方误差衡量）与在具有k个特征的数据集B上训练的模型相同，其中k < d。这里，两个数据集需要具有相同的目标值。一个小的p值将表明模型性能显著不同。

请注意，所有给定的测试样本都用于f检验。

详情请参见 https://en.wikipedia.org/wiki/F-test#Regression_problems。

Parameters:

X_training_a – 模型A的输入训练样本。
X_training_b – 模型B的输入训练样本。这些样本的特征应少于X_training_a中的样本。
Y_training – 目标训练值。
X_test_a – 模型A的测试样本。
X_test_b – 模型B的测试样本。
Y_test – 测试值。

Returns:

一个在 [0, 1] 区间内的 p 值。

dowhy.gcm.stats.marginal_expectation(prediction_method: Callable[[ndarray], ndarray], feature_samples: ndarray, baseline_samples: ndarray, baseline_feature_indices: List[int], return_averaged_results: bool = True, feature_perturbation: str = 'randomize_columns_jointly', max_batch_size: int = -1) → ndarray[source]#

估计当随机化不属于baseline_feature_indices的特征时，baseline_noise_samples中样本的边际期望。也就是说，此函数估计

y^i = E[Y | do(x^i_s)] := int_x_s’ E[Y | x^i_s, x_s’] p(x_s’) d x_s’,

其中 x^i_s 是来自 baseline_noise_samples 的第 i 个样本，s 表示 baseline_feature_indices，而 x_s’ ~ X_s’ 表示不在 s 中的随机特征。为了近似积分，给定的 prediction_method 会对相同的 x^i_s 但不同的 x_s’ ~ X_s’ 进行多次评估。

Parameters:: prediction_method – 感兴趣的预测方法。该方法应期望接收一个numpy数组作为输入以进行预测。

预测。 :param feature_samples: 来自联合分布的样本。这些用于随机化不在其中的特征。

基线特征索引。

Parameters:

baseline_samples – 应估计其边际期望的样本。
baseline_feature_indices – 特征在s中的列索引。在估计期望时，这些特征的值保持不变。
return_averaged_results – 如果设置为True，则对第i个样本的所有评估结果取期望值

返回 baseline_noise_samples。如果设置为 False，则返回第 i 个样本的所有相应结果。 :param feature_perturbation: 特征置换的类型：

‘randomize_columns_independently’：不在s中的每个特征分别随机排列。 ‘randomize_columns_jointly’：不在s中的所有特征一起排列。请注意，这仍然代表一个干预分布。

Parameters:: max_batch_size – 用于估计预测的最大批量大小。这对结果有显著影响。

总体内存使用情况。如果设置为-1，所有样本将在一个批次中使用。 :return: 如果return_averaged_results为False，则返回一个numpy数组，其中第i个条目属于随机化其余特征时x^i_s的边际期望。如果return_averaged_results为True，则返回一个二维numpy数组，其中第i个条目包含随机化其余特征时x^i_s的所有预测。

dowhy.gcm.stats.merge_p_values_average(p_values: ndarray | List[float], randomization: bool = False) → float[source]#

一种统计上合理的方法，用于将多个可能相关的p值合并为一个。这是“两倍平均值”规则的统计改进（即更强大）版本，遵循定理5.3（第二个方程，F_UA）在

Gasparini, R. Wang, 和 A. Ramdas, 结合可交换的p值, arXiv 2404.03484, 2024

注意，如果 randomization 为 False，我们在这里有 u = 1。通常，随机化需要较少的假设，但会导致非确定性行为。

Parameters:

p_values – p值的列表或数组。
随机化 – 如果为True，u将从[0, 1]中均匀随机选取（非确定性）。如果为False，u将被设置

到1（确定性）。随机化通常更强大，但提供非确定性的结果。 :return: 基于给定p值的单个p值。

dowhy.gcm.stats.merge_p_values_fdr(p_values: ndarray | List[float], fdr_method: str = 'fdr_bh') → float[source]#

合并p值以表示所有由p值表示的假设均为真的全局零假设。

在这里，我们首先根据提供的错误发现率（FDR）控制方法调整给定的p值，然后返回最小值。

Parameters:

p_values – p值的列表或数组。
fdr_method – 错误发现率控制方法。有关各种选项，请参阅此页面。

Returns:

根据给定的FDR方法调整后的最小p值。

dowhy.gcm.stats.merge_p_values_quantile(p_values: ndarray | List[float], p_values_scaling: ndarray | None = None, quantile: float = 0.5) → float[source]#

应用基于分位数的方法将多个可能依赖的p值合并为一个。这是基于以下描述的方法：

Meinshausen, N., Meier, L. 和 Buehlmann, P., 高维回归的p值, J. Amer. Statist. Assoc.104 1671–1681, 2009

Parameters:

p_values – p值的列表或数组。
p_values_scaling – 每个p值的可选缩放因子列表。
quantile – 用于p值调整的分位数。默认情况下，这是中位数（0.5）。

Returns:

位于分位数阈值上的p值。请注意，这是基于缩放值p_values / quantile的分位数。

dowhy.gcm.stats.permute_features(feature_samples: ndarray, features_to_permute: List[int] | ndarray, randomize_features_jointly: bool) → ndarray[source]#

dowhy.gcm.stochastic_models 模块#

本模块定义了抽象类 StochasticModel 的多种实现。

class dowhy.gcm.stochastic_models.BayesianGaussianMixtureDistribution[source]#

基础类: StochasticModel

clone()[source]#

draw_samples(num_samples: int) → ndarray[来源]#: 为拟合模型绘制样本。

fit(X: ndarray) → None[来源]#: 根据数据拟合模型。

class dowhy.gcm.stochastic_models.EmpiricalDistribution[source]#

基础类：StochasticModel

一个从数据样本中均匀采样的随机模型的实现。通过从训练数据集中随机返回一个样本，该模型代表了训练数据边际分布的无参数表示。然而，它不会生成未见过的数据点。为此，请考虑BayesianGaussianMixtureDistribution。

clone()[source]#

property data: ndarray#

draw_samples(num_samples: int) → ndarray[来源]#: 为拟合模型绘制样本。

fit(X: ndarray) → None[来源]#: 根据数据拟合模型。

class dowhy.gcm.stochastic_models.ScipyDistribution(scipy_distribution: rv_continuous | rv_discrete | None = None, **parameters)[source]#

基础类: StochasticModel

表示任何可以由scipy建模的参数分布。

初始化一个随机模型，该模型允许从Scipy中实现的参数分布中进行采样。

For instance, to use a beta distribution with parameters a=2 and b=0.5:: ScipyDistribution(stats.beta, a=2, b=0.5)
Or a Gaussian distribution with mean=0 and standard deviation 2:: ScipyDistribution(stats.norm, loc=2, scale=0.5)

请注意，参数名称需要与相应的Scipy实现中的参数名称一致。更多信息请参见https://docs.scipy.org/doc/scipy/tutorial/stats.html。

Parameters:

scipy_distribution – 在Scipy中实现的连续或离散参数分布。
parameters – 参数化分布的参数集。

clone()[来源]#

draw_samples(num_samples: int) → ndarray[来源]#: 为拟合模型绘制样本。

static find_suitable_continuous_distribution(distribution_samples: ndarray, divergence_threshold: float = 0.01) → Tuple[rv_continuous, Dict[str, float]][source]#: 尝试找到给定样本的最佳拟合连续参数分布。这是通过拟合不同的参数模型并选择观察样本和生成样本之间KL散度最小的模型来实现的。

fit(X: ndarray) → None[来源]#: 根据数据拟合模型。

static map_scipy_distribution_parameters_to_names(scipy_distribution: rv_continuous | rv_discrete, parameters: Tuple[float]) → Dict[str, float][source]#

辅助函数，用于获取从参数名称到参数值的映射。根据分布是离散还是连续，参数名称略有不同。给定的参数假定遵循scipy拟合函数提供的顺序。

Parameters:

scipy_distribution – scipy 分布。
parameters – 分布的相应参数的值。这里，期望按照与scipy fit函数定义的相同顺序。

Returns:

一个将参数名称映射到其值的字典。

property parameters: Dict[str, float]#

property scipy_distribution: rv_continuous | rv_discrete | None#

dowhy.gcm.uncertainty 模块#

用于估计不确定性（如熵、KL散度等）的函数。

dowhy.gcm.uncertainty.estimate_entropy_discrete(X: ndarray) → float[source]#

假设X中的数据是离散的，估计熵。

Parameters:: X – 离散样本。
Returns:: X的熵。

dowhy.gcm.uncertainty.estimate_entropy_kmeans(X: ndarray) → float[source]#: 相关论文： Kozachenko, L., & Leonenko, N. (1987). 随机向量熵的样本估计. Problemy Peredachi Informatsii, 23(2), 9–16.

dowhy.gcm.uncertainty.estimate_entropy_of_probabilities(X: ndarray) → float[来源]#: 估计X中每个概率向量（按行）的熵，并返回所有结果的平均值。

dowhy.gcm.uncertainty.estimate_entropy_using_discretization(X: ndarray, bin_width: float = 1) → float[source]#

dowhy.gcm.uncertainty.estimate_gaussian_entropy(X: ndarray) → float[来源]#: 关于标准化变量的熵。

dowhy.gcm.uncertainty.estimate_variance(X: ndarray) → float[source]#

dowhy.gcm.unit_change 模块#

本模块提供了用于归因统计单位确定性机制输出值变化的API。

class dowhy.gcm.unit_change.LinearPredictionModel[source]#

基础类：object

abstract property coefficients: ndarray#

class dowhy.gcm.unit_change.SklearnLinearRegressionModel(sklearn_mdl: LinearModel)[source]#

基础类：SklearnRegressionModel, LinearPredictionModel

property coefficients: ndarray#

dowhy.gcm.unit_change.unit_change(background_df: DataFrame, foreground_df: DataFrame, input_column_names: List[str], background_mechanism: PredictionModel, foreground_mechanism: PredictionModel | None = None, shapley_config: ShapleyConfig | None = None) → DataFrame[source]#

此函数将统计单元确定性机制输出值的变化归因于每个输入，如果提供了foreground_mechanism，则还可以归因于机制本身。技术方法在以下研究论文中描述： Kailash Budhathoki, George Michailidis, Dominik Janzing. 解释单元级变化的根本原因. arXiv, 2022.

Parameters:

background_df – 背景数据集。
foreground_df – 前景数据集。
input_column_names – 输入列的名称。
background_mechanism – 背景机制。如果机制没有改变，则使用此机制进行归因。
foreground_mechanism – 前景机制。如果提供，该方法还会将输出变化归因于机制的变化。
shapley_config – 用于计算Shapley值的配置。

Returns:

一个包含每个输入的贡献的数据框，以及可选的机制，用于确定给定输入下确定性机制输出值变化的机制。

dowhy.gcm.unit_change.unit_change_linear(background_mechanism: LinearPredictionModel, background_df: DataFrame, foreground_mechanism: LinearPredictionModel, foreground_df: DataFrame, input_column_names: List[str]) → DataFrame[source]#

计算机制和每个输入对线性确定性机制输出值变化的贡献。

Parameters:

background_mechanism – 线性背景机制。
background_df – 背景数据。
foreground_mechanism – 线性前景机制。
foreground_df – 前景数据。
input_column_names – 两个数据框中输入列的名称。

Returns:

一个pandas数据框，其中包含对提供的每个数据框输出行变化的原因的归因。

dowhy.gcm.unit_change.unit_change_linear_input_only(mechanism: LinearPredictionModel, background_df: DataFrame, foreground_df: DataFrame, input_column_names: List[str]) → DataFrame[源代码]#

计算每个输入对线性确定性机制输出值变化的贡献。

Parameters:

mechanism – 线性机制。
background_df – 背景数据。
foreground_df – 前景数据。
input_column_names – 两个数据框中输入（特征）列的名称。

Returns:

一个pandas数据框，其中包含对提供的每个数据框输出行变化的原因的归因。

dowhy.gcm.unit_change.unit_change_nonlinear(background_mechanism: PredictionModel, background_df: DataFrame, foreground_mechanism: PredictionModel, foreground_df: DataFrame, input_column_names: List[str], shapley_config: ShapleyConfig | None = None) → DataFrame[source]#

计算机制和每个输入对非线性确定性机制输出值变化的贡献。技术方法在以下研究论文中描述： Kailash Budhathoki, George Michailidis, Dominik Janzing. 解释单位级别变化的根本原因. arXiv, 2022.

Parameters:

background_mechanism – 背景机制。
background_df – 背景数据。
foreground_mechanism – 前景机制。
foreground_df – 前景数据。
input_column_names – 两个数据框中输入（特征）列的名称。
shapley_config – 用于计算Shapley值的配置。

Returns:

一个pandas数据框，其中包含对提供的每个数据框输出行变化的原因的归因。

dowhy.gcm.unit_change.unit_change_nonlinear_input_only(mechanism: PredictionModel, background_df: DataFrame, foreground_df: DataFrame, input_column_names: List[str], shapley_config: ShapleyConfig | None = None) → DataFrame[source]#

计算每个输入对非线性确定性机制输出值变化的贡献。技术方法是对以下研究论文中描述的归因方法的修改，没有将机制作为参与者： Kailash Budhathoki, George Michailidis, Dominik Janzing. 解释单位级别变化的根本原因. arXiv, 2022.

Parameters:

mechanism – 机制。
background_df – 背景数据。
foreground_df – 前景数据。
input_column_names – 两个数据框中输入（特征）列的名称。
shapley_config – 用于计算Shapley值的配置。

Returns:

一个pandas数据框，其中包含对提供的每个数据框输出行变化的原因的归因。

dowhy.gcm.validation 模块#

包含一种方法来拒绝因果图并验证因果机制，例如后非线性模型。

class dowhy.gcm.validation.RejectionResult(value)[source]#

基础类：Enum

一个枚举。

NOT_REJECTED = (<enum.auto object>,)#

REJECTED = 1#

dowhy.gcm.validation.refute_causal_structure(causal_graph: ~dowhy.graph.DirectedGraph, data: ~pandas.core.frame.DataFrame, independence_test: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray], float] = <function kernel_based>, conditional_independence_test: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray, ~numpy.ndarray], float] = <function kernel_based>, significance_level: float = 0.05, fdr_control_method: str | None = 'fdr_bh') → Tuple[RejectionResult, Dict[str, Dict[str, Dict[str, bool | float | Dict[str, bool | float]]]]][来源]#

验证因果图中的假设与数据的一致性。为此，在每个节点上，我们测试该节点是否依赖于其每个父节点，并测试局部马尔可夫条件。请注意，有效的局部马尔可夫条件也意味着有效的全局马尔可夫条件。

Parameters:

causal_graph – 一个有向无环图（DAG）。
data – DAG中变量的观测值。
independence_test – 用于检查边缘依赖性的独立性测试。
conditional_independence_test – 用于检查局部马尔可夫条件的条件独立性测试。
significance_level – （条件）独立性检验的显著性水平。
fdr_control_method –
用于控制错误发现率（FDR）的方法。有关各种选项，请参阅此页面。

Returns:

验证过程的结果。元组的第一个元素表示图是否相对于给定数据有效，第二个元素给出了每个节点的测试摘要。以X->Y->Z为例：

[True, {'X': {'local_markov_test': {}, 'edge_dependence_test': {}},
        'Y': {'local_markov_test': {}, 'edge_dependence_test': {'X': {'p_value': 0.5, 'fdr_adjusted_p_value': 0.5, 'success': True}}},
        'Z': {'local_markov_test': {'p_value': 0.0, 'fdr_adjusted_p_value': 0.5, 'success': False},
              'edge_dependence_test': {'Y': {'p_value': 0.5, 'fdr_adjusted_p_value': 0.5, 'success': True}}}}]

dowhy.gcm.validation.refute_invertible_model(causal_model: ~dowhy.gcm.causal_models.InvertibleStructuralCausalModel, data: ~pandas.core.frame.DataFrame, independence_test: ~typing.Callable[[~numpy.ndarray, ~numpy.ndarray], float] = <function kernel_based>, significance_level: float = 0.05, fdr_control_method: str | None = None) → RejectionResult[source]#

验证结构因果模型可以由InvertibleFunctionalCausalModel表示的假设（例如，因果机制是AdditiveNoiseModels和/或PostNonlinearModels）。为此，检查因果机制的残差是否独立于机制的输入（即我们在这里假设因果充分性）。例如，PostNonlinearModels表示

Y = f(g(X) + N),

其中 f 是可逆的（g 不需要是可逆的），X 是 Y 的父节点，N 是（假设为）独立噪声。后一点在这里很重要。对于给定的数据，我们可以重建 N 并在 X 和 N 之间执行独立性测试。

请注意，此方法仅验证因果机制，而不验证图结构。

For the case of post non-linear models, see the following paper for more details:: 张, K., 和 A. Hyvärinen. 关于后非线性因果模型的可识别性. 第25届人工智能不确定性会议 (UAI 2009). AUAI出版社, 2009.

Parameters:

causal_model – 一个已拟合的可逆结构因果模型。
data – DAG中变量的观测值。
independence_test – 用于检查残差和输入是否相关的独立性检验。
significance_level – 用于决定输入和残差是否相关的显著性水平。
fdr_control_method –
用于控制错误发现率（FDR）的方法。有关各种选项，请参阅此页面。

Returns:

验证的结果。如果所有因果机制都与可逆模型假设一致，则不能拒绝因果模型。

dowhy.gcm.whatif 模块#

该模块提供了回答假设问题的功能。

dowhy.gcm.whatif.average_causal_effect(causal_model: ProbabilisticCausalModel, target_node: Any, interventions_alternative: Dict[Any, Callable[[ndarray], float | ndarray]], interventions_reference: Dict[Any, Callable[[ndarray], float | ndarray]], observed_data: DataFrame | None = None, num_samples_to_draw: int | None = None) → float[source]#

估计两组不同干预措施对目标的平均因果效应（ACE）。干预措施可以通过参数interventions_alternative和interventions_reference来指定。例如，如果替代干预是do(T := 1)，而参考干预是do(T := 0)，那么平均因果效应由ACE = E[Y | do(T := 1)] - E[Y | do(T := 0)]给出：

>>> average_causal_effect(causal_model, 'Y', {'T': lambda _ : 1}, {'T': lambda _ : 0})

We can also specify more complex interventions on multiple nodes:

>>> average_causal_effect(causal_model,
>>>                       'Y',
>>>                       {'T': lambda _ : 1, 'X0': lambda x : x + 1},
>>>                       {'T': lambda _ : 0, 'X0': lambda x : x * 2})

在上面，我们将估计 ACE = E[Y | do(T := 1), do(X0 := X0 + 1)] - E[Y | do(T := 0), do(X0 := X0 * 2)]。

注意：目标节点可以是连续实值变量或最多具有两个类别的分类变量（即二元）。

Parameters:

causal_model – 我们执行此干预的概率因果模型。
target_node – 为其估计ACE的目标节点。
interventions_alternative – 定义替代值干预措施的字典。
interventions_reference – 定义参考值干预措施的字典。
observed_data – 我们为因果图中的节点观察到的实际数据。默认情况下，新数据是使用因果模型进行采样的。如果有观测数据可用，提供它们可能会通过减轻由于图或因果模型指定错误而引起的问题来提高准确性。
num_samples_to_draw – 如果没有给出观察数据，从因果模型中抽取的样本数量用于估计ACE。

Returns:

估计的平均因果效应（ACE）。

dowhy.gcm.whatif.counterfactual_samples(causal_model: StructuralCausalModel | InvertibleStructuralCausalModel, interventions: Dict[Any, Callable[[ndarray], float | ndarray]], observed_data: DataFrame | None = None, noise_data: DataFrame | None = None) → DataFrame[source]#

如果我们执行指定的干预措施，估计观察数据的反事实数据。此函数实现了Pearl提出的计算反事实的三步过程（参见https://ftp.cs.ucla.edu/pub/stat_ser/r485.pdf）。

Parameters:

causal_model – 我们执行此干预的（可逆）结构因果模型。如果 noise_data 为 None 且提供了 observed_data，则这必须是一个可逆的结构模型，否则，这可以是一个结构因果模型或一个可逆的模型。
interventions – 包含我们想要执行的干预的字典，按节点名称键控。干预是一个函数，它接受一个值作为输入并返回另一个值。例如，{‘X’: lambda x: 2} 模仿了原子干预 do(X:=2)。
observed_data – 我们在因果图中观察到的节点的实际数据。
noise_data – 对应于因果图中节点的噪声项数据。如果未提供，则必须从观测数据中估计这些数据。然后我们要求节点的因果模型是可逆的。

Returns:

估计的反事实数据。

dowhy.gcm.whatif.interventional_samples(causal_model: ProbabilisticCausalModel, interventions: Dict[Any, Callable[[ndarray], float | ndarray]], observed_data: DataFrame | None = None, num_samples_to_draw: int | None = None) → DataFrame[source]#

对因果图中的节点进行干预。

Parameters:

causal_model – 我们执行此干预的概率因果模型。
interventions – 包含我们想要执行的干预措施的字典，按节点名称键控。干预是一个函数，它接受一个值作为输入并返回另一个值。例如，{‘X’: lambda x: 2} 模仿了原子干预 do(X:=2)。软干预可以表示为 {‘X’: lambda x: 0.2 * x}。
observed_data – 可选地，执行干预的数据。如果没有提供，则基于生成模型生成数据。
num_samples_to_draw – 从干预分布中抽取的样本大小。

Returns:

来自干预分布的样本。

模块内容#

gcm 子包提供了基于图形因果模型（GCM）推理的功能。