HeartMAP: Heart Multi-chamber Analysis Platform

A production-ready Python package for comprehensive single-cell heart analysis with chamber-specific insights

📰 Published in Computational and Structural Biotechnology Journal (2025) | Read the paper

Package Overview

HeartMAP is a specialized bioinformatics package that decodes cellular communication across all four chambers of the human heart. Unlike general single-cell tools, HeartMAP is purpose-built for cardiac biology, offering chamber-specific insights crucial for understanding heart function, disease, and therapeutic opportunities.

Key Features:

Production Ready: Fully tested, documented, and deployed on PyPI
Multiple Interfaces: CLI and Web interface
Easy Installation: pip install heartmap
Configurable: Works on 8GB+ RAM with memory optimization
Validated: Tested on real human heart datasets
Comprehensive: From basic QC to advanced communication analysis

Quick Installation

# Install from PyPI
pip install heartmap

# Install with all features
pip install heartmap[all]

# Verify installation
python -c "import heartmap; print(' HeartMAP ready!')"

Quick Start

30-Second Analysis

# Analyze your heart data with one command
heartmap your_heart_data.h5ad

2-Minute Python Analysis

from heartmap import Config
from heartmap.pipelines import ComprehensivePipeline

# Quick analysis
config = Config.default()
pipeline = ComprehensivePipeline(config)
results = pipeline.run('your_data.h5ad', 'results/')

print(" Analysis complete! Check 'results/' directory.")

Documentation

Document	Description	Use When
User Guide	Complete step-by-step tutorials	Learning HeartMAP
API Documentation	Full API reference	Programming with HeartMAP
Package README	Package-specific documentation	Installing/using the package
Original README	Development documentation	Contributing to HeartMAP

What HeartMAP Can Do

Analysis Pipelines

Pipeline	Purpose	Output	Runtime
Basic	Quality control, cell typing	Cell annotations, QC metrics	5-10 min
Communication	Cell-cell interactions	Communication networks, hubs	10-15 min
Multi-Chamber	Chamber-specific analysis	Chamber markers, comparisons	15-20 min
Comprehensive	Complete analysis	All of the above + reports	20-30 min

Real-World Applications

# Clinical Research: Chamber-specific targets
from heartmap.pipelines import MultiChamberPipeline
pipeline = MultiChamberPipeline(config)
results = pipeline.run('patient_data.h5ad')
lv_targets = results['chamber_markers']['LV']

# Drug Discovery: Communication pathways
from heartmap.pipelines import AdvancedCommunicationPipeline  
pipeline = AdvancedCommunicationPipeline(config)
results = pipeline.run('disease_data.h5ad')
drug_targets = results['communication_hubs']

# Education: Comparative analysis
results1 = pipeline.run('healthy_heart.h5ad')
results2 = pipeline.run('diseased_heart.h5ad')

Performance

Hardware	Dataset Size	Memory	Runtime	Status
8GB RAM	30K cells	~6GB	15 min	Recommended
16GB RAM	50K cells	~12GB	25 min	Optimal
32GB RAM	100K cells	~24GB	45 min	Production

Development

For Contributors

# Development setup
git clone https://github.com/Tumo505/HeartMap.git
cd HeartMap
pip install -e .[dev]

# Run tests
python -m pytest tests/
python -m flake8 src/heartmap/
python -m mypy src/heartmap/

For Package Users

The package is production-ready and maintained. See the User Guide for complete usage instructions.

Scientific Impact

Clinical: Chamber-specific therapeutic strategies
Research: First comprehensive multi-chamber communication atlas
Education: Accessible cardiac biology analysis platform
Industry: Production-ready bioinformatics tool

Use Cases

Pharmaceutical Research: Drug target discovery, safety assessment
Clinical Cardiology: Precision medicine, disease mechanisms
Basic Research: Cardiac development, evolutionary biology
Computational Biology: Method benchmarking, data integration

Requirements

Python: 3.8+ (tested on 3.8-3.11)
Memory: 8GB+ RAM (configurable)
Storage: 2GB+ for package and results
OS: Linux, macOS, Windows

Citation

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

Kgabeng, T., Wang, L., Ngwangwa, H., & Pandelani, T. (2025). HeartMAP: A Multi-Chamber Spatial Framework for Cardiac Cell-Cell Communication. Computational and Structural Biotechnology Journal. https://doi.org/10.1016/J.CSBJ.2025.11.015

