added labels to imshow

Author: emmanuelle

doc/python/imshow.md

@@ -112,16 +112,15 @@ fig.show()
 
 ### Display an xarray image with px.imshow
 
-[xarrays](http://xarray.pydata.org/en/stable/) are labeled arrays (with labeled axes and coordinates). If you pass an xarray image to `px.imshow`, its axes labels and coordinates will be used for ticks. (If you don't want this behavior, just pass `img.values` which is a NumPy array if `img` is an xarray).
+[xarrays](http://xarray.pydata.org/en/stable/) are labeled arrays (with labeled axes and coordinates). If you pass an xarray image to `px.imshow`, its axes labels and coordinates will be used for axis titles. If you don't want this behavior, you can pass `img.values` which is a NumPy array if `img` is an xarray. Alternatively, you can override axis titles hover labels and colorbar title using the `labels` attribute, as below.
 
 ```python
 import plotly.express as px
 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.sel(lon=250.0)
-#airtemps.attrs['long_name'] = 'Temperature' # used for hover
-fig = px.imshow(airtemps.T, color_continuous_scale='RdBu_r', origin='lower')
+fig = px.imshow(airtemps.T, color_continuous_scale='RdBu_r', origin='lower',
+                labels={'colorbar':airtemps.attrs['var_desc']})
 fig.show()
 ```
 
@@ -132,9 +131,10 @@ For xarrays, by default `px.imshow` does not constrain pixels to be square, sinc
 ```python
 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')
+airtemps = xr.tutorial.open_dataset('air_temperature').air.isel(time=500)
+colorbar_title = airtemps.attrs['var_desc'] + '<br> (%s)'%airtemps.attrs['units']
+fig = px.imshow(airtemps, color_continuous_scale='RdBu_r', aspect='equal',
+                labels={'colorbar':colorbar_title})
 fig.show()
 ```
 

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

@@ -68,7 +68,7 @@ def imshow(
     zmin=None,
     zmax=None,
     origin=None,
-    labels=None,
+    labels={},
     color_continuous_scale=None,
     color_continuous_midpoint=None,
     range_color=None,
@@ -104,6 +104,14 @@ def imshow(
         position of the [0, 0] pixel of the image array, in the upper left or lower left
         corner. The convention 'upper' is typically used for matrices and images.
 
+    labels : dict with str keys and str values (default `{}`)
+        Overrides names used in the figure for axis titles (keys ``x`` and ``y``),
+        colorbar title (key ``colorbar``) and hover (key ``color``). The values
+        should correspond to the desired label to be displayed. If ``img`` is an
+        xarray, dimension names are used for axis titles, and long name for the
+        colorbar title (unless overridden in ``labels``). Possible keys are:
+        x, y, color and colorbar.
+
     color_continuous_scale : str or list of str
         colormap used to map scalar data to colors (for a 2D image). This parameter is
         not used for RGB or RGBA images. If a string is provided, it should be the name
@@ -161,6 +169,7 @@ def imshow(
     args = locals()
     apply_default_cascade(args)
     img_is_xarray = False
+    colorbar_title = ''
     if xarray_imported:
         if isinstance(img, xarray.DataArray):
             y_label, x_label = img.dims[0], img.dims[1]
@@ -173,8 +182,18 @@ def imshow(
             img_is_xarray = True
             if aspect is None:
                 aspect = "auto"
-            z_name = img.attrs["long_name"] if "long_name" in img.attrs else "z"
-     #TODO if ...
+            z_name = img.attrs["long_name"] if "long_name" in img.attrs else ""
+            colorbar_title = z_name
+
+    if labels is not None:
+        if 'x' in labels:
+            y_label = labels['x']
+        if 'y' in labels:
+            y_label = labels['y']
+        if 'color' in labels:
+            z_name = labels['color']
+        if 'colorbar' in labels:
+            colorbar_title = labels['colorbar']
 
     if not img_is_xarray:
         if aspect is None:
@@ -207,6 +226,7 @@ def imshow(
             cmid=color_continuous_midpoint,
             cmin=range_color[0],
             cmax=range_color[1],
+            colorbar=dict(title=colorbar_title)
         )
 
     # For 2D+RGB data, use Image trace