diff --git a/.gitignore b/.gitignore
index 7b9716095e1..f35e6de499f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -44,3 +44,4 @@ plotly/tests/test_orca/images/*/tmp
temp-plot.html
.vscode
doc/python/.ipynb_checkpoints
+doc/python/.mapbox_token
diff --git a/doc/python/axes.md b/doc/python/axes.md
index 8a8b883fd3f..eea8f8daed7 100644
--- a/doc/python/axes.md
+++ b/doc/python/axes.md
@@ -5,7 +5,7 @@ jupyter:
text_representation:
extension: .md
format_name: markdown
- format_version: '1.2'
+ format_version: "1.2"
jupytext_version: 1.3.0
kernelspec:
display_name: Python 3
@@ -22,7 +22,8 @@ jupyter:
pygments_lexer: ipython3
version: 3.7.3
plotly:
- description: How to adjust axes properties in python. Includes examples of linear
+ description:
+ How to adjust axes properties in python. Includes examples of linear
and logarithmic axes, axes titles, styling and coloring axes and grid lines,
and more.
display_as: file_settings
@@ -34,23 +35,24 @@ jupyter:
thumbnail: thumbnail/axes.png
---
-This tutorial explain how to set the properties of Cartesian axes, namely [`go.layout.XAxis`](/python/reference/#layout-xaxis) and [`go.layout.YAxis`](python/reference/#layout-xaxis). Other kinds of axes are described in other tutorials:
+This tutorial explain how to set the properties of 2-dimensional Cartesian axes, namely [`go.layout.XAxis`](/python/reference/#layout-xaxis) and [`go.layout.YAxis`](python/reference/#layout-xaxis). Other kinds of axes are described in other tutorials:
+
- [3D axes](/python/3d-axes) The axis object is [`go.layout.Scene`](/python/reference/#layout-scene)
- [Polar axes](/python/polar-chart/). The axis object is [`go.layout.Polar`](/python/reference/#layout-polar)
- [Ternary axes](/python/ternary-plots). The axis object is [`go.layout.Ternary`](/python/reference/#layout-ternary)
-- For Geo axes, see [this choropleth example](/python/choropleth-maps/#world-choropleth-map). The axis object is [`go.layout.Geo`](/python/reference/#layout-geo)
-- For Mapbox axes, see the different mapbox tutorials in the [Maps page](/python/maps/). The axis object is [`go.layout.Mapbox`](/python/reference/#layout-mapbox)
-- Color axes are described in the [color scales tutorial](/python/colorscales/).
+- [Geo axes](/python/map-configuration/). The axis object is [`go.layout.Geo`](/python/reference/#layout-geo)
+- [Mapbox axes](/python/mapbox-layers/). The axis object is [`go.layout.Mapbox`](/python/reference/#layout-mapbox)
+- [Color axes](/python/colorscales/). The axis object is [`go.layout.Coloraxis`](/python/reference/#layout-coloraxis).
**See also** the tutorials on [subplots](/python/subplots) and [multiple axes](/python/multiple-axes/).
-The different types of Cartesian axes are
+The different types of Cartesian axes are
+
- 'linear'
- 'log' (see the [example below](#logarithmic-axes))
- 'date' (see the [tutorial on timeseries](/python/time-series/))
- 'category' (see for example [Bar Charts](/python/bar-charts/))
-- 'multicategory' (see the [example below](#subcategory-(multicategory)-axes) ))
-
+- 'multicategory' (see the [example below](<#subcategory-(multicategory)-axes>))
#### Logarithmic Axes
@@ -92,7 +94,7 @@ fig.show()
### Forcing an axis to be categorical
-If you pass string values for the `x` or `y` parameter, plotly will automatically set the corresponding axis type to `category`, with the exception of string of numbers, in which case the axis is linear. It is however possible to force the axis type by setting explicitely `xaxis_type` to be `category`.
+If you pass string values for the `x` or `y` parameter, plotly will automatically set the corresponding axis type to `category`, with the exception of string of numbers, in which case the axis is linear. It is however possible to force the axis type by setting explicitely `xaxis_type` to be `category`.
```python
import plotly.express as px
@@ -150,17 +152,16 @@ fig.update_layout(title_text="Multi-category axis",)
fig.show()
```
-
#### Toggling Axes Lines, Ticks, Labels, and Autorange
-The different groups of Cartesian axes properties are
+The different groups of Cartesian axes properties are
+
- tick values (locations of tick marks) and tick labels. Tick labels are placed at tick values.
- lines: grid lines (passing through tick values), axis lines, zero lines
- title of the axis
- range of the axis
- domain of the axis
-
#### Tick Placement, Color, and Style
##### Toggling axis tick marks
@@ -169,7 +170,6 @@ Axis tick marks are disabled by default for the default `plotly` theme, but they
Here is an example of turning on inside x-axis and y-axis ticks in a faceted figure created using Plotly Express. Note how the `col` argument to `update_yaxes` is used to only turn on the y-axis ticks for the left-most subplot.
-
```python
import plotly.express as px
df = px.data.iris()
@@ -265,7 +265,6 @@ fig.update_yaxes(showticklabels=False)
fig.show()
```
-
##### Set axis label rotation and font
The orientation of the axis tick mark labels is configured using the `tickangle` axis property. The value of `tickangle` is the angle of rotation, in the clockwise direction, of the labels from vertical in units of degrees. The font family, size, and color for the tick labels are stored under the `tickfont` axis property.
@@ -324,7 +323,6 @@ fig.update_layout(title_text="Apple Stock Price")
fig.show()
```
-
### Axis lines: grid and zerolines
##### Toggling Axis grid lines
@@ -534,7 +532,6 @@ fig.update_yaxes(range=[3, 9])
fig.show()
```
-
### Fixed Ratio Axes
The `scaleanchor` and `scaleratio` axis properties can be used to force a fixed ratio of pixels per unit between two axes.
@@ -593,7 +590,7 @@ fig.show()
##### Decreasing the domain spanned by an axis
-In the example below, the x and y axis are anchored together, and the range of the `xaxis` is set manually. By default, plotly extends the range of the axis (overriding the `range` parameter) to fit in the figure `domain`. You can restrict the `domain` to force the axis to span only the set range, by setting `constrain='domain'` as below.
+In the example below, the x and y axis are anchored together, and the range of the `xaxis` is set manually. By default, plotly extends the range of the axis (overriding the `range` parameter) to fit in the figure `domain`. You can restrict the `domain` to force the axis to span only the set range, by setting `constrain='domain'` as below.
```python
import plotly.graph_objects as go
@@ -687,7 +684,7 @@ fig.show()
### Axis range for log axis type
-If you are using a `log` type of axis and you want to set the range of the axis, you have to give the `log10` value of the bounds when using `fig.update_xaxes` or `fig.update_layout`. However, with `plotly.express` functions you pass directly the values of the range bounds (`plotly.express` then computes the appropriate values to pass to the figure layout).
+If you are using a `log` type of axis and you want to set the range of the axis, you have to give the `log10` value of the bounds when using `fig.update_xaxes` or `fig.update_layout`. However, with `plotly.express` functions you pass directly the values of the range bounds (`plotly.express` then computes the appropriate values to pass to the figure layout).
```python
import plotly.express as px
diff --git a/doc/python/bubble-maps.md b/doc/python/bubble-maps.md
index e1abcc7e7b5..6563221d923 100644
--- a/doc/python/bubble-maps.md
+++ b/doc/python/bubble-maps.md
@@ -33,6 +33,10 @@ jupyter:
thumbnail: thumbnail/bubble-map.jpg
---
+#### Base Map Configuration
+
+Plotly figures made with `px.scatter_geo`, `px.line_geo` or `px.choropleth` functions or containing `go.Choropleth` or `go.Scattergeo` graph objects have a `go.layout.Geo` object which can be used to [control the appearance of the base map](/python/map-configuration/) onto which data is plotted.
+
### Bubble map with Plotly Express
[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/). With `px.scatter_geo`, each line of the dataframe is represented as a marker point. The column set as the `size` argument gives the size of markers.
diff --git a/doc/python/choropleth-maps.md b/doc/python/choropleth-maps.md
index 2a519ecbb15..ca2b1383f58 100644
--- a/doc/python/choropleth-maps.md
+++ b/doc/python/choropleth-maps.md
@@ -5,12 +5,22 @@ jupyter:
text_representation:
extension: .md
format_name: markdown
- format_version: "1.1"
- jupytext_version: 1.1.1
+ format_version: "1.2"
+ jupytext_version: 1.3.1
kernelspec:
display_name: Python 3
language: python
name: python3
+ language_info:
+ codemirror_mode:
+ name: ipython
+ version: 3
+ file_extension: .py
+ mimetype: text/x-python
+ name: python
+ nbconvert_exporter: python
+ pygments_lexer: ipython3
+ version: 3.6.8
plotly:
description: How to make choropleth maps in Python with Plotly.
display_as: maps
@@ -23,14 +33,154 @@ jupyter:
thumbnail: thumbnail/choropleth.jpg
---
-A [Choropleth Map](https://en.wikipedia.org/wiki/Choropleth_map) is a heatmap using geographical boundaries. It is used to represent spatial variations of a quantity. See also the [index of other geographical charts](/python/maps/).
+A [Choropleth Map](https://en.wikipedia.org/wiki/Choropleth_map) is a map composed of colored polygons. It is used to represent spatial variations of a quantity. This page documents how to build **outline** choropleth maps, but you can also build [choropleth **tile maps** using our Mapbox trace types](/python/mapbox-county-choropleth).
-Below we show how to create Choropleth Maps using either Plotly Express' `px.choropleth` or the lower-level `go.Choropleth`.
+Below we show how to create Choropleth Maps using either Plotly Express' `px.choropleth` function or the lower-level `go.Choropleth` graph object.
+
+#### Base Map Configuration
+
+Plotly figures made with `px.scatter_geo`, `px.line_geo` or `px.choropleth` functions or containing `go.Choropleth` or `go.Scattergeo` graph objects have a `go.layout.Geo` object which can be used to [control the appearance of the base map](/python/map-configuration/) onto which data is plotted.
+
+### Introduction: main parameters for choropleth outline maps
+
+Making choropleth maps requires two main types of input:
+
+1. Geometry information:
+ 1. This can either be a supplied GeoJSON file where each feature has either an `id` field or some identifying value in `properties`; or
+ 2. one of the built-in geometries within `plotly`: US states and world countries (see below)
+2. A list of values indexed by feature identifier.
+
+The GeoJSON data is passed to the `geojson` argument, and the data is passed into the `color` argument of `px.choropleth` (`z` if using `graph_objects`), in the same order as the IDs are passed into the `location` argument.
+
+**Note** the `geojson` attribute can also be the URL to a GeoJSON file, which can speed up map rendering in certain cases.
### Choropleth Map with plotly.express
[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on "tidy" data](/python/px-arguments/).
+#### GeoJSON with `feature.id`
+
+Here we load a GeoJSON file containing the geometry information for US counties, where `feature.id` is a [FIPS code](https://en.wikipedia.org/wiki/FIPS_county_code).
+
+```python
+from urllib.request import urlopen
+import json
+with urlopen('https://raw.githubusercontent.com/plotly/datasets/master/geojson-counties-fips.json') as response:
+ counties = json.load(response)
+
+counties["features"][0]
+```
+
+#### Data indexed by `id`
+
+Here we load unemployment data by county, also indexed by [FIPS code](https://en.wikipedia.org/wiki/FIPS_county_code).
+
+```python
+import pandas as pd
+df = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/fips-unemp-16.csv",
+ dtype={"fips": str})
+df.head()
+```
+
+### Choropleth map using GeoJSON
+
+**Note** In this example we set `layout.geo.scope` to `usa` to automatically configure the map to display USA-centric data in an appropriate projection. See the [Geo map configuration documentation](/python/map-configuration/) for more information on scopes.
+
+```python
+from urllib.request import urlopen
+import json
+with urlopen('https://raw.githubusercontent.com/plotly/datasets/master/geojson-counties-fips.json') as response:
+ counties = json.load(response)
+
+import pandas as pd
+df = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/fips-unemp-16.csv",
+ dtype={"fips": str})
+
+import plotly.express as px
+
+fig = px.choropleth(df, geojson=counties, locations='fips', color='unemp',
+ color_continuous_scale="Viridis",
+ range_color=(0, 12),
+ scope="usa",
+ labels={'unemp':'unemployment rate'}
+ )
+fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+### Indexing by GeoJSON Properties
+
+If the GeoJSON you are using either does not have an `id` field or you wish you use one of the keys in the `properties` field, you may use the `featureidkey` parameter to specify where to match the values of `locations`.
+
+In the following GeoJSON object/data-file pairing, the values of `properties.district` match the values of the `district` column:
+
+```python
+import plotly.express as px
+
+df = px.data.election()
+geojson = px.data.election_geojson()
+
+print(df["district"][2])
+print(geojson["features"][0]["properties"])
+```
+
+To use them together, we set `locations` to `district` and `featureidkey` to `"properties.district"`. The `color` is set to the number of votes by the candidate named Bergeron.
+
+**Note** In this example we set `layout.geo.visible` to `False` to hide the base map and frame, and we set `layout.geo.fitbounds` to `'locations'` to automatically zoom the map to show just the area of interest. See the [Geo map configuration documentation](/python/map-configuration/) for more information on projections and bounds.
+
+```python
+import plotly.express as px
+
+df = px.data.election()
+geojson = px.data.election_geojson()
+
+fig = px.choropleth(df, geojson=geojson, color="Bergeron",
+ locations="district", featureidkey="properties.district",
+ projection="mercator"
+ )
+fig.update_geos(fitbounds="locations", visible=False)
+fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+### Discrete Colors
+
+In addition to [continuous colors](/python/colorscales/), we can [discretely-color](/python/discrete-color/) our choropleth maps by setting `color` to a non-numerical column, like the name of the winner of an election.
+
+**Note** In this example we set `layout.geo.visible` to `False` to hide the base map and frame, and we set `layout.geo.fitbounds` to `'locations'` to automatically zoom the map to show just the area of interest. See the [Geo map configuration documentation](/python/map-configuration/) for more information on projections and bounds.
+
+```python
+import plotly.express as px
+
+df = px.data.election()
+geojson = px.data.election_geojson()
+
+fig = px.choropleth(df, geojson=geojson, color="winner",
+ locations="district", featureidkey="properties.district",
+ projection="mercator", hover_data=["Bergeron", "Coderre", "Joly"]
+ )
+fig.update_geos(fitbounds="locations", visible=False)
+fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+
+
+### Using Built-in Country and State Geometries
+
+Plotly comes with two built-in geometries which do not require an external GeoJSON file:
+
+1. USA States
+2. Countries as defined in the Natural Earth dataset.
+
+**Note and disclaimer:** cultural (as opposed to physical) features are by definition subject to change, debate and dispute. Plotly includes data from Natural Earth "as-is" and defers to the [Natural Earth policy regarding disputed borders](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/50m-admin-0-countries-2/) which read:
+
+> Natural Earth Vector draws boundaries of countries according to defacto status. We show who actually controls the situation on the ground.
+
+To use the built-in countries geometry, provide `locations` as [three-letter ISO country codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3).
+
+
+
```python
import plotly.express as px
@@ -42,6 +192,15 @@ fig = px.choropleth(df, locations="iso_alpha",
fig.show()
```
+To use the USA States geometry, set `locationmode='USA-states'` and provide `locations` as two-letter state abbreviations:
+
+```python
+import plotly.express as px
+
+fig = px.choropleth(locations=["CA", "TX", "NY"], locationmode="USA-states", color=[1,2,3], scope="usa")
+fig.show()
+```
+
### Choropleth Maps with go.Choropleth
#### United States Choropleth Map
@@ -150,97 +309,9 @@ fig.update_layout(
fig.show()
```
-#### Choropleth Inset Map
-
-```python
-import plotly.graph_objects as go
-
-import pandas as pd
-df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/2014_ebola.csv')
-df.head()
-
-colors = ['rgb(239,243,255)', 'rgb(189,215,231)', 'rgb(107,174,214)', 'rgb(33,113,181)']
-months = {6:'June', 7:'July', 8:'Aug', 9:'Sept'}
-
-fig = go.Figure()
-
-# scatter chart for outbreak size
-for i in range(6,10)[::-1]:
- df_month = df.query('Month == %d' %i)
- fig.add_trace(go.Scattergeo(
- lon = df_month['Lon'],
- lat = df_month['Lat'],
- text = df_month['Value'],
- name = months[i],
- marker = dict(
- size=df_month['Value']/50,
- color=colors[i-6],
- line_width=0)
- )
- )
-
-df_sept = df.query('Month == 9')
-fig.data[0].update(text = df_sept['Value'].map('{:.0f}'.format).astype(str)+' '+\
- df_sept['Country'],
- mode = 'markers+text',
- textposition = 'bottom center')
-
-
-fig.add_trace(go.Choropleth(
- locationmode='country names',
- locations=df_sept['Country'],
- z=df_sept['Value'],
- text=df_sept['Country'],
- colorscale = [[0,'rgb(0, 0, 0)'],[1,'rgb(0, 0, 0)']],
- autocolorscale = False,
- showscale = False,
- geo = 'geo2'
- ))
-fig.add_trace(go.Scattergeo(
- lon = [21.0936],
- lat = [7.1881],
- text = ['Africa'],
- mode = 'text',
- showlegend = False,
- geo = 'geo2'
- ))
-
-fig.update_layout(
- title_text = 'Ebola cases reported by month in West Africa 2014
\
-Source: \
-HDX',
- geo = dict(
- resolution=50,
- scope='africa',
- showframe=False,
- showcoastlines=True,
- showland=True,
- landcolor="lightgray",
- countrycolor="white" ,
- coastlinecolor="white",
- projection_type='equirectangular',
- lonaxis_range=[ -15.0, -5.0],
- lataxis_range=[ 0.0, 12.0],
- domain = dict(x=[0, 1], y=[ 0, 1])
- ),
- geo2 = dict(
- scope='africa',
- showframe=False,
- showland=True,
- landcolor="lightgray",
- showcountries=False,
- domain=dict(x=[ 0, 0.6], y=[ 0, 0.6]),
- bgcolor='rgba(255, 255, 255, 0.0)',
- ),
- legend_traceorder = 'reversed'
-)
-
-fig.show()
-```
-
-#### Full County Choropleths
+#### County Choropleth Figure Factory
-For the full county choropleth doc page checkout https://plot.ly/python/county-choropleth/
+Plotly also includes a [legacy "figure factory" for creating US county-level choropleth maps](/python/county-choropleth/).
```python
import plotly.figure_factory as ff
diff --git a/doc/python/county-choropleth.md b/doc/python/county-choropleth.md
index 8fa59d78b1f..904eff8fb9b 100644
--- a/doc/python/county-choropleth.md
+++ b/doc/python/county-choropleth.md
@@ -5,8 +5,8 @@ jupyter:
text_representation:
extension: .md
format_name: markdown
- format_version: '1.1'
- jupytext_version: 1.1.1
+ format_version: '1.2'
+ jupytext_version: 1.3.1
kernelspec:
display_name: Python 3
language: python
@@ -20,7 +20,7 @@ jupyter:
name: python
nbconvert_exporter: python
pygments_lexer: ipython3
- version: 3.7.3
+ version: 3.6.8
plotly:
description: How to create colormaped representations of USA counties by FIPS
values in Python.
@@ -34,6 +34,12 @@ jupyter:
thumbnail: thumbnail/county-choropleth-usa-greybkgd.jpg
---
+### Deprecation warning
+
+
+This page describes a legacy "figure factory" method for creating map-like figures using [self-filled scatter traces](/python/shapes). **This is no longer the recommended way to make county-level choropleth maps**, instead we recommend using a [GeoJSON-based approach to making outline choropleth maps](/python/choropleth-maps/) or the alternative [Mapbox tile-based choropleth maps](/python/mapbox-county-choropleth).
+
+
#### Required Packages
`geopandas`, `pyshp` and `shapely` must be installed for this figure factory.
@@ -47,10 +53,10 @@ Run the following commands to install the correct versions of the following modu
If you are using Windows, follow this post to properly install geopandas and dependencies: http://geoffboeing.com/2014/09/using-geopandas-windows/. If you are using Anaconda, do not use PIP to install the packages above. Instead use conda to install them:
-```
+
conda install plotly
conda install geopandas
-```
+
#### FIPS and Values
Every US state and county has an assined ID regulated by the US Federal Government under the term FIPS (Federal Information Processing Standards) codes. There are state codes and county codes: the 2016 state and county FIPS codes can be found at the [US Census Website](https://www.census.gov/geographies/reference-files/2016/demo/popest/2016-fips.html).
diff --git a/doc/python/filled-area-on-mapbox.md b/doc/python/filled-area-on-mapbox.md
index 1d2d5702610..7b7ebe982a8 100644
--- a/doc/python/filled-area-on-mapbox.md
+++ b/doc/python/filled-area-on-mapbox.md
@@ -5,7 +5,7 @@ jupyter:
text_representation:
extension: .md
format_name: markdown
- format_version: '1.1'
+ format_version: "1.1"
jupytext_version: 1.1.1
kernelspec:
display_name: Python 3
@@ -35,16 +35,16 @@ jupyter:
-### Mapbox Access Token
-
-To plot on Mapbox maps with Plotly you *may* need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information.
+### Mapbox Access Token and Base Map Configuration
+To plot on Mapbox maps with Plotly you _may_ need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information.
There are three different ways to show a filled area in a Mapbox map:
+
1. Use a [Scattermapbox](https://plot.ly/python/reference/#scattermapbox) trace and set `fill` attribute to 'toself'
2. Use a Mapbox layout (i.e. by minimally using an empty [Scattermapbox](https://plot.ly/python/reference/#scattermapbox) trace) and add a GeoJSON layer
3. Use the [Choroplethmapbox](https://plot.ly/python/mapbox-county-choropleth/) trace type
-
+
### Filled `Scattermapbox` Trace
@@ -140,4 +140,5 @@ fig.show()
```
#### Reference
+
See https://plot.ly/python/reference/#scattermapbox for more information about mapbox and their attribute options.
diff --git a/doc/python/getting-started.md b/doc/python/getting-started.md
index 577720636b9..d186505da49 100644
--- a/doc/python/getting-started.md
+++ b/doc/python/getting-started.md
@@ -5,7 +5,7 @@ jupyter:
text_representation:
extension: .md
format_name: markdown
- format_version: '1.1'
+ format_version: "1.1"
jupytext_version: 1.1.1
kernelspec:
display_name: Python 3
@@ -29,13 +29,15 @@ jupyter:
name: Getting Started with Plotly
page_type: u-guide
permalink: python/getting-started/
- redirect_from:
+ redirect_from:
- python/getting_started/
- /python/pytables/
---
+
### Overview
+
The plotly Python library ([plotly.py](https://plot.ly/python/)) is an interactive, [open-source](https://github.com/plotly/plotly.py) plotting library that supports over 40 unique chart types covering a wide range of statistical, financial, geographic, scientific, and 3-dimensional use-cases.
Built on top of the Plotly JavaScript library ([plotly.js](https://plot.ly/javascript/)), plotly.py enables Python users to create beautiful interactive web-based visualizations that can be displayed in Jupyter notebooks, saved to standalone HTML files, or served as part of pure Python-built web applications using Dash.
@@ -43,19 +45,23 @@ Built on top of the Plotly JavaScript library ([plotly.js](https://plot.ly/javas
Thanks to deep integration with the [orca](https://github.com/plotly/orca) image export utility, plotly.py also provides great support for non-web contexts including desktop editors (e.g. QtConsole, Spyder, PyCharm) and static document publishing (e.g. exporting notebooks to PDF with high-quality vector images).
### Installation
+
plotly.py may be installed using pip...
```
$ pip install plotly==4.4.1
```
+
or conda.
```
$ conda install -c plotly plotly=4.4.1
```
+
This package contains everything you need to write figures to standalone HTML files.
-> Note: **No internet connection, account, or payment is required to use plotly.py.** Prior to version 4, this library could operate in either an "online" or "offline" mode. The documentation tended to emphasize the online mode, where graphs get published to the Chart Studio web service. In version 4, all "online" functionality was removed from the `plotly` package and is now available as the separate, optional, `chart-studio` package (See below). **plotly.py version 4 is "offline" only, and does not include any functionality for uploading figures or data to cloud services.**
+> Note: **No internet connection, account, or payment is required to use plotly.py.** Prior to version 4, this library could operate in either an "online" or "offline" mode. The documentation tended to emphasize the online mode, where graphs get published to the Chart Studio web service. In version 4, all "online" functionality was removed from the `plotly` package and is now available as the separate, optional, `chart-studio` package (See below). **plotly.py version 4 is "offline" only, and does not include any functionality for uploading figures or data to cloud services.**
+
```python
@@ -65,7 +71,9 @@ fig.write_html('first_figure.html', auto_open=True)
```
+
#### Jupyter Notebook Support
+
For use in the classic [Jupyter Notebook](https://jupyter.org/), install the `notebook` and `ipywidgets`
packages using pip...
@@ -86,7 +94,9 @@ $ jupyter notebook
```
and display plotly figures inline using the notebook renderer...
+
+
```python
import plotly.graph_objects as go
fig = go.Figure(data=go.Bar(y=[2, 3, 1]))
@@ -102,9 +112,11 @@ fig
```
-See [*Displaying Figures in Python*](/python/renderers/) for more information on the renderers framework, and see [*Plotly FigureWidget Overview*](/python/figurewidget/) for more information on using `FigureWidget`.
+
+See [_Displaying Figures in Python_](/python/renderers/) for more information on the renderers framework, and see [_Plotly FigureWidget Overview_](/python/figurewidget/) for more information on using `FigureWidget`.
#### JupyterLab Support (Python 3.5+)
+
For use in [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/), install the `jupyterlab` and `ipywidgets`
packages using pip...
@@ -154,7 +166,9 @@ $ jupyter lab
```
and display plotly figures inline using the `plotly_mimetype` renderer...
+
+
```python
import plotly.graph_objects as go
fig = go.Figure(data=go.Bar(y=[2, 3, 1]))
@@ -162,6 +176,7 @@ fig.show()
```
or using `FigureWidget` objects.
+
```python
import plotly.graph_objects as go
fig = go.FigureWidget(data=go.Bar(y=[2, 3, 1]))
@@ -169,9 +184,11 @@ fig
```
-See [*Displaying Figures in Python*](/python/renderers/) for more information on the renderers framework, and see [*Plotly FigureWidget Overview*](/python/figurewidget/) for more information on using `FigureWidget`.
+
+See [_Displaying Figures in Python_](/python/renderers/) for more information on the renderers framework, and see [_Plotly FigureWidget Overview_](/python/figurewidget/) for more information on using `FigureWidget`.
#### Static Image Export Support
+
plotly.py supports static image export using the `to_image` and `write_image`
functions in the `plotly.io` package. This functionality requires the
installation of the plotly [orca](https://github.com/plotly/orca) command line utility and the
@@ -194,6 +211,7 @@ $ pip install psutil requests
and orca can be installed according to the instructions in the [orca README](https://github.com/plotly/orca).
These packages contain everything you need to save figures as static images.
+
```python
@@ -201,13 +219,16 @@ import plotly.graph_objects as go
fig = go.FigureWidget(data=go.Bar(y=[2, 3, 1]))
fig.write_image('figure.png')
```
+
-See [*Static Image Export in Python*](/python/static-image-export/) for more information on static image export.
+
+See [_Static Image Export in Python_](/python/static-image-export/) for more information on static image export.
#### Extended Geo Support
+
Some plotly.py features rely on fairly large geographic shape files. The county
choropleth figure factory is one such example. These shape files are distributed as a
-separate `plotly-geo` package. This package can be installed using pip...
+separate `plotly-geo` package. This package can be installed using pip...
```
$ pip install plotly-geo==1.0.0
@@ -219,11 +240,12 @@ or conda.
$ conda install -c plotly plotly-geo=1.0.0
```
-See [*USA County Choropleth Maps in Python*](https://plot.ly/python/county-choropleth/) for more information on the county choropleth figure factory.
+See [_USA County Choropleth Maps in Python_](https://plot.ly/python/county-choropleth/) for more information on the county choropleth figure factory.
#### Chart Studio Support
+
The `chart-studio` package can be used to upload plotly figures to Plotly's Chart
-Studio Cloud or On-Prem services. This package can be installed using pip...
+Studio Cloud or On-Prem services. This package can be installed using pip...
```
$ pip install chart-studio==1.0.0
@@ -238,17 +260,19 @@ $ conda install -c plotly chart-studio=1.0.0
> **Note:** This package is optional, and if it is not installed it is not possible for figures to be uploaded to the Chart Studio cloud service.
### Where to next?
-Now that you have everything installed, you are ready to start reading and running examples of [basic charts](/python/basic-charts/), [statistical charts](/python/statistical-charts/), [scientific charts](/python/scientific-charts/), [financial charts](/python/#financial-charts), [geographic charts](/python/maps/), and [3-dimensional charts](/python/3d-charts/).
-For a complete overview of all of the ways that figures can be created and updated, see the [*Plotly User Guide for Python*](/python/user-guide/).
+Now that you have everything installed, you are ready to start reading and running examples of [basic charts](/python/basic-charts/), [statistical charts](/python/statistical-charts/), [scientific charts](/python/scientific-charts/), [financial charts](/python/#financial-charts), [geographic charts and maps](/python/maps/), and [3-dimensional charts](/python/3d-charts/).
+
+For a complete overview of all of the ways that figures can be created and updated, see the [_Plotly User Guide for Python_](/python/user-guide/).
+
+For information on configuring figure layout options (e.g. axes, titles, legends, etc) and styling figures (e.g. colors, fonts, annotations, images, shapes, etc.), see [_Plotly Fundamentals_](/python/plotly-fundamentals).
-For information on configuring figure layout options (e.g. axes, titles, legends, etc) and styling figures (e.g. colors, fonts, annotations, images, shapes, etc.), see [*Plotly Fundamentals*](/python/plotly-fundamentals).
+For information on theming plotly figures, see [_Theming and templates with plotly for Python_](/python/templates/).
-For information on theming plotly figures, see [*Theming and templates with plotly for Python*](/python/templates/).
+For information on all of the ways that plotly figures can be displayed, see [_Displaying plotly figures with plotly for Python_](/python/renderers/).
-For information on all of the ways that plotly figures can be displayed, see [*Displaying plotly figures with plotly for Python*](/python/renderers/).
+For the full searchable reference of every figure property, see the [_Python figure reference_](https://plot.ly/python/reference/).
-For the full searchable reference of every figure property, see the [*Python figure reference*](https://plot.ly/python/reference/).
+For information on using Python to build web applications containing plotly figures, see the [_Dash User Guide_](https://dash.plot.ly/).
-For information on using Python to build web applications containing plotly figures, see the [*Dash User Guide*](https://dash.plot.ly/).
diff --git a/doc/python/lines-on-mapbox.md b/doc/python/lines-on-mapbox.md
index 66cd4bb8d03..7f72184756d 100644
--- a/doc/python/lines-on-mapbox.md
+++ b/doc/python/lines-on-mapbox.md
@@ -5,7 +5,7 @@ jupyter:
text_representation:
extension: .md
format_name: markdown
- format_version: '1.1'
+ format_version: "1.1"
jupytext_version: 1.1.1
kernelspec:
display_name: Python 3
@@ -33,9 +33,9 @@ jupyter:
thumbnail: thumbnail/line_mapbox.jpg
---
-### Mapbox Access Token
+### Mapbox Access Token and Base Map Configuration
-To plot on Mapbox maps with Plotly you *may* need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information.
+To plot on Mapbox maps with Plotly you _may_ need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information.
To draw a line on your map, you either can use [`px.line_mapbox()`](https://www.plotly.express/plotly_express/#plotly_express.line_mapbox) in Plotly Express, or [`Scattermapbox`](https://plot.ly/python/reference/#scattermapbox) traces. Below we show you how to draw a line on Mapbox using Plotly Express.
@@ -89,4 +89,5 @@ fig.show()
```
#### Reference
+
See https://plot.ly/python/reference/#scattermapbox for more information about mapbox and their attribute options.
diff --git a/doc/python/lines-on-maps.md b/doc/python/lines-on-maps.md
index b2e78985e28..514a6a51e1a 100644
--- a/doc/python/lines-on-maps.md
+++ b/doc/python/lines-on-maps.md
@@ -33,9 +33,11 @@ jupyter:
thumbnail: thumbnail/flight-paths.jpg
---
-For other geographical and map charts see [the maps index page](/python/maps/).
+Below we show how to create geographical line plots using either Plotly Express with `px.line_geo` function or the lower-level `go.Scattergeo` object.
-Below we show how to create geographical line plots using either Plotly Express with `px.line_geo` or the lower-level `go.Scattergeo`.
+#### Base Map Configuration
+
+Plotly figures made with `px.scatter_geo`, `px.line_geo` or `px.choropleth` functions or containing `go.Choropleth` or `go.Scattergeo` graph objects have a `go.layout.Geo` object which can be used to [control the appearance of the base map](/python/map-configuration/) onto which data is plotted.
## Lines on Maps with Plotly Express
diff --git a/doc/python/map-configuration.md b/doc/python/map-configuration.md
new file mode 100644
index 00000000000..36e5439dbe2
--- /dev/null
+++ b/doc/python/map-configuration.md
@@ -0,0 +1,227 @@
+---
+jupyter:
+ jupytext:
+ notebook_metadata_filter: all
+ text_representation:
+ extension: .md
+ format_name: markdown
+ format_version: "1.2"
+ jupytext_version: 1.3.1
+ kernelspec:
+ display_name: Python 3
+ language: python
+ name: python3
+ language_info:
+ codemirror_mode:
+ name: ipython
+ version: 3
+ file_extension: .py
+ mimetype: text/x-python
+ name: python
+ nbconvert_exporter: python
+ pygments_lexer: ipython3
+ version: 3.6.8
+ plotly:
+ description: How to configure and style base maps for Choropleths and Bubble Maps.
+ display_as: maps
+ language: python
+ layout: base
+ name: Map Configuration and Styling
+ order: 13
+ page_type: u-guide
+ permalink: python/map-configuration/
+ thumbnail: thumbnail/county-level-choropleth.jpg
+---
+
+### Mapbox Maps vs Geo Maps
+
+Plotly supports two different kinds of maps:
+
+1. **Mapbox maps** are [tile-based maps](https://en.wikipedia.org/wiki/Tiled_web_map). If your figure is created with a `px.scatter_mapbox`, `px.line_mapbox`, `px.choropleth_mapbox` or `px.density_mapbox` function or otherwise contains one or more traces of type `go.Scattermapbox`, `go.Choroplethmapbox` or `go.Densitymapbox`, the `layout.mapbox` object in your figure contains configuration information for the map itself.
+2. **Geo maps** are outline-based maps. If your figure is created with a `px.scatter_geo`, `px.line_geo` or `px.choropleth` function or otherwise contains one or more traces of type `go.Scattergeo` or `go.Choropleth`, the `layout.geo` object in your figure contains configuration information for the map itself.
+
+This page documents Geo outline-based maps, and the [Mapbox Layers documentation](/python/mapbox-layers/) describes how to configure Mapbox tile-based maps.
+
+**Note:** Plotly Express cannot create empty figures, so the examples below mostly create an "empty" map using `fig = go.Figure(go.Scattergeo())`. That said, every configuration option here is equally applicable to non-empty maps created with the Plotly Express `px.scatter_geo`, `px.line_geo` or `px.choropleth` functions.
+
+### Physical Base Maps
+
+Plotly Geo maps have a built-in base map layer composed of "physical" and "cultural" (i.e. administrative border) data from the [Natural Earth Dataset](https://www.naturalearthdata.com/downloads/). Various lines and area fills can be shown or hidden, and their color and line-widths specified. In the [default `plotly` template](/python/templates/), a map frame and physical features such as a coastal outline and filled land areas are shown, at a small-scale 1:110m resolution:
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(go.Scattergeo())
+fig.update_layout(height=300, margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+Here is a map with all physical features enabled and styled, at a larger-scale 1:50m resolution:
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(go.Scattergeo())
+fig.update_geos(
+ resolution=50,
+ showcoastlines=True, coastlinecolor="RebeccaPurple",
+ showland=True, landcolor="LightGreen",
+ showocean=True, oceancolor="LightBlue",
+ showlakes=True, lakecolor="Blue",
+ showrivers=True, rivercolor="Blue"
+)
+fig.update_layout(height=300, margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+### Disabling Base Maps
+
+In certain cases, such as large scale [choropleth maps](/python/choropleth-maps/), the default physical map can be distracting. In this case the `layout.geo.visible` attribute can be set to `False` to hide all base map attributes except those which are explicitly set to true. For example in the following map we hide all physical features except rivers and lakes, neither of which are shown by default:
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(go.Scattergeo())
+fig.update_geos(
+ visible=False,
+ resolution=50,
+ showlakes=True, lakecolor="Blue",
+ showrivers=True, rivercolor="Blue"
+)
+fig.update_layout(height=300, margin={"r":0,"t":0,"l":0,"b":0})
+
+fig.show()
+```
+
+### Cultural Base Maps
+
+In addition to physical base map features, a "cultural" base map is included which is composed of country borders and selected sub-country borders such as states.
+
+**Note and disclaimer:** cultural features are by definition subject to change, debate and dispute. Plotly includes data from Natural Earth "as-is" and defers to the [Natural Earth policy regarding disputed borders](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/50m-admin-0-countries-2/) which read:
+
+> Natural Earth Vector draws boundaries of countries according to defacto status. We show who actually controls the situation on the ground.
+
+**To create a map with your own cultural features** please refer to our [choropleth documentation](/python/choropleth-maps/).
+
+Here is a map with only cultural features enabled and styled, at a 1:50m resolution, which includes only country boundaries. See below for country sub-unit cultural base map features:
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(go.Scattergeo())
+fig.update_geos(
+ visible=False, resolution=50,
+ showcountries=True, countrycolor="RebeccaPurple"
+)
+fig.update_layout(height=300, margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+### Map Projections
+
+Geo maps are drawn according to a given map [projection](https://en.wikipedia.org/wiki/Map_projection) that flattens the Earth's roughly-spherical surface into a 2-dimensional space.
+
+The available projections are `'equirectangular'`, `'mercator'`, `'orthographic'`, `'natural earth'`, `'kavrayskiy7'`, `'miller'`, `'robinson'`, `'eckert4'`, `'azimuthal equal area'`, `'azimuthal equidistant'`, `'conic equal area'`, `'conic conformal'`, `'conic equidistant'`, `'gnomonic'`, `'stereographic'`, `'mollweide'`, `'hammer'`, `'transverse mercator'`, `'albers usa'`, `'winkel tripel'`, `'aitoff'` and `'sinusoidal'`.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(go.Scattergeo())
+fig.update_geos(projection_type="orthographic")
+fig.update_layout(height=300, margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(go.Scattergeo())
+fig.update_geos(projection_type="natural earth")
+fig.update_layout(height=300, margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+Map projections can be rotated using the `layout.geo.projection.rotation` attribute, and maps can be translated using the `layout.geo.center` attributed, as well as truncated to a certain longitude and latitude range using the `layout.geo.lataxis.range` and `layout.geo.lonaxis.range`.
+
+The map below uses all of these attributes to demonstrate the types of effect this can yield:
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(go.Scattergeo())
+fig.update_geos(
+ center=dict(lon=-30, lat=-30),
+ projection_rotation=dict(lon=30, lat=30, roll=30),
+ lataxis_range=[-50,20], lonaxis_range=[0, 200]
+)
+fig.update_layout(height=300, margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+### Automatic Zooming or Bounds Fitting
+
+The `layout.geo.fitbounds` attribute can be set to `locations` to automatically set the center and latitude and longitude range according to the data being plotted. See the [choropleth maps](/python/choropleth-maps/) documentation for more information.
+
+```python
+import plotly.express as px
+
+fig = px.line_geo(lat=[0,15,20,35], lon=[5,10,25,30])
+fig.update_geos(fitbounds="locations")
+fig.update_layout(height=300, margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+### Named Map Scopes and Country Sub-Units
+
+In addition, the named "scope" of a map defines a sub-set of the earth's surface to draw. Each scope has a _default projection type, center and roll, as well as bounds_, and certain scopes contain country sub-unit cultural layers certain resolutions, such as `scope="north america"` at `resolution=50` which contains US state and Canadian province boundaries.
+
+The available scopes are: `'world'`, `'usa'`, `'europe'`, `'asia'`, `'africa'`, `'north america'`, `'south america'`.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(go.Scattergeo())
+fig.update_geos(
+ visible=False, resolution=50, scope="north america",
+ showcountries=True, countrycolor="Black",
+ showsubunits=True, subunitcolor="Blue"
+)
+fig.update_layout(height=300, margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+The `"usa"` scope contains state boundaries at both resolutions, and uses the special `'albers usa'` projection which moves Alaska and Hawaii closer to the "lower 48 states" to reduce projection distortion and produce a more compact map.
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(go.Scattergeo())
+fig.update_geos(
+ visible=False, resolution=110, scope="usa",
+ showcountries=True, countrycolor="Black",
+ showsubunits=True, subunitcolor="Blue"
+)
+fig.update_layout(height=300, margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+### Graticules (Latitude and Longitude Grid Lines)
+
+A graticule can be drawn using `layout.geo.lataxis.showgrid` and `layout.geo.lonaxis.showgrid` with options similar to [2d cartesian ticks](/python/axes/).
+
+```python
+import plotly.graph_objects as go
+
+fig = go.Figure(go.Scattergeo())
+fig.update_geos(lataxis_showgrid=True, lonaxis_showgrid=True)
+fig.update_layout(height=300, margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+### Reference
+
+See https://plot.ly/python/reference/#layout-geo for more information and chart attribute options!
+
+```python
+
+```
diff --git a/doc/python/mapbox-county-choropleth.md b/doc/python/mapbox-county-choropleth.md
index 5214cd47b68..dd5cbebd978 100644
--- a/doc/python/mapbox-county-choropleth.md
+++ b/doc/python/mapbox-county-choropleth.md
@@ -5,8 +5,8 @@ jupyter:
text_representation:
extension: .md
format_name: markdown
- format_version: '1.2'
- jupytext_version: 1.3.0
+ format_version: "1.2"
+ jupytext_version: 1.3.1
kernelspec:
display_name: Python 3
language: python
@@ -20,9 +20,10 @@ jupyter:
name: python
nbconvert_exporter: python
pygments_lexer: ipython3
- version: 3.7.3
+ version: 3.6.8
plotly:
- description: How to make a Mapbox Choropleth Map of US Counties in Python with
+ description:
+ How to make a Mapbox Choropleth Map of US Counties in Python with
Plotly.
display_as: maps
language: python
@@ -34,16 +35,24 @@ jupyter:
thumbnail: thumbnail/mapbox-choropleth.png
---
+A [Choropleth Map](https://en.wikipedia.org/wiki/Choropleth_map) is a map composed of colored polygons. It is used to represent spatial variations of a quantity. This page documents how to build **tile-map** choropleth maps, but you can also build [**outline** choropleth maps using our non-Mapbox trace types](/python/choropleth-maps).
-#### Mapbox Access Token
+Below we show how to create Choropleth Maps using either Plotly Express' `px.choropleth_mapbox` function or the lower-level `go.Choroplethmapbox` graph object.
-To plot on Mapbox maps with Plotly you *may* need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information.
+#### Mapbox Access Tokens and Base Map Configuration
+To plot on Mapbox maps with Plotly you _may_ need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information.
-### Introduction: main parameters for choropleth mapbox charts
+### Introduction: main parameters for choropleth tile maps
-Making choropleth maps requires two main types of input: GeoJSON-formatted geometry information *where each `feature` has an `id`* and a list of values indexed by feature id. The GeoJSON data is passed to the `geojson` attribute, and the data is passed into the `z` (`color` for `px.choropleth_mapbox`) attribute, in the same order as the IDs are passed into the `location` attribute.
+Making choropleth Mapbox maps requires two main types of input:
+1. GeoJSON-formatted geometry information where each feature has either an `id` field or some identifying value in `properties`.
+2. A list of values indexed by feature identifier.
+
+The GeoJSON data is passed to the `geojson` argument, and the data is passed into the `color` argument of `px.choropleth_mapbox` (`z` if using `graph_objects`), in the same order as the IDs are passed into the `location` argument.
+
+**Note** the `geojson` attribute can also be the URL to a GeoJSON file, which can speed up map rendering in certain cases.
#### GeoJSON with `feature.id`
@@ -88,7 +97,7 @@ df = pd.read_csv("https://raw.githubusercontent.com/plotly/datasets/master/fips-
import plotly.express as px
fig = px.choropleth_mapbox(df, geojson=counties, locations='fips', color='unemp',
- color_continuous_scale="Viridis",
+ color_continuous_scale="Viridis",
range_color=(0, 12),
mapbox_style="carto-positron",
zoom=3, center = {"lat": 37.0902, "lon": -95.7129},
@@ -99,6 +108,56 @@ fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
fig.show()
```
+### Indexing by GeoJSON Properties
+
+If the GeoJSON you are using either does not have an `id` field or you wish you use one of the keys in the `properties` field, you may use the `featureidkey` parameter to specify where to match the values of `locations`.
+
+In the following GeoJSON object/data-file pairing, the values of `properties.district` match the values of the `district` column:
+
+```python
+import plotly.express as px
+
+df = px.data.election()
+geojson = px.data.election_geojson()
+
+print(df["district"][2])
+print(geojson["features"][0]["properties"])
+```
+
+To use them together, we set `locations` to `district` and `featureidkey` to `"properties.district"`. The `color` is set to the number of votes by the candidate named Bergeron.
+
+```python
+import plotly.express as px
+
+df = px.data.election()
+geojson = px.data.election_geojson()
+
+fig = px.choropleth_mapbox(df, geojson=geojson, color="Bergeron",
+ locations="district", featureidkey="properties.district",
+ center={"lat": 45.5517, "lon": -73.7073},
+ mapbox_style="carto-positron", zoom=9)
+fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
+### Discrete Colors
+
+In addition to [continuous colors](/python/colorscales/), we can [discretely-color](/python/discrete-color/) our choropleth maps by setting `color` to a non-numerical column, like the name of the winner of an election.
+
+```python
+import plotly.express as px
+
+df = px.data.election()
+geojson = px.data.election_geojson()
+
+fig = px.choropleth_mapbox(df, geojson=geojson, color="winner",
+ locations="district", featureidkey="properties.district",
+ center={"lat": 45.5517, "lon": -73.7073},
+ mapbox_style="carto-positron", zoom=9)
+fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
+fig.show()
+```
+
### Choropleth map using plotly.graph_objects and carto base map (no token needed)
If Plotly Express does not provide a good starting point, it is also possible to use the more generic `go.Choroplethmapbox` function from `plotly.graph_objects`.
@@ -148,5 +207,7 @@ fig.update_layout(mapbox_style="light", mapbox_accesstoken=token,
fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
fig.show()
```
+
#### Reference
+
See https://plot.ly/python/reference/#choroplethmapbox for more information about mapbox and their attribute options.
diff --git a/doc/python/mapbox-layers.md b/doc/python/mapbox-layers.md
index 4d5458a40bc..0aac4981c1a 100644
--- a/doc/python/mapbox-layers.md
+++ b/doc/python/mapbox-layers.md
@@ -5,8 +5,8 @@ jupyter:
text_representation:
extension: .md
format_name: markdown
- format_version: '1.1'
- jupytext_version: 1.1.1
+ format_version: "1.2"
+ jupytext_version: 1.3.1
kernelspec:
display_name: Python 3
language: python
@@ -22,7 +22,8 @@ jupyter:
pygments_lexer: ipython3
version: 3.6.8
plotly:
- description: How to make Mapbox maps in Python with various base layers, with
+ description:
+ How to make Mapbox maps in Python with various base layers, with
or without needing a Mapbox Access token.
display_as: maps
language: python
@@ -35,34 +36,44 @@ jupyter:
---
-#### How Layers Work in Mapbox Maps
-If your figure contains one or more traces of type `go.Scattermapbox`, `go.Choroplethmapbox` or `go.Densitymapbox`, the `layout.mapbox` object in your figure contains configuration information for the map itself. The map is composed of various layers, of three different types:
+### Mapbox Maps vs Geo Maps
- 1. `layout.mapbox.style` defines is the lowest layers, also known as your "base map"
- 2. The various traces in `data` are by default rendered above the base map (although this can be controlled via the `below` attribute).
- 3. `layout.mapbox.layers` is an array that defines more layers that are by default rendered above the traces in `data` (although this can also be controlled via the `below` attribute).
+Plotly supports two different kinds of maps:
+
+1. **Mapbox maps** are [tile-based maps](https://en.wikipedia.org/wiki/Tiled_web_map). If your figure is created with a `px.scatter_mapbox`, `px.line_mapbox`, `px.choropleth_mapbox` or `px.density_mapbox` function or otherwise contains one or more traces of type `go.Scattermapbox`, `go.Choroplethmapbox` or `go.Densitymapbox`, the `layout.mapbox` object in your figure contains configuration information for the map itself.
+2. **Geo maps** are outline-based maps. If your figure is created with a `px.scatter_geo`, `px.line_geo` or `px.choropleth` function or otherwise contains one or more traces of type `go.Scattergeo` or `go.Choropleth`, the `layout.geo` object in your figure contains configuration information for the map itself.
+
+This page documents Mapbox tile-based maps, and the [Geo map documentation](/python/map-configuration/) describes how to configure outline-based maps.
+
+#### How Layers Work in Mapbox Tile Maps
+
+Mapbox tile maps are composed of various layers, of three different types:
+
+1. `layout.mapbox.style` defines is the lowest layers, also known as your "base map"
+2. The various traces in `data` are by default rendered above the base map (although this can be controlled via the `below` attribute).
+3. `layout.mapbox.layers` is an array that defines more layers that are by default rendered above the traces in `data` (although this can also be controlled via the `below` attribute).
#### Mapbox Access Tokens and When You Need Them
-The word "mapbox" in the trace names and `layout.mapbox` refers to the Mapbox.js open-source library, which is integrated into Plotly.py. If your basemap in `layout.mapbox.style` uses data from the Mapbox *service*, then you will need to register for a free account at https://mapbox.com/ and obtain a Mapbox Access token. This token should be provided in `layout.mapbox.access_token` (or, if using Plotly Express, via the `px.set_mapbox_access_token()` configuration function).
+The word "mapbox" in the trace names and `layout.mapbox` refers to the Mapbox.js open-source library, which is integrated into Plotly.py. If your basemap in `layout.mapbox.style` uses data from the Mapbox _service_, then you will need to register for a free account at https://mapbox.com/ and obtain a Mapbox Access token. This token should be provided in `layout.mapbox.access_token` (or, if using Plotly Express, via the `px.set_mapbox_access_token()` configuration function).
-> If your `layout.mapbox.style` does not use data from the Mapbox service, you do *not* need to register for a Mapbox account.
+> If your `layout.mapbox.style` does not use data from the Mapbox service, you do _not_ need to register for a Mapbox account.
#### Base Maps in `layout.mapbox.style`
The accepted values for `layout.mapbox.style` are one of:
-* `"white-bg"` yields an empty white canvas which results in no external HTTP requests
-* `"open-street-map"`, `"carto-positron"`, `"carto-darkmatter"`, `"stamen-terrain"`, `"stamen-toner"` or `"stamen-watercolor"` yeild maps composed of *raster* tiles from various public tile servers which do not require signups or access tokens
-* `"basic"`, `"streets"`, `"outdoors"`, `"light"`, `"dark"`, `"satellite"`, or `"satellite-streets"` yeild maps composed of *vector* tiles from the Mapbox service, and *do* require a Mapbox Access Token or an on-premise Mapbox installation.
-* A Mapbox service style URL, which requires a Mapbox Access Token or an on-premise Mapbox installation.
-* A Mapbox Style object as defined at https://docs.mapbox.com/mapbox-gl-js/style-spec/
-
-
+- `"white-bg"` yields an empty white canvas which results in no external HTTP requests
+- `"open-street-map"`, `"carto-positron"`, `"carto-darkmatter"`, `"stamen-terrain"`, `"stamen-toner"` or `"stamen-watercolor"` yeild maps composed of _raster_ tiles from various public tile servers which do not require signups or access tokens
+- `"basic"`, `"streets"`, `"outdoors"`, `"light"`, `"dark"`, `"satellite"`, or `"satellite-streets"` yeild maps composed of _vector_ tiles from the Mapbox service, and _do_ require a Mapbox Access Token or an on-premise Mapbox installation.
+- A Mapbox service style URL, which requires a Mapbox Access Token or an on-premise Mapbox installation.
+- A Mapbox Style object as defined at https://docs.mapbox.com/mapbox-gl-js/style-spec/
#### OpenStreetMap tiles: no token needed
+
Here is a simple map rendered with OpenStreetMaps tiles, without needing a Mapbox Access Token:
+
```python
@@ -78,18 +89,18 @@ fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
fig.show()
```
-
+
#### Using `layout.mapbox.layers` to Specify a Base Map
If you have access to your own private tile servers, or wish to use a tile server not included in the list above, the recommended approach is to set `layout.mapbox.style` to `"white-bg"` and to use `layout.mapbox.layers` with `below` to specify a custom base map.
-
> If you omit the `below` attribute when using this approach, your data will likely be hidden by fully-opaque raster tiles!
#### Base Tiles from the USGS: no token needed
-Here is an example of a map which uses a public USGS imagery map, specified in `layout.mapbox.layers`, and which is rendered *below* the `data` layer.
+Here is an example of a map which uses a public USGS imagery map, specified in `layout.mapbox.layers`, and which is rendered _below_ the `data` layer.
+
```python
@@ -116,10 +127,11 @@ fig.show()
```
-#### Base Tiles from the USGS, radar overlay from Environment Canada: no token needed
+#### Base Tiles from the USGS, radar overlay from Environment Canada: no token needed
Here is the same example, with in addition, a WMS layer from Environment Canada which displays near-real-time radar imagery in partly-transparent raster tiles, rendered above the `go.Scattermapbox` trace, as is the default:
+
```python
@@ -151,10 +163,9 @@ fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
fig.show()
```
-
-#### Dark tiles from Mapbox service: free token needed
+#### Dark tiles from Mapbox service: free token needed
Here is a map rendered with the `"dark"` style from the Mapbox service, which requires an Access Token:
@@ -176,4 +187,5 @@ fig.show()
```
#### Reference
+
See https://plot.ly/python/reference/#layout-mapbox for more information and options!
diff --git a/doc/python/scatter-plots-on-maps.md b/doc/python/scatter-plots-on-maps.md
index df82f99f885..be23088be84 100644
--- a/doc/python/scatter-plots-on-maps.md
+++ b/doc/python/scatter-plots-on-maps.md
@@ -35,6 +35,10 @@ jupyter:
thumbnail: thumbnail/scatter-plot-on-maps.jpg
---
+#### Base Map Configuration
+
+Plotly figures made with `px.scatter_geo`, `px.line_geo` or `px.choropleth` functions or containing `go.Choropleth` or `go.Scattergeo` graph objects have a `go.layout.Geo` object which can be used to [control the appearance of the base map](/python/map-configuration/) onto which data is plotted.
+
### Geographical Scatter Plot with px.scatter_geo
Here we show the [Plotly Express](/python/plotly-express/) function `px.scatter_geo` for a geographical scatter plot. The `size` argument is used to set the size of markers from a given column of the DataFrame.
diff --git a/doc/python/scattermapbox.md b/doc/python/scattermapbox.md
index 0e5ec5bf785..0f9a32aea2e 100644
--- a/doc/python/scattermapbox.md
+++ b/doc/python/scattermapbox.md
@@ -33,7 +33,7 @@ jupyter:
thumbnail: thumbnail/scatter-mapbox.jpg
---
-#### Mapbox Access Token
+#### Mapbox Access Token and Base Map Configuration
To plot on Mapbox maps with Plotly you _may_ need a Mapbox account and a public [Mapbox Access Token](https://www.mapbox.com/studio). See our [Mapbox Map Layers](/python/mapbox-layers/) documentation for more information.