pyobsplot

Overview

pyobsplot allows to use Observable Plot to create charts in Jupyter notebooks, VSCode notebooks, Google Colab and Quarto documents. Plots are created from Python code with a syntax as close as possible to the JavaScript one.

import polars as pl
from pyobsplot import Plot

penguins = pl.read_csv("data/penguins.csv")

Plot.plot(
    {
        "grid": True,
        "marks": [
            Plot.dot(
                penguins,
                {
                    "x": "flipper_length_mm",
                    "y": "body_mass_g",
                    "fill": "sex",
                    "tip": True,
                },
            )
        ],
    }
)

Or, for a bit more complex example:

Plot.plot(
    {
        "marginLeft": 75,
        "marginRight": 70,
        "x": {"insetRight": 10},
        "y": {"grid": True},
        "facet": {"marginRight": 70},
        "marks": [
            Plot.ruleX([0]),
            Plot.barX(
                penguins,
                Plot.groupY(
                    {"x": "count"}, {"fy": "island", "y": "species", "fill": "sex"}
                ),
            ),
            Plot.text(
                ["The Adelie species is the only one on Torgersen Island."],
                {
                    "fy": ["Torgersen"],
                    "frameAnchor": "right",
                    "lineWidth": 16,
                    "dx": -4,
                },
            ),
        ],
    }
)

Installation and usage

Getting started gives installation instructions and a quick usage overview.

Usage gives more detailed usage instructions.

If you just want to try this package without installing it on your computer, you can open an introduction notebook in Google Colab:

Features and limitations

Features:

  • Syntax as close as possible to the JavaScript one
  • Plots can be generated as Jupyter widgets, or as SVG, HTML or PNG outputs (via typst)
  • Plots can be saved to Widget HTML, static HTML, SVG, PNG or PDF files
  • Pandas and polars DataFrame and Series objects are serialized using Arrow IPC format for improved speed and better data type conversions
  • Works with Jupyter notebooks and Quarto documents
  • Works offline, no iframe or dependency to Observable runtime
  • Caching mechanism of data objects if they are used several times in the same plot
  • Custom JavaScript code can be passed as strings with the js method
  • Python date and datetime objects are automatically converted to JavaScript Date objects

Limitations:

  • Plot interactions (tooltips, crosshair…) are only available with the “widget” format (#16).
  • Very limited integration with IDE (documentation and autocompletion) for Plot methods (unlike in Observable notebooks) (#13).

Credits