titles

Author: nicolaskruchten

Diff for: doc/python/axes.md

@@ -81,14 +81,105 @@ fig.show()
 
 The different groups of Cartesian axes properties are
 
+- title of the axis
 - tick values (locations of tick marks) and tick labels. Tick labels and grid lines are placed at tick values.
 - lines: grid lines (passing through tick values), axis lines, zero lines
-- title of the axis
 - range of the axis
 - domain of the axis
 
 The examples on this page apply to axes of any type, but extra attributes are available for [axes of type `category`](/pythone/categorical-axes/) and [axes of type `date`](/python/time-series/).
 
+
+#### Set and Style Axes Title Labels
+
+##### Set axis title text with Plotly Express
+
+Axis titles are automatically set to the column names when [using Plotly Express with a data frame as input](/python/px-arguments/).
+
+```python
+import plotly.express as px
+df = px.data.tips()
+fig = px.scatter(df, x="total_bill", y="tip", color="sex")
+fig.show()
+```
+
+Axis titles (and [legend titles](/python/legend/)) can also be overridden using the `labels` argument of Plotly Express functions:
+
+```python
+import plotly.express as px
+df = px.data.tips()
+fig = px.scatter(df, x="total_bill", y="tip", color="sex",
+    labels=dict(total_bill="Total Bill ($)", tip="Tip ($)", sex="Payer Gender")
+)
+fig.show()
+```
+
+The PX `labels` argument can also be used without a data frame argument:
+
+
+```python
+import plotly.express as px
+fig = px.bar(df, x=["Apples", "Oranges"], y=[10,20], color=["Here", "There"],
+    labels=dict(x="Fruit", y="Amount", color="Place")
+)
+fig.show()
+```
+
+##### Set axis title text with Graph Objects
+
+Axis titles are set using the nested `title.text` property of the x or y axis. Here is an example of creating a new figure and using `update_xaxes` and `update_yaxes`, with magic underscore notation, to set the axis titles.
+
+```python
+import plotly.express as px
+
+fig = px.line(y=[1, 0])
+
+fig.update_xaxes(title_text='Time')
+fig.update_yaxes(title_text='Value A')
+
+fig.show()
+```
+
+### Set axis title position
+
+This example sets `standoff` attribute to cartesian axes to determine the distance between the tick labels and the axis title. Note that the axis title position is always constrained within the margins, so the actual standoff distance is always less than the set or default value. By default [automargin](https://plotly.com/python/setting-graph-size/#automatically-adjust-margins) is `True` in Plotly template for the cartesian axis, so the margins will be pushed to fit the axis title at given standoff distance.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(go.Scatter(
+    mode = "lines+markers",
+    y = [4, 1, 3],
+    x = ["December", "January", "February"]))
+
+fig.update_xaxes(
+        tickangle = 90,
+        title_text = "Month",
+        title_font = {"size": 20},
+        title_standoff = 25)
+
+fig.update_yaxes(
+        title_text = "Temperature",
+        title_standoff = 25)
+
+fig.show()
+```
+
+##### Set axis title font
+
+Here is an example that configures the font family, size, and color for the axis titles in a figure created using Plotly Express.
+
+```python
+import plotly.express as px
+df = px.data.iris()
+
+fig = px.scatter(df, x="sepal_width", y="sepal_length", facet_col="species")
+fig.update_xaxes(title_font=dict(size=18, family='Courier', color='crimson'))
+fig.update_yaxes(title_font=dict(size=18, family='Courier', color='crimson'))
+
+fig.show()
+```
+
 #### Tick Placement, Color, and Style
 
 ##### Toggling axis tick marks
@@ -262,7 +353,8 @@ Here is an example of setting `showgrid` to `False` in the graph object figure c
 import plotly.express as px
 
 fig = px.line(y=[1, 0])
-fig.update_layout(xaxis_showgrid=False, yaxis_showgrid=False)
+fig.update_xaxes(showgrid=False)
+fig.update_yaxes(showgrid=False)
 fig.show()
 ```
 
@@ -275,43 +367,8 @@ import plotly.express as px
 
 fig = px.line(y=[1, 0])
 
