graphdml¶

Causal effects on networks, with honest confidence intervals.

When a treatment reaches one person, it often reaches their friends too: a vaccine protects the neighbors, a coupon gets shared, a training spreads by word of mouth. graphdml estimates

the ATE: the average effect of treating everyone vs no one, including the ripple
the direct effect (ADE): what the treatment does for the person who receives it
the peer effect (APE): what it does for the people connected to them

using double machine learning with any scikit-learn model, adjusting for confounding that runs through the network, with confidence intervals that account for neighbors being dependent. Graphs can come from pandas, networkx or Neo4j.

Install¶

pip install graphdml               # core
pip install "graphdml[neo4j]"      # with Neo4j support

Requires Python 3.10 or newer.

Quickstart¶

from graphdml import GraphDML
from graphdml.datasets import make_flu_town

ds = make_flu_town()      # 5,000 residents; true effects: -2.0 and -0.5 sick days
model = GraphDML(exposure="sum", random_state=0).fit(ds.data)
print(model.summary())

Where to go next¶


Example datasets	Eight datasets with known truth, and the story behind each
Methodology	Exactly what `fit` computes, and why
Design choices	Each default, with the evidence behind it
Validation	The protocol, and the results
Neo4j integration	Load graphs, write results back, GDS embeddings
API reference	Every public class and function

Does it find real signals?¶

import graphdml
print(graphdml.selftest())

Simulates a world with planted effects and a null twin with none, and checks that graphdml finds the first and stays quiet on the second, while a method that ignores the network does not. See the README for sample output.

Citing¶

The estimator builds on Khatami, Parikh, Chen, Roy and Salimi, Graph Machine Learning based Doubly Robust Estimator for Network Causal Effects (AISTATS 2025). Please cite their paper along with graphdml; see CITATION.cff.