update tutorials + use long_name

Author: emmanuelle

doc/python/datashader.md

@@ -5,8 +5,8 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: "1.2"
-      jupytext_version: 1.3.1
+      format_version: '1.2'
+      jupytext_version: 1.3.0
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,10 +20,9 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.8
+    version: 3.7.3
   plotly:
-    description:
-      How to use datashader to rasterize large datasets, and visualize
+    description: How to use datashader to rasterize large datasets, and visualize
       the generated raster data with plotly.
     display_as: scientific
     language: python
@@ -98,32 +97,18 @@ fig.show()
 ```
 
 ```python
-import plotly.graph_objects as go
+import plotly.express as px
 import pandas as pd
 import numpy as np
 import datashader as ds
 df = pd.read_parquet('https://raw.githubusercontent.com/plotly/datasets/master/2015_flights.parquet')
 
 cvs = ds.Canvas(plot_width=100, plot_height=100)
 agg = cvs.points(df, 'SCHEDULED_DEPARTURE', 'DEPARTURE_DELAY')
-x = np.array(agg.coords['SCHEDULED_DEPARTURE'])
-y = np.array(agg.coords['DEPARTURE_DELAY'])
-
-# Assign nan to zero values so that the corresponding pixels are transparent
-agg = np.array(agg.values, dtype=np.float)
-agg[agg<1] = np.nan
-
-fig = go.Figure(go.Heatmap(
-    z=np.log10(agg), x=x, y=y,
-    hoverongaps=False,
-    hovertemplate='Scheduled departure: %{x:.1f}h <br>Depature delay: %{y} <br>Log10(Count): %{z}',
-    colorbar=dict(title='Count (Log)', tickprefix='1.e')))
-fig.update_xaxes(title_text='Scheduled departure')
-fig.update_yaxes(title_text='Departure delay')
+agg.values = np.log10(agg.values)
+agg.attrs['long_name'] = 'Log10(count)'
+fig = px.imshow(agg, origin='lower')
+fig.update_traces(hoverongaps=False)
+fig.update_layout(coloraxis_colorbar=dict(title='Count (Log)', tickprefix='1.e'))
 fig.show()
-
-```
-
-```python
-
 ```

doc/python/imshow.md

@@ -120,6 +120,7 @@ import xarray as xr
 # Load xarray from dataset included in the xarray tutorial
 # We remove 273.5 to display Celsius degrees instead of Kelvin degrees
 airtemps = xr.tutorial.open_dataset('air_temperature').air.isel(lon=20) - 273.5
+airtemps.attrs['long_name'] = 'Temperature' # used for hover
 fig = px.imshow(airtemps.T, color_continuous_scale='RdBu_r', origin='lower')
 fig.show()
 ```
@@ -132,6 +133,7 @@ For xarrays, by default `px.imshow` does not constrain pixels to be square, sinc
 import plotly.express as px
 import xarray as xr
 airtemps = xr.tutorial.open_dataset('air_temperature').air.isel(time=500) - 273.5
+airtemps.attrs['long_name'] = 'Temperature' # used for hover
 fig = px.imshow(airtemps, color_continuous_scale='RdBu_r', aspect='equal')
 fig.show()
 ```

packages/python/plotly/plotly/express/_imshow.py

@@ -75,15 +75,15 @@ def imshow(
     template=None,
     width=None,
     height=None,
-    aspect=None
+    aspect=None,
 ):
     """
     Display an image, i.e. data on a 2D regular raster.
 
     Parameters
     ----------
 
-    img: array-like image
+    img: array-like image, or xarray
         The image data. Supported array shapes are
 
         - (M, N): an image with scalar data. The data is visualized
@@ -153,6 +153,9 @@ def imshow(
 
     In order to update and customize the returned figure, use
     `go.Figure.update_traces` or `go.Figure.update_layout`.
+
+    If an xarray is passed, dimensions names and coordinates are used for
+    axes labels and ticks.
     """
     args = locals()
     apply_default_cascade(args)
@@ -168,11 +171,12 @@ def imshow(
             y = img.coords[y_label]
             img_is_xarray = True
             if aspect is None:
-                aspect = 'auto'
+                aspect = "auto"
+            z_name = img.attrs["long_name"] if "long_name" in img.attrs else "z"
 
     if not img_is_xarray:
         if aspect is None:
-            aspect = 'equal'
+            aspect = "equal"
 
     img = np.asanyarray(img)
 
@@ -185,7 +189,7 @@ def imshow(
         trace = go.Heatmap(z=img, coloraxis="coloraxis1")
         autorange = True if origin == "lower" else "reversed"
         layout = dict(yaxis=dict(autorange=autorange))
-        if aspect == 'equal':
+        if aspect == "equal":
             layout["xaxis"] = dict(scaleanchor="y", constrain="domain")
             layout["yaxis"]["constrain"] = "domain"
         colorscale_validator = ColorscaleValidator("colorscale", "imshow")
@@ -228,7 +232,15 @@ def imshow(
     fig.update_layout(layout_patch)
     if img_is_xarray:
         if img.ndim <= 2:
-            fig.update_traces(x=x, y=y)
+            hovertemplate = (
+                x_label
+                + ": %{x} <br>"
+                + y_label
+                + ": %{y} <br>"
+                + z_name
+                + " : %{z}<extra></extra>"
+            )
+            fig.update_traces(x=x, y=y, hovertemplate=hovertemplate)
         fig.update_xaxes(title_text=x_label)
         fig.update_yaxes(title_text=y_label)
     fig.update_layout(template=args["template"], overwrite=True)