falsify.falsify_graph()

Falsify a whole DAG against data via a node-permutation test.

Usage

falsify.falsify_graph(
    graph_info,
    data,
    *,
    n_permutations=None,
    significance_level=0.05,
    significance_ci=0.05,
    include_unconditional=True,
    random_seed=None
)

Implements the permutation test of Eulig et al. (2023). The given DAG’s count of Local Markov Condition (LMC) violations is compared to a baseline of randomly relabeled competitor graphs. The DAG is informative when few permutations share its Markov equivalence class. An informative DAG that violates fewer LMCs than the permuted baseline is the positive case: not contradicted and testable. A non-informative DAG is also not rejected, but that verdict is vacuous — interpret it as not falsifiable rather than as evidence for the graph.

Conditional independence is tested with partial correlation, the same linear-Gaussian methodology used by pathmc.identify.test_implications(). Because the test is linear, purely nonlinear dependencies are not detected, so a “not rejected” verdict is only as strong as the linear-Gaussian assumption. The test uses observed data directly and works before sampling.

Parameters

graph_info: GraphInfo

DAG from the structural model. Only contemporaneous (non-temporal) directed edges are used; temporal lag(...) terms appear as ordinary contemporaneous nodes, so falsification targets cross-sectional (observed-variable) structure. Residual covariances (~~) are not supported and raise ValueError.

data: nw.DataFrame

Observed data. Variables without a usable numeric column (latent nodes, or non-numeric columns) are skipped in CI tests but still participate in the d-separation oracle and node permutations.

n_permutations: int | None = None

Number of permuted DAGs in the baseline. Defaults to round(1 / significance_level) (20 at the default level). For small graphs (at most 7 nodes), if this meets or exceeds the number of distinct node relabelings (n!), all of them are enumerated exactly; otherwise random relabelings are sampled.

significance_level: float = 0.05

Significance level for the permutation-based verdict (default 0.05).

significance_ci: float = 0.05

Significance level for each conditional independence test (default 0.05).

include_unconditional: bool = True

Whether to also test the unconditional independences implied by root nodes (default True).

random_seed: int | None = None

Seed for the permutation sampler, for reproducible results.

Returns

FalsificationResult

Verdict (.falsified, .falsifiable), permutation p-values, per-test local violations, and a .plot() helper.

Raises

ValueError

If significance_level or significance_ci is not in (0, 1); if n_permutations is not a positive integer (or, for a large graph, exceeds the sampling cap); or if the model declares a residual covariance (~~), which is unsupported.