Plotting

Pyreball currently supports plotting figures created by Matplotlib, Seaborn, Vega-Altair, Plotly, and Bokeh.

There is a single function print_figure() for all these libraries. Similarly to print_table(), it uses parameters caption, align, caption_position and numbered with the same meaning. In contrast to table captions, the default position of figure captions is bottom.

Matplotlib

When plotting with Matplotlib, it is necessary to create a figure object and pass it to print_figure().

In case of Matplotlib, a user can select the format of the figure via matplotlib_format parameter: either "png" or "svg". In case of "svg", it is also possible to choose whether the figure should be embedded into the HTML file or saved into a separate file and referenced in the HTML file by setting embedded accordingly. Figures in "png" format cannot be embedded into the HTML file.

When the figure is stored into a file, the file is saved in a directory with name equal to the filename stem of the HTML file. For example, for HTML file report.html, the image file will be stored in directory report.

The following code shows an example of a bar chart created with Matplotlib and stored in a "png" format.

import matplotlib.pyplot as plt

import pyreball as pb

fig, ax = plt.subplots()
plt.bar([1, 2, 3], [4, 3, 6])
plt.xlabel("x")
plt.ylabel("y")
pb.print_figure(
    fig,
    caption="Matplotlib barchart as png.",
    matplotlib_format="png",
    embedded=False,
)

The next example shows the same chart, but embedded directly into the HTML document in "svg" format.

import matplotlib.pyplot as plt

import pyreball as pb

fig, ax = plt.subplots()
plt.bar([1, 2, 3], [4, 3, 6])
plt.xlabel("x")
plt.ylabel("y")
pb.print_figure(
    fig,
    caption="Matplotlib barchart as svg.",
    matplotlib_format="svg",
    embedded=True,
)

Seaborn

Seaborn is based on Matplotlib and therefore the code is very similar. Seaborn functions are either axes-level or figure-level, see documentation. For axes-level functions, one can create a Figure and Axes objects as with Matplotlib:

import matplotlib.pyplot as plt
import pandas as pd
import seaborn as sns

import pyreball as pb

df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 3, 6]})

fig, ax = plt.subplots()
sns.barplot(x="x", y="y", data=df, ax=ax, color=sns.xkcd_rgb["windows blue"])
ax.set(xlabel="x", ylabel="y")
pb.print_figure(
    fig,
    caption="Seaborn barchart as png.",
    matplotlib_format="png",
    embedded=False,
)

On the other hand, figure-level functions (e.g., lmplot) don't use ax parameter and return an object of type PairGrid, FacetGrid, JointGrid, or ClusterGrid. In such a case, the object can be also passed to print_figure(). Here are a few examples borrowed from Seaborn's documentation:

import seaborn as sns

import pyreball as pb

tips = sns.load_dataset("tips")
anscombe = sns.load_dataset("anscombe")
penguins = sns.load_dataset("penguins")

fig_facet_grid_lmplot = sns.lmplot(data=penguins, x="bill_length_mm", y="bill_depth_mm")
pb.print_figure(
    fig_facet_grid_lmplot,
    caption="Seaborn FacetGrid from lmplot.",
    matplotlib_format="png",
    embedded=False,
)

fig_facet_grid = sns.FacetGrid(tips, col="time", row="sex")
fig_facet_grid.map(sns.scatterplot, "total_bill", "tip")
pb.print_figure(
    fig_facet_grid,
    caption="Seaborn FacetGrid.",
    matplotlib_format="png",
    embedded=False,
)

fig_pair_grid = sns.PairGrid(penguins)
fig_pair_grid.map(sns.scatterplot)
pb.print_figure(
    fig_pair_grid,
    caption="Seaborn PairGrid.",
    matplotlib_format="png",
    embedded=False,
)

fig_joint_grid = sns.JointGrid(data=penguins, x="bill_length_mm", y="bill_depth_mm")
fig_joint_grid.plot_joint(sns.scatterplot, s=100, alpha=0.5)
fig_joint_grid.plot_marginals(sns.histplot, kde=True)
pb.print_figure(
    fig_joint_grid,
    caption="Seaborn JointGrid.",
    matplotlib_format="png",
    embedded=False,
)

As can be seen from examples above, it is also possible to use parameters matplotlib_format and embedded with Seaborn plots.

Vega-Altair

For Vega-Altair charts, Pyreball does not offer any special parameters like for Matplotlib and Seaborn charts. The charts are always embedded into the HTML and kept interactive.

import altair as alt
import pandas as pd

import pyreball as pb

df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 3, 6]})

fig = (
    alt.Chart(df)
    .mark_bar()
    .encode(
        x=alt.X(
            "x",
            type="nominal",
            sort=None,
            title="x",
            axis=alt.Axis(labelAngle=0),
        ),
        y=alt.Y("y", type="quantitative", title="y"),
        tooltip=["x", "y"],
    )
    .properties(
        width=540,
        height=400,
    )
)
pb.print_figure(fig, caption="Vega-Altair barchart.")

The previous example used altair.Chart object, but other types of charts are also supported, e.g. altair.ConcatChart, altair.HConcatChart.

Plotly

Pyreball supports interactive charts created by Plotly, too.

import pandas as pd
import plotly.express as px

import pyreball as pb

df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 3, 6]})

fig = px.bar(df, x="x", y="y")
pb.print_figure(fig, caption="Plotly chart.")

Bokeh

Another library for plotting interactive charts supported by Pyreball is Bokeh.

import pandas as pd
from bokeh.models import ColumnDataSource, HoverTool
from bokeh.plotting import figure

import pyreball as pb

df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 3, 6]})
df["x"] = df["x"].astype(str)
fig = figure(x_range=df["x"])
fig.vbar(x="x", top="y", width=0.9, source=ColumnDataSource(data=df))
fig.add_tools(HoverTool(tooltips=[("x", "@x"), ("y", "@y")]))
pb.print_figure(fig, caption="Bokeh barchart.")