diff --git a/plugins/plotly-express/docs/README.md b/plugins/plotly-express/docs/README.md index 8bc9aa95d..7155d1c8b 100644 --- a/plugins/plotly-express/docs/README.md +++ b/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) - - +[![Titles and legends - Provides titles and labels for the plot elements](_assets/plot_icons/titles_legends.svg)](titles-legends.md) diff --git a/plugins/plotly-express/docs/sidebar.json b/plugins/plotly-express/docs/sidebar.json index 73a085120..7e14c42a7 100644 --- a/plugins/plotly-express/docs/sidebar.json +++ b/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" diff --git a/plugins/plotly-express/docs/titles-legends.md b/plugins/plotly-express/docs/titles-legends.md new file mode 100644 index 000000000..d6063ea75 --- /dev/null +++ b/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 +) +``` + diff --git a/plugins/plotly-express/docs/unsafe-update-figure.md b/plugins/plotly-express/docs/unsafe-update-figure.md index 8ed953386..acd6b72c8 100644 --- a/plugins/plotly-express/docs/unsafe-update-figure.md +++ b/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`.