{This is a framework of dataset shift.}
causalshift/
├── __init__.py # Top-level exports
├── config.py # All config dataclasses (YAML read/write)
├── pipeline.py # Main pipeline orchestrator
├── configs/
│ └── default.yaml # Default configuration file
├── stages/
│ ├── stage0_grading.py # Causal knowledge grading: Level A/B/C/D
│ ├── stage0_5_audit.py # Data quality audit (τ score)
│ ├── stage1_detection.py # Three-layer shift detection (MMD/DDM/C2ST)
│ ├── stage2_attribution.py# Causal attribution orchestrator (calls plugins)
│ ├── stage3_routing.py # Attribution-driven method routing table
│ ├── stage4_augmentation.py# Counterfactual data augmentation (Route A/B/C)
│ ├── stage5_modeling.py # Robust modelling (IPW/IRM/CORAL/GDA etc.)
│ ├── stage6_evaluation.py # Causal evaluation (Λ*/DISDE/TATE)
│ └── stage7_monitoring.py # Deployment monitoring (DDM/ADWIN/FHDDM)
├── plugins/
│ ├── base.py # Abstract plugin base class
│ ├── graph_plugin.py # SCM/DAG plugin (Level A)
│ ├── invariance_plugin.py # ICP/NILE plugin (Level B)
│ ├── pom_plugin.py # POM/DRCFS plugin (Level B/C)
│ └── anchor_plugin.py # Anchor Regression plugin (Level B+IV)
├── utils/
│ └── report.py # Output data structures for each stage
├── requirements.txt
└── demo.py # End-to-end usage example
└── run_comparison.py # Baseline comparison experiments
└── run_eval_tables.py # Baseline experiments
For more detailed information, please refer to INSTALL.md
If you use conda to manage the Python environment, simply run the following code:
# macOS / Linux
conda activate CausalShift
bash setup_env.sh # CPU-only build
bash setup_env.sh --gpu117 # GPU build (CUDA 11.7)
bash setup_env.sh --core # Core dependencies only (no PyTorch)
# Windows (Anaconda Prompt)
conda activate CausalShift
setup_env.bat
setup_env.bat --gpu117
setup_env.bat --core
REM Required dependencies
pip install -r requirements.txt
REM Optional dependencies (install as needed; see alibi-detect numpy conflict note)
pip install -r requirements-optional.txt
from causalshift import CausalShiftPipeline, CausalShiftConfig
cfg = CausalShiftConfig.from_yaml("causalshift/configs/default.yaml")
result = CausalShiftPipeline(cfg).fit(X_src, y_src, X_tgt, y_tgt, graph=my_dag)
print(result.evaluation.summary())from causalshift.stages import Stage2Attribution
stage2 = Stage2Attribution(cfg)
attr = stage2.run(X_src, y_src, X_tgt, y_tgt, level=KnowledgeLevel.C, ...)from causalshift.plugins import POMPlugin
pom = POMPlugin(config=cfg.attribution)
pom.activate("C")
pom.fit(X_src, y_src, X_tgt, y_tgt)
result = pom.apply(X_src) # returns {'delta_cov': ..., 'delta_concept': ...}conda activate YourEnvName
# CPU mode (default, sklearn backend, no GPU required) — Synthetic SCM (no download needed)
python demo.py --dataset synthetic
python demo.py --dataset cmnist --cmnist-root ./data # Colored MNIST (requires torchvision; auto-downloads MNIST ~11 MB)
# GPU mode (PyTorch MLP backend, requires CUDA)
python demo.py --dataset synthetic --device gpu
python demo.py --dataset cmnist --cmnist-root ./data --device gpu
# WILDS Camelyon17 (requires wilds; auto-downloads ~10 GB) — most popular benchmark (pathology images, hospital covariate shift)
python demo.py --dataset wilds --wilds-name camelyon17 --wilds-root ./data
python demo.py --dataset wilds --device gpu --wilds-name camelyon17 --wilds-root ./data
# CivilComments (~0.1 GB) — text data, no images, no GPU required
python demo.py --dataset wilds --wilds-name civilcomments --wilds-root ./data --use-tfidf --tfidf-features 1000 --n-src 10000 --n-tgt 5000
# Smallest image dataset (~1 GB, wheat head detection)
python demo.py --dataset wilds --wilds-name globalwheat --wilds-root ./data
python demo.py --dataset wilds --device gpu --wilds-name globalwheat --wilds-root ./data
# WILDS iWildCam (~21 GB)
python demo.py --dataset wilds --wilds-name iwildcam --wilds-root ./data
python demo.py --dataset wilds --device gpu --wilds-name iwildcam --wilds-root ./data
# Quiet mode: suppress all progress prints, keep INFO logs only
python demo.py --dataset cmnist --cmnist-root ./data --quiet
python demo.py --dataset wilds --device gpu --wilds-name camelyon17 --wilds-root ./data --quiet--dataset synthetic / cmnist / wilds / tableshift Dataset to use
--shift-type covariate / concept / mixed Single shift variant (synthetic only)
--all-variants (flag) Run all shift variants and average
--n-seeds integer, default 3 Number of repeated runs
--cmnist-root path, default ./data Directory for MNIST data
--wilds-name camelyon17 etc. WILDS dataset name
--wilds-root path, default ./data Directory for WILDS data
--device cpu / gpu Compute device for Stage 5
--quiet (flag) Suppress progress output
# Single shift variant (quick check, ~2–5 min)
python run_comparison.py --dataset synthetic --shift-type covariate
# Average over all shift variants (matches Table 4, ~10–15 min)
python run_comparison.py --dataset synthetic --all-variants --n-seeds 3
# CMNIST，Table 4: CMNIST
python run_comparison.py --dataset cmnist --cmnist-root ./data --device gpu
# WILDS Camelyon17
python run_comparison.py --dataset wilds --wilds-name camelyon17 --wilds-root ./data
# Deep feature extraction (ResNet-50, requires GPU, ~30 min)，Table 4 & 6: Camelyon17（含 Λ* 和 DISDE）
python run_comparison.py --dataset wilds --wilds-name camelyon17 --wilds-root ./data --device gpu --use-resnet --n-src 3000 --n-tgt 1000
# 保存结果
python run_comparison.py --dataset wilds --wilds-name camelyon17 ^
--wilds-root ./data --device gpu --use-resnet ^
--n-src 3000 --n-tgt 1000 > camelyon17_result.txt 2>&1
type camelyon17_result.txt
# Install tableshift (Python 3.10 only — requires ray==2.2, numpy==1.23.5)
pip install git+https://github.com/mlfoundations/tableshift.git
# or clone and install locally
git clone https://github.com/mlfoundations/tableshift.git
cd tableshift
pip install -e .
cd ..
# Python 3.11 compatible alternative: folktables (covers TableShift ACS tasks)
pip install folktables
# Demo mode: run the full CausalShift pipeline on a single ACS task
python demo.py --dataset tableshift --tableshift-name acsincome
# ACS income prediction (region/year shift) — most commonly used
python run_comparison.py --dataset tableshift --tableshift-name acsincome
# Voter turnout prediction (year shift)
python run_comparison.py --dataset tableshift --tableshift-name anes
# Run all 5 supported tasks: acsincome, acsemployment, acspubcov, acsmobility, acstraveltime
python run_comparison.py --dataset tableshift --all-tableshift# 第一步：确认 config 字段名是否匹配（必须先跑一次）
python run_ablation.py --probe-config
# 快速验证（1 seed，约8分钟）
python run_ablation.py --n-seeds 1 --quiet
# 完整 Table 7（3 seeds × 3 variants = 9 runs × 5 configs = 45 次，约20-30分钟）
python run_ablation.py
# 完整 Table 7（3 seeds × 3 variants，约20-30分钟）,保存结果至json文件
python run_ablation.py --save-json ablation_results.json
# Step 1：先跑合成数据（Table 3 全部 + Table 6 合成部分，约10分钟）
python run_eval_tables.py --n-seeds 3 --save-json eval_tables_results.json
# Step 2：Camelyon17 第一次运行（提取并保存ResNet特征，约15-20分钟）
python run_eval_tables.py --include-camelyon17 ^
--wilds-root ./data --device gpu ^
--save-features camelyon17_features.npz ^
--save-json eval_tables_results.json
# Step 2b：之后重新运行时，直接加载保存的特征（约3分钟）
python run_eval_tables.py --include-camelyon17 ^
--load-features camelyon17_features.npz ^
--save-json eval_tables_results.json
import warnings
warnings.filterwarnings("ignore", category=UserWarning, module="torchvision")
warnings.filterwarnings("ignore", category=RuntimeWarning, message=".*NumPy.*")set OMP_NUM_THREADS=1
set MKL_NUM_THREADS=1
set OPENBLAS_NUM_THREADS=1or persist via conda environment variables:
conda env config vars set OMP_NUM_THREADS=1 MKL_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 -n CausalShift