cognitive-digital-twin 0.1.2

A framework for AI-driven digital twins for cognitive decline.

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

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

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)

# 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

# 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 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

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

Reproduce Main Results

# 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

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

# 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

API Documentation

Generate local documentation:

pip install sphinx sphinx-rtd-theme
cd docs
make html
open _build/html/index.html

🧪 Testing

# 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 for details.

Development Setup

# 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:

@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 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 [e-mail]
• Author Website: bulentsoykan.com
• Professional Profile: LinkedIn
• Technical Blog: bulentsoykan.github.io

---

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