Deploy HeartMAP platform

README.md

@@ -1,12 +1,129 @@
 ---
-title: HeartMAP
-emoji: 🐠
-colorFrom: blue
-colorTo: gray
+title: HeartMAP - Single-Cell Heart Analysis
+emoji: 🫀
+colorFrom: red
+colorTo: pink
 sdk: gradio
-sdk_version: 5.41.0
+sdk_version: 4.0.0
 app_file: app.py
 pinned: false
+license: mit
+tags:
+  - single-cell
+  - genomics
+  - heart
+  - bioinformatics
+  - research-tool
+  - scanpy
+  - cell-communication
+  - cardiac-analysis
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🫀 HeartMAP: Single-Cell Heart Analysis Platform
+
+**Comprehensive analysis of single-cell RNA-seq data from cardiac tissue**
+
+## 🔬 What is HeartMAP?
+
+HeartMAP is a specialized bioinformatics platform designed for analyzing single-cell RNA sequencing (scRNA-seq) data from cardiac tissue. It provides researchers with tools to:
+
+- 🧬 **Identify cell types** in heart tissue across multiple chambers
+- 📊 **Analyze cell-to-cell communication** networks
+- 🏠 **Compare different heart chambers** (RA, RV, LA, LV)
+- 🔍 **Perform quality control** and preprocessing
+- 📈 **Generate publication-ready visualizations**
+
+## 🚀 How to Use
+
+1. **Upload your data**: Provide a `.h5ad` (AnnData) file containing single-cell RNA-seq counts
+2. **Choose analysis type**: 
+   - **Basic**: Fast clustering and cell type identification
+   - **Comprehensive**: Full pipeline with communication analysis
+3. **Set parameters**: Adjust maximum cells for your computational needs
+4. **Run analysis**: Get results in minutes with interactive visualizations
+5. **Download results**: Get CSV files with detailed analysis results
+
+## 📊 Input Data Format
+
+HeartMAP expects **AnnData (.h5ad) files** with:
+- **Gene expression counts** (cells × genes matrix)
+- Optional: **chamber annotations** in `.obs['chamber']`
+- Optional: **existing cell type labels** in `.obs['cell_type']`
+
+## 🎯 Analysis Pipeline
+
+### Basic Analysis
+- Quality control filtering
+- Normalization and scaling
+- Dimensionality reduction (PCA, UMAP)
+- Leiden clustering
+- Basic cell type annotation
+
+### Comprehensive Analysis
+- All basic analysis steps
+- Advanced cell type identification
+- Cell-to-cell communication analysis
+- Multi-chamber comparative analysis
+- Communication network visualization
+- Statistical testing
+
+## 📈 Output
+
+- **Interactive visualizations**: UMAP plots, quality metrics
+- **Summary statistics**: Cell counts, gene expression metrics
+- **Downloadable results**: CSV files with cell annotations and metrics
+- **Quality control plots**: Distribution of key metrics
+
+## 🔬 Research Applications
+
+HeartMAP is designed for researchers studying:
+
+- **Cardiac development** and maturation
+- **Heart disease mechanisms** (heart failure, cardiomyopathy)
+- **Therapeutic responses** to treatments
+- **Cell-type specific** gene expression patterns
+- **Inter-chamber differences** in cellular composition
+- **Cell communication networks** in healthy and diseased hearts
+
+## 📚 Citation
+
+If you use HeartMAP in your research, please cite:
+
+```bibtex
+@software{heartmap2024,
+  title={HeartMAP: A comprehensive platform for single-cell cardiac analysis},
+  author={[Your Name]},
+  year={2024},
+  url={https://github.com/Tumo505/GRAIL-Heart-cell-cell-communication}
+}
+```
+
+## 🔗 Links
+
+- **GitHub Repository**: [GRAIL-Heart-cell-cell-communication](https://github.com/Tumo505/GRAIL-Heart-cell-cell-communication)
+- **Documentation**: See repository README for detailed usage
+- **Issues & Support**: Report issues on GitHub
+
+## ⚠️ Disclaimer
+
+HeartMAP is a research tool. Results should be validated with additional experiments and domain expertise. This platform is designed to assist researchers but does not replace careful biological interpretation and validation.
+
+## 🏷️ Technical Details
+
+- **Framework**: Built with scanpy, pandas, and scikit-learn
+- **Interface**: Gradio web application
+- **Input**: AnnData (.h5ad) format
+- **Analysis**: Statistical and computational biology methods
+- **Visualization**: matplotlib, seaborn, plotly
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our GitHub repository for:
+- Bug reports and feature requests
+- Code contributions
+- Documentation improvements
+- Example datasets and use cases
+
+---
+
+**Note**: This is academic research software. Always validate computational results with experimental evidence and consult domain experts for biological interpretation.

app.py

@@ -0,0 +1,286 @@
+"""
+HeartMAP: Single-Cell Heart Analysis Platform
+Hugging Face Spaces Deployment
+"""
+
+import gradio as gr
+import os
+import sys
+import tempfile
+import shutil
+from pathlib import Path
+import traceback
+
+# Add src to path for imports
+sys.path.insert(0, 'src')
+
+from heartmap import Config, HeartMapModel
+from heartmap.pipelines import ComprehensivePipeline, BasicPipeline
+from heartmap.data import DataLoader
+import scanpy as sc
+import pandas as pd
+import matplotlib.pyplot as plt
+import seaborn as sns
+
+# Set up scanpy settings
+sc.settings.verbosity = 1  # Reduce verbosity
+sc.settings.set_figure_params(dpi=80, facecolor='white')
+
+def analyze_heart_data(file, analysis_type, max_cells):
+    """
+    Main analysis function for Gradio interface
+    """
+    try:
+        if file is None:
+            return "❌ Please upload a .h5ad file", None, None
+        
+        # Create temporary directory for this analysis
+        with tempfile.TemporaryDirectory() as temp_dir:
+            temp_path = Path(temp_dir)
+            
+            # Save uploaded file
+            input_file = temp_path / "input_data.h5ad"
+            shutil.copy(file.name, input_file)
+            
+            # Create configuration
+            config = Config.default()
+            config.data.max_cells_subset = int(max_cells)
+            config.data.max_genes_subset = min(5000, int(max_cells // 2))
+            config.data.test_mode = True
+            config.update_paths(str(temp_path))
+            config.create_directories()
+            
+            # Create pipeline based on analysis type
+            if analysis_type == "Basic Analysis":
+                pipeline = BasicPipeline(config)
+            else:
+                pipeline = ComprehensivePipeline(config)
+            
+            # Run analysis
+            results = pipeline.run(str(input_file), str(temp_path / "results"))
+            adata = results['adata']
+            
+            # Generate summary
+            summary = f"""
+## 🎉 Analysis Complete!
+
+### 📊 Dataset Summary:
+- **Cells analyzed**: {adata.n_obs:,}
+- **Genes analyzed**: {adata.n_vars:,}
+- **Cell types identified**: {len(adata.obs['leiden'].unique()) if 'leiden' in adata.obs else 'N/A'}
+- **Analysis type**: {analysis_type}
+
+### 🔬 Key Findings:
+- Clustering performed using Leiden algorithm
+- UMAP embedding computed for visualization
+- {f"Chamber information available: {', '.join(adata.obs['chamber'].unique())}" if 'chamber' in adata.obs else "Single chamber analysis"}
+
+### 📈 Quality Metrics:
+- **Mean genes per cell**: {adata.obs['n_genes'].mean():.0f}
+- **Mean counts per cell**: {adata.obs['total_counts'].mean():.0f}
+- **Mitochondrial gene %**: {adata.obs['pct_counts_mt'].mean():.1f}%
+
+### 🎯 Next Steps:
+1. Download detailed results (CSV files)
+2. Examine cell type markers
+3. Explore communication networks
+4. Compare with your research questions
+            """
+            
+            # Create visualization
+            fig, axes = plt.subplots(2, 2, figsize=(12, 10))
+            fig.suptitle('HeartMAP Analysis Results', fontsize=16, fontweight='bold')
+            
+            # UMAP plot
+            if 'X_umap' in adata.obsm:
+                sc.pl.umap(adata, color='leiden', ax=axes[0,0], show=False, frameon=False)
+                axes[0,0].set_title('Cell Clusters (UMAP)')
+            else:
+                axes[0,0].text(0.5, 0.5, 'UMAP not available', ha='center', va='center')
+                axes[0,0].set_title('UMAP Visualization')
+            
+            # Quality metrics
+            if 'n_genes' in adata.obs:
+                axes[0,1].hist(adata.obs['n_genes'], bins=50, alpha=0.7, color='skyblue')
+                axes[0,1].set_xlabel('Number of genes')
+                axes[0,1].set_ylabel('Number of cells')
+                axes[0,1].set_title('Genes per Cell Distribution')
+            
+            # Mitochondrial gene percentage
+            if 'pct_counts_mt' in adata.obs:
+                axes[1,0].hist(adata.obs['pct_counts_mt'], bins=50, alpha=0.7, color='lightcoral')
+                axes[1,0].set_xlabel('Mitochondrial gene %')
+                axes[1,0].set_ylabel('Number of cells')
+                axes[1,0].set_title('Mitochondrial Gene Expression')
+            
+            # Chamber distribution (if available)
+            if 'chamber' in adata.obs:
+                chamber_counts = adata.obs['chamber'].value_counts()
+                axes[1,1].pie(chamber_counts.values, labels=chamber_counts.index, autopct='%1.1f%%')
+                axes[1,1].set_title('Chamber Distribution')
+            else:
+                # Cluster distribution
+                if 'leiden' in adata.obs:
+                    cluster_counts = adata.obs['leiden'].value_counts().head(10)
+                    axes[1,1].bar(range(len(cluster_counts)), cluster_counts.values, color='lightgreen')
+                    axes[1,1].set_xlabel('Cluster')
+                    axes[1,1].set_ylabel('Number of cells')
+                    axes[1,1].set_title('Top 10 Clusters')
+            
+            plt.tight_layout()
+            
+            # Save plot
+            plot_file = temp_path / "analysis_results.png"
+            plt.savefig(plot_file, dpi=150, bbox_inches='tight')
+            plt.close()
+            
+            # Create downloadable results
+            results_df = pd.DataFrame({
+                'cell_id': adata.obs.index,
+                'cluster': adata.obs.get('leiden', 'Unknown'),
+                'n_genes': adata.obs.get('n_genes', 0),
+                'total_counts': adata.obs.get('total_counts', 0),
+                'pct_counts_mt': adata.obs.get('pct_counts_mt', 0),
+                'chamber': adata.obs.get('chamber', 'Unknown')
+            })
+            
+            results_csv = temp_path / "heartmap_results.csv"
+            results_df.to_csv(results_csv, index=False)
+            
+            return summary, str(plot_file), str(results_csv)
+            
+    except Exception as e:
+        error_msg = f"""
+## ❌ Analysis Error
+
+**Error**: {str(e)}
+
+**Possible solutions**:
+1. Ensure your file is a valid .h5ad (AnnData) format
+2. Try reducing the maximum number of cells
+3. Check that your data contains gene expression counts
+4. Verify the file is not corrupted
+
+**Error details**:
+```
+{traceback.format_exc()}
+```
+        """
+        return error_msg, None, None
+
+def create_demo_interface():
+    """Create Gradio interface"""
+    
+    with gr.Blocks(title="HeartMAP: Heart Cell Communication Analysis", theme=gr.themes.Soft()) as demo:
+        gr.Markdown("""
+# 🫀 HeartMAP: Single-Cell Heart Analysis Platform
+
+**Analyze single-cell RNA-seq data from cardiac tissue across multiple heart chambers**
+
+Upload your .h5ad file to get started with comprehensive heart cell analysis including:
+- 🔬 Cell type identification and clustering
+- 📊 Quality control and preprocessing
+- 🗣️ Cell-to-cell communication analysis
+- 🏠 Multi-chamber comparative analysis
+- 📈 Advanced visualizations
+
+## 📚 About HeartMAP
+HeartMAP is a comprehensive platform for analyzing single-cell RNA sequencing data from cardiac tissue. 
+It provides tools for cell annotation, communication analysis, and multi-chamber comparison studies.
+
+**Example datasets**: Use 10X Genomics h5ad files or any AnnData-compatible single-cell data.
+        """)
+        
+        with gr.Row():
+            with gr.Column(scale=1):
+                gr.Markdown("## 📤 Upload Data")
+                file_input = gr.File(
+                    label="Upload .h5ad file",
+                    file_types=[".h5ad"],
+                    file_count="single"
+                )
+                
+                analysis_type = gr.Dropdown(
+                    choices=["Basic Analysis", "Comprehensive Analysis"],
+                    value="Basic Analysis",
+                    label="Analysis Type",
+                    info="Basic: Fast clustering and annotation. Comprehensive: Full pipeline with communication analysis."
+                )
+                
+                max_cells = gr.Slider(
+                    minimum=1000,
+                    maximum=20000,
+                    value=5000,
+                    step=1000,
+                    label="Maximum Cells to Analyze",
+                    info="Reduce for faster analysis or if you have memory constraints"
+                )
+                
+                analyze_btn = gr.Button("🚀 Start Analysis", variant="primary", size="lg")
+            
+            with gr.Column(scale=2):
+                gr.Markdown("## 📊 Results")
+                output_text = gr.Markdown(value="Upload a file and click 'Start Analysis' to begin...")
+                output_plot = gr.Image(label="Analysis Visualization")
+                output_file = gr.File(label="Download Results (CSV)")
+        
+        # Examples
+        with gr.Row():
+            gr.Markdown("""
+## 📋 Example Analyses
+
+### What HeartMAP can analyze:
+- **Healthy heart tissue** from multiple chambers (RA, RV, LA, LV)
+- **Disease models** (heart failure, cardiomyopathy, etc.)
+- **Development studies** (embryonic, postnatal heart development)
+- **Treatment responses** (drug effects, therapeutic interventions)
+
+### Expected file format:
+- **AnnData (.h5ad)** format with gene expression counts
+- **Cells as observations** (rows) and **genes as variables** (columns)
+- Optional: **chamber annotations** in `.obs['chamber']`
+- Optional: **cell type annotations** in `.obs['cell_type']`
+
+### Analysis outputs:
+- **Cell clustering** and UMAP visualization
+- **Quality control** metrics and filtering
+- **Cell type identification** using marker genes
+- **Communication networks** between cell types
+- **Chamber-specific** analysis and comparisons
+            """)
+        
+        # Set up the analysis trigger
+        analyze_btn.click(
+            fn=analyze_heart_data,
+            inputs=[file_input, analysis_type, max_cells],
+            outputs=[output_text, output_plot, output_file],
+            show_progress=True
+        )
+        
+        # Footer
+        gr.Markdown("""
+---
+### 📖 Citation
+If you use HeartMAP in your research, please cite:
+```
+HeartMAP: A comprehensive platform for single-cell cardiac analysis
+https://github.com/Tumo505/GRAIL-Heart-cell-cell-communication
+```
+
+### 🔗 Links
+- **GitHub**: [HeartMAP Repository](https://github.com/Tumo505/GRAIL-Heart-cell-cell-communication)
+- **Documentation**: See README for detailed usage instructions
+- **Issues**: Report bugs or request features on GitHub
+
+**Note**: This is a research tool. Results should be validated with additional experiments.
+        """)
+    
+    return demo
+
+if __name__ == "__main__":
+    demo = create_demo_interface()
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False
+    )

config.yaml

@@ -0,0 +1,62 @@
+# HeartMAP Configuration for Hugging Face Deployment
+# Optimized for cloud environment with memory constraints
+
+data:
+  # File paths (will be set dynamically)
+  raw_data_dir: "data/raw"
+  processed_data_dir: "data/processed"
+  
+  # Processing limits (optimized for cloud)
+  max_cells_subset: 10000        # Reduced for cloud deployment
+  max_genes_subset: 5000         # Reduced for faster processing
+  min_genes: 200                 # Minimum genes per cell
+  min_cells: 3                   # Minimum cells per gene
+  max_pct_mt: 25                 # Maximum mitochondrial gene percentage
+  
+  # Performance settings
+  test_mode: true                # Enable for faster demo processing
+  use_raw_counts: true
+  backup_processed: false        # Disable to save space
+
+analysis:
+  # Clustering parameters
+  resolution: 0.5                # Leiden clustering resolution
+  n_neighbors: 15               # Reduced for speed
+  n_pcs: 30                     # Reduced principal components
+  
+  # Marker gene analysis
+  n_marker_genes: 20            # Reduced for cloud deployment
+  min_fold_change: 1.5
+  max_adj_pvalue: 0.05
+  
+  # Visualization
+  embedding_method: "umap"
+  color_palette: "tab10"
+
+model:
+  # Model settings
+  save_intermediate: false       # Disable to save space
+  use_gpu: false                # CPU only for cloud
+  batch_size: 1000              # Smaller batches for memory
+  random_state: 42
+  
+  # Feature selection
+  highly_variable_genes: 2000   # Reduced for speed
+  flavor: "seurat_v3"
+
+communication:
+  # Cell communication analysis
+  min_expression_threshold: 0.1
+  pvalue_threshold: 0.05
+  top_interactions: 50          # Reduced for demo
+  
+paths:
+  # Output directories (will be set dynamically)
+  base_dir: "."
+  results_dir: "results"
+  figures_dir: "figures"
+  logs_dir: "logs"
+  
+  # Model persistence
+  models_dir: "models"
+  cache_dir: "cache"

requirements.txt

@@ -0,0 +1,14 @@
+scanpy>=1.9.0
+pandas>=1.5.0
+numpy>=1.21.0
+scipy>=1.9.0
+scikit-learn>=1.1.0
+matplotlib>=3.5.0
+seaborn>=0.11.0
+anndata>=0.8.0
+plotly>=5.0.0
+networkx>=2.8.0
+tqdm
+statsmodels
+pyyaml>=6.0
+gradio>=4.0.0

src/heartmap.egg-info/PKG-INFO

@@ -0,0 +1,456 @@
+Metadata-Version: 2.4
+Name: heartmap
+Version: 1.0.0
+Summary: Heart Multi-chamber Analysis Platform for single-cell RNA-seq
+Home-page: https://github.com/Tumo505/HeartMap
+Author: Tumo Kgabeng, Lulu Wang, Harry Ngwangwa, Thanyani Pandelani
+Author-email: 28346416@mylife.unisa.ac.za
+Project-URL: Documentation, https://github.com/Tumo505/HeartMap/wiki
+Project-URL: Source, https://github.com/Tumo505/HeartMap
+Project-URL: Tracker, https://github.com/Tumo505/HeartMap/issues
+Keywords: single-cell,RNA-seq,heart,cell-communication,bioinformatics,spatial-transcriptomics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: scanpy>=1.9.0
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: scipy>=1.9.0
+Requires-Dist: scikit-learn>=1.1.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: seaborn>=0.11.0
+Requires-Dist: anndata>=0.8.0
+Requires-Dist: plotly>=5.0.0
+Requires-Dist: networkx>=2.8.0
+Requires-Dist: tqdm
+Requires-Dist: statsmodels
+Provides-Extra: communication
+Requires-Dist: liana>=0.1.0; extra == "communication"
+Requires-Dist: cellphonedb>=3.0.0; extra == "communication"
+Requires-Dist: omnipath>=1.0.0; extra == "communication"
+Provides-Extra: api
+Requires-Dist: fastapi>=0.100.0; extra == "api"
+Requires-Dist: uvicorn>=0.23.0; extra == "api"
+Requires-Dist: pydantic>=2.0.0; extra == "api"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: jupyter>=1.0.0; extra == "dev"
+Requires-Dist: notebook>=6.0.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: liana>=0.1.0; extra == "all"
+Requires-Dist: cellphonedb>=3.0.0; extra == "all"
+Requires-Dist: omnipath>=1.0.0; extra == "all"
+Requires-Dist: fastapi>=0.100.0; extra == "all"
+Requires-Dist: uvicorn>=0.23.0; extra == "all"
+Requires-Dist: pydantic>=2.0.0; extra == "all"
+Requires-Dist: pytest>=7.0.0; extra == "all"
+Requires-Dist: pytest-cov>=4.0.0; extra == "all"
+Requires-Dist: black>=23.0.0; extra == "all"
+Requires-Dist: flake8>=6.0.0; extra == "all"
+Requires-Dist: mypy>=1.0.0; extra == "all"
+Requires-Dist: jupyter>=1.0.0; extra == "all"
+Requires-Dist: notebook>=6.0.0; extra == "all"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# HeartMAP: Heart Multi-chamber Analysis Platform
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.16745118.svg)](https://doi.org/10.5281/zenodo.16745118)
+
+## 🫀 Project Overview
+
+HeartMAP is a comprehensive, modular analysis platform for mapping cell-cell communication across all four chambers of the human heart using single-cell RNA sequencing data. The platform integrates multiple analysis pipelines and machine learning models to provide insights into chamber-specific biology, cross-chamber signaling, and therapeutic targets.
+
+### � **New Refactored Architecture!**
+
+This version has been completely refactored for:
+- ✅ **Deployment Ready**: Easy installation and deployment on any platform
+- ✅ **Hugging Face Compatible**: Ready for Hugging Face Spaces deployment
+- ✅ **Modular Design**: Reusable components and clear separation of concerns
+- ✅ **API Interface**: REST API and CLI for integration with other tools
+- ✅ **Scalable**: Configurable memory usage and performance optimization
+- ✅ **Reproducible**: Comprehensive configuration management and testing
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Basic installation
+pip install heartmap
+
+# Full installation with all features
+pip install heartmap[all]
+
+# Development installation
+git clone https://github.com/Tumo505/HeartMap.git
+cd HeartMap
+pip install -e .[all]
+```
+
+### Usage
+
+#### Command Line Interface
+```bash
+# Run comprehensive analysis
+heartmap data/raw/healthy_human_4chamber_map_unnormalized_V3.h5ad --analysis-type comprehensive --output-dir results
+
+# Run basic analysis only
+heartmap data/raw/healthy_human_4chamber_map_unnormalized_V3.h5ad --analysis-type basic --output-dir results/basic
+```
+
+#### Python API
+```python
+from heartmap import Config, HeartMapModel
+from heartmap.pipelines import ComprehensivePipeline
+
+# Create configuration
+config = Config.default()
+config.data.max_cells_subset = 50000  # Optimize for your memory
+
+# Run comprehensive analysis
+pipeline = ComprehensivePipeline(config)
+results = pipeline.run("data/raw/healthy_human_4chamber_map_unnormalized_V3.h5ad", "results/")
+
+# Or use individual models
+model = HeartMapModel(config)
+model.fit(adata)
+predictions = model.predict(adata)
+```
+
+#### REST API
+```bash
+# Start API server
+heartmap-api --config config.yaml
+
+# Use API
+curl -X POST "http://localhost:8000/analyze" \
+     -H "Content-Type: multipart/form-data" \
+     -F "file=@your_data.h5ad" \
+     -F "analysis_type=comprehensive"
+```
+
+## 📁 New Project Structure
+
+```
+HeartMAP/
+├── src/
+│   └── heartmap/           # Main package
+│       ├── config/         # Configuration management
+│       ├── data/           # Data processing utilities
+│       ├── models/         # Analysis models
+│       ├── pipelines/      # Analysis pipelines
+│       ├── utils/          # Utility functions
+│       └── api/            # API interfaces
+├── scripts/                # Example scripts and tools
+│   ├── run_examples.py     # Usage examples
+│   ├── migrate.py          # Migration from legacy
+│   └── legacy/             # Original analysis scripts
+├── notebooks/              # Jupyter notebooks
+├── tests/                  # Test suite
+├── config.yaml            # Default configuration
+├── setup.py               # Package setup
+└── requirements-dev.txt   # Development dependencies
+```
+
+## 🔬 Analysis Components
+
+### 1. **Basic Pipeline**
+- Data preprocessing and quality control
+- Cell type annotation and clustering
+- Basic visualization and export
+
+### 2. **Advanced Communication Analysis**
+- Cell-cell communication inference
+- Communication hub identification
+- Pathway enrichment analysis
+- Temporal communication patterns
+
+### 3. **Multi-Chamber Atlas**
+- Chamber-specific marker identification
+- Cross-chamber correlation analysis
+- Chamber-specific therapeutic targets
+
+### 4. **Comprehensive Pipeline**
+- Integration of all analysis components
+- Comprehensive reporting and visualization
+- Model persistence and reusability
+
+## 📊 Key Features
+
+### 🔧 **Technical Features**
+- **Modular Architecture**: Independent, reusable components
+- **Configuration Management**: YAML/JSON configuration with validation
+- **Memory Optimization**: Automatic dataset scaling for available resources
+- **Model Persistence**: Save and load trained models
+- **Comprehensive Testing**: Full test suite with CI/CD
+- **API Integration**: REST API and CLI interfaces
+- **Docker Support**: Containerized deployment
+
+### 🧬 **Scientific Features**
+- **Chamber-Specific Analysis**: LA, RA, LV, RV specific patterns
+- **Communication Networks**: Cell-cell interaction mapping
+- **Hub Cell Identification**: Key regulatory cell types
+- **Pathway Analysis**: Cardiac development, angiogenesis, ECM remodeling
+- **Marker Discovery**: Chamber and cell-type specific biomarkers
+- **Cross-Chamber Correlations**: Inter-chamber relationship analysis
+
+## � Key Results
+
+### Chamber Distribution
+- **RA (Right Atrium):** 28.4% of cells
+- **LV (Left Ventricle):** 27.0% of cells  
+- **LA (Left Atrium):** 26.4% of cells
+- **RV (Right Ventricle):** 18.2% of cells
+
+### Chamber-Specific Markers
+- **RA:** NPPA, MIR100HG, MYL7, MYL4, PDE4D
+- **RV:** NEAT1, MYH7, FHL2, C15orf41, PCDH7
+- **LA:** NPPA, ELN, MYL7, EBF2, RORA
+- **LV:** CD36, LINC00486, FHL2, RP11-532N4.2, MYH7
+
+### Cross-Chamber Correlations
+- **RV vs LV:** r = 0.985 (highest correlation)
+- **RA vs LA:** r = 0.960
+- **LA vs LV:** r = 0.870 (lowest correlation)
+
+## � Deployment Options
+
+### Hugging Face Spaces
+```bash
+# Deploy to Hugging Face Spaces
+git clone https://github.com/Tumo505/HeartMap.git
+cd HeartMap
+# Upload app.py and requirements to your Hugging Face Space
+```
+
+### Docker Deployment
+```bash
+# Build and run with Docker
+docker build -t heartmap .
+docker run -p 8000:8000 -v $(pwd)/data:/app/data heartmap
+
+# Or use docker-compose
+docker-compose up
+```
+
+### Local Development
+```bash
+# Clone and setup
+git clone https://github.com/Tumo505/HeartMap.git
+cd HeartMap
+pip install -e .[dev]
+
+# Run tests
+python tests/test_heartmap.py
+
+# Start development server
+python scripts/run_api_server.py
+```
+
+## 📚 Documentation
+
+- **API Documentation**: Available at `/docs` when running the API server
+- **Configuration Guide**: See `config.yaml` for all options
+- **Example Notebooks**: Check `notebooks/` directory
+- **Migration Guide**: Run `python scripts/migrate.py` to convert legacy analysis
+
+## 🔄 Migration from Legacy Version
+
+If you have existing HeartMAP analysis results:
+
+```bash
+# Run migration script
+python scripts/migrate.py
+
+# This will:
+# - Copy legacy scripts to scripts/legacy/
+# - Create migration notebooks
+# - Generate example scripts with new API
+# - Set up deployment files
+```
+
+## 🧪 Configuration
+
+Create a `config.yaml` file to customize analysis:
+
+```yaml
+data:
+  min_genes: 200
+  min_cells: 3
+  max_cells_subset: 50000    # Optimize for your memory
+  max_genes_subset: 5000     # Reduce for faster analysis
+  random_seed: 42
+
+analysis:
+  resolution: 0.5
+  n_marker_genes: 25
+  use_leiden: true
+
+model:
+  save_intermediate: true
+  use_gpu: false
+```
+
+## 🎯 Clinical Applications
+
+- **Personalized Medicine**: Chamber-specific treatment strategies
+- **Drug Development**: Chamber-specific therapeutic targets
+- **Disease Understanding**: Chamber-specific disease mechanisms
+- **Biomarker Discovery**: Chamber and communication-specific markers
+
+## 🔒 Data Integrity & Reproducibility
+
+- **SHA-256 Checksums**: Automatic data integrity verification
+- **Fixed Random Seeds**: Reproducible results across runs
+- **Version Control**: Model and configuration versioning
+- **Comprehensive Logging**: Full analysis provenance tracking
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature-name`
+3. Install development dependencies: `pip install -e .[dev]`
+4. Run tests: `python tests/test_heartmap.py`
+5. Submit a pull request
+
+## 📄 License
+
+This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
+
+## 📖 Citation
+
+```bibtex
+@software{heartmap2024,
+  title={HeartMAP: A Multi-Chamber Spatial Framework for Cardiac Cell-Cell Communication},
+  author={Kgabeng, Tumo and Pandelani, Thanyani and Wang, Lulu and Ngwangwa, Harry},
+  year={2024},
+  url={https://github.com/Tumo505/HeartMap},
+  version={1.0.0}
+}
+```
+
+## 🆘 Support
+
+- **Issues**: [GitHub Issues](https://github.com/Tumo505/HeartMap/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/Tumo505/HeartMap/discussions)
+- **Email**: 28346416@mylife.unisa.ac.za
+
+## 🎉 Acknowledgments
+
+- Department of Mechanical, Bioresources and Biomedical Engineering, University of South Africa
+- Department of Engineering, Reykjavik University
+- Single Cell Portal (SCP498) for providing the heart dataset
+- The open-source scientific Python community
+
+## 🔒 Data Integrity
+
+### SHA-256 Checksums
+To ensure the integrity of raw data files, the HeartMAP project uses **SHA-256 checksums**. This guarantees that the raw data files have not been modified or corrupted during storage or transfer.
+
+### Where SHA-256 is Used:
+1. **Raw Data Verification**:
+   - Before preprocessing, the pipeline verifies the integrity of raw data files in the `data/raw/` directory using a `checksums.txt` file.
+   - Example:
+     ```bash
+     python utils/sha256_checksum.py verify data/raw data/raw/checksums.txt
+     ```
+
+2. **Checksum Generation**:
+   - SHA-256 checksums are generated for all raw data files and stored in `checksums.txt`.
+   - Example:
+     ```bash
+     python utils/sha256_checksum.py generate data/raw data/raw/checksums.txt
+     ```
+
+### Why SHA-256?
+Using SHA-256 ensures:
+- Data integrity during storage and transfer.
+- Detection of accidental or malicious modifications to raw data files.
+- Reproducibility by verifying that the same raw data is used across different runs.
+
+## 🔄 Reproducibility
+
+The HeartMAP project ensures reproducibility in all stochastic processes by using fixed random seeds. This guarantees consistent results across different runs of the pipeline. Below are the key areas where random seeds are applied:
+
+1. **Random Sampling**:
+   - Fixed seed (`seed = 42`) is used for randomly sampling cells during data scaling and preprocessing.
+   - Example:
+     ```python
+     np.random.seed(42)
+     cell_indices = np.random.choice(adata.n_obs, size=50000, replace=False)
+     ```
+
+2. **Mock Data Generation**:
+   - Fixed seed is used to generate mock communication interactions for testing and visualization.
+   - Example:
+     ```python
+     np.random.seed(42)
+     mock_interactions = pd.DataFrame({
+         'source': np.random.choice(cell_types.index, n_interactions),
+         'target': np.random.choice(cell_types.index, n_interactions),
+         'score': np.random.uniform(0, 1, n_interactions)
+     })
+     ```
+
+3. **Clustering**:
+   - Fixed seed (`random_state=42`) is used for K-means clustering as a fallback when Leiden clustering is unavailable.
+   - Example:
+     ```python
+     kmeans = KMeans(n_clusters=n_clusters, random_state=42)
+     ```
+
+4. **LIANA Analysis**:
+   - Fixed seed is passed to the LIANA analysis function for reproducibility in ligand-receptor interaction analysis.
+   - Example:
+     ```python
+     li.mt.rank_aggregate.by_sample(
+         adata,
+         groupby=cell_type_col,
+         resource_name='consensus',
+         n_perms=100,
+         seed=42,
+         verbose=True
+     )
+     ```
+
+### Why Fixed Seeds?
+Using fixed random seeds ensures:
+- Consistent results across different runs of the pipeline.
+- Easier debugging and validation of results.
+- Reproducibility for scientific publications and collaborative workflows.
+
+## 🚀 Next Steps
+
+1. Validate markers and communication patterns with literature and experiments
+2. Integrate spatial transcriptomics and disease data
+3. Develop chamber-specific clinical applications
+

src/heartmap.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+NOTICE
+README.md
+setup.py
+src/heartmap/__init__.py
+src/heartmap.egg-info/PKG-INFO
+src/heartmap.egg-info/SOURCES.txt
+src/heartmap.egg-info/dependency_links.txt
+src/heartmap.egg-info/entry_points.txt
+src/heartmap.egg-info/requires.txt
+src/heartmap.egg-info/top_level.txt
+src/heartmap/api/__init__.py
+src/heartmap/config/__init__.py
+src/heartmap/data/__init__.py
+src/heartmap/models/__init__.py
+src/heartmap/pipelines/__init__.py
+src/heartmap/utils/__init__.py
+tests/test_heartmap.py

src/heartmap.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

src/heartmap.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+heartmap = heartmap.api:run_cli
+heartmap-api = heartmap.api:create_api

src/heartmap.egg-info/requires.txt

@@ -0,0 +1,46 @@
+scanpy>=1.9.0
+pandas>=1.5.0
+numpy>=1.21.0
+scipy>=1.9.0
+scikit-learn>=1.1.0
+matplotlib>=3.5.0
+seaborn>=0.11.0
+anndata>=0.8.0
+plotly>=5.0.0
+networkx>=2.8.0
+tqdm
+statsmodels
+
+[all]
+liana>=0.1.0
+cellphonedb>=3.0.0
+omnipath>=1.0.0
+fastapi>=0.100.0
+uvicorn>=0.23.0
+pydantic>=2.0.0
+pytest>=7.0.0
+pytest-cov>=4.0.0
+black>=23.0.0
+flake8>=6.0.0
+mypy>=1.0.0
+jupyter>=1.0.0
+notebook>=6.0.0
+
+[api]
+fastapi>=0.100.0
+uvicorn>=0.23.0
+pydantic>=2.0.0
+
+[communication]
+liana>=0.1.0
+cellphonedb>=3.0.0
+omnipath>=1.0.0
+
+[dev]
+pytest>=7.0.0
+pytest-cov>=4.0.0
+black>=23.0.0
+flake8>=6.0.0
+mypy>=1.0.0
+jupyter>=1.0.0
+notebook>=6.0.0

src/heartmap.egg-info/top_level.txt

@@ -0,0 +1 @@
+heartmap

src/heartmap/__init__.py

@@ -0,0 +1,22 @@
+"""
+HeartMAP: Heart Multi-chamber Analysis Platform
+
+A comprehensive framework for analyzing cell-cell communication across all four chambers 
+of the human heart using single-cell RNA sequencing data.
+"""
+
+__version__ = "1.0.0"
+__author__ = "Tumo Kgabeng, Thanyani Pandelani, Lulu Wang, Harry Ngwangwa"
+__email__ = "28346416@mylife.unisa.ac.za"
+
+from .models import HeartMapModel
+from .pipelines import BasicPipeline, AdvancedCommunicationPipeline, MultiChamberPipeline
+from .config import Config
+
+__all__ = [
+    "HeartMapModel",
+    "BasicPipeline", 
+    "AdvancedCommunicationPipeline",
+    "MultiChamberPipeline",
+    "Config"
+]

src/heartmap/api/__init__.py

@@ -0,0 +1,259 @@
+"""
+API interface for HeartMAP
+"""
+
+from typing import Dict, Any, Optional, Union, List
+import warnings
+from pathlib import Path
+import tempfile
+import json
+
+from ..config import Config, load_config
+from ..models import HeartMapModel
+
+try:
+    from fastapi import FastAPI, UploadFile, File, HTTPException
+    from fastapi.responses import FileResponse, JSONResponse
+    from pydantic import BaseModel
+    import uvicorn
+    FASTAPI_AVAILABLE = True
+except ImportError:
+    FASTAPI_AVAILABLE = False
+    warnings.warn("FastAPI not available. Install with: pip install fastapi uvicorn")
+
+from ..models import HeartMapModel
+from ..pipelines import ComprehensivePipeline, BasicPipeline, AdvancedCommunicationPipeline, MultiChamberPipeline
+
+
+class AnalysisRequest(BaseModel):
+    """Request model for analysis"""
+    analysis_type: str = "comprehensive"  # basic, advanced, multi_chamber, comprehensive
+    config_overrides: Optional[Dict[str, Any]] = None
+    output_format: str = "json"  # json, csv, h5ad
+
+
+class AnalysisResponse(BaseModel):
+    """Response model for analysis"""
+    status: str
+    message: str
+    results: Optional[Dict[str, Any]] = None
+    output_files: Optional[List[str]] = None
+
+
+class HeartMapAPI:
+    """REST API for HeartMAP analysis"""
+    
+    def __init__(self, config: Union[str, Config, None] = None):
+        if isinstance(config, Config):
+            self.config = config
+        else:
+            self.config = load_config(config)
+        self.app = FastAPI(
+            title="HeartMAP API",
+            description="Heart Multi-chamber Analysis Platform API",
+            version="1.0.0"
+        ) if FASTAPI_AVAILABLE else None
+        
+        if FASTAPI_AVAILABLE:
+            self._setup_routes()
+    
+    def _setup_routes(self):
+        """Setup API routes"""
+        
+        @self.app.get("/")
+        async def root():
+            return {"message": "HeartMAP API", "version": "1.0.0"}
+        
+        @self.app.get("/health")
+        async def health_check():
+            return {"status": "healthy"}
+        
+        @self.app.post("/analyze", response_model=AnalysisResponse)
+        async def analyze_data(
+            file: UploadFile = File(...),
+            request: AnalysisRequest = AnalysisRequest()
+        ):
+            """Analyze single-cell data"""
+            try:
+                # Save uploaded file temporarily
+                with tempfile.NamedTemporaryFile(delete=False, suffix=".h5ad") as tmp_file:
+                    content = await file.read()
+                    tmp_file.write(content)
+                    tmp_file_path = tmp_file.name
+                
+                # Update config with overrides
+                if request.config_overrides:
+                    # Apply config overrides (simplified)
+                    pass
+                
+                # Create output directory
+                with tempfile.TemporaryDirectory() as output_dir:
+                    # Run analysis based on type
+                    pipeline = self._get_pipeline(request.analysis_type)
+                    results = pipeline.run(tmp_file_path, output_dir)
+                    
+                    # Format response
+                    response_data = self._format_results(results, request.output_format)
+                    
+                    return AnalysisResponse(
+                        status="success",
+                        message="Analysis completed successfully",
+                        results=response_data
+                    )
+                    
+            except Exception as e:
+                raise HTTPException(status_code=500, detail=str(e))
+            finally:
+                # Clean up temporary file
+                Path(tmp_file_path).unlink(missing_ok=True)
+        
+        @self.app.get("/models")
+        async def list_models():
+            """List available analysis models"""
+            return {
+                "models": [
+                    "basic",
+                    "advanced_communication", 
+                    "multi_chamber",
+                    "comprehensive"
+                ]
+            }
+        
+        @self.app.get("/config")
+        async def get_config():
+            """Get current configuration"""
+            return self.config.to_dict()
+        
+        @self.app.post("/config")
+        async def update_config(new_config: Dict[str, Any]):
+            """Update configuration"""
+            try:
+                self.config = Config.from_dict(new_config)
+                return {"status": "success", "message": "Configuration updated"}
+            except Exception as e:
+                raise HTTPException(status_code=400, detail=str(e))
+    
+    def _get_pipeline(self, analysis_type: str):
+        """Get analysis pipeline by type"""
+        pipelines = {
+            "basic": BasicPipeline(self.config),
+            "advanced_communication": AdvancedCommunicationPipeline(self.config),
+            "multi_chamber": MultiChamberPipeline(self.config),
+            "comprehensive": ComprehensivePipeline(self.config)
+        }
+        
+        if analysis_type not in pipelines:
+            raise ValueError(f"Unknown analysis type: {analysis_type}")
+        
+        return pipelines[analysis_type]
+    
+    def _format_results(self, results: Dict[str, Any], output_format: str) -> Dict[str, Any]:
+        """Format results for API response"""
+        if output_format == "json":
+            # Convert complex objects to serializable format
+            formatted = {}
+            
+            if 'results' in results:
+                res = results['results']
+                formatted['summary'] = {
+                    'n_cells': results.get('adata', {}).n_obs if 'adata' in results else 0,
+                    'analysis_completed': True
+                }
+                
+                # Extract key metrics
+                if 'annotation' in res:
+                    ann_res = res['annotation']
+                    if 'metadata' in ann_res:
+                        formatted['annotation_summary'] = ann_res['metadata']
+                
+                if 'communication' in res:
+                    comm_res = res['communication']
+                    if 'metadata' in comm_res:
+                        formatted['communication_summary'] = comm_res['metadata']
+                
+                if 'multi_chamber' in res:
+                    chamber_res = res['multi_chamber']
+                    if 'metadata' in chamber_res:
+                        formatted['multi_chamber_summary'] = chamber_res['metadata']
+            
+            return formatted
+        
+        else:
+            raise ValueError(f"Unsupported output format: {output_format}")
+    
+    def run(self, host: str = "0.0.0.0", port: int = 8000, debug: bool = False):
+        """Run the API server"""
+        if not FASTAPI_AVAILABLE:
+            raise ImportError("FastAPI not available. Install with: pip install fastapi uvicorn")
+        
+        uvicorn.run(self.app, host=host, port=port, debug=debug)
+
+
+class CLIInterface:
+    """Command line interface for HeartMAP"""
+    
+    def __init__(self):
+        self.config = None
+    
+    def run_analysis(self, 
+                    data_path: str,
+                    analysis_type: str = "comprehensive",
+                    output_dir: str = "results",
+                    config_path: Optional[str] = None):
+        """Run analysis from command line"""
+        
+        # Load configuration
+        self.config = load_config(config_path)
+        
+        # Update output directory
+        self.config.update_paths(Path(output_dir).parent)
+        self.config.create_directories()
+        
+        # Get pipeline
+        pipelines = {
+            "basic": BasicPipeline(self.config),
+            "advanced": AdvancedCommunicationPipeline(self.config),
+            "multi_chamber": MultiChamberPipeline(self.config),
+            "comprehensive": ComprehensivePipeline(self.config)
+        }
+        
+        if analysis_type not in pipelines:
+            raise ValueError(f"Unknown analysis type: {analysis_type}")
+        
+        pipeline = pipelines[analysis_type]
+        
+        # Run analysis
+        print(f"Starting {analysis_type} analysis...")
+        results = pipeline.run(data_path, output_dir)
+        
+        print(f"Analysis completed! Results saved to: {output_dir}")
+        return results
+
+
+def create_api(config_path: Optional[str] = None) -> HeartMapAPI:
+    """Create HeartMAP API instance"""
+    return HeartMapAPI(config_path)
+
+
+def run_cli():
+    """Run command line interface"""
+    import argparse
+    
+    parser = argparse.ArgumentParser(description="HeartMAP Analysis Platform")
+    parser.add_argument("data_path", help="Path to input data file")
+    parser.add_argument("--analysis-type", default="comprehensive",
+                       choices=["basic", "advanced", "multi_chamber", "comprehensive"],
+                       help="Type of analysis to run")
+    parser.add_argument("--output-dir", default="results",
+                       help="Output directory for results")
+    parser.add_argument("--config", help="Path to configuration file")
+    
+    args = parser.parse_args()
+    
+    cli = CLIInterface()
+    cli.run_analysis(
+        data_path=args.data_path,
+        analysis_type=args.analysis_type,
+        output_dir=args.output_dir,
+        config_path=args.config
+    )

src/heartmap/config/__init__.py

@@ -0,0 +1,156 @@
+"""
+Configuration management for HeartMAP
+"""
+
+import os
+from pathlib import Path
+from typing import Dict, Any, Optional, List
+import yaml
+import json
+from dataclasses import dataclass, asdict
+
+
+@dataclass
+class DataConfig:
+    """Data processing configuration"""
+    min_genes: int = 200
+    min_cells: int = 3
+    max_cells_subset: Optional[int] = None
+    max_genes_subset: Optional[int] = None
+    target_sum: float = 1e4
+    n_top_genes: int = 2000
+    random_seed: int = 42
+    test_mode: bool = False
+
+
+@dataclass
+class AnalysisConfig:
+    """Analysis configuration"""
+    n_components_pca: int = 50
+    n_neighbors: int = 10
+    n_pcs: int = 40
+    resolution: float = 0.5
+    n_marker_genes: int = 25
+    use_leiden: bool = True
+    use_liana: bool = True
+
+
+@dataclass
+class ModelConfig:
+    """Model configuration"""
+    model_type: str = "comprehensive"
+    save_intermediate: bool = True
+    use_gpu: bool = False
+    batch_size: Optional[int] = None
+    max_memory_gb: Optional[float] = None
+
+
+@dataclass
+class PathConfig:
+    """Path configuration"""
+    data_dir: str = "data"
+    raw_data_dir: str = "data/raw"
+    processed_data_dir: str = "data/processed"
+    results_dir: str = "results"
+    figures_dir: str = "figures"
+    models_dir: str = "models"
+    
+    
+@dataclass
+class Config:
+    """Main configuration class"""
+    data: DataConfig
+    analysis: AnalysisConfig
+    model: ModelConfig
+    paths: PathConfig
+    
+    @classmethod
+    def from_dict(cls, config_dict: Dict[str, Any]) -> 'Config':
+        """Create config from dictionary"""
+        return cls(
+            data=DataConfig(**config_dict.get('data', {})),
+            analysis=AnalysisConfig(**config_dict.get('analysis', {})),
+            model=ModelConfig(**config_dict.get('model', {})),
+            paths=PathConfig(**config_dict.get('paths', {}))
+        )
+    
+    @classmethod
+    def from_yaml(cls, yaml_path: str) -> 'Config':
+        """Load config from YAML file"""
+        with open(yaml_path, 'r') as f:
+            config_dict = yaml.safe_load(f)
+        return cls.from_dict(config_dict)
+    
+    @classmethod
+    def from_json(cls, json_path: str) -> 'Config':
+        """Load config from JSON file"""
+        with open(json_path, 'r') as f:
+            config_dict = json.load(f)
+        return cls.from_dict(config_dict)
+    
+    @classmethod
+    def default(cls) -> 'Config':
+        """Create default configuration"""
+        return cls(
+            data=DataConfig(),
+            analysis=AnalysisConfig(),
+            model=ModelConfig(),
+            paths=PathConfig()
+        )
+    
+    @classmethod
+    def from_file(cls, file_path: str) -> 'Config':
+        """Load config from file (YAML or JSON)"""
+        return load_config(file_path)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert config to dictionary"""
+        return asdict(self)
+    
+    def save_yaml(self, yaml_path: str) -> None:
+        """Save config to YAML file"""
+        with open(yaml_path, 'w') as f:
+            yaml.dump(self.to_dict(), f, default_flow_style=False)
+    
+    def save_json(self, json_path: str) -> None:
+        """Save config to JSON file"""
+        with open(json_path, 'w') as f:
+            json.dump(self.to_dict(), f, indent=2)
+    
+    def update_paths(self, base_dir: str) -> None:
+        """Update all paths relative to base directory"""
+        base_path = Path(base_dir)
+        self.paths.data_dir = str(base_path / "data")
+        self.paths.raw_data_dir = str(base_path / "data" / "raw")
+        self.paths.processed_data_dir = str(base_path / "data" / "processed")
+        self.paths.results_dir = str(base_path / "results")
+        self.paths.figures_dir = str(base_path / "figures")
+        self.paths.models_dir = str(base_path / "models")
+    
+    def create_directories(self) -> None:
+        """Create all configured directories"""
+        dirs_to_create = [
+            self.paths.data_dir,
+            self.paths.raw_data_dir,
+            self.paths.processed_data_dir,
+            self.paths.results_dir,
+            self.paths.figures_dir,
+            self.paths.models_dir
+        ]
+        
+        for dir_path in dirs_to_create:
+            Path(dir_path).mkdir(parents=True, exist_ok=True)
+
+
+def load_config(config_path: Optional[str] = None) -> Config:
+    """Load configuration from file or return default"""
+    if config_path is None:
+        return Config.default()
+    
+    config_path = Path(config_path)
+    if config_path.suffix.lower() in ['.yml', '.yaml']:
+        return Config.from_yaml(str(config_path))
+    elif config_path.suffix.lower() == '.json':
+        return Config.from_json(str(config_path))
+    else:
+        raise ValueError(f"Unsupported config file format: {config_path.suffix}")

src/heartmap/data/__init__.py

@@ -0,0 +1,250 @@
+"""
+Data processing utilities for HeartMAP
+"""
+
+import os
+import hashlib
+import subprocess
+from pathlib import Path
+from typing import Optional, Union, Tuple, Dict, Any, List
+import warnings
+
+import scanpy as sc
+import pandas as pd
+import numpy as np
+import anndata as ad
+from scipy.sparse import issparse
+
+from ..config import Config
+
+
+class DataValidator:
+    """Validate data integrity and format"""
+    
+    @staticmethod
+    def verify_checksum(file_path: str, expected_checksum: str) -> bool:
+        """Verify file checksum"""
+        sha256_hash = hashlib.sha256()
+        with open(file_path, "rb") as f:
+            for byte_block in iter(lambda: f.read(4096), b""):
+                sha256_hash.update(byte_block)
+        return sha256_hash.hexdigest() == expected_checksum
+    
+    @staticmethod
+    def validate_anndata(adata: ad.AnnData) -> Tuple[bool, List[str]]:
+        """Validate AnnData object structure"""
+        issues = []
+        
+        if adata.n_obs == 0:
+            issues.append("No cells in dataset")
+        if adata.n_vars == 0:
+            issues.append("No genes in dataset")
+        
+        # Check for required obs columns
+        required_obs = ['n_genes', 'n_counts']
+        for col in required_obs:
+            if col not in adata.obs.columns:
+                issues.append(f"Missing required obs column: {col}")
+        
+        # Check for NaN/inf values
+        if issparse(adata.X):
+            if not np.isfinite(adata.X.data).all():
+                issues.append("Non-finite values in X matrix")
+        else:
+            if not np.isfinite(adata.X).all():
+                issues.append("Non-finite values in X matrix")
+        
+        return len(issues) == 0, issues
+
+
+class DataLoader:
+    """Load and preprocess data"""
+    
+    def __init__(self, config: Config):
+        self.config = config
+        
+    def load_raw_data(self, file_path: str, verify_integrity: bool = True) -> ad.AnnData:
+        """Load raw single-cell data"""
+        file_path = Path(file_path)
+        
+        if not file_path.exists():
+            raise FileNotFoundError(f"Data file not found: {file_path}")
+        
+        # Load data based on file format
+        if file_path.suffix == '.h5ad':
+            adata = sc.read_h5ad(file_path)
+        elif file_path.suffix == '.h5':
+            adata = sc.read_10x_h5(file_path, genome=None, gex_only=True)
+        elif file_path.suffix == '.csv':
+            adata = sc.read_csv(file_path).T  # Transpose to have genes as variables
+        else:
+            raise ValueError(f"Unsupported file format: {file_path.suffix}")
+        
+        # Validate data
+        is_valid, issues = DataValidator.validate_anndata(adata)
+        if not is_valid:
+            warnings.warn(f"Data validation issues: {'; '.join(issues)}")
+        
+        return adata
+    
+    def preprocess_basic(self, adata: ad.AnnData) -> ad.AnnData:
+        """Basic preprocessing pipeline"""
+        adata = adata.copy()
+        
+        # Make gene names unique
+        adata.var_names_make_unique()
+        
+        # Store raw data
+        adata.raw = adata
+        
+        # Basic filtering
+        sc.pp.filter_cells(adata, min_genes=self.config.data.min_genes)
+        sc.pp.filter_genes(adata, min_cells=self.config.data.min_cells)
+        
+        return adata
+    
+    def calculate_qc_metrics(self, adata: ad.AnnData) -> ad.AnnData:
+        """Calculate quality control metrics"""
+        adata = adata.copy()
+        
+        # Mitochondrial genes
+        adata.var['mt'] = adata.var_names.str.startswith('MT-')
+        
+        # Ribosomal genes
+        adata.var['ribo'] = adata.var_names.str.startswith(('RPS', 'RPL'))
+        
+        # Hemoglobin genes
+        adata.var['hb'] = adata.var_names.str.contains('^HB[^(P)]')
+        
+        # Calculate QC metrics
+        sc.pp.calculate_qc_metrics(
+            adata, 
+            percent_top=None, 
+            log1p=False, 
+            inplace=True
+        )
+        sc.pp.calculate_qc_metrics(
+            adata, 
+            qc_vars=['mt', 'ribo', 'hb'], 
+            percent_top=None, 
+            log1p=False, 
+            inplace=True
+        )
+        
+        return adata
+    
+    def scale_for_memory(self, adata: ad.AnnData) -> ad.AnnData:
+        """Scale dataset for memory constraints"""
+        if self.config.data.max_cells_subset and adata.n_obs > self.config.data.max_cells_subset:
+            np.random.seed(self.config.data.random_seed)
+            cell_indices = np.random.choice(
+                adata.n_obs, 
+                size=self.config.data.max_cells_subset, 
+                replace=False
+            )
+            adata = adata[cell_indices].copy()
+        
+        if self.config.data.max_genes_subset and adata.n_vars > self.config.data.max_genes_subset:
+            # Select most variable genes
+            if issparse(adata.X):
+                # For sparse matrices, convert to dense temporarily for variance calculation
+                dense_subset = adata.X[:min(1000, adata.n_obs), :].toarray()
+                gene_vars = np.var(dense_subset, axis=0)
+            else:
+                gene_vars = np.var(adata.X, axis=0)
+            
+            top_gene_indices = np.argsort(gene_vars)[-self.config.data.max_genes_subset:]
+            adata = adata[:, top_gene_indices].copy()
+        
+        return adata
+    
+    def normalize_and_scale(self, adata: ad.AnnData) -> ad.AnnData:
+        """Normalize and scale data"""
+        adata = adata.copy()
+        
+        # Clean data - remove infinite values
+        if issparse(adata.X):
+            adata.X.data = np.nan_to_num(adata.X.data, nan=0, posinf=0, neginf=0)
+        else:
+            adata.X = np.nan_to_num(adata.X, nan=0, posinf=0, neginf=0)
+        
+        # Normalize to target sum
+        sc.pp.normalize_total(adata, target_sum=self.config.data.target_sum)
+        
+        # Log transform
+        sc.pp.log1p(adata)
+        
+        return adata
+
+
+    def preprocess(self, adata: ad.AnnData) -> ad.AnnData:
+        """Complete preprocessing pipeline (convenience method)"""
+        adata = self.preprocess_basic(adata)
+        adata = self.scale_for_memory(adata)
+        adata = self.normalize_and_scale(adata)
+        return adata
+
+
+class DataProcessor:
+    """Main data processing class"""
+    
+    def __init__(self, config: Config):
+        self.config = config
+        self.loader = DataLoader(config)
+    
+    def process_from_raw(self, 
+                        file_path: str, 
+                        save_intermediate: bool = True) -> ad.AnnData:
+        """Complete processing pipeline from raw data"""
+        
+        # Load raw data
+        adata = self.loader.load_raw_data(file_path)
+        
+        # Basic preprocessing
+        adata = self.loader.preprocess_basic(adata)
+        
+        if save_intermediate:
+            adata.write(os.path.join(
+                self.config.paths.processed_data_dir, 
+                "preprocessed.h5ad"
+            ))
+        
+        # Calculate QC metrics
+        adata = self.loader.calculate_qc_metrics(adata)
+        
+        if save_intermediate:
+            adata.write(os.path.join(
+                self.config.paths.processed_data_dir, 
+                "qc_calculated.h5ad"
+            ))
+        
+        # Scale for memory if needed
+        if (self.config.data.max_cells_subset or 
+            self.config.data.max_genes_subset):
+            adata = self.loader.scale_for_memory(adata)
+            
+            if save_intermediate:
+                adata.write(os.path.join(
+                    self.config.paths.processed_data_dir, 
+                    "scaled.h5ad"
+                ))
+        
+        # Normalize and scale
+        adata = self.loader.normalize_and_scale(adata)
+        
+        if save_intermediate:
+            adata.write(os.path.join(
+                self.config.paths.processed_data_dir, 
+                "normalized.h5ad"
+            ))
+        
+        return adata
+    
+    def create_test_dataset(self, adata: ad.AnnData, n_cells: int = 1000) -> ad.AnnData:
+        """Create small test dataset"""
+        np.random.seed(self.config.data.random_seed)
+        
+        n_cells = min(n_cells, adata.n_obs)
+        cell_indices = np.random.choice(adata.n_obs, size=n_cells, replace=False)
+        
+        return adata[cell_indices].copy()

src/heartmap/models/__init__.py

@@ -0,0 +1,486 @@
+"""
+Core models for HeartMAP analysis
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional, List, Tuple
+import warnings
+import pickle
+import json
+from pathlib import Path
+
+try:
+    import scanpy as sc
+    import pandas as pd
+    import numpy as np
+    import anndata as ad
+    from scipy.sparse import issparse
+    from scipy.stats import pearsonr
+    from sklearn.metrics.pairwise import cosine_similarity
+    DEPS_AVAILABLE = True
+except ImportError:
+    DEPS_AVAILABLE = False
+    warnings.warn("Some dependencies not available. Install requirements for full functionality.")
+
+from ..config import Config
+
+
+class BaseModel(ABC):
+    """Base class for all HeartMAP models"""
+    
+    def __init__(self, config: Config):
+        self.config = config
+        self.is_fitted = False
+        self.metadata = {}
+    
+    @abstractmethod
+    def fit(self, adata: 'ad.AnnData') -> 'BaseModel':
+        """Fit the model to data"""
+        pass
+    
+    @abstractmethod
+    def predict(self, adata: 'ad.AnnData') -> Dict[str, Any]:
+        """Make predictions using the fitted model"""
+        pass
+    
+    def save(self, path: str) -> None:
+        """Save model to disk"""
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        
+        model_data = {
+            'config': self.config.to_dict(),
+            'is_fitted': self.is_fitted,
+            'metadata': self.metadata,
+            'model_state': self._get_state()
+        }
+        
+        with open(path, 'wb') as f:
+            pickle.dump(model_data, f)
+    
+    @classmethod
+    def load(cls, path: str) -> 'BaseModel':
+        """Load model from disk"""
+        with open(path, 'rb') as f:
+            model_data = pickle.load(f)
+        
+        config = Config.from_dict(model_data['config'])
+        model = cls(config)
+        model.is_fitted = model_data['is_fitted']
+        model.metadata = model_data['metadata']
+        model._set_state(model_data['model_state'])
+        
+        return model
+    
+    @abstractmethod
+    def _get_state(self) -> Dict[str, Any]:
+        """Get model internal state for saving"""
+        pass
+    
+    @abstractmethod
+    def _set_state(self, state: Dict[str, Any]) -> None:
+        """Set model internal state from loaded data"""
+        pass
+
+
+class CellAnnotationModel(BaseModel):
+    """Model for cell type annotation"""
+    
+    def __init__(self, config: Config):
+        super().__init__(config)
+        self.cluster_labels = None
+        self.marker_genes = None
+        self.cell_type_map = None
+    
+    def fit(self, adata: 'ad.AnnData') -> 'CellAnnotationModel':
+        """Fit cell annotation model"""
+        if not DEPS_AVAILABLE:
+            raise ImportError("Required dependencies not available")
+        
+        adata = adata.copy()
+        
+        # Find highly variable genes
+        sc.pp.highly_variable_genes(
+            adata, 
+            n_top_genes=self.config.data.n_top_genes
+        )
+        adata.raw = adata
+        adata = adata[:, adata.var.highly_variable]
+        
+        # Scale data
+        sc.pp.scale(adata, max_value=10)
+        
+        # PCA
+        sc.tl.pca(adata, n_comps=self.config.analysis.n_components_pca)
+        
+        # Neighborhood graph
+        sc.pp.neighbors(
+            adata,
+            n_neighbors=self.config.analysis.n_neighbors,
+            n_pcs=self.config.analysis.n_pcs
+        )
+        
+        # Clustering
+        if self.config.analysis.use_leiden:
+            try:
+                sc.tl.leiden(adata, resolution=self.config.analysis.resolution)
+                cluster_key = 'leiden'
+            except ImportError:
+                # Fallback to K-means
+                from sklearn.cluster import KMeans
+                n_clusters = 10
+                kmeans = KMeans(
+                    n_clusters=n_clusters, 
+                    random_state=self.config.data.random_seed
+                )
+                cluster_labels = kmeans.fit_predict(adata.obsm['X_pca'][:, :20])
+                adata.obs['leiden'] = pd.Categorical(cluster_labels.astype(str))
+                cluster_key = 'leiden'
+        
+        # UMAP
+        sc.tl.umap(adata)
+        
+        # Find marker genes
+        sc.tl.rank_genes_groups(
+            adata, 
+            cluster_key, 
+            method='wilcoxon',
+            n_genes=self.config.analysis.n_marker_genes
+        )
+        
+        self.cluster_labels = adata.obs[cluster_key].copy()
+        self.marker_genes = pd.DataFrame(adata.uns['rank_genes_groups']['names'])
+        self.is_fitted = True
+        
+        # Store important data in obsm/uns for later use
+        self.metadata = {
+            'n_cells': adata.n_obs,
+            'n_genes': adata.n_vars,
+            'n_clusters': len(adata.obs[cluster_key].unique()),
+            'cluster_key': cluster_key
+        }
+        
+        return self
+    
+    def predict(self, adata: 'ad.AnnData') -> Dict[str, Any]:
+        """Predict cell types for new data"""
+        if not self.is_fitted:
+            raise ValueError("Model must be fitted before prediction")
+        
+        # This is a simplified prediction - in practice you'd want more sophisticated methods
+        # For now, we'll use the stored cluster information
+        return {
+            'cluster_labels': self.cluster_labels,
+            'marker_genes': self.marker_genes,
+            'metadata': self.metadata
+        }
+    
+    def _get_state(self) -> Dict[str, Any]:
+        """Get model state for saving"""
+        return {
+            'cluster_labels': self.cluster_labels,
+            'marker_genes': self.marker_genes.to_dict() if self.marker_genes is not None else None,
+            'cell_type_map': self.cell_type_map
+        }
+    
+    def _set_state(self, state: Dict[str, Any]) -> None:
+        """Set model state from loaded data"""
+        self.cluster_labels = state['cluster_labels']
+        self.marker_genes = pd.DataFrame(state['marker_genes']) if state['marker_genes'] else None
+        self.cell_type_map = state['cell_type_map']
+
+
+class CommunicationModel(BaseModel):
+    """Model for cell-cell communication analysis"""
+    
+    def __init__(self, config: Config):
+        super().__init__(config)
+        self.communication_scores = None
+        self.hub_scores = None
+        self.pathway_scores = None
+    
+    def fit(self, adata: 'ad.AnnData') -> 'CommunicationModel':
+        """Fit communication model"""
+        if not DEPS_AVAILABLE:
+            raise ImportError("Required dependencies not available")
+        
+        # Ensure we have cell type annotations
+        if 'leiden' not in adata.obs.columns:
+            raise ValueError("Cell type annotations required. Run CellAnnotationModel first.")
+        
+        adata = adata.copy()
+        
+        # Calculate communication specificity
+        self.communication_scores = self._calculate_communication_specificity(adata)
+        
+        # Identify hub cells
+        self.hub_scores = self._identify_hub_cells(adata)
+        
+        # Calculate pathway scores
+        self.pathway_scores = self._calculate_pathway_scores(adata)
+        
+        self.is_fitted = True
+        self.metadata = {
+            'n_cells': adata.n_obs,
+            'n_cell_types': len(adata.obs['leiden'].unique()),
+            'communication_pairs': len(self.communication_scores)
+        }
+        
+        return self
+    
+    def _calculate_communication_specificity(self, adata: 'ad.AnnData') -> pd.DataFrame:
+        """Calculate cell-type communication specificity"""
+        cell_types = adata.obs['leiden'].unique()
+        specificity_data = []
+        
+        for ct1 in cell_types:
+            for ct2 in cell_types:
+                if ct1 != ct2:
+                    cells_ct1 = adata.obs['leiden'] == ct1
+                    cells_ct2 = adata.obs['leiden'] == ct2
+                    
+                    ct1_expr = adata[cells_ct1].X.mean(axis=0)
+                    ct2_expr = adata[cells_ct2].X.mean(axis=0)
+                    
+                    if issparse(ct1_expr):
+                        ct1_expr = ct1_expr.A1
+                        ct2_expr = ct2_expr.A1
+                    
+                    correlation = np.corrcoef(ct1_expr, ct2_expr)[0, 1]
+                    
+                    specificity_data.append({
+                        'source': ct1,
+                        'target': ct2,
+                        'communication_score': abs(correlation) if not np.isnan(correlation) else 0
+                    })
+        
+        return pd.DataFrame(specificity_data)
+    
+    def _identify_hub_cells(self, adata: 'ad.AnnData') -> pd.Series:
+        """Identify communication hub cells"""
+        hub_scores = []
+        
+        for i in range(adata.n_obs):
+            if issparse(adata.X):
+                cell_expr = adata.X[i].toarray().flatten()
+            else:
+                cell_expr = adata.X[i]
+            
+            # Calculate hub score based on expression diversity
+            hub_score = (cell_expr.std() * cell_expr.mean()) / (cell_expr.var() + 1)
+            hub_scores.append(hub_score)
+        
+        return pd.Series(hub_scores, index=adata.obs.index)
+    
+    def _calculate_pathway_scores(self, adata: 'ad.AnnData') -> pd.DataFrame:
+        """Calculate pathway activity scores"""
+        heart_pathways = {
+            'Cardiac_Development': ['GATA4', 'NKX2-5', 'MEF2C', 'TBX5', 'HAND1', 'HAND2'],
+            'Angiogenesis': ['VEGFA', 'VEGFB', 'VEGFC', 'FLT1', 'KDR', 'PDGFB'],
+            'ECM_Remodeling': ['COL1A1', 'COL3A1', 'MMP2', 'MMP9', 'TIMP1', 'TIMP2'],
+            'Calcium_Signaling': ['CACNA1C', 'CACNA1D', 'CACNA1G', 'CACNA1H', 'CACNA1S'],
+        }
+        
+        pathway_scores = {}
+        
+        for pathway, genes in heart_pathways.items():
+            present_genes = [g for g in genes if g in adata.var_names]
+            
+            if present_genes:
+                cell_type_scores = {}
+                
+                for ct in adata.obs['leiden'].unique():
+                    ct_mask = adata.obs['leiden'] == ct
+                    ct_expr = adata[ct_mask, present_genes].X.mean(axis=0)
+                    
+                    if issparse(ct_expr):
+                        pathway_score = ct_expr.A1.mean()
+                    else:
+                        pathway_score = ct_expr.mean()
+                    
+                    cell_type_scores[ct] = pathway_score
+                
+                pathway_scores[pathway] = cell_type_scores
+        
+        return pd.DataFrame(pathway_scores).T
+    
+    def predict(self, adata: 'ad.AnnData') -> Dict[str, Any]:
+        """Predict communication patterns for new data"""
+        if not self.is_fitted:
+            raise ValueError("Model must be fitted before prediction")
+        
+        return {
+            'communication_scores': self.communication_scores,
+            'hub_scores': self.hub_scores,
+            'pathway_scores': self.pathway_scores,
+            'metadata': self.metadata
+        }
+    
+    def _get_state(self) -> Dict[str, Any]:
+        """Get model state for saving"""
+        return {
+            'communication_scores': self.communication_scores.to_dict() if self.communication_scores is not None else None,
+            'hub_scores': self.hub_scores.to_dict() if self.hub_scores is not None else None,
+            'pathway_scores': self.pathway_scores.to_dict() if self.pathway_scores is not None else None
+        }
+    
+    def _set_state(self, state: Dict[str, Any]) -> None:
+        """Set model state from loaded data"""
+        self.communication_scores = pd.DataFrame(state['communication_scores']) if state['communication_scores'] else None
+        self.hub_scores = pd.Series(state['hub_scores']) if state['hub_scores'] else None
+        self.pathway_scores = pd.DataFrame(state['pathway_scores']) if state['pathway_scores'] else None
+
+
+class MultiChamberModel(BaseModel):
+    """Model for multi-chamber heart analysis"""
+    
+    def __init__(self, config: Config):
+        super().__init__(config)
+        self.chamber_markers = None
+        self.chamber_expression = None
+        self.cross_chamber_correlations = None
+    
+    def fit(self, adata: 'ad.AnnData') -> 'MultiChamberModel':
+        """Fit multi-chamber model"""
+        if not DEPS_AVAILABLE:
+            raise ImportError("Required dependencies not available")
+        
+        # Check for chamber information or create mock data
+        if 'chamber' not in adata.obs.columns:
+            warnings.warn("No chamber information found. Creating mock chamber assignments.")
+            chambers = ['LA', 'RA', 'LV', 'RV']
+            np.random.seed(self.config.data.random_seed)
+            adata.obs['chamber'] = np.random.choice(chambers, adata.n_obs)
+        
+        chambers = adata.obs['chamber'].unique()
+        
+        # Find chamber-specific markers
+        self.chamber_markers = {}
+        for chamber in chambers:
+            adata.obs['is_chamber'] = (adata.obs['chamber'] == chamber).astype(str)
+            sc.tl.rank_genes_groups(adata, groupby='is_chamber', method='wilcoxon')
+            markers = sc.get.rank_genes_groups_df(adata, group='True')
+            self.chamber_markers[chamber] = markers.head(20)
+        
+        # Calculate chamber expression profiles
+        self.chamber_expression = {}
+        for chamber in chambers:
+            chamber_data = adata[adata.obs['chamber'] == chamber]
+            chamber_expr = chamber_data.X.mean(axis=0)
+            if issparse(chamber_expr):
+                chamber_expr = chamber_expr.A1
+            self.chamber_expression[chamber] = chamber_expr
+        
+        # Calculate cross-chamber correlations
+        self.cross_chamber_correlations = self._calculate_cross_chamber_correlations()
+        
+        self.is_fitted = True
+        self.metadata = {
+            'n_cells': adata.n_obs,
+            'n_chambers': len(chambers),
+            'chambers': list(chambers)
+        }
+        
+        return self
+    
+    def _calculate_cross_chamber_correlations(self) -> pd.DataFrame:
+        """Calculate correlations between chambers"""
+        chambers = list(self.chamber_expression.keys())
+        correlations = np.zeros((len(chambers), len(chambers)))
+        
+        for i, chamber1 in enumerate(chambers):
+            for j, chamber2 in enumerate(chambers):
+                expr1 = self.chamber_expression[chamber1]
+                expr2 = self.chamber_expression[chamber2]
+                correlations[i, j] = np.corrcoef(expr1, expr2)[0, 1]
+        
+        return pd.DataFrame(correlations, index=chambers, columns=chambers)
+    
+    def predict(self, adata: 'ad.AnnData') -> Dict[str, Any]:
+        """Predict chamber-specific patterns for new data"""
+        if not self.is_fitted:
+            raise ValueError("Model must be fitted before prediction")
+        
+        return {
+            'chamber_markers': self.chamber_markers,
+            'chamber_expression': self.chamber_expression,
+            'cross_chamber_correlations': self.cross_chamber_correlations,
+            'metadata': self.metadata
+        }
+    
+    def _get_state(self) -> Dict[str, Any]:
+        """Get model state for saving"""
+        return {
+            'chamber_markers': {k: v.to_dict() for k, v in self.chamber_markers.items()} if self.chamber_markers else None,
+            'chamber_expression': self.chamber_expression,
+            'cross_chamber_correlations': self.cross_chamber_correlations.to_dict() if self.cross_chamber_correlations is not None else None
+        }
+    
+    def _set_state(self, state: Dict[str, Any]) -> None:
+        """Set model state from loaded data"""
+        self.chamber_markers = {k: pd.DataFrame(v) for k, v in state['chamber_markers'].items()} if state['chamber_markers'] else None
+        self.chamber_expression = state['chamber_expression']
+        self.cross_chamber_correlations = pd.DataFrame(state['cross_chamber_correlations']) if state['cross_chamber_correlations'] else None
+
+
+class HeartMapModel(BaseModel):
+    """Main HeartMAP model combining all analysis components"""
+    
+    def __init__(self, config: Config):
+        super().__init__(config)
+        self.annotation_model = CellAnnotationModel(config)
+        self.communication_model = CommunicationModel(config)
+        self.multi_chamber_model = MultiChamberModel(config)
+    
+    def fit(self, adata: 'ad.AnnData') -> 'HeartMapModel':
+        """Fit complete HeartMAP model"""
+        # Fit annotation model
+        self.annotation_model.fit(adata)
+        
+        # Add cluster information to adata for downstream analysis
+        adata.obs['leiden'] = self.annotation_model.cluster_labels
+        
+        # Fit communication model
+        self.communication_model.fit(adata)
+        
+        # Fit multi-chamber model
+        self.multi_chamber_model.fit(adata)
+        
+        self.is_fitted = True
+        self.metadata = {
+            'annotation': self.annotation_model.metadata,
+            'communication': self.communication_model.metadata,
+            'multi_chamber': self.multi_chamber_model.metadata
+        }
+        
+        return self
+    
+    def predict(self, adata: 'ad.AnnData') -> Dict[str, Any]:
+        """Complete HeartMAP prediction"""
+        if not self.is_fitted:
+            raise ValueError("Model must be fitted before prediction")
+        
+        annotation_results = self.annotation_model.predict(adata)
+        communication_results = self.communication_model.predict(adata)
+        multi_chamber_results = self.multi_chamber_model.predict(adata)
+        
+        return {
+            'annotation': annotation_results,
+            'communication': communication_results,
+            'multi_chamber': multi_chamber_results,
+            'metadata': self.metadata
+        }
+    
+    def _get_state(self) -> Dict[str, Any]:
+        """Get model state for saving"""
+        return {
+            'annotation_model': self.annotation_model._get_state(),
+            'communication_model': self.communication_model._get_state(),
+            'multi_chamber_model': self.multi_chamber_model._get_state()
+        }
+    
+    def _set_state(self, state: Dict[str, Any]) -> None:
+        """Set model state from loaded data"""
+        self.annotation_model._set_state(state['annotation_model'])
+        self.communication_model._set_state(state['communication_model'])
+        self.multi_chamber_model._set_state(state['multi_chamber_model'])

src/heartmap/pipelines/__init__.py

@@ -0,0 +1,283 @@
+"""
+Analysis pipelines for HeartMAP
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional, List, Tuple
+import warnings
+from pathlib import Path
+
+try:
+    import scanpy as sc
+    import pandas as pd
+    import numpy as np
+    import anndata as ad
+    import matplotlib.pyplot as plt
+    import seaborn as sns
+    DEPS_AVAILABLE = True
+except ImportError:
+    DEPS_AVAILABLE = False
+    warnings.warn("Some dependencies not available. Install requirements for full functionality.")
+
+from ..config import Config
+from ..data import DataProcessor
+from ..models import CellAnnotationModel, CommunicationModel, MultiChamberModel, HeartMapModel
+from ..utils import Visualizer, ResultsExporter
+
+
+class BasePipeline(ABC):
+    """Base class for analysis pipelines"""
+    
+    def __init__(self, config: Config):
+        self.config = config
+        self.data_processor = DataProcessor(config)
+        self.visualizer = Visualizer(config)
+        self.exporter = ResultsExporter(config)
+        self.results = {}
+    
+    @abstractmethod
+    def run(self, data_path: str, output_dir: Optional[str] = None) -> Dict[str, Any]:
+        """Run the complete pipeline"""
+        pass
+    
+    def save_results(self, output_dir: str) -> None:
+        """Save pipeline results"""
+        output_path = Path(output_dir)
+        output_path.mkdir(parents=True, exist_ok=True)
+        
+        self.exporter.export_results(self.results, output_path)
+
+
+class BasicPipeline(BasePipeline):
+    """Basic single-cell analysis pipeline"""
+    
+    def __init__(self, config: Config):
+        super().__init__(config)
+        self.model = CellAnnotationModel(config)
+    
+    def run(self, data_path: str, output_dir: Optional[str] = None) -> Dict[str, Any]:
+        """Run basic analysis pipeline"""
+        if not DEPS_AVAILABLE:
+            raise ImportError("Required dependencies not available")
+        
+        print("=== Running Basic Pipeline ===")
+        
+        # Load and process data
+        print("1. Loading and processing data...")
+        adata = self.data_processor.process_from_raw(data_path)
+        
+        # Fit annotation model
+        print("2. Performing cell annotation...")
+        self.model.fit(adata)
+        
+        # Get results
+        results = self.model.predict(adata)
+        adata.obs['leiden'] = results['cluster_labels']
+        
+        # Generate visualizations
+        print("3. Generating visualizations...")
+        if output_dir:
+            viz_dir = Path(output_dir) / "figures"
+            viz_dir.mkdir(parents=True, exist_ok=True)
+            
+            # UMAP plot
+            sc.pl.umap(adata, color=['leiden'], legend_loc='on data',
+                      title='Cell Type Clusters', show=False)
+            plt.savefig(viz_dir / "umap_clusters.png", dpi=300, bbox_inches='tight')
+            plt.close()
+            
+            # QC metrics
+            self.visualizer.plot_qc_metrics(adata, viz_dir)
+        
+        # Store results
+        self.results = {
+            'adata': adata,
+            'model': self.model,
+            'results': results
+        }
+        
+        # Save results
+        if output_dir:
+            self.save_results(output_dir)
+            # Save processed data
+            adata.write(Path(output_dir) / "annotated_data.h5ad")
+            # Save model
+            self.model.save(Path(output_dir) / "annotation_model.pkl")
+        
+        print("Basic pipeline completed!")
+        return self.results
+
+
+class AdvancedCommunicationPipeline(BasePipeline):
+    """Advanced cell-cell communication analysis pipeline"""
+    
+    def __init__(self, config: Config):
+        super().__init__(config)
+        self.model = CommunicationModel(config)
+    
+    def run(self, data_path: str, output_dir: Optional[str] = None) -> Dict[str, Any]:
+        """Run advanced communication analysis pipeline"""
+        if not DEPS_AVAILABLE:
+            raise ImportError("Required dependencies not available")
+        
+        print("=== Running Advanced Communication Pipeline ===")
+        
+        # Load processed data (should have cell annotations)
+        print("1. Loading annotated data...")
+        adata = sc.read_h5ad(data_path)
+        
+        if 'leiden' not in adata.obs.columns:
+            raise ValueError("Input data must have cell type annotations. Run BasicPipeline first.")
+        
+        # Fit communication model
+        print("2. Analyzing cell-cell communication...")
+        self.model.fit(adata)
+        
+        # Get results
+        results = self.model.predict(adata)
+        
+        # Generate visualizations
+        print("3. Generating communication visualizations...")
+        if output_dir:
+            viz_dir = Path(output_dir) / "figures"
+            viz_dir.mkdir(parents=True, exist_ok=True)
+            
+            self.visualizer.plot_communication_heatmap(
+                results['communication_scores'], viz_dir
+            )
+            self.visualizer.plot_hub_scores(
+                adata, results['hub_scores'], viz_dir
+            )
+            self.visualizer.plot_pathway_scores(
+                results['pathway_scores'], viz_dir
+            )
+        
+        # Store results
+        self.results = {
+            'adata': adata,
+            'model': self.model,
+            'results': results
+        }
+        
+        # Save results
+        if output_dir:
+            self.save_results(output_dir)
+            self.model.save(Path(output_dir) / "communication_model.pkl")
+        
+        print("Advanced communication pipeline completed!")
+        return self.results
+
+
+class MultiChamberPipeline(BasePipeline):
+    """Multi-chamber heart analysis pipeline"""
+    
+    def __init__(self, config: Config):
+        super().__init__(config)
+        self.model = MultiChamberModel(config)
+    
+    def run(self, data_path: str, output_dir: Optional[str] = None) -> Dict[str, Any]:
+        """Run multi-chamber analysis pipeline"""
+        if not DEPS_AVAILABLE:
+            raise ImportError("Required dependencies not available")
+        
+        print("=== Running Multi-Chamber Pipeline ===")
+        
+        # Load data
+        print("1. Loading data...")
+        adata = sc.read_h5ad(data_path)
+        
+        # Fit multi-chamber model
+        print("2. Analyzing multi-chamber patterns...")
+        self.model.fit(adata)
+        
+        # Get results
+        results = self.model.predict(adata)
+        
+        # Generate visualizations
+        print("3. Generating multi-chamber visualizations...")
+        if output_dir:
+            viz_dir = Path(output_dir) / "figures"
+            viz_dir.mkdir(parents=True, exist_ok=True)
+            
+            self.visualizer.plot_chamber_composition(
+                adata, viz_dir
+            )
+            self.visualizer.plot_chamber_markers(
+                results['chamber_markers'], viz_dir
+            )
+            self.visualizer.plot_cross_chamber_correlations(
+                results['cross_chamber_correlations'], viz_dir
+            )
+        
+        # Store results
+        self.results = {
+            'adata': adata,
+            'model': self.model,
+            'results': results
+        }
+        
+        # Save results
+        if output_dir:
+            self.save_results(output_dir)
+            self.model.save(Path(output_dir) / "multi_chamber_model.pkl")
+        
+        print("Multi-chamber pipeline completed!")
+        return self.results
+
+
+class ComprehensivePipeline(BasePipeline):
+    """Comprehensive HeartMAP analysis pipeline"""
+    
+    def __init__(self, config: Config):
+        super().__init__(config)
+        self.model = HeartMapModel(config)
+    
+    def run(self, data_path: str, output_dir: Optional[str] = None) -> Dict[str, Any]:
+        """Run comprehensive HeartMAP analysis"""
+        if not DEPS_AVAILABLE:
+            raise ImportError("Required dependencies not available")
+        
+        print("=== Running Comprehensive HeartMAP Pipeline ===")
+        
+        # Load and process data
+        print("1. Loading and processing data...")
+        adata = self.data_processor.process_from_raw(data_path)
+        
+        # Fit complete model
+        print("2. Fitting comprehensive HeartMAP model...")
+        self.model.fit(adata)
+        
+        # Get results
+        results = self.model.predict(adata)
+        
+        # Update adata with all results
+        adata.obs['leiden'] = results['annotation']['cluster_labels']
+        adata.obs['hub_score'] = results['communication']['hub_scores']
+        
+        # Generate comprehensive visualizations
+        print("3. Generating comprehensive visualizations...")
+        if output_dir:
+            viz_dir = Path(output_dir) / "figures"
+            viz_dir.mkdir(parents=True, exist_ok=True)
+            
+            # Create comprehensive dashboard
+            self.visualizer.create_comprehensive_dashboard(adata, results, viz_dir)
+        
+        # Store results
+        self.results = {
+            'adata': adata,
+            'model': self.model,
+            'results': results
+        }
+        
+        # Save results
+        if output_dir:
+            self.save_results(output_dir)
+            adata.write(Path(output_dir) / "heartmap_complete.h5ad")
+            self.model.save(Path(output_dir) / "heartmap_model.pkl")
+            
+            # Generate comprehensive report
+            self.exporter.generate_comprehensive_report(self.results, output_dir)
+        
+        print("Comprehensive HeartMAP pipeline completed!")
+        return self.results

src/heartmap/utils/__init__.py

@@ -0,0 +1,350 @@
+"""
+Utility functions and classes for HeartMAP
+"""
+
+import os
+import hashlib
+from pathlib import Path
+from typing import Dict, Any, Optional, List
+import warnings
+
+try:
+    import matplotlib.pyplot as plt
+    import seaborn as sns
+    import pandas as pd
+    import numpy as np
+    import scanpy as sc
+    import plotly.express as px
+    import plotly.graph_objects as go
+    from plotly.subplots import make_subplots
+    PLOTTING_AVAILABLE = True
+except ImportError:
+    PLOTTING_AVAILABLE = False
+    warnings.warn("Plotting dependencies not available")
+
+from ..config import Config
+
+
+class Visualizer:
+    """Visualization utilities for HeartMAP"""
+    
+    def __init__(self, config: Config):
+        self.config = config
+        
+    def plot_qc_metrics(self, adata, save_dir: Path) -> None:
+        """Plot quality control metrics"""
+        if not PLOTTING_AVAILABLE:
+            return
+        
+        fig, axes = plt.subplots(2, 2, figsize=(12, 10))
+        
+        # Number of genes
+        axes[0,0].hist(adata.obs['n_genes'], bins=50, alpha=0.7)
+        axes[0,0].set_xlabel('Number of genes')
+        axes[0,0].set_ylabel('Number of cells')
+        axes[0,0].set_title('Genes per cell')
+        
+        # Total counts
+        axes[0,1].hist(adata.obs['total_counts'], bins=50, alpha=0.7)
+        axes[0,1].set_xlabel('Total counts')
+        axes[0,1].set_ylabel('Number of cells')
+        axes[0,1].set_title('UMI per cell')
+        
+        # Mitochondrial percentage
+        if 'pct_counts_mt' in adata.obs.columns:
+            axes[1,0].hist(adata.obs['pct_counts_mt'], bins=50, alpha=0.7)
+            axes[1,0].set_xlabel('Mitochondrial %')
+            axes[1,0].set_ylabel('Number of cells')
+            axes[1,0].set_title('Mitochondrial gene %')
+        
+        # Scatter plot
+        axes[1,1].scatter(adata.obs['total_counts'], adata.obs['n_genes'], alpha=0.6, s=1)
+        axes[1,1].set_xlabel('Total counts')
+        axes[1,1].set_ylabel('Number of genes')
+        axes[1,1].set_title('Genes vs UMI')
+        
+        plt.tight_layout()
+        plt.savefig(save_dir / "qc_metrics.png", dpi=300, bbox_inches='tight')
+        plt.close()
+    
+    def plot_communication_heatmap(self, comm_scores: pd.DataFrame, save_dir: Path) -> None:
+        """Plot cell-cell communication heatmap"""
+        if not PLOTTING_AVAILABLE:
+            return
+        
+        # Create pivot table
+        pivot_df = comm_scores.pivot(
+            index='source', 
+            columns='target', 
+            values='communication_score'
+        )
+        
+        plt.figure(figsize=(10, 8))
+        sns.heatmap(pivot_df, annot=True, cmap='viridis', fmt='.3f')
+        plt.title('Cell-Cell Communication Specificity')
+        plt.tight_layout()
+        plt.savefig(save_dir / "communication_heatmap.png", dpi=300, bbox_inches='tight')
+        plt.close()
+    
+    def plot_hub_scores(self, adata, hub_scores: pd.Series, save_dir: Path) -> None:
+        """Plot communication hub scores"""
+        if not PLOTTING_AVAILABLE:
+            return
+        
+        # Add hub scores to adata for plotting
+        adata.obs['hub_score'] = hub_scores
+        
+        sc.pl.umap(adata, color='hub_score', title='Communication Hub Score', show=False)
+        plt.savefig(save_dir / "hub_scores.png", dpi=300, bbox_inches='tight')
+        plt.close()
+    
+    def plot_pathway_scores(self, pathway_scores: pd.DataFrame, save_dir: Path) -> None:
+        """Plot pathway activity scores"""
+        if not PLOTTING_AVAILABLE or pathway_scores.empty:
+            return
+        
+        plt.figure(figsize=(12, 8))
+        sns.heatmap(pathway_scores, annot=True, cmap='Blues', fmt='.3f')
+        plt.title('Pathway Activity by Cell Type')
+        plt.tight_layout()
+        plt.savefig(save_dir / "pathway_scores.png", dpi=300, bbox_inches='tight')
+        plt.close()
+    
+    def plot_chamber_composition(self, adata, save_dir: Path) -> None:
+        """Plot chamber composition"""
+        if not PLOTTING_AVAILABLE:
+            return
+        
+        if 'chamber' not in adata.obs.columns:
+            return
+        
+        chamber_counts = adata.obs['chamber'].value_counts()
+        
+        fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(15, 6))
+        
+        # Bar plot
+        chamber_counts.plot(kind='bar', ax=ax1)
+        ax1.set_title('Cell Counts by Chamber')
+        ax1.set_xlabel('Chamber')
+        ax1.set_ylabel('Number of Cells')
+        
+        # Pie chart
+        ax2.pie(chamber_counts.values, labels=chamber_counts.index, autopct='%1.1f%%')
+        ax2.set_title('Chamber Proportions')
+        
+        plt.tight_layout()
+        plt.savefig(save_dir / "chamber_composition.png", dpi=300, bbox_inches='tight')
+        plt.close()
+    
+    def plot_chamber_markers(self, chamber_markers: Dict, save_dir: Path) -> None:
+        """Plot chamber-specific markers"""
+        if not PLOTTING_AVAILABLE:
+            return
+        
+        n_chambers = len(chamber_markers)
+        fig, axes = plt.subplots(2, 2, figsize=(15, 12))
+        axes = axes.flatten()
+        
+        for i, (chamber, markers) in enumerate(chamber_markers.items()):
+            if i < 4 and not markers.empty:
+                top_10 = markers.head(10)
+                axes[i].barh(range(len(top_10)), -np.log10(top_10['pvals_adj']))
+                axes[i].set_yticks(range(len(top_10)))
+                axes[i].set_yticklabels(top_10['names'])
+                axes[i].set_xlabel('-log10(adjusted p-value)')
+                axes[i].set_title(f'Top Markers - {chamber}')
+        
+        plt.tight_layout()
+        plt.savefig(save_dir / "chamber_markers.png", dpi=300, bbox_inches='tight')
+        plt.close()
+    
+    def plot_cross_chamber_correlations(self, correlations: pd.DataFrame, save_dir: Path) -> None:
+        """Plot cross-chamber correlations"""
+        if not PLOTTING_AVAILABLE:
+            return
+        
+        plt.figure(figsize=(8, 6))
+        sns.heatmap(correlations, annot=True, cmap='coolwarm', center=0, fmt='.3f')
+        plt.title('Cross-Chamber Expression Correlations')
+        plt.tight_layout()
+        plt.savefig(save_dir / "cross_chamber_correlations.png", dpi=300, bbox_inches='tight')
+        plt.close()
+    
+    def create_comprehensive_dashboard(self, adata, results: Dict, save_dir: Path) -> None:
+        """Create comprehensive analysis dashboard"""
+        if not PLOTTING_AVAILABLE:
+            return
+        
+        # Create a large multi-panel figure
+        fig = plt.figure(figsize=(20, 16))
+        
+        # Panel 1: UMAP with clusters
+        ax1 = plt.subplot(3, 3, 1)
+        sc.pl.umap(adata, color='leiden', ax=ax1, show=False, frameon=False)
+        ax1.set_title('Cell Type Clusters')
+        
+        # Panel 2: UMAP with hub scores
+        ax2 = plt.subplot(3, 3, 2)
+        sc.pl.umap(adata, color='hub_score', ax=ax2, show=False, frameon=False)
+        ax2.set_title('Communication Hubs')
+        
+        # Panel 3: Chamber composition (if available)
+        if 'chamber' in adata.obs.columns:
+            ax3 = plt.subplot(3, 3, 3)
+            chamber_counts = adata.obs['chamber'].value_counts()
+            ax3.pie(chamber_counts.values, labels=chamber_counts.index, autopct='%1.1f%%')
+            ax3.set_title('Chamber Distribution')
+        
+        # Additional panels for other analyses...
+        
+        plt.tight_layout()
+        plt.savefig(save_dir / "comprehensive_dashboard.png", dpi=300, bbox_inches='tight')
+        plt.close()
+
+
+class ResultsExporter:
+    """Export analysis results in various formats"""
+    
+    def __init__(self, config: Config):
+        self.config = config
+    
+    def export_results(self, results: Dict, output_dir: Path) -> None:
+        """Export all results to files"""
+        output_dir.mkdir(parents=True, exist_ok=True)
+        
+        # Export tables
+        tables_dir = output_dir / "tables"
+        tables_dir.mkdir(exist_ok=True)
+        
+        # Export specific result types
+        if 'results' in results and 'marker_genes' in results['results']:
+            marker_genes = results['results']['marker_genes']
+            if marker_genes is not None:
+                marker_genes.to_csv(tables_dir / "marker_genes.csv")
+        
+        if 'results' in results and 'communication_scores' in results['results']:
+            comm_scores = results['results']['communication_scores']
+            if comm_scores is not None:
+                comm_scores.to_csv(tables_dir / "communication_scores.csv", index=False)
+    
+    def generate_comprehensive_report(self, results: Dict, output_dir: str) -> None:
+        """Generate comprehensive analysis report"""
+        output_path = Path(output_dir)
+        
+        # Get basic statistics
+        adata = results.get('adata')
+        if adata is None:
+            return
+        
+        n_cells = adata.n_obs
+        n_genes = adata.n_vars
+        
+        # Generate report
+        report = f"""# HeartMAP Analysis Report
+
+## Dataset Overview
+- **Total Cells**: {n_cells:,}
+- **Total Genes**: {n_genes:,}
+
+## Analysis Components Completed
+- ✅ Cell type annotation
+- ✅ Cell-cell communication analysis
+- ✅ Multi-chamber analysis
+
+## Key Findings
+
+### Cell Type Annotation
+"""
+        
+        if 'leiden' in adata.obs.columns:
+            cluster_counts = adata.obs['leiden'].value_counts()
+            report += f"- **Number of cell types identified**: {len(cluster_counts)}\n"
+            report += f"- **Cell type distribution**:\n"
+            for cluster, count in cluster_counts.head(5).items():
+                pct = 100 * count / n_cells
+                report += f"  - Cluster {cluster}: {count:,} cells ({pct:.1f}%)\n"
+        
+        if 'chamber' in adata.obs.columns:
+            chamber_counts = adata.obs['chamber'].value_counts()
+            report += f"\n### Chamber Distribution\n"
+            for chamber, count in chamber_counts.items():
+                pct = 100 * count / n_cells
+                report += f"- **{chamber}**: {count:,} cells ({pct:.1f}%)\n"
+        
+        report += """
+### Communication Analysis
+- Cell-cell communication patterns identified
+- Communication hub cells detected
+- Pathway activity scores calculated
+
+## Files Generated
+- `heartmap_complete.h5ad`: Complete processed dataset
+- `heartmap_model.pkl`: Trained HeartMAP model
+- `figures/`: All visualization outputs
+- `tables/`: Exported data tables
+
+## Next Steps
+1. Validate findings with literature
+2. Investigate specific cell type interactions
+3. Apply model to new datasets
+"""
+        
+        # Save report
+        with open(output_path / "analysis_report.md", 'w') as f:
+            f.write(report)
+
+
+class ChecksumValidator:
+    """Validate data integrity using checksums"""
+    
+    @staticmethod
+    def calculate_sha256(file_path: str) -> str:
+        """Calculate SHA-256 checksum of file"""
+        sha256_hash = hashlib.sha256()
+        with open(file_path, "rb") as f:
+            for byte_block in iter(lambda: f.read(4096), b""):
+                sha256_hash.update(byte_block)
+        return sha256_hash.hexdigest()
+    
+    @staticmethod
+    def verify_file(file_path: str, expected_checksum: str) -> bool:
+        """Verify file against expected checksum"""
+        actual_checksum = ChecksumValidator.calculate_sha256(file_path)
+        return actual_checksum == expected_checksum
+    
+    @staticmethod
+    def generate_checksums(directory: str, output_file: str) -> None:
+        """Generate checksums for all files in directory"""
+        directory = Path(directory)
+        checksums = {}
+        
+        for file_path in directory.rglob('*'):
+            if file_path.is_file():
+                rel_path = file_path.relative_to(directory)
+                checksum = ChecksumValidator.calculate_sha256(str(file_path))
+                checksums[str(rel_path)] = checksum
+        
+        # Save checksums
+        with open(output_file, 'w') as f:
+            for file_path, checksum in checksums.items():
+                f.write(f"{checksum}  {file_path}\n")
+
+
+def setup_logging(level: str = "INFO") -> None:
+    """Setup logging configuration"""
+    import logging
+    
+    logging.basicConfig(
+        level=getattr(logging, level.upper()),
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+        handlers=[
+            logging.StreamHandler(),
+            logging.FileHandler('heartmap.log')
+        ]
+    )
+
+
+def create_logger(name: str):
+    """Create a logger with the given name"""
+    import logging
+    return logging.getLogger(name)