uplot

Unified API and style for Python plotting libraries.

Usage

plotly 5

matplotlib

import numpy as np
import uplot

x = np.linspace(0, np.pi*4, num=100)
phi = np.pi/4

fig = uplot.figure('plotly')
fig.plot(x, np.sin(x - 0*phi), name='#1')
fig.plot(x, np.sin(x - 1*phi), name='#2')
fig.plot(x, np.sin(x - 2*phi), name='#3')
fig.plot(x, np.sin(x - 3*phi), name='#4')
fig.xlabel('X').ylabel('Y')
fig.legend().show()

import numpy as np
import uplot

x = np.linspace(0, np.pi*4, num=100)
phi = np.pi/4

fig = uplot.figure('matplotlib')
fig.plot(x, np.sin(x - 0*phi), name='#1')
fig.plot(x, np.sin(x - 1*phi), name='#2')
fig.plot(x, np.sin(x - 2*phi), name='#3')
fig.plot(x, np.sin(x - 3*phi), name='#4')
fig.xlabel('X').ylabel('Y')
fig.legend().show()

💡 See gallery for more examples.

Install

Recent stable version (without any plotting library):

pip install "uplot @ git+https://github.com/makarovdi/uplot.git@main"

To automatically install all optional dependencies (matplotlib, plotly, ...):

pip install "uplot[all] @ git+https://github.com/makarovdi/uplot.git@main"

If you need only matplotlib support:

pip install "uplot[matplotlib] @ git+https://github.com/makarovdi/uplot.git@main"

💡 Replace [matplotlib] with [plotly5] for plotly-only installation

Plotting Libs - Pros & Cons

Matplotlib

🟢 Highly configurable.
🟢 Good documentation and a lot of ready-to-use recipes (e.g. on StackOverflow).
🟡 Common API (MATLAB legacy).

🔴 Limited interactivity (especially for Jupyter).
🔴 API, behavior and parameter names are inconsistent (e.g. plt.xlim and axis.set_xlim).
🔴 Slow and limited 3D rendering.

Plotly

🟢 Very good interactivity.
🟢 Native compatibility with Jupyter.
🟢 Possibility to save interactive plot (html-file).
🟢 Fast and interactive 3D plot.

🔴 Not well documented (a lot of parameters, small amount of examples).
🔴 High memory consumption (limited number of plots in Jupyter).
🔴 Some expected API functions are missing (e.g. imshow).
🔴 3D and 2D axis parameters are not unified (e.g. layout.xaxis doesn't work for 3D).

Extending

Plugin

The plugin system allows extending uplot for visualizing custom objects.
For example, the DataFrame plugin enables this code:

import uplot
import pandas as pd

car_crashes = pd.read_csv(
    'https://raw.githubusercontent.com/mwaskom/seaborn-data/master/car_crashes.csv'
)

fig = uplot.figure()
fig.plot(car_crashes[['total', 'speeding', 'alcohol', 'no_previous']])
fig.show()

To implement the plugin, you can follow this structure:

import numpy as np
import pandas as pd

import uplot.plugin as plugin


class DataFramePlugin(plugin.IPlotPlugin):

    def extract_data(self, obj: pd.DataFrame) -> list[plugin.PlotData]:
        data = []
        for name in obj.columns:
            if not np.issubdtype(obj.dtypes[name], np.number): continue
            y = obj[name].values
            x = np.arange(len(y))
            data.append(plugin.PlotData(x=x, y=y, name=name.replace('_', ' ').title()))
        return data

plugin.register(pd.DataFrame, handler=DataFramePlugin())

💡 Check test/plugin.py for a more advanced plugin example.

Engine

Adding a new plotting library is straightforward. Implement two interfaces IPlotEngine and IFigure:

import uplot
from uplot import IPlotEngine, IFigure

class MyEngine(IPlotEngine):
    ...
    def figure(self, ...) -> MyFigure: ...
    
class MyFigure(IFigure):
    def plot(self, ...): ...
    def scatter(self, ...): ...
    ...

# register the engine
uplot.engine.register(MyEngine(), name='test')

Then use it in the regular way:

import uplot

fig = uplot.figure(engine='test')
fig.plot(...)
fig.show()

Verified Versions

	Standalone	JupyterLab `v4.0.6-v4.2.3`	Jupyter Notebook `7.0-7.2`
matplotlib `3.7-3.9`	`gui` 🟢 `save image` 🟢	`inline` 🟢 `ipympl` 🟢	`inline` 🟢 `ipympl` 🟢
plotly `5.16-5.22`	`chromium` 🟢 `save image` 🟢	🟢	🟢

Dependencies

Python ≥ 3.10
numpy ≥ 1.21 v2.0 supported
pillow ≥ 10.2

Optional

matplotlib ≥ 3.7
plotly ≥ 5.17

License

This software is licensed under the BSD-3-Clause license.
See the LICENSE file for details.

TODO

Check the plan for new features here.

MakarovDi / uplot