Heatmap Beautifier

---

name: heatmap-beautifier

description: Professional beautification tool for gene expression heatmaps, automatically adds clustering trees, color annotation tracks, and intelligently optimizes label layout.

license: MIT

skill-author: AIPOCH

---

# Heatmap Beautifier

Professional beautification tool for gene expression heatmaps, automatically adds clustering trees, color annotation tracks, and intelligently optimizes label layout.

Input Validation

This skill accepts: CSV files containing gene expression matrices (genes as rows, samples as columns) for heatmap generation and beautification.

If the user's request does not involve heatmap generation or gene expression visualization — for example, asking to perform differential expression analysis, run statistical tests, or generate other chart types — do not proceed. Instead respond:

> "heatmap-beautifier is designed to generate and beautify gene expression heatmaps from expression matrix data. Your request appears to be outside this scope. Please provide a CSV expression matrix file, or use a more appropriate tool for your task."

Do not continue the workflow when the request is out of scope, missing the required input CSV, or would require unsupported assumptions. For missing inputs, state exactly which fields are missing.

Quick Check

python -m py_compile scripts/main.py
python scripts/main.py --help
# Demo mode (no CSV required):
python scripts/main.py --demo --output demo_heatmap.pdf

When to Use

Workflow

1. **Validate input** — confirm the request is within scope before any processing.

2. Confirm the user objective, required inputs, and non-negotiable constraints.

3. Use the packaged script path or the documented reasoning path with only the inputs that are actually available.

4. Return a structured result that separates assumptions, deliverables, risks, and unresolved items.

5. If execution fails or inputs are incomplete, switch to the fallback path and state exactly what blocked full completion.

Features

Dependencies

pip install seaborn matplotlib scipy pandas numpy

Usage

Basic Usage

from skills.heatmap_beautifier.scripts.main import HeatmapBeautifier

hb = HeatmapBeautifier()
hb.create_heatmap(
    data_path="expression_matrix.csv",
    output_path="output/heatmap.pdf"
)

Command Line Usage

python -m skills.heatmap_beautifier.scripts.main \
    --input expression_matrix.csv \
    --output heatmap.pdf

python -m skills.heatmap_beautifier.scripts.main \
    --input expression_matrix.csv \
    --output heatmap.pdf \
    --row-cluster \
    --col-cluster \
    --row-annotations row_annot.json \
    --col-annotations col_annot.json \
    --title "Gene Expression"

# Demo mode (no CSV required)
python -m skills.heatmap_beautifier.scripts.main --demo --output demo_heatmap.pdf

# Save clustering metadata to JSON for agent consumption
python -m skills.heatmap_beautifier.scripts.main \
    --input expression_matrix.csv \
    --output heatmap.pdf \
    --output-json heatmap_metadata.json

Parameters

| Parameter | Type | Default | Required | Description |

|-----------|------|---------|----------|-------------|

| `--data-path`, `-d` | string | - | Yes* | Path to input data file (CSV) |

| `--demo` | flag | - | No | Generate synthetic 20×10 demo matrix |

| `--output-path`, `-o` | string | heatmap.png | No | Output file path |

| `--title` | string | Gene Expression Heatmap | No | Heatmap title |

| `--cmap` | string | RdBu_r | No | Color map |

| `--center` | float | 0 | No | Color center value |

| `--vmin` | float | -2 | No | Minimum value for color scale |

| `--vmax` | float | 2 | No | Maximum value for color scale |

| `--row-cluster` | bool | true | No | Enable row clustering |

| `--col-cluster` | bool | true | No | Enable column clustering |

| `--standard-scale` | string | None | No | Standardization: row, col, None |

| `--z-score` | int | None | No | Z-score: 0 (row), 1 (col), None |

| `--figsize` | tuple | (12, 10) | No | Figure size (width, height) |

| `--dpi` | int | 300 | No | Resolution (dots per inch) |

| `--format` | string | pdf | No | Output format (pdf, png, svg) |

| `--output-json` | string | - | No | Save clustering metadata (gene_order, sample_order, annotation_colors) to JSON |

*One of `--data-path` or `--demo` is required.

Input Data Format

Expression Matrix (CSV)

,sample1,sample2,sample3,sample4
Gene_A,2.5,-1.2,0.8,-0.5
Gene_B,-0.8,1.5,-2.1,0.3
Gene_C,1.2,0.5,-0.7,1.8

Color Schemes

Error Handling

Fallback Behavior

If `scripts/main.py` fails or required inputs are incomplete:

1. Report the exact failure point and error message.

2. State what can still be completed (e.g., data validation without rendering).

3. Manual fallback: verify CSV format has gene rows and sample columns, then re-run with minimal options: `python -m skills.heatmap_beautifier.scripts.main --input data.csv --output out.png`.

4. Use `--demo` to verify the environment works without a real CSV.

5. Do not fabricate execution outcomes or file contents.

Output Requirements

Every final response must make these items explicit when relevant:

Response Template

Use the following fixed structure for non-trivial requests:

1. Objective

2. Inputs Received

3. Assumptions

4. Workflow

5. Deliverable

6. Risks and Limits

7. Next Checks

For stress/multi-constraint requests, also include:

If the request is simple, you may compress the structure, but still keep assumptions and limits explicit when they affect correctness.

Notes

1. Recommended to perform log2 transformation or standardization on data first

2. Large datasets (>5000 rows) may take longer to process

3. When there are too many rows/columns, some labels will be automatically hidden

4. Default clustering uses Euclidean distance and Ward method