HeartMAP CLI Usage

HeartMAP provides a command-line interface for running analyses without writing Python code.

Installation

pip install heartmap

# Verify installation
heartmap --version

Basic Usage

Quick Analysis

# Run with defaults (comprehensive pipeline)
heartmap your_data.h5ad

# Specify output directory
heartmap your_data.h5ad --output-dir results/my_analysis

Choose Analysis Type

# Basic analysis (QC, clustering, annotation)
heartmap data.h5ad --analysis-type basic

# Communication analysis
heartmap annotated_data.h5ad --analysis-type advanced

# Multi-chamber analysis
heartmap chamber_data.h5ad --analysis-type multi_chamber

# Comprehensive (all analyses)
heartmap data.h5ad --analysis-type comprehensive

Complete CLI Reference

Command Structure

heartmap DATA_PATH [OPTIONS]

Required Arguments

data_path

string

required

Path to input single-cell data fileSupported formats:

AnnData: .h5ad
10X Genomics: .h5
Matrix Market: .mtx (with companion files)
Loom: .loom

Optional Arguments

--analysis-type

string

default:"comprehensive"

Type of analysis to performChoices:

basic - QC, clustering, annotation
advanced - Cell-cell communication
multi_chamber - Chamber-specific analysis
comprehensive - Complete pipeline

--output-dir

string

default:"results"

Directory to save results

--config

string

Path to custom configuration YAML fileExample:

heartmap data.h5ad --config my_config.yaml

Examples

Example 1: Basic Analysis

Perform standard QC, clustering, and annotation:

heartmap heart_data.h5ad \
  --analysis-type basic \
  --output-dir results/basic_analysis

Output:

results/basic_analysis/annotated_data.h5ad - Processed data
results/basic_analysis/figures/ - UMAP plots, QC metrics
results/basic_analysis/tables/ - Marker genes

Example 2: Communication Analysis

Analyze cell-cell communication from annotated data:

heartmap results/basic/annotated_data.h5ad \
  --analysis-type advanced \
  --output-dir results/communication

Output:

Communication heatmaps
Hub score visualizations
L-R interaction tables

Example 3: Multi-Chamber Analysis

Analyze chamber-specific patterns:

heartmap chamber_annotated_data.h5ad \
  --analysis-type multi_chamber \
  --output-dir results/multi_chamber

Requires: Input data must have chamber column in adata.obs

Example 4: Comprehensive Analysis

Run complete HeartMAP pipeline:

heartmap raw_heart_data.h5ad \
  --analysis-type comprehensive \
  --output-dir results/comprehensive \
  --config configs/high_memory.yaml

Output:

All analysis components
Comprehensive dashboard
Automated report

Example 5: Custom Configuration

Create a custom config file my_config.yaml:

data:
  min_genes: 200
  min_cells: 3
  max_cells_subset: 30000
  n_top_genes: 2000

analysis:
  resolution: 0.5
  n_neighbors: 10
  n_pcs: 40
  use_liana: true

model:
  save_intermediate: true

Run with custom config:

heartmap data.h5ad \
  --config my_config.yaml \
  --output-dir results/custom

Configuration Files

Default Configuration

View default configuration:

from heartmap import Config
config = Config.default()
print(config.to_yaml())

Configuration Structure

# Data processing parameters
data:
  min_genes: 200              # Min genes per cell
  min_cells: 3                # Min cells per gene
  max_cells_subset: 50000     # Max cells (memory limit)
  max_genes_subset: 5000      # Max genes
  target_sum: 10000.0         # Normalization target
  n_top_genes: 2000           # Highly variable genes
  random_seed: 42             # For reproducibility
  test_mode: false            # Quick test run

# Analysis parameters
analysis:
  n_components_pca: 50        # PCA components
  n_neighbors: 10             # Neighbors for graph
  n_pcs: 40                   # PCs for neighbors
  resolution: 0.5             # Clustering resolution
  n_marker_genes: 25          # Markers per cluster
  use_leiden: true            # Use Leiden clustering
  use_liana: true             # Use L-R database

# Model parameters
model:
  model_type: comprehensive
  save_intermediate: true
  use_gpu: false
  batch_size: null
  max_memory_gb: null

# Output paths (relative to working directory)
paths:
  data_dir: data
  raw_data_dir: data/raw
  processed_data_dir: data/processed
  results_dir: results
  figures_dir: figures
  models_dir: models

Memory-Optimized Configs

Low Memory (8GB)
Medium (16GB)
High (32GB+)

data:
  max_cells_subset: 10000
  max_genes_subset: 2000
  n_top_genes: 1500

analysis:
  n_components_pca: 30
  n_pcs: 30

data:
  max_cells_subset: 30000
  max_genes_subset: 4000
  n_top_genes: 2000

analysis:
  n_components_pca: 40
  n_pcs: 40

data:
  max_cells_subset: 50000
  max_genes_subset: 5000
  n_top_genes: 3000

analysis:
  n_components_pca: 50
  n_pcs: 50

Advanced Usage

Batch Processing

Process multiple datasets:

#!/bin/bash
# process_all.sh

