Plotting¶

marimo supports most major plotting libraries, including Matplotlib, Seaborn, Plotly, and Altair. Just import your plotting library of choice and use it as you normally would.

For more information about plotting, see the plotting guide.

Reactive charts with Altair¶

Disabling automatic selection¶

marimo automatically adds a default selection based on the mark type, however, you may want to customize the selection behavior of your Altair chart. You can do this by setting chart_selection and legend_selection to False, and using .add_params directly on your Altair chart.

# Create an interval selection
brush = alt.selection_interval(encodings=["x"])

_chart = (
    alt.Chart(traces, height=150)
    .mark_line()
    .encode(x="index:Q", y="value:Q", color="traces:N")
    .add_params(brush) # add the selection to the chart
)

chart = mo.ui.altair_chart(
    _chart,
    # disable automatic selection
    chart_selection=False,
    legend_selection=False
)
chart # You can now access chart.value to get the selected data

marimo.ui.altair_chart(chart: altair.Chart, chart_selection: Literal['point'] | Literal['interval'] | bool = True, legend_selection: list[str] | bool = True, *, label: str = '', on_change: Callable[[pd.DataFrame], None] | None = None) → None¶

Make reactive charts with Altair

Use mo.ui.altair_chart to make Altair charts reactive: select chart data with your cursor on the frontend, get them as a Pandas dataframe in Python!

For Polars DataFrames, you can convert to a Pandas DataFrame. However the returned DataFrame will still be a Pandas DataFrame, so you will need to convert back to a Polars DataFrame if you want.

Example.

import altair as alt
import marimo as mo
from vega_datasets import data

chart = (
    alt.Chart(data.cars())
    .mark_point()
    .encode(
        x="Horsepower",
        y="Miles_per_Gallon",
        color="Origin",
    )
)

chart = mo.ui.altair_chart(chart)

# View the chart and selected data as a dataframe
mo.hstack([chart, chart.value])

Attributes.

value: a Pandas dataframe of the plot data filtered by the selections
dataframe: a Pandas dataframe of the unfiltered chart data
selections: the selection of the chart; this may be an interval along the name of an axis or a selection of points

Initialization Args.

chart: An altair.Chart
chart_selection: optional selection type, "point", "interval", or a bool; defaults to True which will automatically detect the best selection type
legend_selection: optional list of legend fields (columns) for which to enable selection, True to enable selection for all fields, or False to disable selection entirely
label: optional text label for the element
on_change: optional callback to run when this element’s value changes

Performance and Data Transformers¶

Altair has a concept of data transformers, which can be used to improve performance.

Such examples are:

pandas Dataframe has to be sanitized and serialized to JSON.
The rows of a Dataframe might need to be sampled or limited to a maximum number.
The Dataframe might be written to a .csv or .json file for performance reasons.

By default, Altair uses the default data transformer, which is the slowest in marimo. It is limited to 5000 rows (although we increase this to 20_000 rows as marimo can handle this). This includes the data inside the HTML that is being sent over the network, which can also be limited by marimo’s maximum message size.

It is recommended to use the marimo_csv data transformer, which is the most performant and can handle the largest datasets: it converts the data to a CSV file which is smaller and can be sent over the network. This can handle up to +400,000 rows with no issues.

When using mo.ui.altair_chart, we automatically set the data transformer to marimo_csv for you. If you are using Altair directly, you can set the data transformer using the following code:

import altair as alt
alt.data_transformers.enable('marimo_csv')

Reactive plots with Plotly¶

marimo.ui.plotly(figure: go.Figure, config: Dict[str, Any] | None = None, renderer_name: str | None = None, *, label: str = '', on_change: Callable[[JSONType], None] | None = None) → None¶

Make reactive plots with Plotly.

Use mo.ui.plotly to make plotly plots reactive: select data with your cursor on the frontend, get them as a list of dicts in Python!

Example.

import plotly.express as px
import marimo as mo
from vega_datasets import data

_plot = px.scatter(
    data.cars(), x="Horsepower", y="Miles_per_Gallon", color="Origin"
)

plot = mo.ui.plotly(_plot)

# View the plot and selected data
mo.hstack([plot, plot.value])

Or with custom configuration:

plot = mo.ui.plotly(
    _plot,
    config={"staticPlot": True},
)

Attributes.

value: a dict of the plot data
ranges: the selection of the plot; this may be an interval along the name of an axis

Initialization Args.

figure: A plotly.graph_objects.Figure
config: optional configuration for the plot This is a dictionary that is passed directly to the plotly. See the plotly documentation for more information: https://plotly.com/javascript/configuration-options/ This takes precedence over the default configuration of the renderer.
renderer_name: optional renderer to use for the plot. If this is not provided, the default renderer (pio.renderers.default) is used.
label: optional text label for the element
on_change: optional callback to run when this element’s value changes

Interactive matplotlib¶

marimo.mpl.interactive(figure: Figure | Axes) → Html¶

Render a matplotlib figure using an interactive viewer.

The interactive viewer allows you to pan, zoom, and see plot coordinates on mouse hover.

Example:

plt.plot([1, 2])
# plt.gcf() gets the current figure
mo.mpl.interactive(plt.gcf())

Args:

figure: a matplotlib Figure or Axes object

Returns:

An interactive matplotlib figure as an Html object

Other plotting libraries¶

You can use all the popular plotting libraries with marimo. Such as: