Extension: biology

dysonsphere-biology adds molecular-biology charts to dysonsphere - built entirely on the public core + ext surfaces, so every chart it draws is themed, darkmode-aware, and round-trips through ds.save() / ds.read() like a built-in.

pip install dysonsphere-biology

Once installed, its charts resolve lazily under ds.biology:

import dysonsphere as ds

ds.biology.volcano(df, geneCol="gene", label=8)

Volcano plot

volcano() draws log2 fold change against −log₁₀ p, classifies each point as gained / lost / non-differential by the fold-change and p-value thresholds, colors it with the diverging pinksblues endpoints (pink = gained, blue = lost), and layers on optional threshold guides and gene labels:

import numpy as np
import polars as pl

import dysonsphere as ds

# ds.biology comes from the separately-installed `dysonsphere-biology` extension,
# resolved lazily through the entry-point discovery system (pip install dysonsphere-biology).

rng = np.random.default_rng(7)
n = 800

# Simulate a differential-expression result: mostly null, with a tail of real hits whose
# larger fold changes come with smaller p-values.
log2fc = rng.normal(0, 1.0, n)
hits = rng.choice(n, 40, replace=False)
log2fc[hits] += rng.choice([-1, 1], 40) * rng.uniform(1.5, 4.0, 40)
base = rng.uniform(0.001, 1.0, n)
pvalue = np.where(np.abs(log2fc) > 1.5, base**3, base)

df = pl.DataFrame({"gene": [f"G{i}" for i in range(n)], "log2fc": log2fc, "pvalue": pvalue})

ds.theme(chartWidth=150, chartHeight=110)

# label=8 auto-selects the 8 most significant genes (ranked by |log2fc| x -log10 p).
chart = ds.biology.volcano(df, geneCol="gene", label=8, legend=False)

Open in studio →

The gene labels are auto-placed with core’s add_labels force-repel engine (deterministic, connector-linked), and the point ranking is domain-specific: label=8 selects the 8 most significant genes by the combined score |log2fc| × −log10(p).

Key parameters

Parameter	Default	What it does
`log2fcCol` / `pvalueCol`	`"log2fc"` / `"pvalue"`	Effect-size and p-value column names
`geneCol`	`None`	Gene-name column (required when `label` is set)
`fcThreshold`	`1.0`	`
`pThreshold`	`0.05`	P-value cutoff; horizontal guide at −log₁₀ of it
`label`	`None`	`int` (top-N by score), `"significant"` (all hits), or `list[str]` (named genes)
`thresholdLines`	`True`	Draw the fold-change / p-value guide lines
`palette`	`pinksblues` ends	`(gained, lost)` hex colors
`nsColor`	theme grey	Non-differential point color (darkmode-aware)
`legend`	`True`	Show the significance color legend

See the full signature and every parameter in the dysonsphere_biology.volcano reference.

Colors resolve from the active theme at call time (including the darkmode-aware grey), so for a correct light/dark export wrap the call in a ds.save() callable:

ds.save(lambda: ds.biology.volcano(df, geneCol="gene", label=8), "volcano")

Coming next

The biology package is early - manhattan / MA plots, deepTools-style profiles, and a genome browser track are on the roadmap. The library already ships nucleotides and proteins palettes for sequence-colored charts. Want to build one yourself? See writing an extension.