hover and date axis doc upgrades

Author: nicolaskruchten

doc/python/hover-text-and-formatting.md

@@ -5,8 +5,8 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: "1.2"
-      jupytext_version: 1.3.0
+      format_version: '1.2'
+      jupytext_version: 1.3.1
   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.6.8
   plotly:
     description: How to use hover text and formatting in Python with Plotly.
     display_as: file_settings
@@ -32,82 +32,100 @@ jupyter:
     thumbnail: thumbnail/hover-text.png
 ---
 
-#### Hover text with Plotly Express
+### Hover Labels
 
-Many Plotly Express functions support configurable hover text. The `hover_data` argument accepts a list of column names to be added to the hover tooltip. The `hover_name` property controls which column is displayed in bold as the tooltip title.
+One of the most deceptively-power features of interactive visualization using Plotly is the ability for the user to reveal more information about a data point by moving their mouse cursort over the point and having a hover label appear. 
 
-Here is an example that creates a scatter plot using Plotly Express with custom hover data and a custom hover name.
+There are three hover modes available in Plotly. The default setting is `layout.hovermode='closest'`, wherein a single hover label appears for the point directly underneat the cursor:
 
 ```python
 import plotly.express as px
 
-df_2007 = px.data.gapminder().query("year==2007")
+df = px.data.gapminder().query("continent=='Oceania'")
 
-fig = px.scatter(df_2007, x="gdpPercap", y="lifeExp", log_x=True,
-                 hover_name="country", hover_data=["continent"])
+fig = px.line(df, x="year", y="lifeExp", color="country", title="layout.hovermode='closest' (the default)")
+fig.update_traces(mode="markers+lines")
 
 fig.show()
 ```
 
-#### Add Hover Text
+If `layout.hovermode='x'` (or `'y'`), a single hover label appears per trace, for points at the same `x` (or `y`) value as the cursor. If multiple points in a given trace exist at the same coordinate, only one will get a hover label. In the line plot below we have forced markers to appear, to make it clearer what can be hovered over, and we have disabled the built-in Plotly Express `hovertemplate` by setting it to `None`, resulting in a more compact hover label per point:
 
 ```python
-import plotly.graph_objects as go
+import plotly.express as px
 
-fig = go.Figure()
+df = px.data.gapminder().query("continent=='Oceania'")
 
-fig.add_trace(go.Scatter(
-    x=[1, 2, 3, 4, 5],
-    y=[2, 1, 6, 4, 4],
-    hovertext=["Text A", "Text B", "Text C", "Text D", "Text E"],
-    hoverinfo="text",
-    marker=dict(
-        color="green"
-    ),
-    showlegend=False
-))
+fig = px.line(df, x="year", y="lifeExp", color="country", title="layout.hovermode='x'")
+fig.update_traces(mode="markers+lines", hovertemplate=None)
+fig.update_layout(hovermode="x")
 
 fig.show()
 ```
 
-#### Format Hover Text
+If `layout.hovermode='x unified'` (or `'y unified'`), a single hover label appear, describing one point per trace, for points at the same `x` (or `y`) value as the cursor.  If multiple points in a given trace exist at the same coordinate, only one will get an entry in the hover label. In the line plot below we have forced markers to appear, to make it clearer what can be hovered over, and we have disabled the built-in Plotly Express `hovertemplate` by setting it to `None`, resulting in a more compact entry per point in the hover label:
 
 ```python
-import plotly.graph_objects as go
+import plotly.express as px
 
+df = px.data.gapminder().query("continent=='Oceania'")
 
-fig = go.Figure(go.Scatter(
-    x=[1, 2, 3, 4, 5],
-    y=[2.02825, 1.63728, 6.83839, 4.8485, 4.73463],
-    hoverinfo="y",
-    marker=dict(
-        color="green"
-    ),
-    showlegend=False
-))
+fig = px.line(df, x="year", y="lifeExp", color="country", title="layout.hovermode='x unified'")
+fig.update_traces(mode="markers+lines", hovertemplate=None)
+fig.update_layout(hovermode="x unified")
+
+fig.show()
+```
+
+### Customizing Hover Label Appearance
+
+Hover label text and colors default to trace colors in hover modes other than `unified`, and can be globally set via the `layout.hoverlabel` attributes. Hover label appearance can also be controlled per trace in `<trace>.hoverlabel`.
+
+```python
+import plotly.express as px
+
+df = px.data.gapminder().query("continent=='Oceania'")
+
+fig = px.line(df, x="year", y="lifeExp", color="country", title="Custom layout.hoverlabel formatting")
+fig.update_traces(mode="markers+lines")
 
 fig.update_layout(
-    title_text=("Set hover text formatting<br>" +
-                "<a href= https://github.com/d3/d3-time-format/blob/master/README.md#locale_format>" +
-                "https://github.com/d3/d3-time-format/blob/master/README.md#locale_format</a>"),
-    title_font=dict(
-        size=10
-    ),
+    hoverlabel=dict(
+        bgcolor="white", 
+        font_size=16, 
+        font_family="Rockwell"
+    )
 )
 
-fig.update_xaxes(zeroline=False)
-fig.update_yaxes(hoverformat=".2f")
+fig.show()
+```
+
+### Customizing Hover text with Plotly Express
+
+Plotly Express functions automatically add all the data being plotted (x, y, color etc) to the hover label. Many Plotly Express functions also support configurable hover text. The `hover_data` argument accepts a list of column names to be added to the hover tooltip. The `hover_name` property controls which column is displayed in bold as the tooltip title.
+
+Here is an example that creates a scatter plot using Plotly Express with custom hover data and a custom hover name.
+
+```python
+import plotly.express as px
+
+df_2007 = px.data.gapminder().query("year==2007")
+
+fig = px.scatter(df_2007, x="gdpPercap", y="lifeExp", log_x=True,
+                 hover_name="country", hover_data=["continent", "pop"])
 
 fig.show()
 ```
 
