fastcausal

Fast, easy-to-use causal discovery analysis tools for Python.

Overview

fastcausal provides a unified Python interface for causal discovery analysis, combining the functionality of several earlier packages into one pip-installable tool. It supports both interactive Jupyter notebook workflows and config-driven batch processing of large datasets.

Key features:

• No Java dependency — uses tetrad-port (C++ port of Tetrad algorithms) instead of Java
• Seven causal discovery algorithms — PC, FGES, GFCI, BOSS, BOSS-FCI, GRaSP, GRaSP-FCI
• Prior knowledge support — temporal tiers, forbidden/required edges
• Bootstrapped stability analysis — edge frequency selection across subsampled runs
• SEM fitting — automatic structural equation modeling via semopy
• Flexible graph visualization — node styling with fnmatch patterns, multi-graph comparison with shared layouts
• Batch pipeline — config-driven processing of hundreds of cases via CLI (in alpha)
• Report generation — automated Word document reports with embedded graphs (in alpha)

Installation

All features — SEM fitting, Jupyter/matplotlib/seaborn, and Word report generation — are included by default.

Conda install (Miniforge3 recommended)

For reproducible environments (especially for graph tooling and notebooks), use the repository's environment.yml with Miniforge3.

1. Install Miniforge3 (conda-forge based):

   Download and run the installer for your platform (Windows/Linux/MacOSX) from: https://github.com/conda-forge/miniforge/releases/latest

   On Windows machines where you don't have Administrator privileges, on the miniforge install, select "Just Me"

2. Open a new terminal/powershell so conda is available, then create and activate the environment:

   conda env create -f environment.yml
   conda activate fastcausal_env
   

   The environment file already installs fastcausal via pip and the Graphviz binaries required to create/render graphs.

   If you are developing from this repository, replace the PyPI install with an editable install:

   pip uninstall -y fastcausal
   pip install -e .
   

3. Optional sanity check:

python -c "import fastcausal; print(fastcausal.__version__)"

Quick Start

Five lines to your first causal graph:

from fastcausal import FastCausal

fc = FastCausal()
df = fc.load_sample("boston")          # bundled EMA dataset
df = fc.standardize(df)
results, graph = fc.run_search(df, algorithm="gfci", alpha=0.01, penalty_discount=1.0)
fc.show_graph(graph)

Time-series workflow with prior knowledge

For time-series data, add lagged columns, standardize, and encode temporal ordering so that yesterday's values can only be causes (not effects) of today's:

from fastcausal import FastCausal

fc = FastCausal()
df = fc.load_sample("boston")

# Add lagged columns and standardize
lag_stub = "_lag"
df_lag = fc.add_lag_columns(df, lag_stub=lag_stub)
df_std = fc.standardize(df_lag)

# Build temporal prior knowledge explicitly:
# Tier 0 (lag vars) can only be parents of Tier 1 (current-day vars)
cols = df.columns
knowledge = {
    "addtemporal": {
        0: [col + lag_stub for col in cols],
        1: [col for col in cols],
    }
}
# knowledge =>
# {"addtemporal": {
#     0: ["alcohol_bev_lag", "TIB_lag", "TST_lag", "PANAS_PA_lag",
#         "PANAS_NA_lag", "worry_scale_lag", "PHQ9_lag"],
#     1: ["alcohol_bev", "TIB", "TST", "PANAS_PA",
#         "PANAS_NA", "worry_scale", "PHQ9"]
# }}

# Run GFCI causal discovery with SEM fitting
result, graph = fc.run_search(
    df_std,
    algorithm="gfci",
    alpha=0.01,
    penalty_discount=1.0,
    knowledge=knowledge,
)

# Visualize with custom node styles
node_styles = [
    {"pattern": "*_lag",        "style": "dotted"},
    {"pattern": "PANAS_PA*",    "style": "filled", "fillcolor": "lightgreen"},
    {"pattern": "PANAS_NA*",    "style": "filled", "fillcolor": "lightpink"},
    {"pattern": "alcohol_bev*", "shape": "box", "style": "filled",
     "fillcolor": "purple", "fontcolor": "white"},
]
fc.show_graph(graph, node_styles=node_styles)

See fastcausal_demo_short.ipynb for the full interactive demo.

CLI Usage

fastcausal provides a command-line interface for batch processing:

# Data preparation
fastcausal parse --config proj/config.yaml

# Batch causal discovery across cases
fastcausal run --config proj/config.yaml
fastcausal run --config proj/config.yaml --start 0 --end 50
fastcausal run --config proj/config.yaml --list

# Effect size analysis and heatmaps
fastcausal paths --config proj/config.yaml

# Generate Word report
fastcausal report --config proj/config.yaml --mode 2wide

# Quick single-file analysis
fastcausal analyze data.csv --algorithm gfci --output results/

Supported Algorithms

See the Algorithm Guide for detailed parameter reference, edge types, and selection guidance.

Architecture

fastcausal consolidates four earlier codebases into a layered architecture:

pip install fastcausal
        |
    fastcausal  (API + CLI + viz + SEM + batch)
   /          \
tetrad-port    dgraph_flex
(C++ algorithms) (graph rendering)

• tetrad-port — C++ port of CMU Tetrad algorithms, exposed via nanobind
• dgraph_flex — Graphviz-based directed graph rendering

Project Structure

fastcausal/
├── core.py              # FastCausal class (main API)
├── search.py            # Algorithm wrapper (PC, FGES, GFCI, BOSS, GRaSP, ...)
├── sem.py               # SEM fitting via semopy
├── transform.py         # Lag columns, standardization, subsampling
├── knowledge.py         # Prior knowledge handling
├── edges.py             # Edge parsing, selection, deduplication
├── cli.py               # Click-based CLI
├── viz/
│   ├── styling.py       # fnmatch-based node styling
│   ├── graphs.py        # Graph display and save (single + multi)
│   └── plots.py         # Heatmaps and effect size plots
├── pipeline/
│   ├── config.py        # YAML config parsing (v4.0 + v5.0)
│   ├── parse.py         # Data preparation engine
│   ├── batch.py         # Batch causal discovery
│   ├── paths.py         # Effect size analysis
│   ├── report.py        # Word document generation
│   └── metrics.py       # Graph metrics (centrality, ancestors)
└── io/
    ├── data.py           # CSV loading, sample datasets
    └── wearables.py      # Fitbit/Garmin integration (planned)

Documentation

• Algorithm Guide — Algorithm selection, parameters, edge types, prior knowledge
• Migration from fastcda — API mapping for fastcda users
• Migration from cda_tools2 — CLI mapping for cda_tools2 users
• Consolidation Plan — Implementation plan and phase status
• Project Conventions — Development guidelines and conventions

Config File Format

fastcausal uses YAML config files for batch processing. Version 5.0 is the current format; version 4.0 (from cda_tools2) is accepted with a deprecation warning.

GLOBAL:
  version: 5.0
  name: my_project
  title: "My Causal Analysis"

CAUSAL:
  algorithm: gfci
  alpha: 0.05
  penalty_discount: 1.0
  knowledge: prior.txt
  standardize_cols: true

Requirements

• Python >= 3.11
• tetrad-port >= 0.1.0
• dgraph_flex >= 0.1.11
• Graphviz (system install for graph rendering)

License

MIT

Citation

If you use fastcausal in your research, please cite the relevant algorithm papers and this package.

The bundled "boston" EMA dataset is from:

Cunningham TJ, Fields EC, Kensinger EA. "Boston College daily sleep and well-being survey data during early phase of the COVID-19 pandemic." Sci Data. 2021. https://www.nature.com/articles/s41597-021-00886-y