-fig.update_layout(
-    xaxis=dict(showgrid=False, zeroline=False),
-    yaxis=dict(showgrid=False, zeroline=False),
-)
-fig.show()
-```
-
-##### Toggle grid and zerolines with update axis methods
-
-Axis properties can be also updated for figures after they are constructed using the `update_xaxes` and `update_yaxes` graph object figure methods.
-
-Here is an example that disables the x and y axis grid and zero lines using `update_xaxes` and `update_yaxes`.
-
-```python
-import plotly.express as px
-
-fig = px.line(y=[1, 0])
-fig.update_xaxes(showgrid=False, zeroline=False)
-fig.update_yaxes(showgrid=False, zeroline=False)
-
-fig.show()
-```
-
-##### Toggle grid and zerolines for figure created with Plotly Express
-
-An advantage of using the `update_xaxis` and `update_yaxis` methods is that these updates will (by default) apply to all axes in the figure. This is especially useful when customizing figures created using Plotly Express, figure factories, or `make_subplots`.
-
-Here is an example of disabling all grid and zero lines in a faceted figure created by Plotly Express.
-
-```python
-import plotly.express as px
-df = px.data.iris()
-
-fig = px.scatter(df, x="sepal_width", y="sepal_length", facet_col="species")
 fig.update_xaxes(showgrid=False, zeroline=False)
 fig.update_yaxes(showgrid=False, zeroline=False)
-
 fig.show()
 ```
 
@@ -385,63 +442,6 @@ fig.update_yaxes(zeroline=True, zerolinewidth=2, zerolinecolor='LightPink')
 fig.show()
 ```
 
