Skip to content

Commit 9df65df

Browse files
jnumainvilledsmmckenmargaretkennedy
authored
docs: DOC-574: Titles and Legends doc (#1174)
Adds docs for basic info on titles and legends --------- Co-authored-by: Don <dsmmcken@gmail.com> Co-authored-by: margaretkennedy <82049573+margaretkennedy@users.noreply.github.com>
1 parent e1a9971 commit 9df65df

4 files changed

Lines changed: 167 additions & 26 deletions

File tree

‎plugins/plotly-express/docs/README.md‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -91,9 +91,7 @@ This page contains a collection of links to examples demonstrating different plo
9191
[![Subplot - Combines multiple plots into a single layout](_assets/plot_icons/sub_plot.svg)](sub-plots.md)
9292
[![Layer plot - Overlays multiple plots on top of each other](_assets/plot_icons/layer_plots.svg)](layer-plots.md)
9393
[![Multiple axes plot - Uses multiple axes to represent different data dimensions](_assets/plot_icons/multiple_axes.svg)](multiple-axes.md)
94-
95-
<!-- TODO: DOC-574 https://deephaven.atlassian.net/browse/DOC-574 >
96-
<!-- [![Titles and legends - Provides titles and labels for the plot elements](_assets/plot_icons/titles_legends.svg)](other.md) -->
94+
[![Titles and legends - Provides titles and labels for the plot elements](_assets/plot_icons/titles_legends.svg)](titles-legends.md)
9795

9896
</CardList>
9997

‎plugins/plotly-express/docs/sidebar.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,10 @@
135135
"label": "Multiple axes",
136136
"path": "multiple-axes.md"
137137
},
138+
{
139+
"label": "Titles and Legends",
140+
"path": "titles-legends.md"
141+
},
138142
{
139143
"label": "Chart Customization",
140144
"path": "unsafe-update-figure.md"

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

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Titles and Legends
2+
3+
Deephaven Plotly Express provides ways to customize titles and legends with intuitive default behavior.
4+
5+
## Default Title
6+
7+
The names of the x and y axes are set to the column names when passing single column names in.
8+
9+
```python order=line_plot,my_table
10+
import deephaven.plot.express as dx
11+
my_table = dx.data.stocks()
12+
13+
# subset data for just DOG transactions
14+
dog_prices = my_table.where("Sym = `DOG`")
15+
16+
# x and y axis titles are set to the column names, Timestamp and Price
17+
line_plot = dx.line(dog_prices, x="Timestamp", y="Price")
18+
```
19+
20+
## Plot by Titles and Legend
21+
22+
When using the `by` argument, the legend is automatically generated.
23+
An entry is created for each unique value in the `by` column.
24+
25+
```python order=line_plot,mytable
26+
import deephaven.plot.express as dx
27+
my_table = dx.data.stocks()
28+
29+
# A legend entry is created for each unique value in the Sym column
30+
line_plot = dx.line(my_table, x="Timestamp", y="Price", by="Sym")
31+
```
32+
33+
## Titles and Legend for Multiple Columns
34+
35+
When passing in a list of columns, the axis title for the corresponding axis is set to a new name, `value`.
36+
As with the `by` argument, the legend is automatically generated.
37+
38+
```python order=line_plot,mytable
39+
import deephaven.plot.express as dx
40+
my_table = dx.data.stocks()
41+
42+
# subset data for just DOG transactions
43+
dog_prices = my_table.where("Sym = `DOG`")
44+
45+
# A legend entry is created for each unique column name in the y list and the y axis title is set to "value"
46+
line_plot = dx.line(dog_prices, x="Timestamp", y=["Price", "SPet500"])
47+
```
48+
49+
## Title Customization
50+
51+
### Custom Title
52+
53+
Add a title to the plot with the `title` argument.
54+
55+
```python order=line_plot,mytable
56+
import deephaven.plot.express as dx
57+
my_table = dx.data.stocks()
58+
59+
# subset data for just DOG transactions
60+
dog_prices = my_table.where("Sym = `DOG`")
61+
62+
# The plot title is set to "Price of DOG"
63+
line_plot = dx.line(dog_prices, x="Timestamp", y="Price", title="Price of DOG")
64+
```
65+
66+
### Custom Axis Titles
67+
68+
Customize the titles of the x and y axes with the `xaxis_titles` and `yaxis_titles` arguments.
69+
70+
```python order=line_plot,mytable
71+
import deephaven.plot.express as dx
72+
my_table = dx.data.stocks()
73+
74+
# subset data for just DOG transactions
75+
dog_prices = my_table.where("Sym = `DOG`")
76+
77+
# customize the x and y axis titles with xaxis_titles and yaxis_titles
78+
line_plot = dx.line(dog_prices, x="Timestamp", y="Price", xaxis_titles="Timestamp of Transaction", yaxis_titles="Price of DOG")
79+
```
80+
81+
## Legend Customization
82+
83+
Legends are customizable with [unsafe_update_figure](unsafe-update-figure.md). Generally, legend customization is safe.
84+
85+
### Legend Position
86+
87+
By default, the legend is placed in the top right corner of the plot.
88+
Move the legend around the plot with `x`, `y`, `xanchor`, and `yanchor` arguments to the `update_layout` method.
89+
`xanchor` and `yanchor` set the anchor point of the legend, which determine which part of the legend box is used to position the legend.
90+
`x` and `y` set the position of the anchor point relative to the plot area.
91+
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.
92+
Negative values or values above 1 for `x` and `y` move the anchor point outside the plot area.
93+
`xanchor` can be set to `"auto"`, `"left"`, `"center"`, or `"right"` and `yanchor` can be set to `"auto"`, `"top"`, `"middle"`, or `"bottom"`.
94+
95+
### Legend Overlay
96+
97+
Overlay the legend by positioning the top left corner of the legend just inside the plot area.
98+
99+
```py order=legend_overlay_plot,tips
100+
import deephaven.plot.express as dx
101+
102+
tips = dx.data.tips()
103+
104+
def update(figure):
105+
# Update the layout to move the legend to the top left
106+
# x and y are set to move the top left corner of the legend just inside the plot area
107+
figure.update_layout(
108+
legend=dict(yanchor="top", y=0.99, xanchor="left", x=0.01)
109+
)
110+
111+
legend_overlay_plot = dx.scatter(
112+
tips, x="TotalBill", y="Tip", color="Day", unsafe_update_figure=update
113+
)
114+
```
115+
116+
### Horizontal Legend
117+
118+
Customize the legend to be horizontal by updating the layout with `orientation="h"`.
119+
Move the legend just outside the bottom of the plot area by setting `y` to a negative value.
120+
121+
```python order=legend_horizontal_plot,tips
122+
import deephaven.plot.express as dx
123+
124+
tips = dx.data.tips()
125+
126+
def update(figure):
127+
# Update the layout to move the legend to the bottom
128+
# y is negative to move the legend outside the bottom of the plot area
129+
# xanchor and x are set to center the legend
130+
figure.update_layout(
131+
legend=dict(
132+
orientation="h",
133+
yanchor="bottom",
134+
y=-0.3,
135+
xanchor="center",
136+
x=0.5)
137+
)
138+
139+
legend_horizontal_plot = dx.scatter(
140+
tips, x="TotalBill", y="Tip", color="Day", unsafe_update_figure=update
141+
)
142+
```
143+
144+
### Hide Legend
145+
146+
Hide the legend by updating the layout with `showlegend=False`.
147+
148+
```python order=legend_hidden_plot,tips
149+
import deephaven.plot.express as dx
150+
151+
tips = dx.data.tips()
152+
153+
def update(figure):
154+
figure.update_layout(
155+
showlegend=False
156+
)
157+
158+
legend_hidden_plot = dx.scatter(
159+
tips, x="TotalBill", y="Tip", color="Day", unsafe_update_figure=update
160+
)
161+
```
162+

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

Lines changed: 0 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -31,29 +31,6 @@ bar_lined_plot = dx.bar(tips, x="Day", unsafe_update_figure=update)
3131

3232
![Unsafe Update Figure Example](./_assets/unsafe_update_figure.png)
3333

34-
### Legend Location
35-
36-
Change the location of the legend to the bottom of the plot by updating the layout.
37-
38-
```python
39-
import deephaven.plot.express as dx
40-
41-
tips = dx.data.tips()
42-
43-
44-
def update(figure):
45-
# Update the layout to move the legend to the bottom
46-
# y is negative to move the legend outside the plot area
47-
figure.update_layout(
48-
legend=dict(orientation="h", yanchor="bottom", y=-0.3, xanchor="left", x=0.3)
49-
)
50-
51-
52-
legend_bottom_plot = dx.scatter(
53-
tips, x="TotalBill", y="Tip", color="Day", unsafe_update_figure=update
54-
)
55-
```
56-
5734
### Vertical Line
5835

5936
Add a vertical line to a plot with `add_vline`.

0 commit comments

Comments
 (0)