Vector 1
Causal Inference & MMMForecasting & Simulation

Introducing PyCausalSim: Stop Guessing, Start Simulating Causality

Brian J. Curry
Brian J. Curry
November 23, 2025 · 5 min read

A New Python Framework for Causal Discovery Through Simulation

Finally, a tool that tells you WHY things happen, not just WHAT happened

New Version is out, read about it here.

If you’ve ever run an A/B test, analyzed conversion rates, or tried to understand what actually drives your key metrics, you’ve probably faced the same frustrating question:

“Is this really causing the change, or is it just correlation?”

Traditional analytics and machine learning tell you what predicts an outcome. But prediction ≠ causation. And when you need to make decisions — to intervene, to optimize, to change something — you need causation.

Today, I’m excited to introduce PyCausalSim, a new Python framework that uses simulation to discover and validate causal relationships in your data.

The Problem: Correlation Is Easy, Causation Is Hard

Let’s say your conversion rate increased after you reduced page load time. Great! But did the load time cause the increase? Or did something else change at the same time?

  • Maybe you launched a marketing campaign the same week
  • Maybe seasonal effects kicked in
  • Maybe a competitor went offline
  • Maybe it was just random noise

Traditional approaches fail here:

# WRONG: This doesn't work
from sklearn.ensemble import RandomForestRegressor

rf = RandomForestRegressor()
rf.fit(X, y)
print(rf.feature_importances_)  # Tells you what predicts, NOT what causes

Feature importance tells you what predicts your outcome, but it:

  • Doesn’t account for confounding
  • Can’t distinguish cause from effect
  • Fails with selection bias
  • Gives you correlation, not causation

The Solution: PyCausalSim

PyCausalSim takes a different approach. Instead of just finding patterns, it:

  1. Learns the causal structure of your system
  2. Simulates counterfactual scenarios (what would have happened if…)
  3. Validates causal claims with rigorous statistical tests

Here’s how it works:

from pycausalsim import CausalSimulator

# Load your data
simulator = CausalSimulator(
    data=df,
    target='conversion_rate',
    treatment_vars=['page_load_time', 'price', 'design_variant'],
    confounders=['traffic_source', 'device_type']
)

# Discover causal structure
simulator.discover_graph()

# Simulate: What if we reduce load time to 2 seconds?
effect = simulator.simulate_intervention('page_load_time', 2.0)
print(effect.summary())

# Output:
# Effect on conversion_rate: +2.3% (95% CI: [1.8%, 2.8%])
# This is a TRUE causal effect, not just correlation!

What Makes PyCausalSim Different?

1. Simulation-First Approach

Instead of relying solely on statistical assumptions, PyCausalSim uses Monte Carlo simulation to generate counterfactual outcomes. This means you can actually test what would happen if you changed something, without running an expensive A/B test.

2. Multiple Discovery Methods

PyCausalSim supports multiple algorithms for learning causal structure:

  • Constraint-based: PC, FCI algorithms
  • Score-based: GES, FGES algorithms
  • Functional: LiNGAM for non-Gaussian data
  • Neural: NOTEARS (deep learning-based)

Choose the method that fits your data and assumptions.

3. Built-in Validation

Every causal claim is automatically validated:

# Sensitivity analysis
sensitivity = simulator.validate()
sensitivity.confounding_bounds()  # Test for unmeasured confounding
sensitivity.placebo_test()  # Run placebo tests
sensitivity.refute()  # Multiple refutation methods

This helps you catch spurious relationships before you make costly business decisions.

4. Practical Use Cases

PyCausalSim is designed for real-world problems:

E-commerce Conversion Optimization

# Rank true causal drivers of conversion
drivers = simulator.rank_drivers()
# [(page_load_time, 0.15), (price, 0.12), (design, 0.03), ...]

Marketing Attribution

from pycausalsim import MarketingAttribution

# Get TRUE incremental value of each channel
attr = MarketingAttribution(touchpoint_data)
attr.fit(method='shapley')  # Causal Shapley values
weights = attr.get_attribution()

Product Feature Impact

# Understand which features CAUSE engagement
exp = ExperimentAnalysis(ab_test_data)
effect = exp.estimate_effect(method='dr')  # Doubly robust
het = exp.analyze_heterogeneity()  # Who responds differently?

Real-World Example: E-commerce Optimization

Let’s walk through a complete example. Imagine you run an e-commerce site and want to understand what drives conversions:

import pandas as pd
from pycausalsim import CausalSimulator

# Your data
data = pd.read_csv('ecommerce_metrics.csv')

# Initialize
sim = CausalSimulator(
    data=data,
    target='conversion',
    treatment_vars=['page_load_time', 'price', 'shipping_cost'],
    confounders=['traffic_source', 'device', 'time_of_day']
)

