New mapbox functions in PX

packages/python/plotly/plotly/express/__init__.py

@@ -4,6 +4,7 @@
 """
 from __future__ import absolute_import
 from plotly import optional_imports
+from ._imshow import imshow
 
 pd = optional_imports.get_module("pandas")
 if pd is None:
@@ -12,7 +13,6 @@
 Plotly express requires pandas to be installed."""
     )
 
-
 from ._chart_types import (  # noqa: F401
     scatter,
     scatter_3d,
@@ -44,9 +44,10 @@
     treemap,
     funnel,
     funnel_area,
+    choropleth_mapbox,
+    density_mapbox,
 )
 
-from ._imshow import imshow
 
 from ._core import (  # noqa: F401
     set_mapbox_access_token,
@@ -66,6 +67,7 @@
     "scatter_matrix",
     "density_contour",
     "density_heatmap",
+    "density_mapbox",
     "line",
     "line_3d",
     "line_polar",
@@ -82,6 +84,7 @@
     "strip",
     "histogram",
     "choropleth",
+    "choropleth_mapbox",
     "pie",
     "sunburst",
     "treemap",

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

@@ -842,15 +842,13 @@ def choropleth(
     hover_name=None,
     hover_data=None,
     custom_data=None,
-    size=None,
     animation_frame=None,
     animation_group=None,
     category_orders={},
     labels={},
     color_continuous_scale=None,
     range_color=None,
     color_continuous_midpoint=None,
-    size_max=None,
     projection=None,
     scope=None,
     center=None,
@@ -983,6 +981,8 @@ def scatter_mapbox(
     opacity=None,
     size_max=None,
     zoom=8,
+    center=None,
+    mapbox_style=None,
     title=None,
     template=None,
     width=None,
@@ -998,6 +998,85 @@ def scatter_mapbox(
 scatter_mapbox.__doc__ = make_docstring(scatter_mapbox)
 
 
+def choropleth_mapbox(
+    data_frame=None,
+    geojson=None,
+    locations=None,
+    color=None,
+    hover_name=None,
+    hover_data=None,
+    custom_data=None,
+    animation_frame=None,
+    animation_group=None,
+    category_orders={},
+    labels={},
+    color_continuous_scale=None,
+    range_color=None,
+    color_continuous_midpoint=None,
+    opacity=None,
+    zoom=8,
+    center=None,
+    mapbox_style=None,
+    title=None,
+    template=None,
+    width=None,
+    height=None,
+):
+    """
+    In a Mapbox choropleth map, each row of `data_frame` is represented by a
+    colored region on a Mapbox map.
+    """
+    return make_figure(
+        args=locals(),
+        constructor=go.Choroplethmapbox,
+        trace_patch=dict(
+            geojson=geojson
+            if not hasattr(geojson, "__geo_interface__")
+            else geojson.__geo_interface__
+        ),
+    )
+
+
+choropleth_mapbox.__doc__ = make_docstring(choropleth_mapbox)
+
+
+def density_mapbox(
+    data_frame=None,
+    lat=None,
+    lon=None,
+    z=None,
+    hover_name=None,
+    hover_data=None,
+    custom_data=None,
+    animation_frame=None,
+    animation_group=None,
+    category_orders={},
+    labels={},
+    color_continuous_scale=None,
+    range_color=None,
+    color_continuous_midpoint=None,
+    opacity=None,
+    zoom=8,
+    center=None,
+    mapbox_style=None,
+    radius=None,
+    title=None,
+    template=None,
+    width=None,
+    height=None,
+):
+    """
+    In a Mapbox density map, each row of `data_frame` contributes to the intensity of
+    the color of the region around the corresponding point on the map
+    """
+    return make_figure(
+        args=locals(), constructor=go.Densitymapbox, trace_patch=dict(radius=radius)
+    )
+
+
+density_mapbox.__doc__ = make_docstring(density_mapbox)
+
+
 def line_mapbox(
     data_frame=None,
     lat=None,

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

@@ -287,7 +287,7 @@ def make_trace_kwargs(args, trace_spec, g, mapping_labels, sizeref):
                         v_label_col = get_decorated_label(args, col, None)
                         mapping_labels[v_label_col] = "%%{customdata[%d]}" % (position)
             elif k == "color":
-                if trace_spec.constructor == go.Choropleth:
+                if trace_spec.constructor in [go.Choropleth, go.Choroplethmapbox]:
                     result["z"] = g[v]
                     result["coloraxis"] = "coloraxis1"
                     mapping_labels[v_label] = "%{z}"
@@ -380,6 +380,8 @@ def configure_axes(args, constructor, fig, orders):
         go.Scatterpolargl: configure_polar_axes,
         go.Barpolar: configure_polar_axes,
         go.Scattermapbox: configure_mapbox,
+        go.Choroplethmapbox: configure_mapbox,
+        go.Densitymapbox: configure_mapbox,
         go.Scattergeo: configure_geo,
         go.Choropleth: configure_geo,
     }
@@ -502,13 +504,11 @@ def configure_cartesian_axes(args, fig, orders):
 
 
 def configure_ternary_axes(args, fig, orders):
-    fig.update(
-        layout=dict(
-            ternary=dict(
-                aaxis=dict(title=get_label(args, args["a"])),
-                baxis=dict(title=get_label(args, args["b"])),
-                caxis=dict(title=get_label(args, args["c"])),
-            )
+    fig.update_layout(
+        ternary=dict(
+            aaxis=dict(title=get_label(args, args["a"])),
+            baxis=dict(title=get_label(args, args["b"])),
+            caxis=dict(title=get_label(args, args["c"])),
         )
     )
 
@@ -562,28 +562,28 @@ def configure_3d_axes(args, fig, orders):
 
 
 def configure_mapbox(args, fig, orders):
-    fig.update(
-        layout=dict(
-            mapbox=dict(
-                accesstoken=MAPBOX_TOKEN,
-                center=dict(
-                    lat=args["data_frame"][args["lat"]].mean(),
-                    lon=args["data_frame"][args["lon"]].mean(),
-                ),
-                zoom=args["zoom"],
-            )
+    center = args["center"]
+    if not center and "lat" in args and "lon" in args:
+        center = dict(
+            lat=args["data_frame"][args["lat"]].mean(),
+            lon=args["data_frame"][args["lon"]].mean(),
+        )
+    fig.update_layout(
+        mapbox=dict(
+            accesstoken=MAPBOX_TOKEN,
+            center=center,
+            zoom=args["zoom"],
+            style=args["mapbox_style"],
         )
     )
 
 
 def configure_geo(args, fig, orders):
-    fig.update(
-        layout=dict(
-            geo=dict(
-                center=args["center"],
-                scope=args["scope"],
-                projection=dict(type=args["projection"]),
-            )
+    fig.update_layout(
+        geo=dict(
+            center=args["center"],
+            scope=args["scope"],
+            projection=dict(type=args["projection"]),
         )
     )
 
@@ -1083,7 +1083,7 @@ def infer_config(args, constructor, trace_patch):
     # Compute final trace patch
     trace_patch = trace_patch.copy()
 
-    if constructor == go.Histogram2d:
+    if constructor in [go.Histogram2d, go.Densitymapbox]:
         show_colorbar = True
         trace_patch["coloraxis"] = "coloraxis1"
 
@@ -1221,6 +1221,8 @@ def make_figure(args, constructor, trace_patch={}, layout_patch={}):
                 go.Parcats,
                 go.Parcoords,
                 go.Choropleth,
+                go.Choroplethmapbox,
+                go.Densitymapbox,
                 go.Histogram2d,
                 go.Sunburst,
                 go.Treemap,
@@ -1321,7 +1323,7 @@ def make_figure(args, constructor, trace_patch={}, layout_patch={}):
         )
     layout_patch = layout_patch.copy()
     if show_colorbar:
-        colorvar = "z" if constructor == go.Histogram2d else "color"
+        colorvar = "z" if constructor in [go.Histogram2d, go.Densitymapbox] else "color"
         range_color = args["range_color"] or [None, None]
 
         colorscale_validator = ColorscaleValidator("colorscale", "make_figure")

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

@@ -164,6 +164,7 @@
         colref_desc,
         "Values from this column or array_like are used to assign mark sizes.",
     ],
+    radius=["int (default is 30)", "Sets the radius of influence of each point.",],
     hover_name=[
         colref_type,
         colref_desc,
@@ -445,6 +446,12 @@
         "Dict keys are `'lat'` and `'lon'`",
         "Sets the center point of the map.",
     ],
+    mapbox_style=[
+        "str (default `'basic'`, needs Mapbox API token)",
+        "Identifier of base map style, some of which require a Mapbox API token to be set using `plotly.express.set_mapbox_access_token()`.",
+        "Allowed values which do not require a Mapbox API token are `'open-street-map'`, `'white-bg'`, `'carto-positron'`, `'carto-darkmatter'`, `'stamen-terrain'`, `'stamen-toner'`, `'stamen-watercolor'`.",
+        "Allowed values which do require a Mapbox API token are `'basic'`, `'streets'`, `'outdoors'`, `'light'`, `'dark'`, `'satellite'`, `'satellite-streets'`.",
+    ],
     points=[
         "str or boolean (default `'outliers'`)",
         "One of `'outliers'`, `'suspectedoutliers'`, `'all'`, or `False`.",
@@ -456,6 +463,10 @@
     ],
     box=["boolean (default `False`)", "If `True`, boxes are drawn inside the violins."],
     notched=["boolean (default `False`)", "If `True`, boxes are drawn with notches."],
+    geojson=[
+        "GeoJSON-formatted dict",
+        "Must contain a Polygon feature collection, with IDs, which are references from `locations`.",
+    ],
     cumulative=[
         "boolean (default `False`)",
         "If `True`, histogram values are cumulative.",