Marsilea: Declarative Composable Visualizations

Marsilea provides a gallery of composable visualizations built using Python, Marsilea, and Matplotlib. These examples demonstrate how to create complex biological and data-driven figures, including:

• Heatmaps: Complex annotated heatmaps.
• Genomics: Oncoprints, sequence logos, sequence alignments, genome tracks, and arc diagrams.
• Set Theory: UpSet plots.
• Single-cell: Single-cell specific figures.

Each example in the gallery is provided as a full script, allowing you to download the code and replace the sample data with your own datasets.

The Strip, Swarm, and Point plotters draw hue levels on top of each other by default. If you attempt to annotate comparisons between these overlaid levels, the comparison will be skipped with a warning.

To fix this, use dodge=True to separate the hue levels spatially, allowing brackets to point to them correctly.

>>> strip = mp.Strip(
...     {"Control": control, "Treated": treated},
...     dodge=True, size=3, label="Expression",
... )
>>> strip.annotate_stats(pairs="hue", text_format="star")

When calling .annotate_stats(), you can use shorthands to avoid manually defining every pair:

• pairs="hue": Compares the conditions (hue levels) inside every category. Useful when passing a dictionary of DataFrames to a plotter.
• pairs="all": Compares all categories with each other. Note: In grouped plots, this only compares categories within the same group.
• pairs="ref": Reduces the comparison to only those against a single reference. When used with pairs="hue", it compares every condition to one reference condition. When used with pairs="all", it compares every category to one reference category.

>>> # Compare all categories against category '0'
>>> bar.annotate_stats(pairs="all", ref="0", text_format="star")

>>> # Compare conditions within each category
>>> box.annotate_stats(pairs="hue", test="Mann-Whitney")

You can combine multiple WhiteBoard objects using overloaded operators to create complex layouts:

• + (Plus): Places two canvases side-by-side. You can insert an integer between them to specify the amount of white space added.
• / (Divide): Places two canvases top and bottom. You can insert an integer between them to specify the amount of white space added.

# Side-by-side with 1 unit of padding
(wb1 + 1 + wb2).render()

# Top and bottom with 1 unit of padding
(wb1 / 1 / wb2).render()

Marsilea uses the axis information embedded in anndata.acc references to ensure components are placed on the correct side of a board.

• A.obs[...] spans observations (cells) and belongs on the left or right.
• A.var[...] spans variables (genes) and belongs on the top or bottom.

If you attempt to add a reference to the wrong side (e.g., adding an observation reference to the top), Marsilea will raise a MisalignedRef error, which explicitly names the reference and the required fix.

# Correct placement based on axis
h = ma.Heatmap(adata, A.X[:, :])
h.add_left(mp.Colors(A.obs["lineage"]), size=0.2)  # obs goes on left/right
h.add_bottom(mp.Labels(A.var.index))               # var goes on top/bottom

Marsilea allows you to build complex visualizations incrementally by adding building blocks (like bar charts, labels, or dendrograms) to a main plot object (like a Heatmap). This declarative approach is built on top of Matplotlib.

import numpy as np
import marsilea as ma
import marsilea.plotter as mp

data = np.random.default_rng(0).standard_normal((10, 10))

# Initialize the main heatmap
h = ma.Heatmap(data, linewidth=0.5, height=4, width=4)

# Add components incrementally
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()

# Render the final visualization
h.render()

To customize a Marsilea plot using standard Matplotlib commands, you must first call the .render() method. Once rendered, you can retrieve the primary axes using .get_main_ax().

If the plot is a single visualization, .get_main_ax() returns a single Matplotlib Axes object. If the plot is split (e.g., via .cut_rows() or .cut_cols()), it returns a list of Axes objects ordered from the upper left to the lower right.

import marsilea as ma
import numpy as np
from matplotlib.patches import Rectangle

data = np.random.rand(20, 20)
h = ma.Heatmap(data, linewidth=1)
h.render()  # Must call render() first

# For a single plot:
hax = h.get_main_ax()

# For split plots (returns a list):
h.cut_rows(cut=[5])
h.render()
hax_list = h.get_main_ax()
for ax in hax_list:
    # Apply customization to each axis
    pass