Merge branch 'nocolor' of github.com:plotly/plotly.py into nocolor

Author: nicholas-esterer

CHANGELOG.md

@@ -2,6 +2,7 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+
 ## [4.9.0] - unreleased
 
 ### Added
@@ -14,6 +15,12 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 - trendline traces are now of type `scattergl` when `render_mode="webgl"` in Plotly Express ([#2614](https://github.com/plotly/plotly.py/pull/2614))
 
+### Updated
+
+- Added all cartesian-2d Plotly Express functions, plus `imshow` to Pandas backend with `kind` option
+- `plotly.express.imshow` now uses data frame index and columns names and values to populate axis parameters by default ([#2539](https://github.com/plotly/plotly.py/pull/2539))
+
+
 
 ## [4.8.2] - 2020-06-26
 
@@ -22,6 +29,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 - Updated Plotly.js to version 1.54.5. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/v1.54.5/CHANGELOG.md) for more information.
 - `add_traces()` now accepts bare `int`-like values for `rows`/`cols` as well as lists thereof ([#2546](https://github.com/plotly/plotly.py/pull/2546)), with thanks to [@MCBoarder289](https://github.com/MCBoarder289) for the contribution!
 
+
 ### Fixed
 
 - `row`/`col` now accept `int`-like values, not strictly `int` values ([#2451](https://github.com/plotly/plotly.py/pull/2451)), with thanks to [@MCBoarder289](https://github.com/MCBoarder289) for the contribution!

doc/python/dropdowns.md

@@ -147,7 +147,7 @@ fig.update_scenes(
     aspectmode="manual"
 )
 
-# Add drowdowns
+# Add dropdowns
 button_layer_1_height = 1.08
 fig.update_layout(
     updatemenus=[

doc/python/facet-plots.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.2'
-      jupytext_version: 1.3.4
+      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.0
+    version: 3.7.7
   plotly:
     description: How to make Facet and Trellis Plots in Python with Plotly.
     display_as: statistical
@@ -103,7 +103,7 @@ fig.show()
 
 ### Customize Subplot Figure Titles
 
-Since subplot figure titles are [annotations](https://plotly.com/python/text-and-annotations/#simple-annotation), you can use the `for_each_annotation` function to customize them.
+Since subplot figure titles are [annotations](https://plotly.com/python/text-and-annotations/#simple-annotation), you can use the `for_each_annotation` function to customize them, for example to remove the equal-sign (`=`).
 
 In the following example, we pass a lambda function to `for_each_annotation` in order to change the figure subplot titles from `smoker=No` and `smoker=Yes` to just `No` and `Yes`. 
 
@@ -115,8 +115,25 @@ fig.for_each_annotation(lambda a: a.update(text=a.text.split("=")[-1]))
 fig.show()
 ```
 
+### Controlling Facet Spacing
+
+The `facet_row_spacing` and `facet_col_spacing` arguments can be used to control the spacing between rows and columns. These values are specified in fractions of the plotting area in paper coordinates and not in pixels, so they will grow or shrink with the `width` and `height` of the figure. 
+
+The defaults work well with 1-4 rows or columns at the default figure size with the default font size, but need to be reduced to around 0.01 for very large figures or figures with many rows or columns. Conversely, if activating tick labels on all facets, the spacing will need to be increased.
+
 ```python
+import plotly.express as px
 
+df = px.data.gapminder().query("continent == 'Africa'")
+
+fig = px.line(df, x="year", y="lifeExp", facet_col="country", facet_col_wrap=7,
+              facet_row_spacing=0.04, # default is 0.07 when facet_col_wrap is used
+              facet_col_spacing=0.04, # default is 0.03
+              height=600, width=800,
+              title="Life Expectancy in Africa")
+fig.for_each_annotation(lambda a: a.update(text=a.text.split("=")[-1]))
+fig.update_yaxes(showticklabels=True)
+fig.show()
 ```
 
 ### Synchronizing axes in subplots with `matches`
@@ -138,4 +155,4 @@ for i in range(1, 4):
     fig.add_trace(go.Scatter(x=x, y=np.random.random(N)), 1, i)
 fig.update_xaxes(matches='x')
 fig.show()
-```
+```

doc/python/heatmaps.md

@@ -36,7 +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, which [operates on a variety of types of 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.
+[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/). With `px.imshow`, each value of the input array or data frame is represented as a heatmap pixel.
 
 For more examples using `px.imshow`, see the [tutorial on displaying image data with plotly](/python/imshow).
 
@@ -49,6 +49,14 @@ fig = px.imshow([[1, 20, 30],
 fig.show()
 ```
 
+```python
+import plotly.express as px
+
+df = px.data.medals_wide(indexed=True)
+fig = px.imshow(df)
+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:
@@ -182,4 +190,4 @@ Arrays of rasterized values build by datashader can be visualized using
 plotly's heatmaps, as shown in the [plotly and datashader tutorial](/python/datashader/).
 
 #### Reference
-See https://plotly.com/python/reference/#heatmap for more information and chart attribute options!
+See https://plotly.com/python/reference/#heatmap for more information and chart attribute options!

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

@@ -228,7 +228,7 @@ df_2007 = px.data.gapminder().query("year==2007")
 fig = px.scatter(df_2007, x="gdpPercap", y="lifeExp", log_x=True, color='continent'
                 )
 print("plotly express hovertemplate:", fig.data[0].hovertemplate)
-fig.update_traces(hovertemplate='GDP: %{x} <br>Life Expectany: %{y}') # 
+fig.update_traces(hovertemplate='GDP: %{x} <br>Life Expectancy: %{y}') # 
 fig.update_traces(hovertemplate=None, selector={'name':'Europe'}) # revert to default hover
 print("user_defined hovertemplate:", fig.data[0].hovertemplate)
 fig.show()
@@ -404,4 +404,4 @@ fig.show()
 
 #### Reference
 
-See https://plotly.com/python/reference/ for more information and chart attribute options!
+See https://plotly.com/python/reference/ for more information and chart attribute options!

doc/python/legend.md

@@ -428,10 +428,10 @@ fig.add_trace(go.Streamtube(
 ))
 # Update all traces together
 fig.update_traces(showlegend=True, showscale=False)
-fig.update_layout(width=600, title_text='Exporation of a vector field using several traces')
+fig.update_layout(width=600, title_text='Exploration of a vector field using several traces')
 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!

doc/python/pandas-backend.md

@@ -98,7 +98,7 @@ fig.show()
 
 ### Supported Methods
 
-The Plotly backend supports the following `kind`s of Pandas plots: `scatter`, `line`, `area`, `bar`, `barh`, `hist` and `box`, via the call pattern `df.plot(kind='scatter')` or `df.plot.scatter()`. These delegate to the corresponding Plotly Express functions.
+The Plotly backend supports the following `kind`s of Pandas plots: `scatter`, `line`, `area`, `bar`, `barh`, `hist` and `box`, via the call pattern `df.plot(kind='scatter')` or `df.plot.scatter()`. These delegate to the corresponding Plotly Express functions. In addition, the following are valid options to the `kind` argument of `df.plot()`: `violin`, `strip`, `funnel`, `density_heatmap`, `density_contour` and `imshow`, even though the call pattern `df.plot.violin()` is not supported for these kinds of charts, per the Pandas API.
 
 ```python
 import pandas as pd
@@ -198,4 +198,4 @@ fig.show()
 
 ### What about Cufflinks?
 
-There also exists an independent third-party wrapper library around Plotly called [Cufflinks](https://github.com/santosjorge/cufflinks), which provides similar functionality (with an API closer to that of Pandas' default `matplotlib` backend) by adding a `.iplot()` method to Pandas dataframes, as it was developed before Pandas supported configurable backends. Issues and questions regarding Cufflinks should be [raised in the Cufflinks repository](https://github.com/santosjorge/cufflinks/issues/new).
+There also exists an independent third-party wrapper library around Plotly called [Cufflinks](https://github.com/santosjorge/cufflinks), which provides similar functionality (with an API closer to that of Pandas' default `matplotlib` backend) by adding a `.iplot()` method to Pandas dataframes, as it was developed before Pandas supported configurable backends. Issues and questions regarding Cufflinks should be [raised in the Cufflinks repository](https://github.com/santosjorge/cufflinks/issues/new).

doc/python/px-arguments.md

@@ -49,7 +49,7 @@ There are three common conventions for storing column-oriented data, usually in
 * **wide-form data** has one row per value of one of the first variable, and one column per value of the second variable. This is suitable for storing and displaying 2-dimensional data.
 * **mixed-form data** is a hybrid of long-form and wide-form data, with one row per value of one variable, and some columns representing values of another, and some columns representing more variables. See the [wide-form documentation](/python/wide-form/) for examples of how to use Plotly Express to visualize this kind of data.
 
-Every Plotly Express function other than `imshow` can operate on long-form data, and in addition, the following 2D-Cartesian functions can operate on wide-form and mixed-form data: `px.scatter`, `px.line`, `px.area`, `px.bar`, `px.histogram`, `px.violin`, `px.box`, `px.strip`, `px.funnel`, `px.density_heatmap` and `px.density_contour`.
+Every Plotly Express function can operate on long-form data (other than `px.imshow` which operates only on wide-form input), and in addition, the following 2D-Cartesian functions can operate on wide-form and mixed-form data: `px.scatter`, `px.line`, `px.area`, `px.bar`, `px.histogram`, `px.violin`, `px.box`, `px.strip`, `px.funnel`, `px.density_heatmap` and `px.density_contour`.
 
 By way of example here is the same data, represented in long-form first, and then in wide-form:
 
@@ -241,4 +241,4 @@ fig = px.bar(df, x='year', y=gdp, color='continent', labels={'y':'log gdp'},
              hover_data=['country'],
              title='Evolution of world GDP')
 fig.show()
-```
+```

doc/python/wide-form.md

@@ -48,7 +48,7 @@ There are three common conventions for storing column-oriented data, usually in
 * **wide-form data** has one row per value of one of the first variable, and one column per value of the second variable. This is suitable for storing and displaying 2-dimensional data.
 * **mixed-form data** is a hybrid of long-form and wide-form data, with one row per value of one variable, and some columns representing values of another, and some columns representing more variables.
 
-Every Plotly Express function other than `imshow` can operate on long-form data, and in addition, the following 2D-Cartesian functions can operate on wide-form and mixed-form data: `px.scatter`, `px.line`, `px.area`, `px.bar`, `px.histogram`, `px.violin`, `px.box`, `px.strip`, `px.funnel`, `px.density_heatmap` and `px.density_contour`.
+Every Plotly Express function can operate on long-form data (other than `px.imshow` which operates only on wide-form input), and in addition, the following 2D-Cartesian functions can operate on wide-form and mixed-form data: `px.scatter`, `px.line`, `px.area`, `px.bar`, `px.histogram`, `px.violin`, `px.box`, `px.strip`, `px.funnel`, `px.density_heatmap` and `px.density_contour`.
 
 By way of example here is the same data, represented in long-form first, and then in wide-form:
 

packages/python/plotly/plotly/__init__.py

@@ -80,7 +80,20 @@ def plot(data_frame, kind, **kwargs):
     To activate, set pandas.options.plotting.backend="plotly"
     See https://github.com/pandas-dev/pandas/blob/master/pandas/plotting/__init__.py
     """
-    from .express import scatter, line, area, bar, box, histogram
+    from .express import (
+        scatter,
+        line,
+        area,
+        bar,
+        box,
+        histogram,
+        violin,
+        strip,
+        funnel,
+        density_contour,
+        density_heatmap,
+        imshow,
+    )
 
     if kind == "scatter":
         new_kwargs = {k: kwargs[k] for k in kwargs if k not in ["s", "c"]}
@@ -96,9 +109,27 @@ def plot(data_frame, kind, **kwargs):
     if kind == "box":
         new_kwargs = {k: kwargs[k] for k in kwargs if k not in ["by"]}
         return box(data_frame, **new_kwargs)
-    if kind in "hist":
+    if kind in ["hist", "histogram"]:
         new_kwargs = {k: kwargs[k] for k in kwargs if k not in ["by", "bins"]}
         return histogram(data_frame, **new_kwargs)
+    if kind == "violin":
+        return violin(data_frame, **kwargs)
+    if kind == "strip":
+        return strip(data_frame, **kwargs)
+    if kind == "funnel":
+        return funnel(data_frame, **kwargs)
+    if kind == "density_contour":
+        return density_contour(data_frame, **kwargs)
+    if kind == "density_heatmap":
+        return density_heatmap(data_frame, **kwargs)
+    if kind == "imshow":
+        return imshow(data_frame, **kwargs)
+    if kind == "heatmap":
+        raise ValueError(
+            "kind='heatmap' not supported plotting.backend='plotly'. "
+            "Please use kind='imshow' or kind='density_heatmap'."
+        )
+
     raise NotImplementedError(
         "kind='%s' not yet supported for plotting.backend='plotly'" % kind
     )

packages/python/plotly/plotly/express/_doc.py

@@ -231,9 +231,12 @@
     ],
     facet_row_spacing=[
         "float between 0 and 1",
-        "Spacing between facet rows, in paper units.",
+        "Spacing between facet rows, in paper units. Default is 0.03 or 0.0.7 when facet_col_wrap is used.",
+    ],
+    facet_col_spacing=[
+        "float between 0 and 1",
+        "Spacing between facet columns, in paper units Default is 0.02.",
     ],
-    facet_col_spacing=["int", "Spacing between facet columns, in paper units",],
     animation_frame=[
         colref_type,
         colref_desc,

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

@@ -196,6 +196,17 @@ def imshow(
             labels["color"] = xarray.plot.utils.label_from_attrs(img)
             labels["color"] = labels["color"].replace("\n", "<br>")
     else:
+        if hasattr(img, "columns") and hasattr(img.columns, "__len__"):
+            if x is None:
+                x = img.columns
+            if labels.get("x", None) is None and hasattr(img.columns, "name"):
+                labels["x"] = img.columns.name or ""
+        if hasattr(img, "index") and hasattr(img.index, "__len__"):
+            if y is None:
+                y = img.index
+            if labels.get("y", None) is None and hasattr(img.index, "name"):
+                labels["y"] = img.index.name or ""
+
         if labels.get("x", None) is None:
             labels["x"] = ""
         if labels.get("y", None) is None:

packages/python/plotly/plotly/tests/test_core/test_px/test_imshow.py

@@ -150,3 +150,25 @@ def test_imshow_labels_and_ranges():
 
     with pytest.raises(ValueError):
         fig = px.imshow([[1, 2], [3, 4], [5, 6]], x=["a"])
+
+
+def test_imshow_dataframe():
+    df = px.data.medals_wide(indexed=False)
+    fig = px.imshow(df)
+    assert fig.data[0].x[0] == df.columns[0]
+    assert fig.data[0].x[0] == "nation"
+    assert fig.layout.xaxis.title.text is None
+    assert fig.data[0].y[0] == df.index[0]
+    assert fig.data[0].y[0] == 0
+    assert fig.layout.yaxis.title.text is None
+
+    df = px.data.medals_wide(indexed=True)
+    fig = px.imshow(df)
+    assert fig.data[0].x[0] == df.columns[0]
+    assert fig.data[0].x[0] == "gold"
+    assert fig.layout.xaxis.title.text == df.columns.name
+    assert fig.layout.xaxis.title.text == "medal"
+    assert fig.data[0].y[0] == df.index[0]
+    assert fig.data[0].y[0] == "South Korea"
+    assert fig.layout.yaxis.title.text == df.index.name
+    assert fig.layout.yaxis.title.text == "nation"

packages/python/plotly/plotly/tests/test_core/test_px/test_pandas_backend.py

@@ -22,6 +22,18 @@
         (lambda df: df.boxplot(), px.box),
         (lambda df: df.hist(), px.histogram),
         (lambda df: df["A"].hist(), lambda df: px.histogram(df["A"])),
+        (lambda df: df.plot(kind="line"), px.line),
+        (lambda df: df.plot(kind="area"), px.area),
+        (lambda df: df.plot(kind="bar"), px.bar),
+        (lambda df: df.plot(kind="box"), px.box),
+        (lambda df: df.plot(kind="hist"), px.histogram),
+        (lambda df: df.plot(kind="histogram"), px.histogram),
+        (lambda df: df.plot(kind="violin"), px.violin),
+        (lambda df: df.plot(kind="strip"), px.strip),
+        (lambda df: df.plot(kind="funnel"), px.funnel),
+        (lambda df: df.plot(kind="density_contour"), px.density_contour),
+        (lambda df: df.plot(kind="density_heatmap"), px.density_heatmap),
+        (lambda df: df.plot(kind="imshow"), px.imshow),
     ],
 )
 def test_pandas_equiv(pandas_fn, px_fn):