🚶‍♀️ CISD: Causal-Intervention Scenario Design 🚴‍♂️

Advanced Causal Inference Framework for Active Transportation Research

Bridging the gap between causality science and active transportation research

📌 Note: For the Census Tract Network Analysis Tool, please check the Census_Tract_Network branch.

📋 Overview

CISD is a cutting-edge framework that revolutionizes how we understand cause and effect in active transportation systems. By leveraging both traditional causal inference and advanced AI techniques, CISD enables researchers and policymakers to:

• Quantify the true impact of infrastructure interventions
• Account for complex spatial dependencies and longitudinal trends
• Process multimodal data sources including imagery, GPS traces, and textual data
• Generate robust evidence for evidence-based policy decisions

The CISD Approach

CISD treats policy analysis as a principled two-stage process:

1. Define Scenario Vector → Bundle mediating and moderating features into explicit scenarios
2. Apply Treatment Indicator → Estimate counterfactual outcomes when individuals experience different treatments while scenario elements remain fixed

✨ Key Features

🧠 Advanced Framework CISD Estimand: Implementation of the canonical CISD estimand with support for stochastic scenarios Three-Layer Architecture: Representation learning (Φ), balancing (Ψ), and causal learning (Γ) components Causal Machine Learning: Doubly robust estimators with semiparametric efficiency guarantees	🔍 Data Processing Multimodal Analysis: Street imagery, GPS-accelerometer traces, zoning data, and textual data Spatial Analysis: Specialized tools for handling spatial dependencies and geospatial data Longitudinal Methods: Difference-in-differences, fixed effects, synthetic control, and staggered adoption
📊 Visualization Diagnostic Plots: Balance checking and effect heterogeneity visualization Interactive Maps: Spatial effect mapping with rich contextual layers Model Interpretability: Tools to understand complex causal relationships	🌐 Extensible Design Modular Components: Easily extend or replace individual components Integration Support: Works with popular ML frameworks and GIS systems Research Ready: Designed to facilitate reproducible transportation research

🚀 Installation

Choose your installation path

💨 Quick Installation

# Development mode (editable)
pip install -e .

# Direct installation from GitHub
pip install git+https://github.com/pozapas/CausalAT.git

🧩 Installation with Optional Dependencies

# Spatial analysis features
pip install -e ".[spatial]"

# Visualization capabilities
pip install -e ".[viz]"

# Full functionality (all dependencies)
pip install -e ".[all]"

📝 Step-by-Step Guide

Expand for detailed installation instructions

1. Clone the repository

   git clone https://github.com/pozapas/CausalAT.git
   cd CausalAT

2. Create a virtual environment (recommended)

   python -m venv venv
   venv\Scripts\activate   # Windows
   source venv/bin/activate  # Linux/MacOS

3. Install with desired dependencies

   pip install -e ".[all]"

4. Verify installation

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

📦 Dependencies

Core dependencies - Essential libraries for basic functionality

• Data Handling: NumPy, Pandas, SciPy
• Machine Learning: scikit-learn
• Deep Learning: TensorFlow/PyTorch
• Network Analysis: NetworkX

Spatial dependencies - For geospatial analysis

• Spatial Data: GeoPandas, Shapely
• Spatial Statistics: libpysal, ESDA, spreg
• Econometric Models: statsmodels

Visualization dependencies - For data visualization

• Basic Plotting: Matplotlib, Seaborn
• Geospatial Maps: Contextily, Folium
• Interactive Charts: Plotly (for interactive dashboards)

Network analysis dependencies - For transportation network modeling

• Graph Operations: NetworkX
• OSM Integration: OSMnx (OpenStreetMap data)
• Advanced Algorithms: igraph (optional, performance-optimized)

💡 Usage

Interactive Tutorials & Examples

Explore our comprehensive tutorial notebooks to get started with CISD.

Tutorial	Description	Topics
📘 CISD Framework	Introduction to the CISD framework and concepts	Core concepts, estimands, scenario design
🤖 AI-Augmented Inference	Using AI for causal inference in transportation research	Neural networks, representation learning, multimodal data
🗺️ Spatial-Temporal Analysis	Analyzing spatial-temporal effects of infrastructure interventions	GIS integration, spatial autocorrelation, panel data models
🔀 Network Analysis	Working with transportation network data	Graph theory, network metrics, flow modeling

Quick Start: Begin with the CISD Framework tutorial to understand the fundamental concepts before diving into specialized application areas.

📚 Documentation

Package Structure & Module Reference

cisd/
├── core                      # Core implementation of CISD framework
├── representation            # Neural encoders for multimodal data
├── balancing                 # Covariate distribution matching methods
├── causal                    # Causal estimators with efficiency guarantees
├── ai_pipeline               # End-to-end AI workflows for causal inference
├── spatial_temporal          # Spatial and longitudinal data utilities
├── spatial_neighborhood_generator  # Synthetic spatial data generation
└── visualization             # Diagnostic and effect visualization tools

Module Details

• cisd.core: Framework fundamentals, estimand definitions, scenario modeling
• cisd.representation: Feature embedding for images, GPS traces, text using neural networks
• cisd.balancing: Propensity modeling, entropy balancing, distribution matching algorithms
• cisd.causal: Doubly-robust estimators, influence functions, sensitivity analysis
• cisd.ai_pipeline: End-to-end workflows connecting all components
• cisd.spatial_temporal: Spatial weights, autocorrelation tests, panel data models
• cisd.spatial_neighborhood_generator: Synthetic data for testing and benchmarking
• cisd.visualization: Interactive plots, spatial effect maps, balance diagnostics

📄 Citation

If you use CISD in your research, please cite our work:

@software{causalat_cisd,
  title     = {CISD: Causal-Intervention Scenario Design for Active Transportation Research},
  author    = {Rafe, Amir},
  url       = {https://github.com/pozapas/CausalAT},
  year      = {2025},
  month     = {May},
  publisher = {GitHub},
  version   = {1.0.0}
}

Note: A formal paper describing the methodology is forthcoming. This citation will be updated when published.

👥 Contributing

We welcome contributions from researchers, practitioners, and developers!

Ways to contribute:

• 🐛 Report bugs and issues
• 💡 Suggest new features or enhancements
• 🧪 Add test cases
• 📝 Improve documentation
• 🔧 Submit pull requests

Contribution Workflow

1. Fork the repository
2. Clone your fork: git clone https://github.com/YOUR-USERNAME/CausalAT.git
3. Create a feature branch: git checkout -b feature/amazing-feature
4. Develop your contribution
5. Commit your changes: git commit -m 'Add some amazing feature'
6. Push to your branch: git push origin feature/amazing-feature
7. Submit a Pull Request

We strive to maintain high-quality, well-documented code that follows best practices for scientific computing.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Transforming transportation policy analysis with causal science