Documentation | Tutorials | Gallery | llms.txt | Genome Biology

Marsilea: Declarative creation of composable visualization

Marsilea builds complex annotated heatmaps, oncoprints, UpSet plots, sequence logos and other composable visualizations in Python — declaratively, on top of Matplotlib.

Quickstart (8 lines)

import numpy as np import marsilea as ma import marsilea.plotter as mp data = np.random.default_rng(0).standard_normal((10, 10)) h = ma.Heatmap(data, linewidth=0.5, height=4, width=4) h.add_top(mp.Bar(data.mean(axis=0)), size=0.8, pad=0.1) h.add_left(mp.Labels([f"Gene{i}" for i in range(10)]), pad=0.05) h.add_dendrogram("right") h.add_legends() h.render()

Add a bar chart on top, labels on the left, a dendrogram on the right. Each side is just another building block. → Full tutorial

Using scanpy/scverse? Marsilea has an official how-to in the scanpy documentation: Plotting with Marsilea

Installation

PyPI

pip install marsilea

Conda

conda install -c conda-forge marsilea

Use with Agents

Marsilea ships an official agentic skill:

Claude Code

/plugin marketplace add Marsilea-viz/marsilea-skill
/plugin install marsilea@marsilea-marketplace

For other agents, simply ask the agent to install the skill for you.

Once installed, the skill activates automatically whenever you ask Claude for a composable visualization. Marsilea itself still needs to be installed in your Python environment (see above). See the marsilea-skill repository, or Use Marsilea with AI assistants for other assistants and the machine-readable llms.txt.

What is Composable Visualization?

When we do visualization, we often need to combine multiple plots to show different aspects of the data. For example, we may need to create a heatmap to show the expression of genes in different cells, and then create a bar chart to show the expression of genes in different cell types. A visualization contains multiple plots is called a composable visualization. In Marsilea, we employ a declarative approach for user to create composable visualization incrementally.

Examples

Bar chart with images	Stacked bar chart	Arc diagram

Single-cell RNA-seq heatmap	Oncoprint	UpSet plot

More examples →

Citation

If you use Marsilea in your research, please cite the following:

Marsilea: an intuitive generalized paradigm for composable visualizations

Yimin Zheng, Zhihang Zheng, André F. Rendeiro & Edwin Cheung

Genome Biology 2025 Jan 06. DOI: 10.1186/s13059-024-03469-3

Getting help

Found a bug or have a question? Open an issue.