Metadata-Version: 2.4
Name: cognitive-digital-twin
Version: 0.1.1
Summary: A framework for AI-driven digital twins for cognitive decline.
Author-email: Bulent Soykan <soykanb@gmail.com>
Maintainer-email: Bulent Soykan <soykanb@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/bulentsoykan/cognitivedt
Project-URL: Repository, https://github.com/bulentsoykan/cognitivedt
Project-URL: Issues, https://github.com/bulentsoykan/cognitivedt/issues
Project-URL: Documentation, https://github.com/bulentsoykan/cognitivedt/blob/main/docs/README.md
Project-URL: Author, https://www.bulentsoykan.com/
Keywords: cognitive-decline,digital-twin,pytorch,bayesian,deep-learning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: torch>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: scipy>=1.10.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: black>=23.7.0; extra == "dev"
Provides-Extra: bayesian
Requires-Dist: pyro-ppl>=1.8.6; extra == "bayesian"
Provides-Extra: gnn
Requires-Dist: torch-geometric>=2.3.0; extra == "gnn"
Provides-Extra: all
Requires-Dist: cognitivedt[bayesian,dev,gnn]; extra == "all"
Requires-Dist: seaborn; extra == "all"
Dynamic: license-file

# CognitiveTwin: AI-Driven Digital Twins for Personalized Cognitive Decline Prediction

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyTorch](https://img.shields.io/badge/PyTorch-2.0%2B-orange)](https://pytorch.org/)
[![Paper](https://img.shields.io/badge/Paper-ArXiv-red)](https://arxiv.org/abs/XXXX.XXXXX)
[![Author](https://img.shields.io/badge/Author-Bulent%20Soykan-green)](https://www.bulentsoykan.com/)

**CognitiveTwin** is a state-of-the-art AI framework for creating personalized digital twins that predict cognitive decline trajectories in patients with Alzheimer's disease and related dementias. Our approach integrates multi-modal longitudinal data using transformer-based fusion and temporal dynamics modeling to achieve superior prediction accuracy with calibrated uncertainty quantification.

## 🎯 Key Results

- **Superior Accuracy**: MAE of **1.619 MMSE points** (47.5% improvement over SOTA)
- **Strong Temporal Dynamics**: R² = **0.682** with excellent trend capture  
- **Excellent Discrimination**: AUROC = **0.912** for AD progression prediction
- **Well-Calibrated**: ECE = 0.054 with reliable uncertainty estimates
- **Fair Across Demographics**: Balanced performance (male: 1.622, female: 1.614 MAE)
- **Robust to Missing Data**: Only 0.4% degradation under 15% missingness
- **Clinical Utility**: 46% reduction in number needed to screen

## 🏗️ Architecture Overview

```mermaid
graph TB
    A[Multi-Modal Data] --> B[Transformer Fusion]
    B --> C[Temporal Modeling]
    C --> D[Uncertainty Quantification]
    D --> E[Clinical Predictions]
    
    A1[Cognitive Scores] --> B
    A2[MRI Volumetrics] --> B  
    A3[PET/CSF Biomarkers] --> B
    A4[Demographics/Genetics] --> B
    
    C --> C1[GRU-based Dynamics]
    C --> C2[Attention Mechanisms]
    
    E --> E1[MMSE Trajectory]
    E --> E2[95% Prediction Intervals]
    E --> E3[Progression Risk]
```

## 📁 Repository Structure

```
cognitivedt/
├── cognitivedt/                    # Core package
│   ├── data/                       # Data schemas and models
│   ├── io/                         # Data loading and preprocessing  
│   ├── representation/             # Multi-modal fusion models
│   ├── dynamics/                   # Temporal modeling components
│   ├── evaluation/                 # Metrics and validation
│   └── utils/                      # Utilities and helpers
├── experiments/                    # Experimental setup
│   ├── scripts/                    # Training and evaluation scripts
│   │   ├── run_experiments_fixed.py  # Main corrected experiments
│   │   ├── generate_figures.py       # Publication figure generation
│   │   └── generate_tables.py        # LaTeX table generation
│   ├── configs/                    # Experiment configurations
│   └── notebooks/                  # Jupyter analysis notebooks
├── docs/                          # Documentation
│   ├── paper/                     # Research paper and manuscript
│   ├── experiments/               # Experimental results and analysis
│   │   ├── figures/              # Generated publication figures
│   │   ├── tables/               # LaTeX tables for publication
│   │   └── results.md            # Detailed quantitative results
│   ├── technical_guide.md        # Technical implementation guide
│   └── data_guide.md             # Data acquisition and setup guide
├── tests/                         # Unit and integration tests
├── pyproject.toml                # Project configuration
└── README.md                     # This file
```

## 🚀 Quick Start

### Installation

#### Option 1: Install from PyPI (Recommended)

```bash
# Install the latest stable version
pip install cognitivedt

# Or install with all optional dependencies
pip install "cognitivedt[all]"

# For development features
pip install "cognitivedt[dev]"
```

#### Option 2: Install from Source

```bash
# Clone the repository
git clone https://github.com/bulentsoykan/cognitivedt.git
cd cognitivedt

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[all]"
```

### Data Setup

1. **Download TADPOLE Dataset**: Visit [TADPOLE Challenge](https://tadpole.grand-challenge.org/) and download `TADPOLE_D1_D2.csv`
2. **Place in Repository**: Copy the file to the repository root directory
3. **Verify Installation**: Run the data loader test

```bash
python -c "from cognitivedt.io.loader import TADPOLELoader; print('✓ Installation successful')"
```

### Reproduce Main Results

```bash
# Navigate to experiments directory
cd experiments/scripts

# Run corrected experiments (reproduces paper results)
python run_experiments_fixed.py

# Generate publication figures  
python generate_figures.py

# Generate LaTeX tables
python generate_tables.py
```

Expected output:
```
🎯 CORRECTED EXPERIMENTS COMPLETED!
Best model (Transformer) MAE: 1.619
Results saved to: ../../docs/experiments/
```

## 📊 Key Features

### Multi-Modal Data Integration
- **Cognitive Assessments**: MMSE, ADAS-Cog, CDR scores
- **Neuroimaging**: MRI volumetrics (hippocampus, ventricles, cortical thickness)
- **Biomarkers**: PET amyloid/tau, CSF Aβ42/tau ratios
- **Demographics & Genetics**: Age, sex, education, APOE genotype

### Advanced AI Architecture
- **Transformer-Based Fusion**: Cross-modal attention for optimal feature integration
- **Temporal Dynamics**: GRU-based modeling for disease progression patterns
- **Uncertainty Quantification**: Bayesian neural networks with calibrated confidence intervals
- **Robust Training**: Handles missing data and temporal distribution shifts

### Clinical Validation
- **TADPOLE Dataset**: 1,666 patients, 12,505 longitudinal visits
- **Rigorous Evaluation**: Train/validation/test splits with temporal validation
- **Fairness Assessment**: Performance evaluated across demographic groups
- **Clinical Metrics**: Decision curve analysis and number needed to screen

## 🔬 Experimental Results

### Model Performance Comparison

| Method | MAE ↓ | RMSE ↓ | R² ↑ | AUROC ↑ |
|--------|-------|---------|-------|---------|
| LSTM | 3.420 | 4.680 | 0.220 | 0.730 |
| CNN-LSTM | 3.180 | 4.510 | 0.280 | 0.760 |
| Transformer | 2.940 | 4.230 | 0.350 | 0.780 |
| Graph Neural Net | 2.670 | 3.980 | 0.410 | 0.810 |
| **CognitiveTwin (Ours)** | **1.619** | **2.248** | **0.682** | **0.912** |

### Fairness Analysis

| Demographic Group | MAE | AUROC | Performance Gap |
|------------------|-----|-------|-----------------|
| Male | 1.622 | 0.920 | Reference |
| Female | 1.614 | 0.893 | -0.5% |
| Age < 65 | 1.608 | 0.925 | +1.4% |
| Age 65-75 | 1.619 | 0.912 | Reference |
| Age > 75 | 1.635 | 0.901 | -1.0% |

### Robustness Evaluation

| Condition | MAE | Degradation |
|-----------|-----|-------------|
| Complete Data | 1.619 | 0% |
| 15% Missing (MNAR) | 1.625 | +0.4% |
| 25% Missing | 1.741 | +7.5% |
| Temporal Shift | 1.687 | +4.2% |

## 📈 Usage Examples

### Basic Model Training

```python
from cognitivedt import TADPOLELoader
from cognitivedt.representation import TransformerFusionModel
from cognitivedt.dynamics import FixedCognitiveTwinModel
import torch

# Load data
loader = TADPOLELoader()
train_data, val_data, test_data = loader.load_and_split("TADPOLE_D1_D2.csv")

# Create model
model = FixedCognitiveTwinModel(
    input_dim=12,      # Multi-modal feature dimension
    hidden_dim=256,    # Hidden layer size
    n_layers=4,        # Number of transformer layers
    n_heads=8          # Number of attention heads
)

# Train model
optimizer = torch.optim.AdamW(model.parameters(), lr=1e-4)
# ... training loop implementation
```

### Prediction with Uncertainty

```python
# Make predictions with uncertainty quantification
predictions, uncertainties = model.predict_with_uncertainty(test_data)

# Extract prediction intervals
mean_pred = predictions.mean(dim=0)
lower_bound = predictions.quantile(0.025, dim=0) 
upper_bound = predictions.quantile(0.975, dim=0)

print(f"Predicted MMSE: {mean_pred:.1f}")
print(f"95% CI: [{lower_bound:.1f}, {upper_bound:.1f}]")
```

## 📚 Documentation

### Quick Links
- **📄 [Research Paper](docs/paper/manuscript.md)**: Complete research manuscript
- **🔧 [Technical Guide](docs/technical_guide.md)**: Implementation details
- **📊 [Experimental Results](docs/experiments/results.md)**: Detailed quantitative analysis  
- **💾 [Data Guide](docs/data_guide.md)**: Data acquisition and preprocessing

### API Documentation

Generate local documentation:
```bash
pip install sphinx sphinx-rtd-theme
cd docs
make html
open _build/html/index.html
```

## 🧪 Testing

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=cognitivedt --cov-report=html

# Run specific test modules
pytest tests/test_models.py
pytest tests/test_data.py
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

### Development Setup

```bash
# Install development dependencies
pip install -e ".[dev]"

# Set up pre-commit hooks
pre-commit install

# Run code quality checks
ruff check cognitivedt/
black cognitivedt/
mypy cognitivedt/
```

## 📄 Citation

If you use CognitiveTwin in your research, please cite our paper:

```bibtex
@article{cognitivetwin2025,
  title={CognitiveTwin: AI-Driven Digital Twins for Personalized Cognitive Decline Prediction},
  author={Soykan, Bulent},
  year={2026},
  url={https://github.com/bulentsoykan/cognitivedt}
}
```

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- **TADPOLE Challenge** for providing the standardized evaluation framework
- **ADNI Consortium** for the longitudinal neuroimaging data
- **NIH/NIA** for research funding support
- **PyTorch Team** for the deep learning framework

## 📧 Contact

For questions about the research or implementation:

- **Technical Issues**: Open a GitHub issue
- **Research Collaboration**: Contact [soykanb@gmail.com](mailto:soykanb@gmail.com)
- **Author Website**: [bulentsoykan.com](https://www.bulentsoykan.com/)
- **Professional Profile**: [LinkedIn](https://www.linkedin.com/in/bulent-soykan/)
- **Technical Blog**: [bulentsoykan.github.io](https://bulentsoykan.github.io/)

---

**⭐ Star this repository if you find CognitiveTwin useful for your research!**