-#### Set and Style Axes Title Labels
-
-##### Set axis title text
-
-Axis titles are set using the nested `title.text` property of the x or y axis. Here is an example of creating a new figure and using `update_xaxes` and `update_yaxes`, with magic underscore notation, to set the axis titles.
-
-```python
-import plotly.express as px
-
-fig = px.line(y=[1, 0])
-
-fig.update_xaxes(title_text='Time')
-fig.update_yaxes(title_text='Value A')
-
-fig.show()
-```
-
-### Set axis title position
-
-This example sets `standoff` attribute to cartesian axes to determine the distance between the tick labels and the axis title. Note that the axis title position is always constrained within the margins, so the actual standoff distance is always less than the set or default value. By default [automargin](https://plotly.com/python/setting-graph-size/#automatically-adjust-margins) is `True` in Plotly template for the cartesian axis, so the margins will be pushed to fit the axis title at given standoff distance.
-
-```python
-import plotly.graph_objects as go
-
-fig = go.Figure(go.Scatter(
-    mode = "lines+markers",
-    y = [4, 1, 3],
-    x = ["December", "January", "February"]))
-
-fig.update_layout(
-    xaxis = dict(
-        tickangle = 90,
-        title_text = "Month",
-        title_font = {"size": 20},
-        title_standoff = 25),
-    yaxis = dict(
-        title_text = "Temperature",
-        title_standoff = 25))
-
-fig.show()
-```
-
-##### Set axis title font
-
-Here is an example that configures the font family, size, and color for the axis titles in a figure created using Plotly Express.
-
-```python
-import plotly.express as px
-df = px.data.iris()
-
-fig = px.scatter(df, x="sepal_width", y="sepal_length", facet_col="species")
-fig.update_xaxes(title_font=dict(size=18, family='Courier', color='crimson'))
-fig.update_yaxes(title_font=dict(size=18, family='Courier', color='crimson'))
-
-fig.show()
-```
-
 #### Setting the Range of Axes Manually
 
 The visible x and y axis range can be configured manually by setting the `range` axis property to a list of two values, the lower and upper boundary.
@@ -492,12 +492,12 @@ fig.add_trace(go.Scatter(
 fig.update_layout(
     width = 800,
     height = 500,
-    title = "fixed-ratio axes",
-    yaxis = dict(
-      scaleanchor = "x",
-      scaleratio = 1,
-    )
+    title = "fixed-ratio axes"
 )
+fig.update_yaxes(
+    scaleanchor = "x",
+    scaleratio = 1,
+  )
 
 fig.show()
 ```
@@ -516,15 +516,15 @@ fig.add_trace(go.Scatter(
 fig.update_layout(
     width = 800,
     height = 500,
-    title = "fixed-ratio axes with compressed axes",
-    xaxis = dict(
-      range=[-1,4],  # sets the range of xaxis
-      constrain="domain",  # meanwhile compresses the xaxis by decreasing its "domain"
-    ),
-    yaxis = dict(
-      scaleanchor = "x",
-      scaleratio = 1,
-    ),
+    title = "fixed-ratio axes with compressed axes"
+)
+fig.update_xaxes(
+    range=[-1,4],  # sets the range of xaxis
+    constrain="domain",  # meanwhile compresses the xaxis by decreasing its "domain"
+)
+fig.update_yaxes(
+    scaleanchor = "x",
+    scaleratio = 1
 )
 fig.show()
 ```
@@ -546,16 +546,17 @@ fig.add_trace(go.Scatter(
 fig.update_layout(
     width = 800,
     height = 500,
-    title = "fixed-ratio axes",
-    yaxis = dict(
-      scaleanchor = "x",
-      scaleratio = 1,
-    ),
-    xaxis = dict(
-        range=(-0.5, 3.5),
-        constrain='domain'
-    )
+    title = "fixed-ratio axes"
+)
+fig.update_xaxes(
+    scaleanchor = "x",
+    scaleratio = 1,
 )
+fig.update_yaxes(
+    range=(-0.5, 3.5),
+    constrain='domain'
+)
+
 
 fig.show()
 ```
@@ -577,15 +578,15 @@ fig.add_trace(go.Scatter(
 fig.update_layout(
     width = 800,
     height = 500,
-    title = "fixed-ratio axes with compressed axes",
-    xaxis = dict(
-      range=[-1,4],  # sets the range of xaxis
-      constrain="domain",  # meanwhile compresses the xaxis by decreasing its "domain"
-    ),
-    yaxis = dict(
-      scaleanchor = "x",
-      scaleratio = 1,
-    ),
+    title = "fixed-ratio axes with compressed axes"
+)
+fig.update_xaxes(
+    range=[-1,4],  # sets the range of xaxis
+    constrain="domain",  # meanwhile compresses the xaxis by decreasing its "domain"
+)
+fig.update_yaxes(
+    scaleanchor = "x",
+    scaleratio = 1,
 )
 
 fig.show()

Diff for: doc/python/facet-plots.md

@@ -107,7 +107,7 @@ fig.show()
 
 Since subplot figure titles are [annotations](https://plotly.com/python/text-and-annotations/#simple-annotation), you can use the `for_each_annotation` function to customize them, for example to remove the equal-sign (`=`).
 
-In the following example, we pass a lambda function to `for_each_annotation` in order to change the figure subplot titles from `smoker=No` and `smoker=Yes` to just `No` and `Yes`. 
+In the following example, we pass a lambda function to `for_each_annotation` in order to change the figure subplot titles from `smoker=No` and `smoker=Yes` to just `No` and `Yes`.
 
 ```python
 import plotly.express as px
@@ -117,9 +117,23 @@ fig.for_each_annotation(lambda a: a.update(text=a.text.split("=")[-1]))
 fig.show()
 ```
 
+### Controlling Facet Ordering
+
+By default, Plotly Express lays out categorical data in the order in which it appears in the underlying data. Every 2-d cartesian Plotly Express function also includes a `category_orders` keyword argument which can be used to control [the order in which categorical axes are drawn](/python/categorical-axes/), but beyond that can also control [the order in which discrete colors appear in the legend](/python/discrete-color/), and the order in which facets are laid out.
+
+```python
+import plotly.express as px
+df = px.data.tips()
+fig = px.bar(df, x="day", y="total_bill", color="smoker", barmode="group", facet_col="sex",
+             category_orders={"day": ["Thur", "Fri", "Sat", "Sun"],
+                              "smoker": ["Yes", "No"],
+                              "sex": ["Male", "Female"]})
+fig.show()
+```
+
 ### Controlling Facet Spacing
 
-The `facet_row_spacing` and `facet_col_spacing` arguments can be used to control the spacing between rows and columns. These values are specified in fractions of the plotting area in paper coordinates and not in pixels, so they will grow or shrink with the `width` and `height` of the figure. 
+The `facet_row_spacing` and `facet_col_spacing` arguments can be used to control the spacing between rows and columns. These values are specified in fractions of the plotting area in paper coordinates and not in pixels, so they will grow or shrink with the `width` and `height` of the figure.
 
 The defaults work well with 1-4 rows or columns at the default figure size with the default font size, but need to be reduced to around 0.01 for very large figures or figures with many rows or columns. Conversely, if activating tick labels on all facets, the spacing will need to be increased.
 
@@ -140,7 +154,7 @@ fig.show()
 
 ### Synchronizing axes in subplots with `matches`
 
-Using `facet_col` from `plotly.express` let [zoom](https://help.plotly.com/zoom-pan-hover-controls/#step-3-zoom-in-and-zoom-out-autoscale-the-plot) and [pan](https://help.plotly.com/zoom-pan-hover-controls/#step-6-pan-along-axes) each facet to the same range implicitly. However, if the subplots are created with `make_subplots`, the axis needs to be updated with `matches` parameter to update all the subplots accordingly. 
+Using `facet_col` from `plotly.express` let [zoom](https://help.plotly.com/zoom-pan-hover-controls/#step-3-zoom-in-and-zoom-out-autoscale-the-plot) and [pan](https://help.plotly.com/zoom-pan-hover-controls/#step-6-pan-along-axes) each facet to the same range implicitly. However, if the subplots are created with `make_subplots`, the axis needs to be updated with `matches` parameter to update all the subplots accordingly.
 
 Zoom in one trace below, to see the other subplots zoomed to the same x-axis range. To pan all the subplots, click and drag from the center of x-axis to the side: