Skip to main content

​
Common Issues

This guide covers the most common issues users encounter when working with HeartMAP and provides solutions to resolve them.

​
Memory Issues

​
Memory Errors During Analysis

Error: MemoryError or system running out of RAM during analysis
Solution: Reduce the dataset size in your configuration file:
config.yaml
data:
  max_cells_subset: 10000  # Reduce from default 50000
  max_genes_subset: 2000   # Reduce from default 5000

​
Memory Optimization Guidelines

Choose appropriate settings based on your system RAM:
System RAMmax_cells_subsetmax_genes_subsetUse Case
8GB10,0002,000Laptop/Desktop
16GB30,0004,000Workstation
32GB50,0005,000Server
64GB+100,000+10,000+HPC/Cloud
Start with smaller values and gradually increase them to find the optimal balance for your system.

​
Installation Issues

​
Import Errors

Error: ModuleNotFoundError: No module named 'heartmap'
Solution 1: Reinstall with all dependencies: 
pip install -e .[all]
Solution 2: Check Python path and installation: 
# Verify installation location
python -c "import heartmap; print(heartmap.__file__)"

# Check installed version
pip show heartmap
Solution 3: Ensure virtual environment is activated: 
# Linux/Mac
source heartmap_env/bin/activate

# Windows
heartmap_env\Scripts\activate

​
Missing Dependencies

Error: Import errors for specific packages (scanpy, liana, etc.)
Solution: Install missing dependencies: 
# Install all dependencies
pip install -r requirements-dev.txt

# Or install specific feature sets
pip install heartmap[communication]  # Communication analysis
pip install heartmap[api]            # API features
pip install heartmap[all]            # Everything

​
Data Loading Issues

​
Invalid Data Format

Error: Unable to load .h5ad file or data format errors
Solution 1: Verify data format: 
import scanpy as sc

# Test loading
try:
    adata = sc.read_h5ad('data/raw/your_file.h5ad')
    print(f"✓ Data loaded: {adata.n_obs} cells, {adata.n_vars} genes")
except Exception as e:
    print(f"✗ Error: {e}")
Solution 2: Check file permissions: 
ls -la data/raw/
# Ensure you have read permissions
Solution 3: Verify file integrity: 
# Check if file is corrupted
file data/raw/your_file.h5ad

# Verify checksums if available
python utils/sha256_checksum.py verify data/raw data/raw/checksums.txt

​
Missing Required Columns

Error: KeyError for expected columns like ‘chamber’ or ‘cell_type’
Solution: Check your data structure: 
import scanpy as sc

adata = sc.read_h5ad('your_data.h5ad')

# Check available columns
print("Available columns:", adata.obs.columns.tolist())

# Add chamber column if missing
if 'chamber' not in adata.obs.columns:
    # Add chamber information from your metadata
    adata.obs['chamber'] = your_chamber_labels
    adata.write_h5ad('your_data.h5ad')

​
Performance Issues

​
Slow Analysis

Issue: Analysis taking too long to complete
Solution 1: Enable test mode for quick validation:
config.yaml
data:
  test_mode: true  # Uses smaller subset for testing
Solution 2: Reduce computational parameters:
config.yaml
analysis:
  n_components_pca: 30      # Reduce from 50
  n_neighbors: 10           # Keep default
  n_pcs: 30                 # Reduce from 40
  n_marker_genes: 15        # Reduce from 25
Solution 3: Use GPU acceleration (if available):
config.yaml
model:
  use_gpu: true

​
Long Runtime

Expected runtimes for different configurations:
Dataset SizeMemoryConfigurationExpected Runtime
10K cells8GBBasic5-10 minutes
30K cells16GBComprehensive15-20 minutes
50K cells32GBComprehensive25-30 minutes
100K cells64GBComprehensive45-60 minutes

​
Analysis Errors

​
Clustering Failures

Error: Clustering algorithm fails or produces unexpected results
Solution: Adjust clustering parameters:
config.yaml
analysis:
  resolution: 0.3          # Lower resolution for fewer clusters
  n_neighbors: 15          # Increase for smoother clusters
  use_leiden: true         # Try Leiden instead of Louvain

​
Communication Analysis Errors

Error: LIANA or communication analysis fails
Solution 1: Ensure cell type annotations exist: 
# Check if cell types are annotated
if 'cell_type' not in adata.obs.columns:
    # Run basic pipeline first to get cell types
    from heartmap.pipelines import BasicPipeline
    pipeline = BasicPipeline(config)
    results = pipeline.run('your_data.h5ad', 'results/')
Solution 2: Disable LIANA if it’s causing issues:
config.yaml
analysis:
  use_liana: false  # Disable communication analysis temporarily

​
Configuration Issues

​
Invalid Configuration

Error: Configuration validation errors
Solution: Use default configuration as a starting point: 
from heartmap import Config

# Start with defaults
config = Config.default()

# Modify specific parameters
config.data.max_cells_subset = 30000
config.analysis.resolution = 0.5

# Save custom configuration
config.to_yaml('my_config.yaml')

​
Path Issues

Error: File or directory not found errors
Solution: Check and create required directories: 
import os

# Create required directories
directories = ['data/raw', 'data/processed', 'results', 'figures', 'models']
for directory in directories:
    os.makedirs(directory, exist_ok=True)

​
Validation Tools

​
Quick Validation

Run the validation script to check your setup: 
python scripts/validate.py
This script checks:
  • Python version and environment
  • Package installation
  • Dependencies
  • Configuration
  • Data access

​
Test with Mock Data

Test your installation with generated mock data: 
python scripts/demo.py
This will:
  • Generate mock heart data
  • Run a quick analysis
  • Verify all components work correctly

​
Getting Help

​
Check Logs

HeartMAP creates logs in the results directory: 
# View recent logs
cat results/heartmap.log

# Check for errors
grep -i error results/heartmap.log

​
Diagnostic Information

Gather diagnostic information for bug reports: 
import heartmap
import sys
import scanpy

print(f"HeartMAP version: {heartmap.__version__}")
print(f"Python version: {sys.version}")
print(f"Scanpy version: {scanpy.__version__}")

# Check configuration
config = Config.default()
print(f"Configuration: {config}")

​
Support Channels

GitHub Issues

Report bugs and request features

GitHub Discussions

Ask questions and share knowledge

Documentation

Review comprehensive guides and API docs

Email Support

Contact: [email protected]

​
Platform-Specific Issues

​
Windows

Issue: Path separator errors 
import os

# Use os.path.join for cross-platform compatibility
data_path = os.path.join('data', 'raw', 'your_data.h5ad')

​
macOS

Issue: Installation issues with certain packages 
# Install Xcode command line tools if needed
xcode-select --install

# Use homebrew for system dependencies
brew install hdf5

​
Linux

Issue: Permission errors 
# Ensure proper permissions
chmod +x scripts/*.sh

# Run setup with proper permissions
bash scripts/setup.sh
Most issues can be resolved by following the installation instructions carefully and using the appropriate memory settings for your system. If you continue to experience problems, please reach out through our support channels.

Build docs developers (and LLMs) love

Get started for freeTalk to us