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][source]#

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 本身）的重构噪声。通过这种方式，可以估计上游异常相对于异常噪声值解释了多少异常分数。

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

相关论文：Janzing, D., Budhathoki, K., Minorics, L., & Bloebaum, P. (2019). Causal structure based root cause analysis of outliers https://arxiv.org/abs/1912.02724

参数:

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 – 用于 Shapley 估计器的 ShapleyConfig。

返回:

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

dowhy.gcm.anomaly.attribute_anomaly_scores(anomaly_samples: ~numpy.ndarray, distribution_samples: ~numpy.ndarray, anomaly_scoring_func: ~typing.Callable[[~numpy.ndarray], ~numpy.ndarray], attribute_mean_deviation: bool, shapley_config: ~typing.Union[~dowhy.gcm.shapley.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)] 的贡献，即给定评分器的特征相关性。

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

density_estimator = GaussianMixtureDensityEstimator() density_estimator.fit(original_observations) anomaly_scoring_func = lambda x, y: estimate_inverse_density_score(x, y, density_estimator)

相关论文：Janzing, D., Budhathoki, K., Minorics, L., & Bloebaum, P. (2022). Causal structure based root cause analysis of outliers https://arxiv.org/abs/1912.02724

参数:

anomaly_samples – 估计贡献的样本 x。只要 anomaly_scoring_func 支持这些样本的维度，其维度无关紧要。
distribution_samples – 从（非异常）分布 X 中抽取的样本。
anomaly_scoring_func – 一个函数 g，以 X 中的样本作为输入并返回异常分数。
attribute_mean_deviation – 如果设置为 False，则基于 IT 分数估计贡献；如果设置为 True，则基于给定评分函数的特征相关性。
shapley_config – 用于 Shapley 估计器的 ShapleyConfig。

返回:

一个 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]#

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

参数:

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

返回:

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

dowhy.gcm.anomaly_scorer 模块#

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

基类: ABC

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

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

参数:: X – 从底层数据分布中抽取的样本。

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

dowhy.gcm.anomaly_scorers 模块#

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

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

基类: AnomalyScorer

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

score(x) = -log(P(S(X) >= S(x)))

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

有关 IT 分数的更多详细信息，请参阅: 基于因果结构的异常值根本原因分析 Kailash Budhathoki, Patrick Bloebaum, Lenon Minorics, Dominik Janzing (2022)

分数越高，观测值是异常的可能性越高。

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

参数:: X – 从底层数据分布中抽取的样本。

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

class dowhy.gcm.anomaly_scorers.InverseDensityScorer(density_estimator: ~typing.Union[~dowhy.gcm.density_estimator.DensityEstimator, None] = None)[source]#

基类: AnomalyScorer

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

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

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

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

参数:: X – 从底层数据分布中抽取的样本。

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

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

基类: AnomalyScorer

给定一个异常观测值 x 和来自分布 X 的样本，这个分数表示: score(x) = |x - E[X]| / std[X]

此分数根据样本与 X 均值的距离进行评分，并按 X 的标准差进行缩放。这在 Gaussian 变量中也等同于 Z-score。

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

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

参数:: X – 从底层数据分布中抽取的样本。

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

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

基类: AnomalyScorer

给定一个异常观测值 x 和来自分布 X 的样本，这个分数表示: 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 中位数的左侧还是右侧，我们估计两侧的分位数并取最小值。在这里，这些概率是通过计数估计的，由于一半的样本位于中位数的一侧，我们需要将其乘以二以获得双侧分位数。例如

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

然后，x 位于右侧分位数，X 中只有一个样本大于 x。因此，我们得到: 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]#

参数:: X – 从底层数据分布中抽取的样本。

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

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

基类: AnomalyScorer

给定一个异常观测值 x 和来自分布 X 的样本，这个分数表示: score(x) = |x - med[X]| / mad[X]

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

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

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

参数:: X – 从底层数据分布中抽取的样本。

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

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

基类: AnomalyScorer

类似于 RescaledMedianCDFQuantileScorer，但此评分器更直接地基于秩和可交换性假设。

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