# Step 1: Discover causal structure
sim.discover_graph(method='notears')
sim.plot_graph()  # Visualize relationships

# Step 2: Test interventions
load_effect = sim.simulate_intervention('page_load_time', 2.0)
price_effect = sim.simulate_intervention('price', current * 0.9)

# Step 3: Find optimal policy
optimal = sim.optimize_policy(
    objective='maximize_conversion',
    constraints={'price': (10, 50)}
)

print(optimal)
# Tells you the best settings for all variables!

Why This Matters

The difference between correlation and causation isn’t academic — it’s about money:

  • Wasted Ad Spend: If you’re optimizing for the wrong thing, you’re burning budget
  • Wrong Product Decisions: Building features that don’t actually drive engagement
  • Misattributed Credit: Giving credit to channels that aren’t actually working

With PyCausalSim, you can:

- Test before you invest: Simulate interventions before deploying them — Stop wasting money: Find what actually drives results — Make confident decisions: Know the causal effect, not just correlation

Getting Started

Install PyCausalSim directly from GitHub:

pip install git+https://github.com/Bodhi8/pycausalsim.git

Or clone and install locally:

git clone https://github.com/Bodhi8/pycausalsim.git
cd pycausalsim
pip install -e .
Note: PyPI integration coming soon. For now, install directly from GitHub.

Try the quick start example:

from pycausalsim import CausalSimulator
import pandas as pd

# Load your data
data = pd.read_csv('your_data.csv')

# Create simulator
simulator = CausalSimulator(
    data=data,
    target='your_outcome_variable',
    treatment_vars=['variables', 'you', 'can', 'control']
)

# Discover and simulate!
simulator.discover_graph()
effect = simulator.simulate_intervention('your_variable', new_value)
print(effect.summary())

What’s Next

PyCausalSim v0.1.0 is just the beginning. The roadmap includes:

v0.1.x (Q1 2025):

  • PyPI package distribution
  • Core algorithm implementations
  • Extended examples and tutorials

v0.2.0 (Q2 2025):

  • Full uplift modeling
  • Neural causal models
  • Enhanced visualization

v0.3.0 (Q3 2025):

  • Agent-based simulation
  • Time-series causal discovery
  • Real-time inference

v1.0.0 (Q4 2025):

  • Production-ready
  • Full benchmarks
  • Industry case studies

Technical Foundation

PyCausalSim builds on decades of causal inference research:

  • Pearl’s Causality Framework: Structural causal models and do-calculus
  • Potential Outcomes: Rubin causal model for treatment effects
  • Modern ML: Neural networks for causal discovery
  • Simulation: Monte Carlo methods for counterfactuals

It integrates with the broader ecosystem:

  • DoWhy (Microsoft)
  • EconML (Microsoft)
  • CausalML (Uber)
  • Papilon (my complex systems framework)

Join the Causal Revolution

Data science is evolving. We’re moving beyond prediction to understanding:

  • Machine Learning: “What will happen?”
  • Causal Inference: “Why did it happen?”
  • PyCausalSim: “What would happen if…?”

Stop guessing. Start simulating.

Resources

  • GitHub: github.com/Bodhi8/pycausalsim
  • Documentation: pycausalsim.readthedocs.io (coming soon)
  • Examples: Check the examples/ directory
  • Issues: Report bugs or request features on GitHub

Try It Today

pip install git+https://github.com/Bodhi8/pycausalsim.git

Then run:

from pycausalsim import CausalSimulator
# Your causal discovery journey starts here
PyPI package coming soon! For now, install from GitHub.

Found this useful? Star the GitHub repo and share with your team!

Have questions? Open an issue or start a discussion on GitHub.

About the Author

Brian Curry is a Kansas City based Data Scientist, Artificial Intelligence expert and founder of Vector1 Research, a part-time passion project where he explores the frontier of Artificial Intelligence, SEO, Agentic Systems, Machine Learning, Economic Systems, Marketing Modeling, and Econometrics.

His work focuses on building intelligent systems that reveal the causal structures driving performance across marketing, content, and economics. He is the creator of:

  • PyCausalSim: A Python framework for causal discovery through simulation
  • Papilon: An open-source framework for complex system optimization
  • Daedalus: A platform for causal and economic analysis
  • Memory-Node Encapsulation (MNE): A revolutionary data structure for artificial episodic memory and cognitive AI reasoning

Contact: brian at vector1.ai | Vector1 AI Economics Lab

This article may be shared with attribution under Creative Commons Attribution 4.0 International (CC BY 4.0).

License: Creative Commons Attribution 4.0 (CC BY 4.0)

Tags: #causalinference #datascience #python #machinelearning #statistics #abtesting #analytics #simulation #causality

“Correlation is not causation. But simulation can reveal causation.”

Related research