Causalens - Causal DAG Summarization 💻

Technologies Getting Started

Causalens is a demo tool designed to demonstrate how large causal DAGs (Directed Acyclic Graphs) can be summarized into smaller graphs while preserving core causal structure. This approach helps users work with high-dimensional DAGs more effectively and conduct causal inference without being overwhelmed by too many nodes or edges.

Key Features

• Interactive UI: Built with Streamlit, offering an intuitive interface for uploading or generating DAGs.
• Configurable Summarization: Size Constraint: Limit the number of nodes in the resulting summary DAG.
• Semantic Threshold: Cluster nodes only if they have sufficient semantic similarity.
• Graph Editing: Add or remove edges on the original DAG—ideal for correcting minor errors or exploring hypothetical changes.
• Causal Inference: Compute Average Treatment Effects (ATE) and other causal measures on both the original and summarized DAG for comparison.
• Robustness: Summaries remain informative even if the input DAG has missing or redundant edges.

📱 Visit this Project

💻 Technologies

These libraries and frameworks together power the CaGreS demo tool, ensuring a seamless experience from data import to summarization and causal inference.

🚀 Getting started

Choose your platform of installation:

• Windows
• Linux
• macOS
• Docker

Prerequisites

• Git 2+: Ensure you have Git installed and configured.
• Python 3.11: Required for the Streamlit app and data manipulations (above versions of Python were not tested).
• C/C++ Compiler (on Windows, you typically need the Build Tools for Visual Studio or a full Visual Studio installation) if you plan to install pygraphviz via pip (it compiles native code).
• Docker (optional): If you prefer running the tool in a container (recommended for Windows users).

Cloning

git clone https://github.com/weaver20/CasualDAG_Sum.git
cd /CasualDAG_Sum

This downloads the code and moves you into the project directory.

Starting

Windows

1. Open Windows PowerShell.

2. Create a virtual environment (named venv for example):

   python -m venv venv

3. Activate the virtual environment:

   venv\Scripts\activate

4. Installing System-Level Graphviz: you must install the system-level Graphviz with development headers.

   • Download the Graphviz installer for Windows from the official Graphviz website.
   • Run the installer and select a Complete or Custom installation that includes the C headers (development libraries).
   • By default, it installs to something like: C:\Program Files\Graphviz, Inside this folder, you should see:
     • bin\ (contains dot.exe, etc.)
     • include\graphviz (should contain cgraph.h)
     • lib\ or lib64\ (contains .lib files for linking)
   • Add Graphviz bin folder to PATH (ensure to restart the PowerShell terminal afterwards).

5. Once Graphviz (with headers) is installed and on your system, you can install PyGraphviz:

   pip install pygraphviz

   • If that fails with an error like graphviz/cgraph.h: No such file or directory, it means the compiler can’t find the headers. Try the following:

   • Add Graphviz’s include and lib folders to your environment variables so MSVC can see them:

     $Env:INCLUDE = "C:\Program Files\Graphviz\include;$Env:INCLUDE"
     $Env:LIB = "C:\Program Files\Graphviz\lib;$Env:LIB"

   • Re-install with no cache (to force a rebuild):

     pip install --no-cache-dir --force-reinstall pygraphviz

   • If it still can’t find the headers, you can specify them directly:

     pip install --no-cache-dir pygraphviz \
      --global-option=build_ext \
      --global-option="-IC:\Program Files\Graphviz\include" \
      --global-option="-LC:\Program Files\Graphviz\lib"

   • If installation succeeds, open a Python shell and execute:

     import pygraphviz
     print(pygraphviz.__version__)

   Check the output, if there are no errors it means pygraphviz has been successfully installed and is now usable.

6. Check Python version, then install dependencies:

   pip install -r requirements.txt

7. Start the streamlit app:

   python -m streamlit run app.py --server.port 8081 --server.address localhost

Linux

1. Open a terminal and install Python if needed:

   sudo apt-get install python3-pip

2. Install Graphviz and Dev Headers:

   • Dbian/Ubuntu:

     sudo apt-get update
     sudo apt-get install build-essential graphviz libgraphviz-dev pkg-config

   • Fedora/CentOS/RHEL:

     sudo dnf install graphviz graphviz-devel

     This ensures both the runtime (dot, etc.) and the development headers (like cgraph.h).

3. Install PyGraphviz:

   pip install pygraphviz

   • If it still can’t find headers, you may need to manually specify:

     pip install pygraphviz --no-cache-dir \
     --global-option=build_ext \
     --global-option="-I/usr/include/graphviz" \
     --global-option="-L/usr/lib"

     Adjust paths for your distro if needed.

4. Install PyVis:

    pip install pyvis

5. Install dependencies:

   pip install -r requirements.txt

6. Start the streamlit app:

   python -m streamlit run app.py --server.port 8081 --server.address localhost

macOS

1. Install Homebrew (if you don’t have it yet):

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install Graphhviz:

   brew install graphviz

   This includes the development headers by default.

3. Install PyGraphviz (if needed):

   pip install pygraphviz

   • If you encounter missing header errors, ensure you have Xcode Command Line Tools installed:

     xcode-select --install

   • Sometimes specifying include/lib paths is required:

     pip install pygraphviz --no-cache-dir \
      --global-option=build_ext \
      --global-option="-I/usr/local/include/graphviz" \
      --global-option="-L/usr/local/lib"

     (Adjust paths if brew installed Graphviz elsewhere—often under /opt/homebrew on Apple Silicon or /usr/local on Intel.)

4. Install PyVis:

   pip install pyvis

5. Install dependencies:

   pip install -r requirements.txt

6. Start the streamlit app:

   python -m streamlit run app.py --server.port 8081 --server.address localhost

Docker

1. Build the Docker image:

   docker build -t your-image-name .

2. Run the container:

   docker run -p 8501:8501 your-image-name

3. Access it through the browser at http://localhost:8501 or at http://0.0.0.0:8501.

• The Dockerfile is configured to expose PORT 8501 as an input to the container in order to communicate with the Streamlit application, but feel free to change it according to your desire.
• Running the app on a container prevents changes to reflect instantly (in case you test any changes within the source code on your local repository). In case you would like to test changes you will be required to re-build the Docker image and re-run the Docker container.

📫 Contribute

Contributions are highly appreciated! If you’d like to help:

1. Fork this repository and create a new branch for your feature or bug fix.
2. Make your changes, ensuring they align with our coding style and add relevant tests if possible.
3. Commit your code with clear messages.
4. Open a pull request describing the changes you’ve made and their motivation.

For major changes or big new features, feel free to open an Issue first to discuss your idea and gather feedback from maintainers and the community. We look forward to collaborating with you!

Documentations that might help

📝 How to create a Pull Request

💾 Commit pattern