具体来说，p 值计算为以下各项中的最小值：1. 从上开始的秩乘以二再除以样本总数。2. 从下开始的秩乘以二再除以样本总数。3. 1（确保 p 值至多为 1）。

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

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

例如: X = [-3, -2, -1, 0, 1, 2, 3] x = 2.5
然后，: 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[source]#

参数:: X – 从底层数据分布中抽取的样本。

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

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

基类: AnomalyScorer

给定一个异常观测值 x 和来自分布 X 的样本，这个分数表示: score(x) = -log(2 * min[P(X > x) + P(X = x) / 2, P(X < x) + P(X = x) / 2])

这里认为两个 NaN 值相等。

这是通过计算负对数概率 -log(1 - s) 获得的 MedianCDFQuantileScorer 分数 s 的重缩放版本。这样做的好处是可以放大概率的微小差异，特别是当它们接近 0 时。例如，概率 0.02 和 0.01 之间的差异似乎很小且不重要，但重缩放后的差异将显著更大：-log(0.02) - log(0.01) −= 8.5。

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

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

参数:: X – 从底层数据分布中抽取的样本。

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

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]][source]#

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

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

自动选择考虑以下类型的因果机制

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

如果是非根节点且数据是连续的：Addivive Noise Models (ANM) 的形式为 Y = f(X) + N，其中 X 是输入（通常是 Y 的直接因果父节点），并且假设未观测到的噪声 N 独立于 X。为了选择最优的 f 模型，会评估不同的回归模型，并选择均方误差最小的模型。请注意，最小化均方误差等价于选择最优的 ANM 模型。更多详细信息请参阅以下论文

Hoyer, P., Janzing, D., Mooij, J. M., Peters, J., & Schölkopf, B. (2008). Nonlinear causal discovery with additive noise models. Advances in neural information processing systems, 21

如果是非根节点且数据是离散的：离散 Addivive Noise Models 的定义几乎与非离散 ANM 相同，但有一个额外的约束是返回离散值。请注意，这里的“离散”指的是有顺序的数值。如果数据是分类的，请考虑将其表示为字符串以确保正确的模型选择。更多详细信息请参阅以下论文

Peters, J., Janzing, D., & Scholkopf, B. (2011). Causal inference on discrete data using additive noise models. IEEE Transactions on Pattern Analysis and Machine Intelligence, 33(12), 2436-2450.

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

当前的模型库是

使用“GOOD”质量

数值型: - Linear Regressor - Linear Regressor with polynomial features - Histogram Gradient Boost Regressor

分类型: - Logistic Regressor - Logistic Regressor with polynomial features - Histogram Gradient Boost Classifier

使用“BETTER”质量

数值型: - Linear Regressor - Linear Regressor with polynomial features - Gradient Boost Regressor - Ridge Regressor - Lasso Regressor - Random Forest Regressor - Support Vector Regressor - Extra Trees Regressor - KNN Regressor - Ada Boost Regressor

分类型: - Logistic Regressor - Logistic Regressor with polynomial features - Histogram Gradient Boost Classifier - Random Forest Classifier - Extra Trees Classifier - Support Vector Classifier - KNN Classifier - Gaussian Naive Bayes Classifier - Ada Boost Classifier

使用“BEST”质量：基于 AutoGluon（可选依赖项，需要安装）的 AutoML 模型。虽然模型选择本身很快，但训练和推理速度可能比其他选项慢得多。注意：这需要可选的 autogluon.tabular 依赖项。

参数:

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

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

返回:

一个包含模型选择过程详细信息的汇总对象。

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

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

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

dowhy.gcm.causal_mechanisms 模块#

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

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

基类: PostNonlinearModel

表示形式为: Y = f(X) + N，

的连续函数因果模型，其中 X 是输入（通常是 Y 的直接因果父节点），并且假设未观测到的噪声 N 独立于 X。这是 PostNonlinearModel 的一个特殊实例，其中函数 g 是恒等函数。

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

参数:

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

clone()[source]#

class dowhy.gcm.causal_mechanisms.ClassifierFCM(classifier_model: ~typing.Union[~dowhy.gcm.ml.classification.ClassificationModel, None] = None)[source]#

