docs: Expand plotting docs

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")
 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,15 +154,19 @@
 
 """
 # --8<-- [start:altair_show_plot]
-(
+chart =  (
     df.plot.point(
         x="sepal_length",
         y="sepal_width",
         color="species",
     )
-    .properties(width=500)
+    .properties(width=500, title="Irises")
     .configure_scale(zero=False)
+    .configure_axisX(tickMinStep=1)
 )
+chart.encoding.x.title = "Sepal Length"
+chart.encoding.y.title = "Sepal Width"
+chart
 # --8<-- [end:altair_show_plot]
 """
 
@@ -146,9 +177,12 @@
         y="sepal_width",
         color="species",
     )
-    .properties(width=500)
+    .properties(width=500, title="Irises")
     .configure_scale(zero=False)
+    .configure_axisX(tickMinStep=1)
 )
+chart.encoding.x.title = "Sepal Length"
+chart.encoding.y.title = "Sepal Width"
 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

@@ -21,24 +21,12 @@ Polars has a `plot` method to create plots using [Altair](https://altair-viz.git
 --8<-- "python/user-guide/misc/visualization.py:altair_make_plot"
 ```
 
-This is shorthand for:
-
-```python
-import altair as alt
-
-(
-    alt.Chart(df).mark_point(tooltip=True).encode(
-        x="sepal_length",
-        y="sepal_width",
-        color="species",
-    )
-    .properties(width=500)
-    .configure_scale(zero=False)
-)
-```
+For configuration, we suggest reading [Chart Configuration](https://altair-viz.github.io/altair-tutorial/notebooks/08-Configuration.html).
+For example, you can:
 
-and is only provided for convenience, and to signal that Altair is known to work well with
-Polars.
+- 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
 

py-polars/polars/dataframe/frame.py

@@ -640,6 +640,15 @@ def plot(self) -> DataFramePlot:
         - for any other attribute `attr`, `df.plot.attr(**kwargs)`
           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 (assuming you've done ``import altair as alt``):
+
+        - 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)``
+        - set the x-axis-title by passing ``x=alt.X('length', title='Length')`` instead of ``x='length'``
 
         Examples
         --------
@@ -678,6 +687,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

@@ -7497,6 +7497,13 @@ 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>`_.
+
+        - 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: