facet spacing, closes #2584

Author: nicolaskruchten

CHANGELOG.md

@@ -6,8 +6,12 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Added
 
-- `px.NO_COLOR` constant to override wide-form color assignment in Plotly Express
-- trendline traces are now of type `scattergl` when `render_mode="webgl"` in Plotly Express
+- `px.NO_COLOR` constant to override wide-form color assignment in Plotly Express ([#2614](https://github.com/plotly/plotly.py/pull/2614))
+- `facet_row_spacing` and `facet_col_spacing` added to Plotly Express cartesian 2d functions ([#2614](https://github.com/plotly/plotly.py/pull/2614))
+
+### Fixed
+
+- trendline traces are now of type `scattergl` when `render_mode="webgl"` in Plotly Express ([#2614](https://github.com/plotly/plotly.py/pull/2614))
 
 
 ## [4.8.2] - 2020-06-26

packages/python/plotly/plotly/express/_chart_types.py

@@ -23,6 +23,8 @@ def scatter(
     facet_row=None,
     facet_col=None,
     facet_col_wrap=0,
+    facet_row_spacing=None,
+    facet_col_spacing=None,
     error_x=None,
     error_x_minus=None,
     error_y=None,
@@ -74,6 +76,8 @@ def density_contour(
     facet_row=None,
     facet_col=None,
     facet_col_wrap=0,
+    facet_row_spacing=None,
+    facet_col_spacing=None,
     hover_name=None,
     hover_data=None,
     animation_frame=None,
@@ -141,6 +145,8 @@ def density_heatmap(
     facet_row=None,
     facet_col=None,
     facet_col_wrap=0,
+    facet_row_spacing=None,
+    facet_col_spacing=None,
     hover_name=None,
     hover_data=None,
     animation_frame=None,
@@ -213,6 +219,8 @@ def line(
     facet_row=None,
     facet_col=None,
     facet_col_wrap=0,
+    facet_row_spacing=None,
+    facet_col_spacing=None,
     error_x=None,
     error_x_minus=None,
     error_y=None,
@@ -260,6 +268,8 @@ def area(
     facet_row=None,
     facet_col=None,
     facet_col_wrap=0,
+    facet_row_spacing=None,
+    facet_col_spacing=None,
     animation_frame=None,
     animation_group=None,
     category_orders={},
@@ -301,6 +311,8 @@ def bar(
     facet_row=None,
     facet_col=None,
     facet_col_wrap=0,
+    facet_row_spacing=None,
+    facet_col_spacing=None,
     hover_name=None,
     hover_data=None,
     custom_data=None,
@@ -353,6 +365,8 @@ def histogram(
     facet_row=None,
     facet_col=None,
     facet_col_wrap=0,
+    facet_row_spacing=None,
+    facet_col_spacing=None,
     hover_name=None,
     hover_data=None,
     animation_frame=None,
@@ -417,6 +431,8 @@ def violin(
     facet_row=None,
     facet_col=None,
     facet_col_wrap=0,
+    facet_row_spacing=None,
+    facet_col_spacing=None,
     hover_name=None,
     hover_data=None,
     custom_data=None,
@@ -464,6 +480,8 @@ def box(
     facet_row=None,
     facet_col=None,
     facet_col_wrap=0,
+    facet_row_spacing=None,
+    facet_col_spacing=None,
     hover_name=None,
     hover_data=None,
     custom_data=None,
@@ -514,6 +532,8 @@ def strip(
     facet_row=None,
     facet_col=None,
     facet_col_wrap=0,
+    facet_row_spacing=None,
+    facet_col_spacing=None,
     hover_name=None,
     hover_data=None,
     custom_data=None,
@@ -1398,6 +1418,8 @@ def funnel(
     facet_row=None,
     facet_col=None,
     facet_col_wrap=0,
+    facet_row_spacing=None,
+    facet_col_spacing=None,
     hover_name=None,
     hover_data=None,
     custom_data=None,

packages/python/plotly/plotly/express/_core.py

@@ -2060,9 +2060,9 @@ def init_figure(args, subplot_type, frame_list, nrows, ncols, col_labels, row_la
             row_heights = [main_size] * (nrows - 1) + [1 - main_size]
             vertical_spacing = 0.01
         elif args.get("facet_col_wrap", 0):
-            vertical_spacing = 0.07
+            vertical_spacing = args.get("facet_row_spacing", None) or 0.07
         else:
-            vertical_spacing = 0.03
+            vertical_spacing = args.get("facet_row_spacing", None) or 0.03
 
         if bool(args.get("marginal_y", False)):
             if args["marginal_y"] == "histogram" or ("color" in args and args["color"]):
@@ -2073,7 +2073,7 @@ def init_figure(args, subplot_type, frame_list, nrows, ncols, col_labels, row_la
             column_widths = [main_size] * (ncols - 1) + [1 - main_size]
             horizontal_spacing = 0.005
         else:
-            horizontal_spacing = 0.02
+            horizontal_spacing = args.get("facet_col_spacing", None) or 0.02
     else:
         # Other subplot types:
         #   'scene', 'geo', 'polar', 'ternary', 'mapbox', 'domain', None

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

@@ -224,6 +224,11 @@
         "Wraps the column variable at this width, so that the column facets span multiple rows.",
         "Ignored if 0, and forced to 0 if `facet_row` or a `marginal` is set.",
     ],
+    facet_row_spacing=[
+        "float between 0 and 1",
+        "Spacing between facet rows, in paper units.",
+    ],
+    facet_col_spacing=["int", "Spacing between facet columns, in paper units",],
     animation_frame=[
         colref_type,
         colref_desc,

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

@@ -1,5 +1,4 @@
 import plotly.express as px
-import numpy as np
 
 
 def test_reversed_colorscale():

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

@@ -0,0 +1,43 @@
+import plotly.express as px
+from pytest import approx
+
+
+def test_facets():
+    df = px.data.tips()
+    fig = px.scatter(df, x="total_bill", y="tip")
+    assert "xaxis2" not in fig.layout
+    assert "yaxis2" not in fig.layout
+    assert fig.layout.xaxis.domain == (0.0, 1.0)
+    assert fig.layout.yaxis.domain == (0.0, 1.0)
+
+    fig = px.scatter(df, x="total_bill", y="tip", facet_row="sex", facet_col="smoker")
+    assert fig.layout.xaxis4.domain[0] - fig.layout.xaxis.domain[1] == approx(0.02)
+    assert fig.layout.yaxis4.domain[0] - fig.layout.yaxis.domain[1] == approx(0.03)
+
+    fig = px.scatter(df, x="total_bill", y="tip", facet_col="day", facet_col_wrap=2)
+    assert fig.layout.xaxis4.domain[0] - fig.layout.xaxis.domain[1] == approx(0.02)
+    assert fig.layout.yaxis4.domain[0] - fig.layout.yaxis.domain[1] == approx(0.07)
+
+    fig = px.scatter(
+        df,
+        x="total_bill",
+        y="tip",
+        facet_row="sex",
+        facet_col="smoker",
+        facet_col_spacing=0.09,
+        facet_row_spacing=0.08,
+    )
+    assert fig.layout.xaxis4.domain[0] - fig.layout.xaxis.domain[1] == approx(0.09)
+    assert fig.layout.yaxis4.domain[0] - fig.layout.yaxis.domain[1] == approx(0.08)
+
+    fig = px.scatter(
+        df,
+        x="total_bill",
+        y="tip",
+        facet_col="day",
+        facet_col_wrap=2,
+        facet_col_spacing=0.09,
+        facet_row_spacing=0.08,
+    )
+    assert fig.layout.xaxis4.domain[0] - fig.layout.xaxis.domain[1] == approx(0.09)
+    assert fig.layout.yaxis4.domain[0] - fig.layout.yaxis.domain[1] == approx(0.08)