基类: FunctionalCausalModel, ProbabilityEstimatorModel

表示形式为: Y = f(X, N)，

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

property classifier_model: ClassificationModel#

clone()[source]#

draw_noise_samples(num_samples: int) → ndarray[source]#

返回 [0, 1] 范围内的均匀采样值。

参数:: num_samples – 噪声样本的数量。
返回:: [0, 1] 范围内的噪声样本。

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

返回给定 parent_samples 的类别概率。

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

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

评估模型 Y = f(X, N)，其中 X 是 parent_samples，N 是 noise_samples。这里的累积分布函数由 parent_samples 定义。例如，假设我们有 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) 所覆盖的区间内。

参数:

parent_samples – 输入 X 的样本。
noise_samples – [0, 1] 范围内的噪声样本。

返回:

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

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

拟合底层分类模型。

参数:

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

返回:

None

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

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

基类: ABC

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

abstract clone()[source]#

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 可以取任何整数值。

参数:

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

clone()[source]#

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)

参数:

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

返回:

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

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

给定样本 (X, N)，评估后非线性模型。通过以下步骤完成：

评估 f(X)

评估 f(X) + N

返回 g(f(X) + N)

参数:

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

返回:

基于给定样本的 Y 值。

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

拟合形式为 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

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

参数:

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

返回:

None

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

基类: ConditionalStochasticModel

代表函数因果模型 (FCM)，这是一种特定类型的条件随机模型，定义为

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

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

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

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

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

基类: 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)[source]#

基类: InvertibleFunctionalCausalModel

代表后非线性 FCM，即以下形式的模型：: Y = g(f(X) + N),

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

参数:

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

clone()[source]#

draw_noise_samples(num_samples: int) → ndarray[source]#

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

参数:: num_samples – 噪声样本的数量。
返回:: 一个包含 num_samples 个噪声样本的 numpy 数组。

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)

参数:

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

返回:

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

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

给定样本 (X, N)，评估后非线性模型。通过以下步骤完成：

评估 f(X)

评估 f(X) + N

返回 g(f(X) + N)

参数:

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

返回:

基于给定样本的 Y 值。

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

拟合形式为 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

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

参数:

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

返回:

None

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[source]#

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

基类: ABC

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

abstract clone()[source]#

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

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

dowhy.gcm.causal_models 模块#

此模块定义了图形因果模型 (GCM) 的基本类。

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。

参数:

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

causal_mechanism(node: Any) → StochasticModel | InvertibleFunctionalCausalModel#

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

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

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

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

参数:

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)[source]#

基类: object

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

参数:

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

causal_mechanism(node: Any) → StochasticModel | ConditionalStochasticModel#

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

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

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

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

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

参数:

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)[source]#

基类: ProbabilisticCausalModel

代表结构因果模型 (SCM)，例如 counterfactual_samples() 所需的模型。与 ProbabilisticCausalModel 相比，SCM 使用函数因果模型描述非根节点的数据生成过程。

参数:

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

causal_mechanism(node: Any) → StochasticModel | FunctionalCausalModel#

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

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

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

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

参数:

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[source]#

dowhy.gcm.causal_models.validate_causal_graph(causal_graph: DirectedGraph) → None[source]#

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[source]#

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[source]#

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 个估计分位数（无偏差校正）经验性估计的，其中分位数由给定的 confidence_level 确定。

注意：假设 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)

有关通过自举法估计置信区间的更多详细信息，请参见此处。

参数:

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

返回:

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

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

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'))

参数:

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

返回:

一个元组，包含 (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[source]#

基类: ABC

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

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

dowhy.gcm.density_estimators 模块#

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

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

基类: DensityEstimator

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

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

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

class dowhy.gcm.density_estimators.KernelDensityEstimator1D[source]#

基类: 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]#

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

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

研究论文：Kailash Budhathoki, Dominik Janzing, Patrick Bloebaum, Hoiyi Ng. Why did the distribution change?. Proceedings of The 24th International Conference on Artificial Intelligence and Statistics, PMLR 130:1666-1674, 2021.

