PyComplexHeatmap Documentation

The PyComplexHeatmap gallery demonstrates various complex visualization capabilities. Key use cases include:

• Heatmap Annotations: Creating heatmaps with associated annotations, custom annotations, or plotting only the annotations.
• Composite Heatmaps: Combining multiple heatmaps horizontally.
• Clustering Strategies: Clustering between groups or clustering within groups.
• Specialized Plots:
  • OncoPrint: Visualizing categorical variables or using split columns.
  • Dot Clustermap: Visualizing enrichment results or dot clustermaps with annotations.
  • DotClustermapPlotter: Visualizing up to five-dimensional data.
• Biological Data Types: Specialized workflows for DNA methylation (cell type specific signatures) and single-cell data.

The PyComplexHeatmap package is organized into several specialized submodules for different heatmap and visualization tasks:

• PyComplexHeatmap.annotations: For managing and visualizing annotations.
• PyComplexHeatmap.clustermap: For creating clustered heatmaps.
• PyComplexHeatmap.colors: For color palette management.
• PyComplexHeatmap.dotHeatmap: For generating dot heatmaps.
• PyComplexHeatmap.oncoPrint: For creating OncoPrint-style visualizations.
• PyComplexHeatmap.utils: For utility functions.

If you need the latest features or fixes from the development branch, you can install directly from the GitHub repository using pip or by cloning the repository and running the setup script.

# Install directly via pip from GitHub
pip install git+https://github.com/DingWB/PyComplexHeatmap

# OR: Manual installation via git clone
git clone https://github.com/DingWB/PyComplexHeatmap
cd PyComplexHeatmap
python setup.py install

If you previously installed a version of PyComplexHeatmap and want to switch to the developmental version from GitHub, it is recommended to uninstall the existing version first to avoid conflicts.

pip uninstall PyComplexHeatmap
pip install git+https://github.com/DingWB/PyComplexHeatmap

PyComplexHeatmap requires the following Python packages:

• matplotlib
• numpy
• pandas
• scipy
• fastcluster (optional, but recommended for clustering performance)

You can pre-install the core dependencies using:

pip install --ignore-install matplotlib numpy pandas fastcluster

You can install the stable version of PyComplexHeatmap using pip. To ensure you have the latest stable release, use the --upgrade flag.

pip install PyComplexHeatmap
# or to upgrade
pip install --upgrade PyComplexHeatmap

To build the project documentation, you need to install Sphinx and several extensions via pip and conda. This setup includes support for Jupyter notebooks (nbsphinx), various themes, and Pandoc for document conversion.

pip install sphinx sphinx-autobuild sphinx-rtd-theme pandoc nbsphinx sphinx_pdj_theme sphinx_sizzle_theme recommonmark readthedocs-sphinx-search
conda install conda-forge::pandoc

PyComplexHeatmap provides several ways to learn how to use the package for visualizing multimodal genomics data:

• Simple Guide: A quickstart for beginners to get started with basic heatmaps.
• Advanced Usage: Detailed tutorials for complex scenarios like clustering between groups, custom annotations, or plotting only annotations.
• Kwargs Reference: A comprehensive list of keyword arguments available for customizing plots.
• Gallery/Examples: Visual examples covering various plot types including:
  • oncoPrint: Visualizing categorical variables.
  • DotClustermapPlotter: Visualizing up to five-dimensional data using dot clustermaps.
  • anno_img: Visualizing motif enrichment results using images.
  • Composite heatmaps (combining heatmaps horizontally).

You can install PyComplexHeatmap via pip for the stable version or directly from GitHub for the developmental version.

Stable Version

Use pip to install or upgrade the package.

Developmental Version

To install the latest version from the GitHub repository, use the git+https URL. You can also clone the repository and install it manually using setup.py.

# Install stable version
pip install PyComplexHeatmap

# Upgrade stable version
pip install --upgrade PyComplexHeatmap

# Install developmental version from GitHub
pip install git+https://github.com/DingWB/PyComplexHeatmap

# Reinstall developmental version
pip uninstall -y PyComplexHeatmap && pip install git+https://github.com/DingWB/PyComplexHeatmap

# Manual installation from cloned repo
git clone https://github.com/DingWB/PyComplexHeatmap
cd PyComplexHeatmap
python setup.py install

Follow these steps to initialize the documentation structure using sphinx-quickstart:

1. Create and enter the docs directory: mkdir -p docs && cd docs.
2. Run sphinx-quickstart.
3. When prompted, select y for Separate source and build directories.
4. Provide the project name (e.g., PyComplexHeatmap).
5. Configure source/conf.py as needed and add .rst files to the source directory.
6. To allow the root index.html to redirect to the built documentation, edit docs/index.html to include: <meta http-equiv="refresh" content="0; url=./build/html/index.html" />.

mkdir -p docs && cd docs
sphinx-quickstart
# Separate source and build directories (y/n) [n]: y
# Project name: PyComplexHeatmap