checkpoint

Author: nicolaskruchten

doc/python/figure-labels.md

@@ -5,8 +5,8 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.1'
-      jupytext_version: 1.2.1
+      format_version: '1.2'
+      jupytext_version: 1.4.2
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.3
+    version: 3.7.7
   plotly:
     description: How to set the global font, title, legend-entries, and axis-titles
       in python.
@@ -34,6 +34,62 @@ jupyter:
     thumbnail: thumbnail/figure-labels.png
 ---
 
+### Automatic Labelling with Plotly Express
+
+[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on a variety of types of data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/).
+
+When using Plotly Express, your axes and legend are automatically labelled, and it's easy to override the automation for a customized figure using the `labels` keyword argument. The title of your figure is up to you though!
+
+Here's a figure with automatic labels and then the same figure with overridden labels. Note the fact that when overriding labels, the axes, legend title *and hover labels* reflect the specified labels automatically.
+
+```python
+import plotly.express as px
+
+df = px.data.iris()
+fig = px.scatter(df, x="sepal_length", y="sepal_width", color="species",
+                title="Automatic Labels Based on Data Frame Column Names")
+fig.show()
+```
+
+```python
+import plotly.express as px
+
+df = px.data.iris()
+fig = px.scatter(df, x="sepal_length", y="sepal_width", color="species",
+                 labels={
+                     "sepal_length": "Sepal Length (cm)",
+                     "sepal_width": "Sepal Width (cm)",
+                     "species": "Species of Iris"
+                 },
+                title="Manually Specified Labels")
+fig.show()
+```
+
+### Global and Local Font Specification
+
+You can set the figure-wide font with the `layout.font` attribute, which will apply to all titles and tick labels, but this can be overridden for specific plot items like individual axes and legend titles etc. In the following figure, we set the figure-wide font to Courier New in blue, and then override this for certain parts of the figure.
+
+```python
+import plotly.express as px
+
+df = px.data.iris()
+fig = px.scatter(df, x="sepal_length", y="sepal_width", color="species",
+                title="Playing with Fonts")
+fig.update_layout(
+    font_family="Courier New",
+    font_color="blue",
+    title_font_family="Times New Roman",
+    title_font_color="red",
+    legend_title_font_color="green"
+)
+fig.update_xaxes(title_font_family="Arial")
+fig.show()
+```
+
+### Manual Labelling with Graph Objects
+
+When using (graph objects)[/python/graph-objects/] rather than [Plotly Express](/python/plotly-express/), you will need to explicitly label traces and axes:
+
 ```python
 import plotly.graph_objects as go
 
@@ -54,12 +110,13 @@ fig.add_trace(go.Scatter(
 
 fig.update_layout(
     title="Plot Title",
-    xaxis_title="x Axis Title",
-    yaxis_title="y Axis Title",
+    xaxis_title="X Axis Title",
+    yaxis_title="X Axis Title",
+    legend_title="Legend Title",
     font=dict(
         family="Courier New, monospace",
         size=18,
-        color="#7f7f7f"
+        color="RebeccaPurple"
     )
 )
 
@@ -90,4 +147,4 @@ fig.show()
 ```
 
 #### Reference
-See https://plotly.com/python/reference/#layout for more information!
+See https://plotly.com/python/reference/#layout for more information!

doc/python/legend.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.2'
-      jupytext_version: 1.3.0
+      jupytext_version: 1.4.2
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.3
+    version: 3.7.7
   plotly:
     description: How to configure and style the legend in Plotly with Python.
     display_as: file_settings
@@ -33,6 +33,18 @@ jupyter:
     thumbnail: thumbnail/legends.gif
 ---
 
+### Legends versus Color Bars
+
+Plotly figures can contain two different legend-like guides: legends and color bars. Legends are used to provide a key for discrete visual variables such as [discrete colors](/python/discrete-color/) or [symbols](/python/marker-style/), whereas [color bars are used to provide a key for continuous color, and are configured differently](/python/colorscales/).
+
+
+### Legends with Plotly Express
+
+[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on a variety of types of data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/).
+
+Plotly Express will automatically construct and label a legend for any figure that uses [discrete color](/python/discrete-color/) or marker [symbols](/python/marker-style/)
+
+
 #### Show Legend
 
 By default the legend is displayed on Plotly charts with multiple traces.
@@ -434,4 +446,4 @@ fig.show()
 
 #### Reference
 
-See https://plotly.com/python/reference/#layout-legend for more information!
+See https://plotly.com/python/reference/#layout-legend for more information!