参数:

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 的图类时进行自定义。此函数必须复制节点和边。节点的属性将在副本中被覆盖，因此该算法独立于此工厂的属性复制行为。

返回:

默认情况下，如果 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]#

根据“旧”和“新”因果图生成的分布，将 target_node 边际分布的变化归因于上游节点。假设这些图代表相同的因果结构，并且已分别拟合到相应的数据。

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

相关论文：Budhathoki, K., Janzing, D., Bloebaum, P., & Ng, H. (2021). Why did the distribution change? arXiv preprint arXiv:2102.13384。

参数:

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

返回:

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

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 函数进行评估。然后将这些结果对多个不同的父样本进行平均。

参数:

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 manual。

返回:

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

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 值，即原始数据和新数据是由相同的机制生成的。在这里，我们检查指示样本是来自原始数据集还是新数据集的二元标签之间的依赖关系。如果标签不能提供信息来确定样本是来自原始/新分布，那么机制很可能没有改变。

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

参数:

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

返回:

零假设（机制没有改变）的 p 值。

dowhy.gcm.divergence module#

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

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

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[source]#

根据分类器给出的概率估计 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。

参数:

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

返回:

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 et al., 2009)。

尽管理论上这可以处理多维输入，但对于具有多个维度的数据，请考虑使用 estimate_kl_divergence_continuous_clf。

Q. Wang, S. R. Kulkarni, and S. Verdú, “Divergence estimation for multidimensional densities via k-nearest-neighbor distances”, IEEE Transactions on Information Theory, vol. 55, no. 5, pp. 2392-2405, May 2009.

参数:

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 表示使用所有可用核心。请注意，在大多数应用中，并行化这反而会引入更多开销，导致运行速度变慢。

return: 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[source]#

dowhy.gcm.falsify module#

此模块提供了根据观测数据对用户提供的 DAG 进行证伪的功能。

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

基类: object

数据集类，包含使用节点置换检验对图进行证伪的评估结果。

…

属性#

summarydict: 包含评估摘要的字典。
significance_levelfloat: 基于该值对给定 DAG 进行证伪的显著性水平。
falsifiablebool: 给定的 DAG 是否可证伪。
falsifiedbool: 给定的 DAG 是否已被证伪。

significance_level: float#

suggestions: dict | None = None#

summary: dict#

update_significance_level(significance_level: float)[source]#: 更新显著性水平，以决定是否对给定 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[source]#

使用观测数据对给定的 DAG 进行证伪。

此方法返回使用置换检验通过观测数据对用户提供的 DAG 进行证伪的结果。为此，我们通过使用条件独立性 (CI) 检验来测试图所隐含的局部马尔可夫条件 (LMC) 的违反情况，从而构建检验统计量。零假设是给定图的随机节点置换的 LMC 违反数量。我们的检验可以解释为给定图在所隐含的 CI 方面是否显著优于随机图。为了确定给定图是否可被我们的度量证伪，我们实现了第二个检验，该检验报告给定图在所隐含的 CI 方面是否“足够独特”。为此，我们计算随机节点置换中有多少属于与给定图相同的马尔可夫等价类 (MEC)，并且只有当属于与给定图相同 MEC 的置换 DAG 的比例“合理地”小时，我们才得出结论认为给定图是可证伪的。

返回的 EvaluationResult 对象具有两个属性：falsified 和 falsifiable: falsifiable: 给定图所在的 MEC 与 >= 1-significance_level 的置换 DAG 所在的 MEC 不同falsified: 给定图是可证伪的，并且违反的 LMC 少于 >= 1-significance_level 的置换 DAG

默认情况下，我们只运行 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 检验因果最小性的违反情况来完成的。

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

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 的输入特征的基于总体的特征重要性。此方法使用 feature_samples 中给定的所有样本，通过比较 prediction_method 在某些特征随机化时的输出与未随机化特征时的输出。subset_scoring_func 定义了如何比较这些预测。例如，偏差的方差。

如果随机化预测应与原始数据进行比较，则可以通过忽略第二个输入参数（使用所有特征预测的值）并在 set 函数中定义。取而代之的是，可以使用原始数据。

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

