Hierarchical Causal RSSM for Individual Treatment Effects

A deep latent variable model for estimating Individual Treatment Effects (ITE) from observational retail data. The model uses hard causal gates, normalizing flows, and curriculum training to achieve interpretable and robust causal inference.

🎯 Key Features

• Hard Causal Gates: Enforce z^C = 0 when treatment is absent (verified <10⁻¹⁰)
• ε-Preservation: Individual counterfactuals via normalizing flows
• Two-Stage Curriculum: Prevents latent collapse (2/32 → 8/8 active dims)
• Additive Decoder: Interpretable decomposition: Y = Natural + Lift

📊 Results

Metric	Value
Treatment Effect (Campaign B)	+8.2% sales lift
Confounding Bias (vs Naive)	2.4× overestimation
Optimal Targeting Efficiency	1.9× vs random
E-value (Robustness)	1.37

🚀 Quick Start

Installation

# Clone repository
git clone https://github.com/prabakaranc98/PMML_RSSM.git
cd PMML_RSSM

# Create environment
conda create -n hcrssm python=3.10
conda activate hcrssm

# Install dependencies
pip install -r requirements.txt

Training

# Two-stage curriculum training
python train_phase5.py

Analysis

# Run comprehensive analysis
python analyze_phase5.py

# Counterfactual study
python counterfactual_study.py

# Validate model claims
python validate_all_claims.py

📁 Project Structure

src/
├── models/
│   ├── hierarchical_rssm_phase5.py  # Main model
│   ├── flows.py                      # Normalizing flows
│   └── config_phase5.py             # Configuration
└── evaluation/
    └── counterfactual_analysis.py   # CF analysis tools

train_phase5.py          # Training script
analyze_phase5.py        # Analysis and ITE estimation
counterfactual_study.py  # G-computation study
validate_all_claims.py   # Validation suite

🔬 Model Architecture

Customer Behavior = Natural Dynamics + Causal Effects
        Y         =    g_N(z^I, z^N)  + g_C(z^C)

Latent Variables:
  z^I (16-dim): Time-invariant customer identity
  z^N (16-dim): Natural shopping dynamics  
  z^C (8-dim):  Treatment effects (gated when A=0)

📖 Data

The model is trained on the Dunnhumby "Complete Journey" dataset:

• 2,500 households
• 276,484 shopping baskets
• 3 campaign types + display/mailer exposures

📝 Citation

@article{hcrssm2024,
  title={Hierarchical Causal RSSM for Individual Treatment Effect Estimation},
  author={Prabakaran Chandran},
  year={2025}
}

📄 License

MIT License - see LICENSE for details.