Skip to content
dysonsphere

Getting started

Install

Section titled “Install”
Terminal window
# with pip
pip install dysonsphere


# with uv
uv pip install dysonsphere


# add as a project dependency
uv add dysonsphere

Requires Python >= 3.11. The runtime dependencies install with it:

  • Altair >= 5.5 - the charting layer
  • Polars >= 1.19 - the native DataFrame (pandas input is accepted and converted)
  • NumPy >= 1.26 - numeric primitives
  • SciPy >= 1.11 - the statistics behind add_comparisons() / add_correlation()
  • vl-convert >= 1.7 - the SVG/PNG renderer behind save()

pandas and duckdb are optional - only needed for read(..., output="pandas"/"duckdb").

dysonsphere is an Altair companion. Its functions return native Altair objects, so you keep Altair’s full API and compose dysonsphere’s additions with +. Data can be a polars or a pandas DataFrame.

The shape of the library

Section titled “The shape of the library”

Everything hangs off one namespace, dysonsphere (conventionally ds):

  • ds.theme() - register a global theme. Call it once; every Altair chart afterwards inherits perceptually uniform palettes and publication-ready styling. See Theming.
  • Marks - ds.mark_strip(), ds.mark_violin() build composite plots. See Marks.
  • Annotations - ds.add_rule(), ds.add_text(), ds.add_shade(), ds.add_comparisons(), ds.add_correlation() return layers you add with +. See Annotations and Statistics.
  • ds.save() / ds.read() / ds.load() - export figures that carry their own provenance, statistics, theme, and data. See Saving & reading.

Your first chart

Section titled “Your first chart”
import polars as pl
import altair as alt
import dysonsphere as ds


ds.theme(palette="blues")


df = pl.DataFrame({"group": ["A", "B", "C", "D"], "value": [3.0, 5.0, 2.0, 6.0]})


chart = (
    alt.Chart(df)
    .mark_bar()
    .encode(x="group:N", y="value:Q", color=alt.Color("group:N", legend=None))
)
Open in studio →

ds.theme() registers the theme; palette="blues" sets the categorical color scheme. Because the theme is global, plain alt.Chart(...) picks it up - dysonsphere only had to set the palette.

Saving

Section titled “Saving”
ds.save(chart, "figure")   # writes figure.svg + figure.json by default

save() bakes provenance, the resolved theme, and (when present) statistics into the file, which ds.read() and ds.load() pull back out later.

Try it live

Section titled “Try it live”

Every example on this site has an Open in studio link: the Chart Studio runs the real library in your browser via WebAssembly - edit the code and watch the chart update, or upload your own data and build a chart from controls. No install required.