Setup for CL KCI in Tetrad - cmu-phil/tetrad GitHub Wiki

Setting up a Python Virtual Environment for CL KCI in Tetrad

This page describes how to set up a Python virtual environment (venv) for running the
causal-learn KCI (Kernel Conditional Independence) test through the experimental
CL KCI (Python bridge) integration in Tetrad.

The setup is intentionally:

  • Isolated (does not affect system Python)
  • Reproducible
  • Optional (users who do not want Python integration can ignore it)

These instructions assume macOS with Homebrew Python, but the same approach works on Linux.

Overview

To use CL KCI in Tetrad, you need:

  1. A Python virtual environment containing:
    • numpy
    • scipy
    • scikit-learn
    • causal-learn
  2. The path to that venv's python executable.

You do not need to manually download the server script.
Tetrad includes a bundled version of:

pytetrad/tools/kci_server.py

which is identical to the version in:

https://github.com/cmu-phil/py-tetrad/blob/main/pytetrad/tools/kci_server.py

By default, Tetrad uses the bundled script.

1. Choose a location for the virtual environment

Pick a stable location that will not move or be deleted accidentally.

Recommended:

~/venvs/tetrad-clkci/

We assume:

VENV_DIR="$HOME/venvs/tetrad-clkci"

Create the parent directory if needed:

mkdir -p "$HOME/venvs"

2. Create the virtual environment

Check your Python:

which python3
python3 --version

Create the venv:

python3 -m venv "$VENV_DIR"

Activate it:

source "$VENV_DIR/bin/activate"

Verify:

which python
python --version

It should point inside ~/venvs/tetrad-clkci.

3. Upgrade pip and build tools

This prevents common PEP 668 or "externally managed environment" errors:

python -m pip install --upgrade pip setuptools wheel

4. Install required packages

Inside the activated venv:

python -m pip install numpy scipy scikit-learn
python -m pip install causal-learn

Sanity check:

python -c "import numpy, scipy, sklearn; import causallearn; print('causal-learn OK')"

If this prints successfully, your environment is ready.

5. Identify the pythonExe path for Tetrad

Tetrad must be told exactly which Python executable to use.

For the venv:

PYTHON_EXE="$VENV_DIR/bin/python"

Verify it works:

"$PYTHON_EXE" --version

This full path is what you provide as pythonExe in Tetrad.

6. Configuring Tetrad

When selecting:

KCI, Causal Learn (Python)

you will configure two parameters:

1. pythonExe

Full path to your venv Python:

/Users/yourname/venvs/tetrad-clkci/bin/python

2. pythonCiServer

Set this to:

Use bundled script

(or leave it blank if that is the default)

You only need to provide a file path here if you are deliberately overriding the bundled script (advanced use).

7. Optional: Smoke-test Python manually

Before launching Tetrad, you can confirm the environment works:

source ~/venvs/tetrad-clkci/bin/activate
python -c "import causallearn; print('causal-learn ok')"

If this succeeds, Tetrad should be able to launch the Python subprocess successfully.

8. Debugging Common Errors

"pythonExe does not exist"

Check the exact path:

ls -l ~/venvs/tetrad-clkci/bin/python

"Python server not ready: Traceback ..."

This usually means:

  • A missing dependency
  • The wrong Python executable
  • A broken venv

Test directly:

~/venvs/tetrad-clkci/bin/python -c "import causallearn"

If that fails, fix the Python environment first.

Process starts but independence tests fail

Check:

  • No NaNs in your dataset (KCI generally does not handle NaNs well)
  • The dataset is continuous
  • The sample size is adequate for kernel testing

9. Intended Usage

The CL KCI integration is intended primarily as:

  • A nonlinear CI test option
  • A benchmarking tool
  • A way to compare Tetrad searches with causal-learn KCI behavior
  • A diagnostic complement to Vertex Checker and Markov Checker

It is currently experimental and not required for normal Tetrad usage.

Quick Checklist

After setup:

source ~/venvs/tetrad-clkci/bin/activate
python -c "import causallearn; print('ok')"

Then in Tetrad:

  • Set pythonExe to your venv's Python
  • Leave pythonCiServer as Use bundled script
  • Run PC / PC-Max / other search

Last updated: CL KCI bundled-script integration phase.