From 958d1ef0280a8c65f7ca3e31d7df9b5c1e8b7699 Mon Sep 17 00:00:00 2001 From: Marco Edward Gorelli Date: Sat, 7 Dec 2024 17:57:32 +0000 Subject: [PATCH] docs: Expand plotting docs (#19719) --- .../python/user-guide/misc/visualization.py | 50 ++++++++++++++++--- docs/source/user-guide/misc/visualization.md | 8 +++ py-polars/polars/dataframe/frame.py | 21 ++++++++ py-polars/polars/series/series.py | 8 +++ 4 files changed, 79 insertions(+), 8 deletions(-) diff --git a/docs/source/src/python/user-guide/misc/visualization.py b/docs/source/src/python/user-guide/misc/visualization.py index b82a1cc78367..5be33b6b4823 100644 --- a/docs/source/src/python/user-guide/misc/visualization.py +++ b/docs/source/src/python/user-guide/misc/visualization.py @@ -15,6 +15,9 @@ y="sepal_length", by="species", width=650, + title="Irises", + xlabel='Sepal Width', + ylabel='Sepal Length', ) # --8<-- [end:hvplot_show_plot] """ @@ -27,6 +30,9 @@ y="sepal_length", by="species", width=650, + title="Irises", + xlabel="Sepal Width", + ylabel="Sepal Length", ) hvplot.save(plot, "docs/assets/images/hvplot_scatter.html", resources="cdn") with open("docs/assets/images/hvplot_scatter.html", "r") as f: @@ -44,6 +50,9 @@ y=df["sepal_length"], c=df["species"].cast(pl.Categorical).to_physical(), ) +ax.set_title('Irises') +ax.set_xlabel('Sepal Width') +ax.set_ylabel('Sepal Length') # --8<-- [end:matplotlib_show_plot] """ @@ -58,6 +67,9 @@ y=df["sepal_length"], c=df["species"].cast(pl.Categorical).to_physical(), ) +ax.set_title("Irises") +ax.set_xlabel("Sepal Width") +ax.set_ylabel("Sepal Length") fig.savefig("docs/assets/images/matplotlib_scatter.png") with open("docs/assets/images/matplotlib_scatter.png", "rb") as f: png = base64.b64encode(f.read()).decode() @@ -67,12 +79,19 @@ """ # --8<-- [start:seaborn_show_plot] import seaborn as sns +import matplotlib.pyplot as plt + +fig, ax = plt.subplots() sns.scatterplot( df, x="sepal_width", y="sepal_length", hue="species", + ax=ax, ) +ax.set_title('Irises') +ax.set_xlabel('Sepal Width') +ax.set_ylabel('Sepal Length') # --8<-- [end:seaborn_show_plot] """ @@ -81,12 +100,16 @@ import matplotlib.pyplot as plt fig, ax = plt.subplots() -ax = sns.scatterplot( +sns.scatterplot( df, x="sepal_width", y="sepal_length", hue="species", + ax=ax, ) +ax.set_title("Irises") +ax.set_xlabel("Sepal Width") +ax.set_ylabel("Sepal Length") fig.savefig("docs/assets/images/seaborn_scatter.png") with open("docs/assets/images/seaborn_scatter.png", "rb") as f: png = base64.b64encode(f.read()).decode() @@ -103,6 +126,8 @@ y="sepal_length", color="species", width=650, + title="Irises", + labels={'sepal_width': 'Sepal Width', 'sepal_length': 'Sepal Length'} ) # --8<-- [end:plotly_show_plot] """ @@ -116,6 +141,8 @@ y="sepal_length", color="species", width=650, + title="Irises", + labels={"sepal_width": "Sepal Width", "sepal_length": "Sepal Length"}, ) fig.write_html( "docs/assets/images/plotly_scatter.html", full_html=False, include_plotlyjs="cdn" @@ -127,28 +154,35 @@ """ # --8<-- [start:altair_show_plot] -( +chart = ( df.plot.point( - x="sepal_length", - y="sepal_width", + x="sepal_width", + y="sepal_length", color="species", ) - .properties(width=500) + .properties(width=500, title="Irises") .configure_scale(zero=False) + .configure_axisX(tickMinStep=1) ) +chart.encoding.x.title = "Sepal Width" +chart.encoding.y.title = "Sepal Length" +chart # --8<-- [end:altair_show_plot] """ # --8<-- [start:altair_make_plot] chart = ( df.plot.point( - x="sepal_length", - y="sepal_width", + x="sepal_width", + y="sepal_length", color="species", ) - .properties(width=500) + .properties(width=500, title="Irises") .configure_scale(zero=False) + .configure_axisX(tickMinStep=1) ) +chart.encoding.x.title = "Sepal Width" +chart.encoding.y.title = "Sepal Length" chart.save("docs/assets/images/altair_scatter.html") with open("docs/assets/images/altair_scatter.html", "r") as f: chart_html = f.read() diff --git a/docs/source/user-guide/misc/visualization.md b/docs/source/user-guide/misc/visualization.md index 28cbb4ee668e..b092df886d57 100644 --- a/docs/source/user-guide/misc/visualization.md +++ b/docs/source/user-guide/misc/visualization.md @@ -39,6 +39,14 @@ import altair as alt and is only provided for convenience, and to signal that Altair is known to work well with Polars. +For configuration, we suggest reading +[Chart Configuration](https://altair-viz.github.io/altair-tutorial/notebooks/08-Configuration.html). +For example, you can: + +- Change the width/height/title with `.properties(width=500, height=350, title="My amazing plot")`. +- Change the x-axis label rotation with `.configure_axisX(labelAngle=30)`. +- Change the opacity of the points in your scatter plot with `.configure_point(opacity=.5)`. + ## hvPlot If you import `hvplot.polars`, then it registers a `hvplot` method which you can use to create diff --git a/py-polars/polars/dataframe/frame.py b/py-polars/polars/dataframe/frame.py index 5a659c295789..d44201de7b35 100644 --- a/py-polars/polars/dataframe/frame.py +++ b/py-polars/polars/dataframe/frame.py @@ -642,6 +642,16 @@ def plot(self) -> DataFramePlot: is shorthand for `alt.Chart(df).mark_attr(tooltip=True).encode(**kwargs).interactive()` + For configuration, we suggest reading + `Chart Configuration `_. + For example, you can: + + - Change the width/height/title with + ``.properties(width=500, height=350, title="My amazing plot")``. + - Change the x-axis label rotation with ``.configure_axisX(labelAngle=30)``. + - Change the opacity of the points in your scatter plot with + ``.configure_point(opacity=.5)``. + Examples -------- Scatter plot: @@ -655,6 +665,13 @@ def plot(self) -> DataFramePlot: ... ) >>> df.plot.point(x="length", y="width", color="species") # doctest: +SKIP + Set the x-axis title by using ``altair.X``: + + >>> import altair as alt + >>> df.plot.point( + ... x=alt.X("length", title="Length"), y="width", color="species" + ... ) # doctest: +SKIP + Line plot: >>> from datetime import date @@ -679,6 +696,10 @@ def plot(self) -> DataFramePlot: >>> df.plot.bar( ... x="day", y="value", color="day", column="group" ... ) # doctest: +SKIP + + Or, to make a stacked version of the plot above: + + >>> df.plot.bar(x="day", y="value", color="group") # doctest: +SKIP """ if not _ALTAIR_AVAILABLE or parse_version(altair.__version__) < (5, 4, 0): msg = "altair>=5.4.0 is required for `.plot`" diff --git a/py-polars/polars/series/series.py b/py-polars/polars/series/series.py index d3d53b3c7fa8..787af72a92bc 100644 --- a/py-polars/polars/series/series.py +++ b/py-polars/polars/series/series.py @@ -7507,6 +7507,14 @@ def plot(self) -> SeriesPlot: is shorthand for `alt.Chart(s.to_frame().with_row_index()).mark_attr(tooltip=True).encode(x='index', y=s.name, **kwargs).interactive()` + For configuration, we suggest reading + `Chart Configuration `_. + For example, you can: + + - Change the width/height/title with ``.properties(width=500, height=350, title="My amazing plot")``. + - Change the x-axis label rotation with ``.configure_axisX(labelAngle=30)``. + - Change the opacity of the points in your scatter plot with ``.configure_point(opacity=.5)``. + Examples -------- Histogram: