docs: Expand plotting docs (#19719)

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()

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

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 <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)``.
+
         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`"

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 <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)``.
+
         Examples
         --------
         Histogram: