docs: Add unsafe_update_figure doc

plugins/plotly-express/docs/sidebar.json

@@ -133,6 +133,10 @@
           {
             "label": "Multiple axes",
             "path": "multiple-axes.md"
+          },
+          {
+            "label": "`unsafe_update_figure` Chart Customization",
+            "path": "unsafe_update_figure.md"
           }
         ]
       }

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

@@ -0,0 +1,107 @@
+# `unsafe_update_figure` Chart Customization
+
+To customize a chart in a way that is not directly supported by Deephaven Plotly Express (`dx`), use the `unsafe_update_figure` parameter.  
+A Plotly [`Figure`](https://plotly.com/python/figure-structure/) object backs every `dx` chart, and `unsafe_update_figure` allows you to directly modify this object.  
+
+> [!WARNING]
+> Update figure is marked "unsafe" because some modifications can entirely break your figure, and care must be taken.  
+> `dx` maps `Table` columns to an index of a trace within `Figure.data` which will break if the trace order changes. Do not remove traces. Add new traces at the end of the list.
+
+`unsafe_update_figure` accepts a function that takes a Plotly `Figure` object as input and optionally returns a modified `Figure` object. If a `Figure` is not returned, it is assumed that the input `Figure` has been modified in place.
+
+## Examples
+
+### Bar Line
+
+Add a line to bars in a bar plot with `update_traces`.
+
+```python
+import deephaven.plot.express as dx
+
+tips = dx.data.tips()
+
+
+def update(figure):
+    # Add a gray line to the bars
+    figure.update_traces(marker_line_width=3, marker_line_color="gray")
+
+
+bar_lined_plot = dx.bar(tips, x="Day", unsafe_update_figure=update)
+```
+
+### 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`.
+
+```python
+import deephaven.plot.express as dx
+
+tips = dx.data.tips()
+
+
+def update(figure):
+    # Add a dashed orange vertical line at x=20
+    figure.add_vline(x=20, line_width=3, line_dash="dash", line_color="orange")
+
+
+scatter_vline_plot = dx.scatter(
+    tips, x="TotalBill", y="Tip", unsafe_update_figure=update
+)
+```
+
+### Between Line Fill
+
+Fill the area between lines in a line plot with `fill="tonexty"`.
+
+```python
+import deephaven.plot.express as dx
+
+my_table = dx.data.stocks()
+
+# subset data for just DOG transactions and add upper and lower bounds
+dog_prices = my_table.where("Sym = `DOG`").update_view(
+    ["UpperPrice = Price + 5", "LowerPrice = Price - 5"]
+)
+
+
+def update(figure):
+    # tonexty fills the area between the trace and the previous trace in the list
+    figure.update_traces(
+        fill="tonexty", fillcolor="rgba(123,67,0,0.3)", selector={"name": "LowerPrice"}
+    )
+    figure.update_traces(
+        fill="tonexty", fillcolor="rgba(123,67,0,0.3)", selector={"name": "Price"}
+    )
+
+
+# Order matters for y since the fill is between the trace and the previous trace in the list
+filled_line_plot = dx.line(
+    dog_prices,
+    x="Timestamp",
+    y=["UpperPrice", "Price", "LowerPrice"],
+    unsafe_update_figure=update,
+)
+```