falsify.FalsificationResult

Result of a permutation-based DAG falsification test.

Usage

falsify.FalsificationResult(
    given_lmc_violations,
    n_lmc_tests,
    given_lmc_violation_fraction,
    perm_lmc_violation_fractions,
    perm_tpa_violation_fractions,
    p_value_lmc,
    p_value_tpa,
    n_permutations,
    n_in_mec,
    significance_level,
    significance_ci,
    local_violations
)

Produced by falsify_graph(). The verdict follows Eulig et al. (2023): the DAG is falsifiable (informative) when few node permutations share its Markov equivalence class, and falsified (rejected) when, despite being informative, it does not violate fewer Local Markov Conditions than the permuted baseline.

Parameters

given_lmc_violations: int

Number of Local Markov Condition violations of the given DAG.

n_lmc_tests: int

Number of LMC (parental conditional independence) tests run on the given DAG. Tests requiring unavailable data are not counted.

given_lmc_violation_fraction: float

given_lmc_violations / n_lmc_tests (0 if no tests ran).

perm_lmc_violation_fractions: np.ndarray

Fraction of LMC violations for each permuted DAG, shape (n_permutations,).

perm_tpa_violation_fractions: np.ndarray

Fraction of parental d-separation (tPA) violations for each permuted DAG relative to the given DAG, shape (n_permutations,).

p_value_lmc: float

Fraction of permutations whose LMC violation fraction is less than or equal to the given DAG’s. Small values mean the DAG beats the random baseline.

p_value_tpa: float

Fraction of permutations lying in the Markov equivalence class of the given DAG (zero tPA violations). Small values mean the DAG is informative / falsifiable.

n_permutations: int

Number of permuted DAGs evaluated.

n_in_mec: int

Number of permutations sharing the given DAG’s Markov equivalence class.

significance_level: float

Significance level for the permutation-based verdict.

significance_ci: float

Significance level used for each conditional independence test.

local_violations: pd.DataFrame

One row per LMC test on the given DAG with columns node, non_descendant, conditioning_set, p_value, and violation.

Attributes

Name	Description
can_evaluate	Whether the verdict is well-defined.
falsifiable	Whether the DAG is informative enough to be falsified.
falsified	Whether the data falsify (reject) the DAG.
violations	Subset of local_violations where the LMC test was violated.

---

can_evaluate

Whether the verdict is well-defined.

can_evaluate: bool

False when the DAG implies no testable parental conditional independences (e.g. a fully connected graph), in which case both falsifiable and falsified are None.

---

falsifiable

Whether the DAG is informative enough to be falsified.

falsifiable: bool | None

True when the fraction of permutations in the given DAG’s Markov equivalence class is at most significance_level. None when can_evaluate is False.

---

falsified

Whether the data falsify (reject) the DAG.

falsified: bool | None

True only when the DAG is strictly informative (p_value_tpa < significance_level) and its LMC violations are not clearly better than the permuted baseline (p_value_lmc exceeds significance_level). None when can_evaluate is False.

The strict < on the informativeness side mirrors Eulig et al. (2023) / dowhy, where a DAG sitting exactly at the boundary (p_value_tpa == significance_level) is not rejected.

---

violations

Subset of local_violations where the LMC test was violated.

violations: pd.DataFrame

Methods

Name	Description
plot()	Plot histograms of permuted-baseline violation fractions.

---

plot()

Plot histograms of permuted-baseline violation fractions.

Usage

plot(ax=None, bins=None)

Shows the distribution of LMC violation fractions (blue) and tPA d-separation violation fractions (orange) across permuted DAGs, with dashed vertical lines marking the given DAG’s values. A given DAG far to the left of the LMC histogram beats the baseline.

Parameters

ax: matplotlib.axes.Axes | None = None

Axes to plot on. Creates a new figure if None.

bins: int | str | Sequence[float] | numpy.ndarray | None = None

Passed through to matplotlib.axes.Axes.hist: a positive integer bin count, a binning strategy name such as "auto", or a sequence of bin edges. Defaults to an automatic choice.

Returns

matplotlib.figure.Figure

The figure containing the histogram.

Raises

RuntimeError

If the result cannot be evaluated (no LMC tests).

ValueError

If bins is neither one of the accepted types nor, for an integer bin count, positive. Strategy names and bin edges are validated by matplotlib, which reports them more precisely.