docs and tests for imshow changes

Author: nicolaskruchten

Diff for: doc/python/heatmaps.md

@@ -36,9 +36,7 @@ jupyter:
 
 ### Heatmap with `plotly.express` and `px.imshow`
 
-[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly. With `px.imshow`, each value of the input array is represented as a heatmap pixel.
-
-`px.imshow` makes opiniated choices for representing heatmaps, such as using square pixels. To override this behaviour, you can use `fig.update_layout` or use the `go.Heatmap` trace from `plotly.graph_objects` as described below. 
+[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/). With `px.imshow`, each value of the input array is represented as a heatmap pixel.
 
 For more examples using `px.imshow`, see the [tutorial on displaying image data with plotly](/python/imshow).
 
@@ -51,6 +49,22 @@ fig = px.imshow([[1, 20, 30],
 fig.show()
 ```
 
+### Customizing the axes and labels on a heatmap
+
+You can use the `x`, `y` and `labels` arguments to customize the display of a heatmap, and use `.update_xaxes()` to move the x axis tick labels to the top:
+
+```python
+import plotly.express as px
+data=[[1, 25, 30, 50, 1], [20, 1, 60, 80, 30], [30, 60, 1, 5, 20]]
+fig = px.imshow(data,
+                labels=dict(x="Day of Week", y="Time of Day", color="Productivity"),
+                x=['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday'],
+                y=['Morning', 'Afternoon', 'Evening']
+               )
+fig.update_xaxes(side="top")
+fig.show()
+```
+
 ### Basic Heatmap with `plotly.graph_objects`
 
 If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Heatmap` function from `plotly.graph_objects`.
@@ -67,7 +81,7 @@ fig.show()
 
 ### Heatmap with Categorical Axis Labels
 
-In this example we also show how to ignore [hovertext](https://plot.ly/python/hover-text-and-formatting/) when we have [missing values](https://plot.ly/python/missing_values) in the data by setting the [hoverongaps](https://plot.ly/python/reference/#heatmap-hoverongaps) to False. 
+In this example we also show how to ignore [hovertext](https://plot.ly/python/hover-text-and-formatting/) when we have [missing values](https://plot.ly/python/missing_values) in the data by setting the [hoverongaps](https://plot.ly/python/reference/#heatmap-hoverongaps) to False.
 
 ```python
 import plotly.graph_objects as go

Diff for: doc/python/imshow.md

@@ -74,7 +74,7 @@ fig = px.imshow(img)
 fig.show()
 ```
 
-### Display single-channel 2D image as grayscale
+### Display single-channel 2D data as a heatmap
 
 For a 2D image, `px.imshow` uses a colorscale to map scalar data to colors. The default colorscale is the one of the active template (see [the tutorial on templates](/python/templates/)).
 
@@ -88,44 +88,67 @@ fig.show()
 
 ### Choose the colorscale to display a single-channel image
 
+You can customize the [continuous color scale](/python/colorscales/) just like with any other Plotly Express function:
 
 ```python
 import plotly.express as px
 import numpy as np
 img = np.arange(100).reshape((10, 10))
-fig = px.imshow(img, color_continuous_scale='gray', labels=dict(x="yoo", y="yaa", color="hey"),
-               width=600, height=600, 
-                x=["a","b","c","d","e","f","g","h","i","j"],
-                y=["a","b","c","d","e","f","g","h","i","j"]
-               )
+fig = px.imshow(img, color_continuous_scale='Viridis')
+fig.show()
+```
+
+You can use this to make the image grayscale as well:
+
+```python
+import plotly.express as px
+import numpy as np
+img = np.arange(100).reshape((10, 10))
+fig = px.imshow(img, color_continuous_scale='gray')
 fig.show()
 ```
 
-### Hiding the colorbar when displaying a single-channel image
+### Hiding the colorbar and axis labels
 
-See [the tutorial on coloraxis](/python/colorscales/#share-color-axis) for more details on coloraxis.
+See the [continuous color](/python/colorscales/) and [cartesian axes](/python/axes/) pages for more details.
 
 ```python
 import plotly.express as px
 from skimage import data
 img = data.camera()
 fig = px.imshow(img, color_continuous_scale='gray')
 fig.update_layout(coloraxis_showscale=False)
+fig.update_xaxes(showticklabels=False)
+fig.update_yaxes(showticklabels=False)
+fig.show()
+```
+
+### Customizing the axes and labels on a single-channel image
+
+You can use the `x`, `y` and `labels` arguments to customize the display of a heatmap, and use `.update_xaxes()` to move the x axis tick labels to the top:
+
+```python
+import plotly.express as px
+data=[[1, 25, 30, 50, 1], [20, 1, 60, 80, 30], [30, 60, 1, 5, 20]]
+fig = px.imshow(data,
+                labels=dict(x="Day of Week", y="Time of Day", color="Productivity"),
+                x=['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday'],
+                y=['Morning', 'Afternoon', 'Evening']
+               )
+fig.update_xaxes(side="top")
 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 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 in the next example.
+[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 above.
 
 ```python
 import plotly.express as px
 import xarray as xr
 # Load xarray from dataset included in the xarray tutorial
 airtemps = xr.tutorial.open_dataset('air_temperature').air.sel(lon=250.0)
-fig = px.imshow(airtemps.T, color_continuous_scale='RdBu_r', origin='lower',
-                labels={'color':airtemps.attrs['var_desc']}
-               )
+fig = px.imshow(airtemps.T, color_continuous_scale='RdBu_r', origin='lower')
 fig.show()
 ```
 
@@ -233,7 +256,7 @@ fig.show()
 ### imshow and datashader
 
 Arrays of rasterized values build by datashader can be visualized using
-imshow. See the [plotly and datashader tutorial](/python/datashader/) for 
+imshow. See the [plotly and datashader tutorial](/python/datashader/) for
 examples on how to use plotly and datashader.
 
 

Diff for: packages/python/plotly/plotly/express/_doc.py

@@ -6,13 +6,6 @@
 except AttributeError:  # python 2
     getfullargspec = inspect.getargspec
 
-# TODO contents of columns
-# TODO explain categorical
-# TODO handle color
-# TODO handle details of box/violin/histogram
-# TODO handle details of column selection with `dimensions`
-# TODO document "or `None`, default `None`" in various places
-# TODO standardize positioning and casing of 'default'
 
 colref_type = "str or int or Series or array-like"
 colref_desc = "Either a name of a column in `data_frame`, or a pandas Series or array_like object."
@@ -325,11 +318,11 @@
     ],
     title=["str", "The figure title."],
     template=[
-        "or dict or plotly.graph_objects.layout.Template instance",
-        "The figure template name or definition.",
+        "str or dict or plotly.graph_objects.layout.Template instance",
+        "The figure template name (must be a key in plotly.io.templates) or definition.",
     ],
     width=["int (default `None`)", "The figure width in pixels."],
-    height=["int (default `600`)", "The figure height in pixels."],
+    height=["int (default `None`)", "The figure height in pixels."],
     labels=[
         "dict with str keys and str values (default `{}`)",
         "By default, column names are used in the figure for axis titles, legend entries and hovers.",

Diff for: packages/python/plotly/plotly/express/_imshow.py

@@ -101,18 +101,24 @@ def imshow(
         a multichannel image of floats, the max of the image is computed and zmax is the
         smallest power of 256 (1, 255, 65535) greater than this max value,
         with a 5% tolerance. For a single-channel image, the max of the image is used.
+        Overridden by range_color.
 
     origin : str, 'upper' or 'lower' (default 'upper')
         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 and hover (key ``color``). The values should correspond
+        Sets names used in the figure for axis titles (keys ``x`` and ``y``),
+        colorbar title and hoverlabel (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, and color.
 
+    x, y: list-like, optional
+        x and y are used to label the axes of single-channel heatmap visualizations and
+        their lengths must match the lengths of the second and first dimensions of the
+        img argument. They are auto-populated if the input is an xarray.
+
     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
@@ -121,7 +127,7 @@ def imshow(
 
     color_continuous_midpoint : number
         If set, computes the bounds of the continuous color scale to have the desired
-        midpoint.
+        midpoint. Overridden by range_color or zmin and zmax.
 
     range_color : list of two numbers
         If provided, overrides auto-scaling on the continuous color scale, including
@@ -138,7 +144,7 @@ def imshow(
         The figure width in pixels.
 
     height: number
-        The figure height in pixels, defaults to 600.
+        The figure height in pixels.
 
     aspect: 'equal', 'auto', or None
       - 'equal': Ensures an aspect ratio of 1 or pixels (square pixels)
@@ -207,6 +213,16 @@ def imshow(
 
     # For 2d data, use Heatmap trace
     if img.ndim == 2:
+        if y is not None and img.shape[0] != len(y):
+            raise ValueError(
+                "The length of the y vector must match the length of the first "
+                + "dimension of the img matrix."
+            )
+        if x is not None and img.shape[1] != len(x):
+            raise ValueError(
+                "The length of the x vector must match the length of the second "
+                + "dimension of the img matrix."
+            )
         trace = go.Heatmap(x=x, y=y, z=img, coloraxis="coloraxis1")
         autorange = True if origin == "lower" else "reversed"
         layout = dict(yaxis=dict(autorange=autorange))

Diff for: packages/python/plotly/plotly/tests/test_core/test_px/test_imshow.py

@@ -126,3 +126,27 @@ def test_imshow_xarray():
     assert fig.layout.xaxis.title.text == "dim_cols"
     assert fig.layout.yaxis.title.text == "dim_rows"
     assert np.all(np.array(fig.data[0].x) == np.array(da.coords["dim_cols"]))
+
+
+def test_imshow_labels_and_ranges():
+    fig = px.imshow([[1, 2], [3, 4], [5, 6]],)
+    assert fig.layout.xaxis.title.text is None
+    assert fig.layout.yaxis.title.text is None
+    assert fig.layout.coloraxis.colorbar.title.text is None
+    assert fig.data[0].x is None
+    assert fig.data[0].y is None
+    fig = px.imshow(
+        [[1, 2], [3, 4], [5, 6]],
+        x=["a", "b"],
+        y=["c", "d", "e"],
+        labels=dict(x="the x", y="the y", color="the color"),
+    )
+    # Dimensions are used for axis labels and coordinates
+    assert fig.layout.xaxis.title.text == "the x"
+    assert fig.layout.yaxis.title.text == "the y"
+    assert fig.layout.coloraxis.colorbar.title.text == "the color"
+    assert fig.data[0].x[0] == "a"
+    assert fig.data[0].y[0] == "c"
+
+    with pytest.raises(ValueError):
+        fig = px.imshow([[1, 2], [3, 4], [5, 6]], x=["a"])