相关论文：Janzing, D., Minorics, L., & Bloebaum, P. (2020). Feature relevance quantification in explainable AI: A causal problem. In International Conference on Artificial Intelligence and Statistics (pp. 2907-2916). PMLR.

prediction_method – 一个可调用对象，期望为给定样本返回预测。

参数:

feature_samples – 来自联合分布的样本。
subset_scoring_func – 用于根据模型输出估计感兴趣数量的集合函数。此函数期望两个输入：预测模型在某些特征被置换时的输出，以及模型在同一样本上未置换特征时的输出。集合函数表示样本之间的比较，例如偏差的方差。这随后被用作联盟博弈中的“特征函数”，用于估计 Shapley 值。
max_num_samples_randomization – 用于随机化子集中未包含的特征的最大样本数量。对于更精确的结果（如果样本足够），考虑增加此数量；或者对于更少的内存消耗和更快的运行时间，减少此数量。
max_num_baseline_samples – set 函数评估所用的最大样本数量。这些样本被用作子集中特征的固定观测值。例如，如果 set_function_summary_func 是均值，则此参数定义了用于估计均值的最大样本数量。对于更精确的结果（如果样本足够），考虑增加此数量；或者对于更少的内存消耗和更快的运行时间，减少此数量。
max_batch_size – 一次估计多个预测的最大批量大小。这对总体内存使用量有显著影响。如果设置为 -1，则所有样本都在一个批量中使用。
randomize_features_jointly – 如果设置为 True，则联合置换不在子集中的特征。请注意，这仍然表示干预分布。如果设置为 False，则独立置换不在子集中的特征。注意：链接论文中的理论假设此参数设置为 True。
一个 numpy 数组，包含每个输入特征的特征重要性。
shapley_config – Shapley 估计器的配置。

返回:

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]#

估计 prediction_method 在 baseline_noise_samples 中每个样本的特征重要性。此方法使用 feature_samples 中给定的所有样本作为“背景”样本。也就是说，它们应代表输入特征的联合分布中的样本。subset_scoring_func 定义了 prediction_method 在某些特征随机化时的输出与未随机化特征时的输出之间的比较。最常见的函数是期望之间的差异。

feature_samples – 来自联合分布的样本。这些样本用作“背景样本”，用于随机化不在子集中的特征。

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

prediction_method – 一个可调用对象，期望为给定样本返回预测。

参数:

feature_samples – 来自联合分布的样本。
baseline_samples – 要估计其特征重要性的样本。
subset_scoring_func – 用于根据模型输出估计感兴趣数量的集合函数。此函数期望两个输入：预测模型在某些特征被置换时的输出，以及模型在同一样本上未置换特征时的输出。对于回归模型而言，典型的选择是期望之间的差异。这随后被用作联盟博弈中的“特征函数”，用于估计 Shapley 值。
baseline_target_values – 这些基线值与 prediction_method 的子集特定输出进行比较。如果设置为 None（默认），则基线值为应用于 baseline_noise_samples 的给定 prediction_method 的输出，即空子集的输出。
average_set_function – 如果设置为 True，则将应用于每个感兴趣样本的集合函数的平均结果用于估计 Shapley 值。如果设置为 False，则单独估计每个感兴趣样本的 Shapley 值。
randomize_features_jointly – 如果设置为 True，则联合置换不在子集中的特征。请注意，这仍然表示干预分布。如果设置为 False，则独立置换不在子集中的特征。注意：链接论文中的理论假设此参数设置为 True。
一个 numpy 数组，包含 baseline_noise_samples 中每个样本的特征重要性。
一个 numpy 数组，包含每个输入特征的特征重要性。
shapley_config – Shapley 估计器的配置。

返回:

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]#

估计给定 target_node 直接父节点的基于分布的重要性。也就是说，将直接父节点作为 target_node 的底层因果模型的输入特征的重要性。在这里，未观测到的噪声也被视为直接父节点（输入）。用于估计的样本从给定的因果图中抽取。

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

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

causal_model – 已拟合的结构因果模型。

prediction_method – 一个可调用对象，期望为给定样本返回预测。

