docs: DOC-574: Titles and Legends doc

plugins/plotly-express/docs/README.md

@@ -91,9 +91,7 @@ This page contains a collection of links to examples demonstrating different plo
 [![Subplot - Combines multiple plots into a single layout](_assets/plot_icons/sub_plot.svg)](sub-plots.md)
 [![Layer plot - Overlays multiple plots on top of each other](_assets/plot_icons/layer_plots.svg)](layer-plots.md)
 [![Multiple axes plot - Uses multiple axes to represent different data dimensions](_assets/plot_icons/multiple_axes.svg)](multiple-axes.md)
-
-<!-- TODO: DOC-574 https://deephaven.atlassian.net/browse/DOC-574 >
-<!-- [![Titles and legends - Provides titles and labels for the plot elements](_assets/plot_icons/titles_legends.svg)](other.md) -->
+[![Titles and legends - Provides titles and labels for the plot elements](_assets/plot_icons/titles_legends.svg)](titles-legends.md)
 
 </CardList>
 

plugins/plotly-express/docs/sidebar.json

@@ -135,6 +135,10 @@
             "label": "Multiple axes",
             "path": "multiple-axes.md"
           },
+          {
+            "label": "Titles and Legends",
+            "path": "titles-legends.md"
+          },
           {
             "label": "Chart Customization",
             "path": "unsafe-update-figure.md"

plugins/plotly-express/docs/titles-legends.md

@@ -0,0 +1,162 @@
+# Titles and Legends
+
+Deephaven Plotly Express provides ways to customize titles and legends with intuitive default behavior.
+
+## Default Title
+
+The names of the x and y axes are set to the column names when passing single column names in.
+
+```python order=line_plot,my_table
+import deephaven.plot.express as dx
+my_table = dx.data.stocks()
+
+# subset data for just DOG transactions
+dog_prices = my_table.where("Sym = `DOG`")
+
+# x and y axis titles are set to the column names, Timestamp and Price
+line_plot = dx.line(dog_prices, x="Timestamp", y="Price")
+```
+
+## Plot by Titles and Legend
+
+When using the `by` argument, the legend is automatically generated. 
+An entry is created for each unique value in the `by` column. 
+
+```python order=line_plot,mytable
+import deephaven.plot.express as dx
+my_table = dx.data.stocks()
+
+# A legend entry is created for each unique value in the Sym column
+line_plot = dx.line(my_table, x="Timestamp", y="Price", by="Sym")
+```
+
+## Titles and Legend for Multiple Columns
+
+When passing in a list of columns, the axis title for the corresponding axis is set to a new name, `value`.
+As with the `by` argument, the legend is automatically generated.
+
+```python order=line_plot,mytable
+import deephaven.plot.express as dx
+my_table = dx.data.stocks()
+
+# subset data for just DOG transactions
+dog_prices = my_table.where("Sym = `DOG`")
+
+# A legend entry is created for each unique column name in the y list and the y axis title is set to "value"
+line_plot = dx.line(dog_prices, x="Timestamp", y=["Price", "SPet500"])
+```
+
+## Title Customization
+
+### Custom Title
+
+Add a title to the plot with the `title` argument. 
+
+```python order=line_plot,mytable
+import deephaven.plot.express as dx
+my_table = dx.data.stocks()
+
+# subset data for just DOG transactions
+dog_prices = my_table.where("Sym = `DOG`")
+
+# The plot title is set to "Price of DOG"
+line_plot = dx.line(dog_prices, x="Timestamp", y="Price", title="Price of DOG")
+```
+
+### Custom Axis Titles 
+
+Customize the titles of the x and y axes with the `xaxis_titles` and `yaxis_titles` arguments. 
+
+```python order=line_plot,mytable
+import deephaven.plot.express as dx
+my_table = dx.data.stocks()
+
+# subset data for just DOG transactions
+dog_prices = my_table.where("Sym = `DOG`")
+
+# customize the x and y axis titles with xaxis_titles and yaxis_titles
+line_plot = dx.line(dog_prices, x="Timestamp", y="Price", xaxis_titles="Timestamp of Transaction", yaxis_titles="Price of DOG")
+```
+
+## Legend Customization
+
+Legends are customizable with [unsafe_update_figure](unsafe-update-figure.md). Generally, legend customization is safe.
+
+### Legend Position
+
+By default, the legend is placed in the top right corner of the plot.
+Move the legend around the plot with `x`, `y`, `xanchor`, and `yanchor` arguments to the `update_layout` method.
+`xanchor` and `yanchor` set the anchor point of the legend, which determine which part of the legend box is used to position the legend.
+`x` and `y` set the position of the anchor point relative to the plot area.
+For `x` and `y`, 0 is the left or bottom of the plot area and 1 is the right or top of the plot area.
+Negative values or values above 1 for `x` and `y` move the anchor point outside the plot area.
+`xanchor` can be set to `"auto"`, `"left"`, `"center"`, or `"right"` and `yanchor` can be set to `"auto"`, `"top"`, `"middle"`, or `"bottom"`.
+
+### Legend Overlay
+
+Overlay the legend by positioning the top left corner of the legend just inside the plot area.
+
+```py order=legend_overlay_plot,tips
+import deephaven.plot.express as dx
+
+tips = dx.data.tips()
+
+def update(figure):
+    # Update the layout to move the legend to the top left
+    # x and y are set to move the top left corner of the legend just inside the plot area
+    figure.update_layout(
+        legend=dict(yanchor="top", y=0.99, xanchor="left", x=0.01)
+    )
+
+legend_overlay_plot = dx.scatter(
+    tips, x="TotalBill", y="Tip", color="Day", unsafe_update_figure=update
+)
+```
+
+### Horizontal Legend
+
+Customize the legend to be horizontal by updating the layout with `orientation="h"`.
+Move the legend just outside the bottom of the plot area by setting `y` to a negative value.
+
+```python order=legend_horizontal_plot,tips
+import deephaven.plot.express as dx
+
+tips = dx.data.tips()
+
+def update(figure):
+    # Update the layout to move the legend to the bottom
+    # y is negative to move the legend outside the bottom of the plot area
+    # xanchor and x are set to center the legend
+    figure.update_layout(
+        legend=dict(
+            orientation="h", 
+            yanchor="bottom", 
+            y=-0.3, 
+            xanchor="center", 
+            x=0.5)
+    )
+
+legend_horizontal_plot = dx.scatter(
+    tips, x="TotalBill", y="Tip", color="Day", unsafe_update_figure=update
+)
+```
+
+### Hide Legend
+
+Hide the legend by updating the layout with `showlegend=False`.
+
+```python order=legend_hidden_plot,tips
+import deephaven.plot.express as dx
+
+tips = dx.data.tips()
+
+def update(figure):
+    figure.update_layout(
+        showlegend=False
+    )
+
+legend_hidden_plot = dx.scatter(
+    tips, x="TotalBill", y="Tip", color="Day", unsafe_update_figure=update
+)
+```
+

plugins/plotly-express/docs/unsafe-update-figure.md

@@ -31,29 +31,6 @@ bar_lined_plot = dx.bar(tips, x="Day", unsafe_update_figure=update)
 
 ![Unsafe Update Figure Example](./_assets/unsafe_update_figure.png)
 
-### Legend Location
-
-Change the location of the legend to the bottom of the plot by updating the layout.
-
-```python
-import deephaven.plot.express as dx
-
-tips = dx.data.tips()
-
-
-def update(figure):
-    # Update the layout to move the legend to the bottom
-    # y is negative to move the legend outside the plot area
-    figure.update_layout(
-        legend=dict(orientation="h", yanchor="bottom", y=-0.3, xanchor="left", x=0.3)
-    )
-
-
-legend_bottom_plot = dx.scatter(
-    tips, x="TotalBill", y="Tip", color="Day", unsafe_update_figure=update
-)
-```
-
 ### Vertical Line
 
 Add a vertical line to a plot with `add_vline`.