@article{KGABENG2025,
title = {HeartMAP: A Multi-Chamber Spatial Framework for Cardiac Cell-Cell Communication},
journal = {Computational and Structural Biotechnology Journal},
year = {2025},
issn = {2001-0370},
doi = {https://doi.org/10.1016/j.csbj.2025.11.015},
url = {https://www.sciencedirect.com/science/article/pii/S2001037025004866},
author = {Tumo Kgabeng and Lulu Wang and Harry Ngwangwa and Thanyani Pandelani},
keywords = {single-cell RNA-seq, cell-cell communication, cardiac chambers, spatial transcriptomics, therapeutic targets},
abstract = {Understanding cell-cell communication within and between the four distinct cardiac chambers is fundamental to elucidating cardiac function and disease mechanisms. Each chamber exhibits unique cellular and molecular characteristics that reflect specialised physiological roles, yet existing frameworks for mapping chamber-specific intercellular networks have remained limited. Here, we present HeartMAP (Heart Multi-chamber Analysis Platform), a computational framework that infers cardiac cell-cell communication networks at chamber resolution through integration of single-cell RNA-seq co-expression patterns and ligand-receptor interaction databases. Using a dataset of 287,269 cells from seven healthy human heart donors (Single Cell Portal SCP498), we identified chamber-specific cell populations, communication networks, and therapeutic targets. HeartMAP employs a progressive three-tier analytical approach comprising basic pipeline analysis, advanced communication modelling and multi-chamber atlas construction to reveal both conserved and chamber-specific signalling pathways; cross-chamber correlation analysis demonstrated the highest similarity between ventricles (r = 0.985) and the lowest between left atrium and left ventricle (r = 0.870), reflecting functional specialisation. Communication hub analysis identified atrial cardiomyocytes and adipocytes as key signalling centres with hub scores of 0.037 to 0.047, while differential expression analysis revealed over 150 significantly different genes per chamber pair. These findings establish a molecular foundation for precision cardiology approaches, enabling chamber-specific therapeutic strategies that could improve treatment outcomes for cardiovascular diseases. HeartMAP is freely available as a Python package than can be installed using “pip install heartmap”, the package’s documentation can be found on https://pypi.org/project/heartmap/, it can also be accessed via a user-friendly web interface freely available at https://huggingface.co/spaces/Tumo505/heartmap-cell-analysis.}
}

License

Apache 2.0 License - see LICENSE for details.

Support

Documentation: User Guide | API Docs
Community: GitHub Discussions
Issues: GitHub Issues
Contact: 28346416@mylife.unisa.ac.za

HeartMAP: Production-ready cardiac single-cell analysis for researchers worldwide

Install today: pip install heartmap

Supporting Files

├── scripts/                 # Setup and utility scripts
│   ├── setup.sh            # Automated environment setup
│   ├── validate.py         # Installation validation
│   ├── migrate.py          # Legacy code migration
│   └── deploy_huggingface.sh # HuggingFace deployment
├── tests/                   # Comprehensive test suite
├── notebooks/               # Jupyter notebook examples
├── config.yaml             # Default configuration
├── setup.py                # Package installation
├── Dockerfile              # Container deployment
├── docker-compose.yml      # Multi-service orchestration
└── app.py                  # Gradio web interface

Quick Start

Option 1: Automated Setup (Recommended)

# Clone the repository
git clone https://github.com/Tumo505/HeartMap.git
cd HeartMap

# Run automated setup script
./scripts/setup.sh

# Activate the environment
source heartmap_env/bin/activate  # Linux/Mac
# OR: heartmap_env\Scripts\activate  # Windows

# Validate installation
python scripts/validate.py

# Start analyzing!
heartmap data/raw/your_data.h5ad --analysis-type comprehensive

Option 2: Manual Installation

# Create virtual environment
python3 -m venv heartmap_env
source heartmap_env/bin/activate

# Install dependencies
pip install -r requirements-dev.txt

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

# Validate installation
python scripts/validate.py

Option 3: Package Installation

# Install from PyPI (when available)
pip install heartmap[all]

# Or install specific features
pip install heartmap[communication]  # Communication analysis only
pip install heartmap[api]            # API features only

Usage Examples

1. Command Line Interface

# Basic analysis
heartmap data/raw/heart_data.h5ad

# Comprehensive analysis with custom output
heartmap data/raw/heart_data.h5ad \
    --analysis-type comprehensive \
    --output-dir results/comprehensive \
    --config my_config.yaml

# Specific analysis types
heartmap data/raw/heart_data.h5ad --analysis-type annotation
heartmap data/raw/heart_data.h5ad --analysis-type communication  
heartmap data/raw/heart_data.h5ad --analysis-type multi-chamber

# Memory-optimized for large datasets
heartmap data/raw/large_dataset.h5ad \
    --analysis-type comprehensive \
    --config config_large.yaml

2. Python API

from heartmap import Config, HeartMapModel
from heartmap.pipelines import ComprehensivePipeline

# Load and customize configuration
config = Config.from_yaml('config.yaml')
config.data.max_cells_subset = 50000  # Optimize for your memory
config.data.max_genes_subset = 5000

# Option A: Use full HeartMAP model
model = HeartMapModel(config)
results = model.analyze('data/raw/heart_data.h5ad')

# Option B: Use specific pipeline
pipeline = ComprehensivePipeline(config)
results = pipeline.run('data/raw/heart_data.h5ad', 'results/')

# Save model for reuse
model.save('models/my_heartmap_model')

# Load and reuse saved model
loaded_model = HeartMapModel.load('models/my_heartmap_model')
new_results = loaded_model.predict(new_data)

3. REST API

# Start API server
python scripts/run_api_server.py
# Server available at http://localhost:8000
# API docs at http://localhost:8000/docs

# Use the API
curl -X POST "http://localhost:8000/analyze" \
     -H "Content-Type: multipart/form-data" \
     -F "file=@data/raw/heart_data.h5ad" \
     -F "analysis_type=comprehensive"

# Check available models
curl http://localhost:8000/models

# Update configuration
curl -X POST "http://localhost:8000/config" \
     -H "Content-Type: application/json" \
     -d '{"data": {"max_cells_subset": 30000}}'

4. Web Interface (Gradio)

# Start web interface
python app.py
# Access at http://localhost:7860

# Features:
# - Upload .h5ad files
# - Select analysis type
# - Configure memory settings
# - Download results

5. Jupyter Notebooks

# Install Jupyter
pip install jupyter

# Start notebook server
jupyter lab

# Open example notebooks:
# - notebooks/01_basic_analysis.ipynb
# - notebooks/02_advanced_communication.ipynb
# - notebooks/03_multi_chamber_analysis.ipynb
# - notebooks/04_comprehensive_analysis.ipynb

Configuration

HeartMAP uses YAML configuration files for easy customization:

# config.yaml or my_config.yaml
data:
  min_genes: 200
  min_cells: 3
  max_cells_subset: 50000        # Adjust based on your RAM
  max_genes_subset: 5000         # Reduce for faster analysis
  target_sum: 10000.0
  n_top_genes: 2000
  random_seed: 42
  test_mode: false               # Set true for quick testing

analysis:
  n_components_pca: 50
  n_neighbors: 10
  n_pcs: 40
  resolution: 0.5
  n_marker_genes: 25
  use_leiden: true
  use_liana: true                # Cell-cell communication

model:
  model_type: "comprehensive"
  save_intermediate: true
  use_gpu: false                 # Set true if GPU available
  batch_size: null
  max_memory_gb: null            # Auto-detect memory

paths:
  data_dir: "data"
  raw_data_dir: "data/raw"
  processed_data_dir: "data/processed"
  results_dir: "results"
  figures_dir: "figures"
  models_dir: "models"

Memory Optimization Guidelines

System RAM	max_cells_subset	max_genes_subset	Use Case
8GB	10,000	2,000	Laptop/Desktop
16GB	30,000	4,000	Workstation
32GB	50,000	5,000	Server
64GB+	100,000+	10,000+	HPC/Cloud

Analysis Components

1. Basic Pipeline

Data Preprocessing: Quality control, normalization, scaling
Cell Type Annotation: Clustering and cell type identification
Basic Visualization: UMAP, t-SNE, cluster plots
Quality Metrics: Cell and gene filtering statistics

2. Advanced Communication Analysis

Cell-Cell Communication: Ligand-receptor interaction analysis
Communication Hubs: Identification of key signaling cells
Pathway Enrichment: Cardiac development and disease pathways
Network Analysis: Communication network topology

3. Multi-Chamber Atlas

Chamber-Specific Analysis: RA, RV, LA, LV specific patterns
Marker Identification: Chamber-specific biomarkers
Cross-Chamber Correlations: Inter-chamber relationship analysis
Comparative Analysis: Chamber-to-chamber differences

4. Comprehensive Pipeline

Integrated Analysis: All components combined
Advanced Visualizations: Multi-panel figures and dashboards
Comprehensive Reports: Automated result summaries
Model Persistence: Save complete analysis state

Deployment Guide

Local Development Setup

Prerequisites

Python 3.8+ (recommended: Python 3.10)
Git
Docker (optional, for containerized deployment)
8GB+ RAM (16GB+ recommended for larger datasets)

Quick Setup

# Clone and setup environment
git clone https://github.com/Tumo505/HeartMap.git
cd HeartMap

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

# Install dependencies
pip install --upgrade pip
pip install -r requirements-dev.txt
pip install -e .[all]

# Configure the platform
cp config.yaml my_config.yaml
# Edit my_config.yaml to match your system resources

# Test installation
python scripts/validate.py
python scripts/run_examples.py

Docker Deployment

# Single service
docker build -t heartmap .
docker run -p 8000:8000 -v $(pwd)/data:/app/data heartmap

# Multi-service with docker-compose
docker-compose up
# Services:
# - API server: http://localhost:8000  
# - Gradio interface: http://localhost:7860
# - Worker processes for batch analysis

Hugging Face Spaces Deployment

# Prepare deployment files
./scripts/deploy_huggingface.sh

# Upload to your Hugging Face Space:
# 1. Create new Space at https://huggingface.co/new-space
# 2. Choose Gradio SDK
# 3. Upload generated files:
#    - app.py (Gradio interface)
#    - requirements.txt (Dependencies)
#    - src/ (Source code)
#    - config.yaml (Configuration)

Cloud Platforms

AWS Deployment

# ECS deployment
docker build -t heartmap .
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin $ECR_URI
docker tag heartmap:latest $ECR_URI/heartmap:latest
docker push $ECR_URI/heartmap:latest

# Lambda deployment for serverless
sam build
sam deploy --guided

Google Cloud Platform

# Cloud Run deployment
gcloud builds submit --tag gcr.io/$PROJECT_ID/heartmap
gcloud run deploy --image gcr.io/$PROJECT_ID/heartmap --platform managed

Azure

# Container Instances
az container create --resource-group myResourceGroup \
    --name heartmap --image myregistry.azurecr.io/heartmap:latest

Scientific 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)

Testing & Validation

Run Tests

# Full test suite
python tests/test_heartmap.py

# Validation suite
python scripts/validate.py

# Example analysis with mock data
python scripts/demo.py

Performance Benchmarks

Dataset Size	Memory Usage	Processing Time	Output
10K cells	2GB RAM	5 minutes	Complete analysis
50K cells	8GB RAM	15 minutes	Complete analysis
100K cells	16GB RAM	30 minutes	Complete analysis

Use Cases

Research Applications

Interactive Analysis: Jupyter notebooks for exploration
Batch Processing: Command-line analysis of multiple datasets
Pipeline Integration: Python API for custom workflows
Collaborative Research: Shared configurations and models

Production Applications

Web Services: REST API for applications
Public Access: Hugging Face Spaces for community use
Microservices: Containerized deployment in cloud
High-Throughput: Scalable analysis for large cohorts

Educational Use

Teaching Platform: Web interface for students
Reproducible Science: Containerized environments
Method Comparison: Multiple analysis approaches
Best Practices: Clean, documented codebase

Data Integrity & Reproducibility

SHA-256 Checksums

Purpose: Ensure data file integrity during storage/transfer
Implementation: Automatic verification before analysis
Usage: python utils/sha256_checksum.py verify data/raw data/raw/checksums.txt

Fixed Random Seeds

Purpose: Ensure reproducible results across runs
Implementation: Fixed seeds in all stochastic processes
Scope: Random sampling, clustering, mock data generation

Examples of Reproducible Components

Random Sampling:

np.random.seed(42)
cell_indices = np.random.choice(adata.n_obs, size=50000, replace=False)

Clustering:

kmeans = KMeans(n_clusters=n_clusters, random_state=42)

LIANA Analysis:

li.mt.rank_aggregate.by_sample(
    adata, groupby=cell_type_col, resource_name='consensus',
    n_perms=100, seed=42, verbose=True
)

🔧 Development & Contributing

Development Setup

# Development setup
git clone https://github.com/Tumo505/HeartMap.git
cd HeartMap
./scripts/setup.sh
source heartmap_env/bin/activate

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

# Run tests before committing
python tests/test_heartmap.py
python scripts/validate.py

# Code quality checks
black src/ tests/ scripts/  # Code formatting
flake8 src/ --max-line-length=100  # Linting
mypy src/heartmap --ignore-missing-imports  # Type checking

Adding New Features

New Models: Inherit from BaseModel in src/heartmap/models/
New Pipelines: Inherit from BasePipeline in src/heartmap/pipelines/
API Endpoints: Add to src/heartmap/api/rest.py
Configuration: Extend dataclasses in src/heartmap/config/

Testing Guidelines

# Test structure
tests/
├── test_config.py       # Configuration management
├── test_data.py         # Data processing
├── test_models.py       # Analysis models
├── test_pipelines.py    # Analysis pipelines
└── test_api.py          # API interfaces

Troubleshooting

Common Issues

Memory Errors

# Reduce dataset size in config
data:
  max_cells_subset: 10000
  max_genes_subset: 2000

Import Errors

# Reinstall with all dependencies
pip install -e .[all]

# Check Python path
python -c "import heartmap; print(heartmap.__file__)"

Data Loading Issues

# Verify data format
python -c "import scanpy as sc; print(sc.read_h5ad('data/raw/your_file.h5ad'))"

# Check file permissions
ls -la data/raw/

Performance Issues

# Enable test mode for quick validation
test_mode: true  # in config.yaml

# Use GPU acceleration (if available)
model:
  use_gpu: true

Getting Help

Validation: python scripts/validate.py
Logs: Check logs in results/ directory
Test Mode: Set test_mode: true in configuration
Mock Data: python scripts/demo.py for testing
Documentation: Comprehensive docstrings in source code

Requirements

System Requirements

Python: 3.8+ (recommended: 3.10)
Memory: 8GB+ recommended (configurable)
Storage: 5GB+ for data and results
OS: Linux, macOS, Windows

Dependencies

Core: scanpy, pandas, numpy, scipy, scikit-learn
Visualization: matplotlib, seaborn, plotly
Communication: liana, cellphonedb (optional)
API: fastapi, uvicorn (optional)
Web: gradio (optional)

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

Contributing

Fork the repository
Create a feature branch: git checkout -b feature-name
Install development dependencies: pip install -e .[dev]
Run tests: python tests/test_heartmap.py
Submit a pull request

📄 License

Ssee the LICENSE file for details.

Support

Issues: GitHub Issues
Discussions: GitHub 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

HeartMAP is now production-ready and available for research, deployment, and collaboration!

Whether you're a researcher exploring cardiac biology, a developer building applications, or an educator teaching single-cell analysis, HeartMAP provides the tools and flexibility you need.

Name		Name	Last commit message	Last commit date
Latest commit History 73 Commits
.github/workflows		.github/workflows
analysis		analysis
figures		figures
results		results
scripts		scripts
src/heartmap		src/heartmap
tests		tests
utils		utils
.bumpversion.cfg		.bumpversion.cfg
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
api_server.py		api_server.py
app.py		app.py
config.yaml		config.yaml
docker-compose.yml		docker-compose.yml
environment.yml		environment.yml
requirements-api.txt		requirements-api.txt
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
setup.py		setup.py
test_lr_integration.py		test_lr_integration.py

License

Tumo505/HeartMap

Folders and files

Latest commit

History

Repository files navigation

HeartMAP: Heart Multi-chamber Analysis Platform

Package Overview

Quick Installation

Quick Start

30-Second Analysis

2-Minute Python Analysis

Documentation

What HeartMAP Can Do

Analysis Pipelines

Real-World Applications

Performance

Development

For Contributors

For Package Users

Scientific Impact

Use Cases

Requirements

Citation

License

Support

Supporting Files

Quick Start

Option 1: Automated Setup (Recommended)

Option 2: Manual Installation

Option 3: Package Installation

Usage Examples

1. Command Line Interface

2. Python API

3. REST API

4. Web Interface (Gradio)

5. Jupyter Notebooks

Configuration

Memory Optimization Guidelines

Analysis Components

1. Basic Pipeline

2. Advanced Communication Analysis

3. Multi-Chamber Atlas

4. Comprehensive Pipeline

Deployment Guide

Local Development Setup

Prerequisites

Quick Setup

Docker Deployment

Hugging Face Spaces Deployment

Cloud Platforms

AWS Deployment

Google Cloud Platform

Azure

Scientific Results

Chamber Distribution

Chamber-Specific Markers

Cross-Chamber Correlations

Testing & Validation

Run Tests

Performance Benchmarks

Use Cases

Research Applications

Production Applications

Educational Use

Data Integrity & Reproducibility

SHA-256 Checksums

Fixed Random Seeds

Examples of Reproducible Components

🔧 Development & Contributing

Development Setup

Adding New Features

Testing Guidelines

Troubleshooting

Common Issues

Memory Errors

Import Errors

Data Loading Issues

Performance Issues

Getting Help

Packages