参数:

target_node – 感兴趣的因果模型所在的节点。
parent_samples – 给定 target_node 的父节点的样本。如果给定 None，则根据图生成新样本。这些样本用于随机化不在子集中的特征。
subset_scoring_func – 用于根据模型输出估计感兴趣数量的集合函数。此函数期望两个输入：因果模型在某些特征被置换时的输出，以及模型在同一样本上未置换特征时的输出。集合函数表示样本之间的比较，例如偏差的方差。这随后被用作联盟博弈中的“特征函数”，用于估计 Shapley 值。
num_samples_randomization – 用于评估集合函数的背景父样本数量。如果未给定 parent_samples，则表示从父节点的联合分布中生成的样本数量，并用于随机化不在子集中的特征。对于更精确的结果（如果样本足够），考虑增加此数量；或者对于更少的内存消耗和更快的运行时间，减少此数量。
num_samples_baseline – set 函数评估所用的样本数量。这些样本被用作子集中父节点的固定观测值。对于更精确的结果（如果样本足够），考虑增加此数量；或者对于更少的内存消耗和更快的运行时间，减少此数量。
max_batch_size – 一次估计多个预测的最大批量大小。这对总体内存使用量有显著影响。如果设置为 -1，则所有样本都在一个批量中使用。
有两个返回值。一个字典，包含给定 target_node 每个直接父节点的特征重要性，以及噪声的特征重要性。
shapley_config – 用于 Shapley 估计器的 ShapleyConfig。

返回:

dowhy.gcm.fitting_sampling module#

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

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

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

causal_model – 根据给定的因果模型生成新样本。

参数:

num_samples – 要抽取的样本数量。
一个 pandas 数据帧，其中列对应于图中的节点，行对应于抽取的联合样本。

返回:

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

将每个节点的因果机制拟合到数据。这通过迭代遍历图中的节点，并单独调用相应的 fit 函数将其分配的因果机制拟合到数据来完成。由于模块化假设，我们可以独立于其他机制拟合图中的每个机制。对于根节点，训练数据是所提供数据中相应的列。对于非根节点，数据基于节点的父节点及其自身。在拟合节点之前，此函数首先验证分配的机制是否有效，即根节点是否遵循 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 方法。

causal_model – 包含将要拟合的节点机制的因果模型。

参数:

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

返回:

（可选）一个 CausalModelEvaluationResult 对象，通过交叉验证总结了因果机制的性能。

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

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

参数:

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

返回:

None

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. Quantifying Causal Influences. The Annals of Statistics, Vol. 41, No. 5, 2324-2358, 2013.

参数:

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

返回:

每条边的因果强度。

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][source]#

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

研究论文: Janzing et al. Quantifying causal contributions via structure preserving interventions. arXiv:2007.00714, 2021.

参数:

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

返回:

每个祖先节点对由目标节点的 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]#

使用提供的 baseline_samples 作为参考，估计上游节点对指定 target_node 的内在因果影响。在此上下文中，观测值被归因于上游节点中存在的噪声因子。与 intrinsic_causal_influence 相比，此方法量化的是单个观测值而不是分布的影响。请注意，由于需要重建噪声项，当前实现仅支持非分类数据。

研究论文: Janzing et al. Quantifying causal contributions via structure preserving interventions. arXiv:2007.00714, 2021.

参数:

causal_model – 已拟合的可逆结构因果模型。
target_node – 感兴趣的节点。
baseline_samples – 应估计其影响的样本。
noise_feature_samples – 用作“背景”样本的可选上游节点噪声样本。如果未提供 None，则根据图生成新的噪声样本。这些样本用于随机化不属于子集的特征。
prediction_model – 用于估计祖先噪声项子集与目标节点之间函数关系的预测模型。这可以是 PredictionModel 的实例、字符串“approx”或字符串“exact”。使用“exact”时，通过在图中传播给定的噪声输入直接利用图中的底层因果模型，确保生成的样本遵循拟合的模型。相比之下，“approx”方法涉及基于从图中采样的 Hospice 选择和训练合适的模型。这可能导致与拟合模型结果的偏差，但在某些设置下更快且更鲁棒。
subset_scoring_func – 用于基于此估计感兴趣数量的集合函数。此函数需要两个输入：在某些特征被置换时模型对某些样本的输出，以及在没有特征被置换时模型对相同样本的输出。默认情况下，估计这些样本均值之间的差值。
num_noise_feature_samples – 如果未提供 noise_feature_samples，则从图中抽取噪声样本。此参数指示抽取的数量。
有两个返回值。一个字典，包含给定 target_node 每个直接父节点的特征重要性，以及噪声的特征重要性。
auto_assign_quality – 用于“approx” prediction_model 选项的自动分配质量。
shapley_config – 用于 Shapley 估计器的 ShapleyConfig。

