PCI Paper: Computational Notebooks

Companion notebooks for the paper Probabilistic Causal Impact (PCI), available on arXiv at arxiv.org/abs/2609.04177. Each notebook reproduces a specific chunk of the paper’s quantitative content: it verifies the numbers, generates the figures, and stress-tests PCI against alternatives (PN/PS/PNS, marginal SHAP, causal SHAP, gradient-based attribution, classical actual-cause probabilities).

Setup

Requires uv.

uv sync --group docs
make -C docs html       # build this HTML site
make -C docs serve      # browse at http://localhost:8000

Read the notebooks here, on the rendered HTML site. Each one ships with its full publication-quality outputs (figures, tables, print statements). Raw .ipynb files live under docs/source/ if you want to inspect or modify the source.

The notebooks

The set divides cleanly into two halves: closed-form verification of the worked examples (Sections 2 and 4 of the paper) and empirical benchmarks that compare PCI to existing attribution and actual-cause machinery.

Closed-form verification. Small, hand-checkable models where every number quoted in the paper can be recomputed analytically.

Old Boys’ Club Bank: a worked example: Old Boys’ Club Bank: PN, PS, PNS, PCI, SHAP.

Recomputes every number in Section 2 of the paper for the stochastic OBCB example. Population-level and individual (Alice, Bob) versions of Pearl’s PN, PS, PNS; PCI with and without witnesses; plain SHAP and causal SHAP on both the 2-feature and 3-feature games. Closes with a four-method comparison table that drives the paper’s “what each method picks up” discussion. Closed-form throughout, with no Monte Carlo and no fitting.

Signal with Mediation: SHAP, Causal SHAP, and PCI: Signal with mediation: the chain X → M → Y.

Verifies the numerical content of Sections 4.4–4.6 on a linear Gaussian chain with additive noise. Computes plain SHAP, causal SHAP, and PCI (without and with the third variable as witness) on three factual instances, then assembles the full desiderata table. A Monte Carlo cross-check sits alongside each closed-form value.

Causal Archetypes: PCI vs SHAP on Overdetermination, Preemption, and Irrelevance: Three causal archetypes plus an irrelevance control.

Synthetic SCM with linear-necessary-and-sufficient inputs, an overdetermined branch, a preempted branch, and a disconnected control. Runs PCI’s necessity / sufficiency decomposition on two contrasting factual cases (preempted vs. unpreempted regime) and compares against marginal SHAP and causal SHAP on the same model. Demonstrates the methodological gap that motivates the N / S split: SHAP returns one number per feature; PCI returns two, and the two numbers carry distinct structural information.

PCI on Pearl’s Desert Traveller: Pearl’s desert traveler: PCI vs Definition 10.3.5.

Walks through PCI’s three responsibility factors (necessity, sufficiency, joint PNS) on Pearl’s basic deterministic desert traveler, then on a weak-poison variant where the cyanide step is stochastic. Throughout we run PCI under forensic-conditioned noise (one pyro model per scenario with the noise pinned at the scenario’s forensic realisation), with ThinSearchSampler and a hand-rolled enumeration agreeing within Monte Carlo noise. The weak-poison case exhibits three intuitions PCI captures and Pearl’s binary actual-cause indicator structurally cannot: adding noise to a path lowers its own cause’s responsibility; within a scenario the operative cause still wins; reliable causes beat unreliable causes across scenarios.

Empirical benchmarks. Larger experiments that compare PCI to existing machinery on synthetic SCMs and a dynamical SIR model.

Actual Causality Benchmark: PCI vs. classical actual causality.

Compares PCI against Halpern–Pearl-style actual-cause probabilities on the generalised throwing problem. Exact actual-cause computations (one pair, two pairs, scaling sweep) followed by approximate estimation via SearchForExplanation. The runtime / search-space / accuracy plots in the paper come from this notebook.

PCI on a dynamical SIR model with policies: PCI on a dynamical SIR model with policies.

Applies PCI to a Bayesian SIR epidemiological model with two interacting non-pharmaceutical policies (lockdown, mask-wearing). Mirrors the chirho tutorial on explainable reasoning in dynamical systems but swaps the explanatory machinery for the PCI thin-search sampler. Recovers chirho’s qualitative finding (lockdown is the dominant cause of excessive overshoot) while exposing the necessity / sufficiency decomposition that classical actual causality collapses.

Gradient-Based Attribution vs PCI: PCI vs. gradient-based attribution.

Compares PCI’s responsibility scores against gradient / sensitivity-based attribution methods on a controlled synthetic model. Probes invariance to feature scale, sensitivity to priors, and the differential causal effect. Targets the paper’s discussion of why gradient methods are not causally faithful even when their numbers look plausible.