README.md

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.

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.

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
• Two renderers available: widget, which generates plots as Jupyter widgets, and jsdom, which generates SVG or HTML outputs
• Pandas and polars DataFrame and Series objects are serialized using Arrow IPC format for improved speed and better 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:

• Plot interactions (tooltips, crosshair...) are not available with the jsdom renderer (juba#16).
• Plots with legends don't work in Quarto in formats other than HTML. (juba#9)
• Very limited integration with IDE (documentation and autocompletion) for Plot methods. (juba#13)

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.