Skip to main content

​
Installation Guide

HeartMAP is available on PyPI and can be installed with a single command. This guide covers different installation methods and system requirements.

​
System Requirements

Before installing HeartMAP, ensure your system meets these requirements:

​
Minimum Requirements

  • Python: 3.8 or higher (tested on Python 3.8-3.11)
  • Memory: 8GB+ RAM (16GB recommended for larger datasets)
  • Storage: 2GB+ for package and results
  • Operating System: Linux, macOS, or Windows

​
Python Version Support

Python 3.8

Supported

Python 3.9

Supported

Python 3.10

Recommended

Python 3.11

Supported
Python 3.7 and earlier are not supported. Python 3.12+ may work but has not been extensively tested.

​
Quick Installation

The fastest way to get started with HeartMAP: 
pip install heartmap

​
Installation Options

HeartMAP offers different installation options depending on which features you need.

​
Basic Installation

Installs core dependencies for basic analysis: 
pip install heartmap
Core dependencies:
  • scanpy>=1.9.0 - Single-cell analysis
  • pandas>=1.5.0 - Data manipulation
  • numpy>=1.21.0 - Numerical computing
  • scipy>=1.9.0 - Scientific computing
  • scikit-learn>=1.1.0 - Machine learning
  • matplotlib>=3.5.0 - Visualization
  • seaborn>=0.11.0 - Statistical visualization
  • anndata>=0.8.0 - Annotated data structures
  • plotly>=5.0.0 - Interactive plots
  • networkx>=2.8.0 - Network analysis
  • python-igraph>=0.10.0 - Graph algorithms
  • leidenalg>=0.8.0 - Clustering
  • pyyaml>=6.0 - Configuration files

​
Communication Analysis

For advanced cell-cell communication analysis: 
pip install heartmap[communication]
Additional dependencies:
  • liana>=0.1.0 - Ligand-receptor analysis
  • cellphonedb>=3.0.0 - Cell communication database
  • omnipath>=1.0.0 - Signaling database

​
API Features

For REST API and web service deployment: 
pip install heartmap[api]
Additional dependencies:
  • fastapi>=0.100.0 - Web framework
  • uvicorn>=0.23.0 - ASGI server
  • pydantic>=2.0.0 - Data validation

​
Development Installation

For contributors and developers: 
pip install heartmap[dev]
Additional dependencies:
  • pytest>=7.0.0 - Testing framework
  • pytest-cov>=4.0.0 - Code coverage
  • black>=23.0.0 - Code formatting
  • flake8>=6.0.0 - Linting
  • mypy>=1.0.0 - Type checking
  • types-PyYAML>=6.0.0 - Type stubs
  • jupyter>=1.0.0 - Notebooks
  • notebook>=6.0.0 - Jupyter interface

​
Complete Installation

Installs all features (recommended for most users): 
pip install heartmap[all]
This includes all dependencies from communication, api, and dev extras.

​
Installation from Source

For the latest development version or to contribute:
1

Clone the repository

git clone https://github.com/Tumo505/HeartMap.git
cd HeartMap
2

Create virtual environment (optional but recommended)

python -m venv heartmap_env
source heartmap_env/bin/activate  # Linux/Mac
# OR
heartmap_env\Scripts\activate  # Windows
3

Install in development mode

pip install -e .[all]
The -e flag installs in editable mode, so changes to the source code are immediately reflected.

​
Verify Installation

After installation, verify that HeartMAP is working correctly:
1

Check package import

python -c "import heartmap; print(heartmap.__version__)"
Expected output:
2.0.2
2

Check CLI availability

heartmap --help
You should see the HeartMAP command-line interface help message.
3

Verify core dependencies

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

print("✅ HeartMAP ready!")

​
Memory Configuration

HeartMAP can be configured to work with different memory constraints:
System RAMRecommended SettingsUse Case
8GBmax_cells_subset: 10000
max_genes_subset: 2000		Laptop/Desktop
16GBmax_cells_subset: 30000
max_genes_subset: 4000		Workstation
32GBmax_cells_subset: 50000
max_genes_subset: 5000		Server
64GB+max_cells_subset: 100000+
max_genes_subset: 10000+		HPC/Cloud
You can configure these settings in a config.yaml file or programmatically through the Config class.

​
Troubleshooting

​
Common Installation Issues

​
ImportError: No module named ‘heartmap’

Solution: Make sure you’ve activated the correct virtual environment and installed HeartMAP: 
pip install heartmap
# Verify installation
pip list | grep heartmap

​
Memory errors during installation

Solution: Install dependencies one at a time or increase pip’s memory limit: 
pip install --no-cache-dir heartmap[all]

​
Compilation errors with igraph or leidenalg

Solution: These packages require compilation. Install build tools: 
sudo apt-get install build-essential python3-dev
pip install heartmap[all]

​
Conflicts with existing packages

Solution: Create a fresh virtual environment: 
python -m venv heartmap_clean
source heartmap_clean/bin/activate
pip install heartmap[all]

​
Checking Installation Status

Use this script to verify all components:
verify_installation.py
import sys

try:
    import heartmap
    print(f"✅ HeartMAP version: {heartmap.__version__}")
except ImportError:
    print("❌ HeartMAP not found")
    sys.exit(1)

try:
    from heartmap import Config
    from heartmap.pipelines import BasicPipeline, ComprehensivePipeline
    print("✅ Core modules imported successfully")
except ImportError as e:
    print(f"❌ Import error: {e}")
    sys.exit(1)

try:
    import scanpy as sc
    import pandas as pd
    import numpy as np
    print("✅ Core dependencies available")
except ImportError as e:
    print(f"⚠️ Some dependencies missing: {e}")

print("\n🎉 HeartMAP installation verified!")
Run with: 
python verify_installation.py

​
Next Steps

Now that HeartMAP is installed, you’re ready to start analyzing cardiac data:

Quick Start

Run your first analysis in minutes

Configuration

Learn how to configure HeartMAP for your system

Tutorials

Explore step-by-step guides

API Reference

Dive into the Python API

​
Getting Help

If you encounter issues during installation:

Build docs developers (and LLMs) love

Get started for freeTalk to us