Causalvis: Visualizations for Causal Inference

This repository contains supplemental materials for the ACM CHI 2023 paper titled:

Causalvis: Visualizations for Causal Inference

Causalvis is a python library of interactive visualizations for causal inference, designed to work with the JupyterLab computational environment.

Citation

@inproceedings{Guo_Causalvis_2023,
	address = {Hamburg, Germany},
	title = {{Causalvis}: Visualizations for Causal Inference},
	booktitle = {Proceedings of the 2023 CHI Conference on Human Factors in Computing Systems},
	publisher = {Association for Computing Machinery},
	author = {Guo, Grace and Karavani, Ehud and Endert, Alex and Kwon, Bum Chul},
	year = {2023}
}

Getting Started with Causalvis

The quickest way to ensure that causalvis is installed correctly is to start with a clean conda environment with the exact versions of the following packages:

 conda create -n newenv python=3.8 jupyterlab=3.4 ipywidgets=7.6 ipykernel=5.3 scipy pandas

 conda activate newenv

Install pip for this new environment:

conda install pip

Then install causalvis:

pip install causalvis

The package should show up when you run:

jupyter labextension list

Running Causalvis

In the root project folder, open JupyterLab:

jupyter lab

The notebook folder has a number of examples that demonstrate the various Causalvis modules. We recommend starting with Example_All.ipynb, which has all necessary data sets included and does not require any external packages. Other demo notebooks will require that certain packages are installed such as causallib, causalnex, pandas, scikit-learn, and others. Note that if you created a new conda environment as recommended above, it is recommended that you install these packages using conda, conda-forge, or pip.

To use the causalvis modules in your own projects, you can create a new notebook in python3 and instantiate the widget with the relevant props.

from causalvis import DAG
DAG(attributes=["A", "B"])

Troubleshooting

If you encounter errors when importing causalvis in JupyterLab, first ensure that the package is successfully installed and appears in the Jupyter labextension list.

jupyter labextension list

If this has been verified, check that the python version used by JupyterLab is identical to the version in which causalvis is installed. In cases where there are multiple virtual environments in the same machine, the causalvis package may be installed in a different location.

Documentation

We are working on releasing a comprehensive wiki for causalvis. The link will be updated here as soon as it is ready - check back soon!

Developing for Causalvis

Installation

To run the causalvis library, first clone the repo and install packages:

git clone https://github.com/causalvis/causalvis.git
npm install

Run Modules

To streamline development, we first test components in storybook without installing into JupyterLab.

Start the app with:

npm run storybook

This should open a new browser window. Each module is listed separately in the left hand menu. Some modules may have multiple examples.

Data Sets

All data sets are located under ./public

Integrating Changes into JupyterLab

 conda create -n newenv python=3.8 jupyterlab=3.4 ipywidgets=7.6 ipykernel=5.3

 conda activate newenv

Ensure that the yarn package manager has been installed on your machine. Check for this by running yarn -v.

If this is your first time installing causalvis, you can automate the rest of the installation by running:

sh ./setup.sh

If you would like to complete the initial installation manually, or if ./setup.sh does not work for any reason, the breakdown of steps are as follows.

Install the relevant npm packages and build:

npm install

npm run build

Navigate to the causalvis subfolder (the root causalvis folder has a subfolder by the same name). Then run:

pip install -e .

jupyter labextension develop causalvis --overwrite

The package should show up when you run:

jupyter labextension list

For subsequent updates, it is sufficient to run:

sh ./update.sh

If you would like to complete the update manually, or if ./update.sh does not work for any reason, the breakdown of steps are as follows.

First update the front-end build:

npm run build

Then navigate to the causalvis/js subfolder and run:

yarn run build

After each update (for both ./update.sh and manual approaches), make sure to exit and restart JupyterLab completely for changes to take effect. It is not sufficient to restart the kernel.