Expression Heatmap

expression-heatmap is a containerized R application for rendering annotated expression heatmaps from a normalized continuous feature-by-sample matrix and matching sample metadata. It runs reproducibly from the command line, in a Docker container, or on HPC through Apptainer/Singularity. Supply explicit input tables and an output directory; the tool writes a self-describing result bundle without changing the input data.

It is a pinned derivation of the canonical OMIX Expression Heatmap module. The canonical scientific implementation and interface are retained byte-for-byte; see OMIX_MODULE_SOURCE.md.

Container image

Use the immutable image reference for reproducible runs:

ghcr.io/nidap-community/expression-heatmap@sha256:565dd7cd5117eb062d2f10b96bf6725e63f9332782f61e2c0e45629bec3b58d4

It was built from application commit a283a95 for linux/amd64. A mutable latest tag is intentionally not used as a deployment identity.

Example output

This compact public TCGA-BRCA example displays 12 named breast-cancer genes across 16 primary-tumor samples, with the cBioPortal patient-level subtype as a top annotation. It demonstrates the default row-standardized display and grouped column ordering; it is a documentation example, not a cohort-wide analysis.

The source, retrieval date, selected samples/genes, and transformation are recorded in docs/README_EXAMPLE_PROVENANCE.md.

Input contract

Use continuous values appropriate for visualization: normalized bulk expression, batch-corrected expression, or single-cell-derived pseudobulk or mean-expression values. Do not supply raw counts, Seurat objects, or a database connection. Rows are features and columns are samples. Duplicate feature identifiers are averaged by the canonical module.

The metadata table has one row per displayed sample. Its sample-ID column must match expression-matrix column names. Any requested annotation fields—for example molecular subtype, mutation status, ESTIMATE score group, or batch—are prepared upstream and supplied as metadata columns.

Quick start

Build a local AMD64 image:

container/build_docker.sh expression-heatmap:local

Run with explicit, read-only input and writable output mounts:

docker run --rm --platform linux/amd64 \
  -v /path/to/input:/data:ro \
  -v /path/to/output:/output \
  expression-heatmap:local \
  --expression_matrix /data/expression_matrix.tsv \
  --sample_metadata /data/sample_metadata.tsv \
  --gene_column Gene \
  --sample_name_column Sample \
  --sample_label_column Sample \
  --group_columns Subtype,Batch \
  --top_genes_by_variance_to_include 100 \
  --output_dir /output

Use the supplied wrapper for the same CAF mount contract:

container/run_docker.sh expression-heatmap:local /path/to/input /path/to/output \
  --expression_matrix /data/expression_matrix.tsv \
  --sample_metadata /data/sample_metadata.tsv \
  --group_columns Subtype \
  --output_dir /output

Core controls

Control	Default	Purpose
--top_genes_by_variance_to_include	500	Highest-variance features to display.
--specific_genes_to_include	None	Space-separated extra feature IDs retained with variable features.
--include_all_genes	false	Display the complete matrix; set --filter_top_genes_by_variance false at the same time.
--group_columns	empty	Comma-separated metadata columns rendered as top annotations.
--center_and_rescale	true	Row-standardize selected features before rendering.
--cluster_samples	true	Unsupervised sample clustering. Choose exactly one sample-ordering mode.
--arrange_sample_columns	false	Group columns by annotation instead of clustering.
--order_by_gene_expression	false	Order columns by one plotted feature.
--heatmap_color_scheme	Bu Yl Rd	One of the canonical palettes in schemas/interface.yml.
--display_gene_names	auto	Show labels for focused panels while avoiding crowding dense maps.
--output_dir	required by application	Writable result directory, normally /output.

The complete canonical parameter set and defaults are in schemas/interface.yml.

Results

The canonical files remain at the chosen output root for command-line compatibility. The wrapper also produces stable application paths:

output/
├── expression_heatmap.png
├── expression_heatmap_matrix.csv
├── expression_heatmap_run_summary.txt
├── figures/expression_heatmap.png
├── tables/expression_heatmap_matrix.csv
├── logs/
│   ├── expression_heatmap_run_summary.txt
│   └── sessionInfo.txt
├── RUN_METADATA.md
└── run_manifest.json

The matrix under tables/ is the exact matrix plotted after canonical duplicate-feature aggregation, selection, and optional row standardization.

Validation

container/build_docker.sh expression-heatmap:local
container/smoke_test.sh expression-heatmap:local
container/parity_test.sh expression-heatmap:local /path/to/OMIX/modules/OMIX-Expression-Heatmap

The parity test verifies that canonical and standalone runs produce identical heatmaps, displayed matrices, and canonical summaries for the same fixture.

HPC use

The image targets linux/amd64. Once a versioned GHCR image is published, it can be pulled into Apptainer or Singularity:

apptainer pull expression-heatmap.sif \
  docker://ghcr.io/nidap-community/expression-heatmap:VERSION

Use container/run_apptainer.sh to bind input to /data and results to /output with the same contract as Docker.