BDCM
Diffusion models for causal inference with unmeasured confounders

Code for the paper Diffusion Model in Causal Inference with Unmeasured Confounders (IEEE SSCI 2023) by Tatsuhiro Shimizu. BDCM (Backdoor Criterion based DCM) uses the backdoor idea to choose which variables enter the diffusion decoder when some confounders are unobserved, improving counterfactual estimates versus DCM in synthetic experiments.

Documentation

Resource	Description
src/bdcm/conf/config.yaml	App defaults (scm, variant, …)
src/bdcm/conf/experiment/	Presets: paper, sanity, preview
tests/	pytest suite (unit + optional integration)

Installation & quick start

git clone https://github.com/tatsu432/BDCM.git
cd BDCM
# uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync
# or: pip install -e .

Run a fast preset (no plots, good for smoke / CI):

export PYTHONPATH=src   # omit if you used pip install -e .
python -m bdcm.experiments experiment=sanity scm=1 variant=simple

Hydra writes under outputs/ (gitignored). Multirun: python -m bdcm.experiments -m experiment=paper,sanity.

Docker

Reproducible environment (Python 3.12, CPU PyTorch, headless Matplotlib). The image uses an editable install under /app so bdcm.config resolves results/ to /app/results (not site-packages).

Build and run (CLI):

docker build -t bdcm:local .
docker run --rm -v "$(pwd)/results:/app/results" -v "$(pwd)/outputs:/app/outputs" bdcm:local experiment=sanity scm=1 variant=simple

Override Hydra args by appending to docker run after the image name (they replace the image CMD but not ENTRYPOINT).

Compose (same volume layout as above):

docker compose build
docker compose run --rm bdcm experiment=preview scm=2 variant=simple

For GPU or CUDA wheels, extend the Dockerfile with an NVIDIA base image and matching PyTorch index; the current file targets CPU only.

Experiment presets

Preset	Use
paper	Full hyperparameters (default CLI experiment)
sanity	Short run, no plots — CI / debugging
preview	Short run with plots for a quick visual check

Override scm=1..5 and variant=simple|complex on the CLI.

Python API

from bdcm import load_experiment_preset, run_scm
from bdcm.experiments.structural import scm1

run_scm(1, scm1.structural_eq_simple, "simple", load_experiment_preset("sanity"))

Compose arbitrary Hydra overrides without the CLI:

from bdcm import compose_config, experiment_config_from_omegaconf

cfg = compose_config(["experiment=preview", "scm=3"])
exp = experiment_config_from_omegaconf(cfg.experiment)

default_experiment_config() loads the paper preset from YAML (same source as the CLI default).

CLI with Hydra

Hydra loads src/bdcm/conf/. Defaults: experiment=paper, scm=1, variant=simple.

export PYTHONPATH=src
python -m bdcm.experiments
python -m bdcm.experiments experiment=sanity scm=2 variant=complex

Tests

From the repo root (pythonpath is set in pyproject.toml):

uv sync --extra dev
uv run pytest

• Fast: pytest -m "not integration" — schedules, presets, MMD, structural SCMs, sampling, validation.
• Integration: tests/test_integration_smoke.py (trains briefly); marked @pytest.mark.integration.

Related work

• Diffusion-based Causal Model (DCM) — observed confounders setting.

Citation

@article{shimizu2023diffusion,
  title={Diffusion Model in Causal Inference with Unmeasured Confounders},
  author={Shimizu, Tatsuhiro},
  journal={arXiv preprint arXiv:2308.03669},
  year={2023}
}