返回:

一个字典列表，指示节点对特定样本目标的内在因果影响。即，每个字典对应于一个基线样本。

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)[source]#

基类: 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

因果模型评估的配置。

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

参数:

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]#

根据给定数据和生成过程估计（归一化的）连续排序概率评分（Continuous Ranked Probability Score, CRPS）。这用于检查概率预测的校准。

参数:

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

返回:

连续排序概率评分。

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[source]#

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

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

可逆函数因果模型假设评估：可逆因果机制依赖于输入与重建噪声相互独立的假设。也就是说，假设没有隐藏的混杂因素，噪声应该与节点的父节点相互独立。这可以通过检验重建噪声和所用输入样本之间的统计独立性来评估。

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

因果图结构评估：通过运行证伪图的方法来评估因果图结构。该方法涉及进行独立性检验，对于更广泛的图可能需要大量时间。结果提供了图是否被拒绝的指示。需要注意的是，未被拒绝的图并不能保证其正确性。这仅意味着评估没有发现基于所提供数据推翻因果图的实质性证据。然而，被拒绝的图可能表明其结构存在潜在问题。

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

参数:

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，则评估因果图结构。

返回:

评估摘要。

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

根据给定样本估计归一化均方误差（Normalized Mean Squared Error, NMSE）。即，按观测值方差归一化的均方根误差。

参数:

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

返回:

归一化 MSE。

dowhy.gcm.shapley 模块#

此模块提供 Shapley 值估计功能。

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

基类: Enum

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

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

SUBSET_SAMPLING: 随机采样子集，并通过加权最小二乘回归估计 Shapley 值。这里，: 只使用了特定数量的随机抽取的子集。
EARLY_STOPPING: 基于少量随机生成的置换估计 Shapley 值。停止估计过程: 当两次运行之间 Shapley 值平均不再变化很大时。
PERMUTATION: 基于固定数量的随机生成的置换估计 Shapley 值。通过微调: 超参数，由于更好地利用了并行化，这可能比早期停止方法更快。

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 值的配置。

参数:

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[source]#

根据提供的集合函数估计 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 值的估计计算量可能很大，并且需要大量内存。如果运行时过慢，请考虑更改默认配置。

参数:

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

返回:

一个 numpy 数组，表示每个玩家的 Shapley 值，即 Shapley 值的数量与 num_players 相同。第 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。

参数:

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

返回:

