pyobsplot 0.3.1

Observable Plot in Jupyter notebooks and Quarto documents

pyobsplot

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.

It allows to do things like :

import polars as pl
from pyobsplot import Plot

penguins = pl.read_csv("https://github.com/juba/pyobsplot/raw/main/doc/data/penguins.csv")

Plot.plot({
    "grid": True,
    "color": {"legend": True},
    "marks": [
        Plot.dot(
            penguins, 
            {"x": "flipper_length_mm", "y": "body_mass_g", "fill": "species"}
        ),
        Plot.density(
            penguins, 
            {"x": "flipper_length_mm", "y": "body_mass_g", "stroke": "species"}
        )
    ]
})

Installation and usage

Warning: this project is at an early stage. There will be bugs, and the API may change.

pyobsplot can be installed with pip:

pip install pyobsplot

For usage instructions, see the documentation website:

• See getting started for a quick usage overview.
• See usage for more detailed usage instructions.

Features and limitations

Features:

• Syntax as close as possible to the JavaScript one
• Two renderers available: widget, which generates plots as Jupyter widgets, and jsdom, which generate SVG or HTML outputs
• Pandas and polars DataFrame and Series objects are serialized using Arrow IPC format for improved speed and data type conversions
• 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
• Works with Jupyter notebooks and Quarto HTML documents. Plots without legends are also supported in PDF and docx outputs with the jsdom renderer.

Limitations:

• Plots with legends don't work in Quarto in formats other than HTML. (#9)
• Some faceting operations produce warnings when used as top-level faceting (but the plots should be fine). This doesn't happen when using mark-level faceting (with the fx and fy channels). (#3)

Credits

• Observable Plot, developed by Mike Bostock and Philippe Rivière among others.
• The widget is developed thanks to the anywidget framework.
• Some code from the jsdom renderer has been adapted from altair_saver.
• The documentation website is generated by Quarto and the bookup custom format.