for file in data/raw/*.h5ad; do
    name=$(basename "$file" .h5ad)
    echo "Processing $name..."
    
    heartmap "$file" \
      --analysis-type comprehensive \
      --output-dir "results/$name" \
      --config configs/batch_config.yaml
    
    echo "Completed $name"
done

echo "All datasets processed!"

Run:

chmod +x process_all.sh
./process_all.sh

Integration with Workflow Managers

Snakemake

# Snakefile
samples = ['sample1', 'sample2', 'sample3']

rule all:
    input:
        expand('results/{sample}/heartmap_complete.h5ad', sample=samples)

rule heartmap_analysis:
    input:
        'data/raw/{sample}.h5ad'
    output:
        'results/{sample}/heartmap_complete.h5ad'
    params:
        outdir='results/{sample}'
    shell:
        'heartmap {input} --analysis-type comprehensive --output-dir {params.outdir}'

Nextflow

// main.nf
params.data = 'data/raw/*.h5ad'
params.outdir = 'results'

process heartmap {
    publishDir "${params.outdir}/${sample}", mode: 'copy'
    
    input:
    path data_file
    
    output:
    path "heartmap_complete.h5ad"
    
    script:
    sample = data_file.simpleName
    """
    heartmap ${data_file} \
      --analysis-type comprehensive \
      --output-dir .
    """
}

workflow {
    data_files = Channel.fromPath(params.data)
    heartmap(data_files)
}

Using with Docker

Run HeartMAP in a container:

# Pull image (when available)
docker pull tumo505/heartmap:latest

# Run analysis
docker run -v $(pwd)/data:/data \
           -v $(pwd)/results:/results \
           tumo505/heartmap:latest \
           heartmap /data/heart_data.h5ad \
             --output-dir /results

Python CLI Interface

Alternatively, use the Python API for CLI functionality:

# run_heartmap.py
from heartmap.api import CLIInterface

cli = CLIInterface()
results = cli.run_analysis(
    data_path='data/heart_data.h5ad',
    analysis_type='comprehensive',
    output_dir='results/comprehensive',
    config_path='config.yaml'
)

print(f"Analysis complete! {results['adata'].n_obs} cells processed.")

Run:

python run_heartmap.py

Troubleshooting

Command not found: heartmap

The CLI may not be in your PATH. Try:

# Using Python module directly
python -m heartmap.api data.h5ad --analysis-type basic

# Or reinstall with pip
pip install --force-reinstall heartmap

Memory errors during analysis

Reduce dataset size in config:

data:
  max_cells_subset: 10000
  max_genes_subset: 2000

Or use test mode:

data:
  test_mode: true

Analysis runs too slow

Reduce PCA components: n_components_pca: 30
Reduce highly variable genes: n_top_genes: 1500
Disable L-R database: use_liana: false
Use test mode for quick validation

File format not supported

Convert your data first:

import scanpy as sc

# From CSV
adata = sc.read_csv('data.csv')

# From 10X directory
adata = sc.read_10x_mtx('filtered_feature_bc_matrix/')

# Save as h5ad
adata.write('data.h5ad')

Then run HeartMAP:

heartmap data.h5ad

Environment Variables

Set environment variables for default behavior:

# Set default output directory
export HEARTMAP_OUTPUT_DIR=results

# Set default config path
export HEARTMAP_CONFIG=configs/default.yaml

# Set number of threads
export HEARTMAP_N_JOBS=8

# Enable verbose logging
export HEARTMAP_VERBOSE=1

Usage:

heartmap data.h5ad  # Uses environment defaults

Tips and Best Practices

Data Organization

Organize your project:

project/
├── data/
│   └── raw/
│       └── heart_data.h5ad
├── configs/
│   └── my_config.yaml
├── results/
└── scripts/
    └── run_analysis.sh

Version Control

Track configurations:

git add configs/*.yaml
git commit -m "Update analysis parameters"

Reproducibility

Always specify --config for consistent results
Set random_seed in config
Document package versions: pip freeze > requirements.txt

Next Steps

API Usage

REST API interface

Python API

CLIInterface reference

Configuration

Full config docs

Get Started

Core Concepts

Guides

Examples

​HeartMAP CLI Usage

​Installation

​Basic Usage

​Quick Analysis

​Choose Analysis Type

​Complete CLI Reference

​Command Structure

​Required Arguments

​Optional Arguments

​Examples

​Example 1: Basic Analysis

​Example 2: Communication Analysis

​Example 3: Multi-Chamber Analysis

​Example 4: Comprehensive Analysis

​Example 5: Custom Configuration

​Configuration Files

​Default Configuration

​Configuration Structure

​Memory-Optimized Configs

​Advanced Usage

​Batch Processing

​Integration with Workflow Managers

​Snakemake

​Nextflow

​Using with Docker

​Python CLI Interface

​Troubleshooting

​Environment Variables

​Tips and Best Practices

Data Organization

Version Control

Reproducibility

​Next Steps

API Usage

Python API

Configuration

Build docs developers (and LLMs) love

HeartMAP CLI Usage

Installation

Basic Usage

Quick Analysis

Choose Analysis Type

Complete CLI Reference

Command Structure

Required Arguments

Optional Arguments

Examples

Example 1: Basic Analysis

Example 2: Communication Analysis

Example 3: Multi-Chamber Analysis

Example 4: Comprehensive Analysis

Example 5: Custom Configuration

Configuration Files

Default Configuration

Configuration Structure

Memory-Optimized Configs

Advanced Usage

Batch Processing

Integration with Workflow Managers

Snakemake

Nextflow

Using with Docker

Python CLI Interface

Troubleshooting

Environment Variables

Tips and Best Practices

Next Steps