[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_noise_samples 中样本的边际期望，同时随机化不属于 baseline_feature_indices 的特征。也就是说，此函数估计

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 的随机化特征。为了近似积分，对相同的 x^i_s 但不同的 x_s’ ~ X_s’ 多次评估给定的 prediction_method。

参数:: prediction_method – 感兴趣的预测方法。此方法应期望以 numpy 数组作为输入来进行

预测。 :param feature_samples: 来自联合分布的样本。这些样本用于随机化不属于

baseline_feature_indices 的特征。

参数:

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 中的所有特征一起置换。请注意，这仍然表示干预分布。

参数:: 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, and A. Ramdas, Combining exchangeable p-values, arXiv 2404.03484, 2024

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

参数:

p_values – p 值的列表或数组。
randomization – 如果为 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 值，然后返回最小值。

参数:

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

返回:

根据给定 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. and Buehlmann, P., p-values for high-dimensional regression, J. Amer. Statist. Assoc.104 1671–1681, 2009

参数:

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

返回:

位于分位数阈值上的 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[source]#: 为拟合模型绘制样本。

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

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

基类： StochasticModel

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

clone()[source]#

property data: ndarray#

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

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

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

基类： StochasticModel

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

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

例如，使用参数 a=2 和 b=0.5 的 Beta 分布：: ScipyDistribution(stats.beta, a=2, b=0.5)
或者使用均值=0 和标准差=2 的高斯分布：: ScipyDistribution(stats.norm, loc=2, scale=0.5)

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

参数:

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

clone()[source]#

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

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[source]#: 根据数据拟合模型。

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

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

参数:

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

返回:

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

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 中数据是离散时的熵。

参数:: X – 离散样本。
返回:: X 的熵。

dowhy.gcm.uncertainty.estimate_entropy_kmeans(X: ndarray) → float[source]#: 相关论文：Kozachenko, L., & Leonenko, N. (1987). Sample estimate of the entropy of a random vector. Problemy Peredachi Informatsii, 23(2), 9–16.

dowhy.gcm.uncertainty.estimate_entropy_of_probabilities(X: ndarray) → float[source]#: 分别估计 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[source]#: 关于标准化变量的熵。

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

dowhy.gcm.unit_change 模块#

此模块提供了用于将确定性机制的输出值变化归因于统计单元的功能。

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. Explaining the root causes of unit-level changes. arXiv, 2022.

参数:

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

返回:

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

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]#

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

参数:

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

返回:

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

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

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

参数:

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

返回:

一个 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. Explaining the root causes of unit-level changes. arXiv, 2022.

参数:

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

返回:

一个 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. Explaining the root causes of unit-level changes. arXiv, 2022.

参数:

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

返回:

一个 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]]]]][source]#

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

参数:

data – DAG 中变量的观测值。
suggestions – 向用户提供建议。目前，唯一的建议来源来自验证因果最小性（使用 validate_cm）。
independence_test – 用于检查边缘依赖性的独立性检验。
significance_level – （条件）独立性检验的显著性水平。
include_unconditional – 也测试根节点的无条件独立性。
fdr_control_method –
虚假发现率 (FDR) 控制方法。有关各种选项，请参阅此页面。

返回:

验证过程的结果。元组的第一个元素表示图是否相对于给定数据有效，第二个元素给出每个节点的测试摘要。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 之间的独立性检验。

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

对于后非线性模型的情况，请参阅以下论文以获取更多详细信息：: Zhang, K., and A. Hyvärinen. On the Identifiability of the Post-Nonlinear Causal Model. 25th Conference on Uncertainty in Artificial Intelligence (UAI 2009). AUAI Press, 2009.

参数:

causal_model – 已拟合的可逆结构因果模型。
suggestions – 向用户提供建议。目前，唯一的建议来源来自验证因果最小性（使用 validate_cm）。
independence_test – 用于检查残差和输入是否相关的独立性检验。
significance_level – 用于判断输入和残差是否相关的显著性水平。
fdr_control_method –
虚假发现率 (FDR) 控制方法。有关各种选项，请参阅此页面。

返回:

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

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})

我们还可以指定对多个节点进行更复杂的干预：

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

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

参数:

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

返回:

估计的平均因果效应 (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 计算反事实的 3 步过程（参见 https://ftp.cs.ucla.edu/pub/stat_ser/r485.pdf）。

参数:

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

返回:

估计的反事实数据。

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]#

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

参数:

causal_model – 我们在其上执行此干预的概率因果模型。
interventions – 包含我们要执行的干预 measures 的字典，以节点名称为键。干预是一个以值作为输入并返回另一个值的函数。例如，{‘X’: lambda x: 2} 模拟原子干预 do(X:=2)。软干预可以表述为 {‘X’: lambda x: 0.2 * x}。
observed_data – 可选地，用于执行干预的数据。如果未给定，则根据生成模型生成数据。
num_samples_to_draw – 从干预分布中抽取的样本大小。

返回:

从干预分布中抽取的样本。

模块内容#

gcm 子包提供了基于图形因果模型 (GCM) 推理构建的功能。