-### Customize tooltip text with a hovertemplate
+### Customizing hover text with a hovertemplate
 
 To customize the tooltip on your graph you can use [hovertemplate](https://plotly.com/python/reference/#pie-hovertemplate), which is a template string used for rendering the information that appear on hoverbox.
 This template string can include `variables` in %{variable} format, `numbers` in [d3-format's syntax](https://github.com/d3/d3-3.x-api-reference/blob/master/Formatting.md#d3_forma), and `date` in [d3-time-format's syntax](https://github.com/d3/d3-3.x-api-reference/blob/master/Time-Formatting.md#format).
 Hovertemplate customize the tooltip text vs. [texttemplate](https://plotly.com/python/reference/#pie-texttemplate) which customizes the text that appears on your chart. <br>
 Set the horizontal alignment of the text within tooltip with [hoverlabel.align](https://plotly.com/python/reference/#layout-hoverlabel-align).
 
+Plotly Express automatically sets the `hovertemplate`, but you can set it manually when using `graph_objects`.
+
 ```python
 import plotly.graph_objects as go
 
@@ -231,7 +249,7 @@ fig.update_layout(title_text='Hover to see the value of z1, z2 and z3 together')
 fig.show()
 ```
 
-### Set Hover Template in Mapbox
+### Setting the Hover Template in Mapbox Maps
 
 ```python
 import plotly.graph_objects as go
@@ -258,6 +276,64 @@ fig.update_layout(
 fig.show()
 ```
 
+### Controlling Hover Text with `graph_objects` and `hoverinfo`
+
+Prior to the addition of `hovertemplate`, hover text was controlled via the now-deprecated `hoverinfo` attribute.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure()
+
+fig.add_trace(go.Scatter(
+    x=[1, 2, 3, 4, 5],
+    y=[2, 1, 6, 4, 4],
+    hovertext=["Text A", "Text B", "Text C", "Text D", "Text E"],
+    hoverinfo="text",
+    marker=dict(
+        color="green"
+    ),
+    showlegend=False
+))
+
+fig.show()
+```
+
+### Spike lines
+
+Plotly supports "spike lines" which link a point to the axis on hover, and can be configured per axis.
+
+```python
+import plotly.express as px
+
+df = px.data.gapminder().query("continent=='Oceania'")
+
+fig = px.line(df, x="year", y="lifeExp", color="country", title="Spike lines active")
+fig.update_traces(mode="markers+lines")
+
+fig.update_xaxes(showspikes=True)
+fig.update_yaxes(showspikes=True)
+
+fig.show()
+```
+
+Spike lines can be styled per axis as well, and the cursor distance setting can be controlled via `layout.spikedistance`.
+
+```python
+import plotly.express as px
+
+df = px.data.gapminder().query("continent=='Oceania'")
+
+fig = px.line(df, x="year", y="lifeExp", color="country", title="Styled Spike Lines")
+fig.update_traces(mode="markers+lines")
+
+fig.update_xaxes(showspikes=True, spikecolor="green", spikesnap="cursor", spikemode="across")
+fig.update_yaxes(showspikes=True, spikecolor="orange", spikethickness=2)
+fig.update_layout(spikedistance=1000, hoverdistance=100)
+
+fig.show()
+```
+
 #### Reference
 
 See https://plotly.com/python/reference/ for more information and chart attribute options!